agentfootprint 11.1.1 → 11.3.0

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

@@ -0,0 +1,81 @@
+/**
+ * backoff — builders of a `RetryPolicy.backoffMs` function: an exponential
+ * schedule, and a wait the server stated winning over it.
+ *
+ * STAND-IN, TO BE DELETED. footprintjs is adding these two helpers to its
+ * attempt runner (`attempt/backoff.ts`): `exponentialBackoff({ baseDelayMs,
+ * multiplier, jitter, maxDelayMs, random })` and
+ * `statedWaitFirst(readStatedWaitMs, inner)`, with these names, signatures and
+ * laws. Once a footprintjs release
+ * ships them, import them in `throttleRetry.ts` and delete this file; nothing
+ * else changes.
+ *
+ * Pattern: Two pure builders. Each returns `(attempt, error?) => ms`.
+ * Role:    The wait `throttleRetry.ts` plans for each retry.
+ * Emits:   N/A.
+ *
+ * ── THE LAW ──────────────────────────────────────────────────────────────
+ * `exponentialBackoff`: after failed attempt `n` (1-based) the ceiling is
+ *
+ *     c = min(maxDelayMs, baseDelayMs × multiplier^(n − 1))
+ *                                     (saturating at MAX_SAFE_INTEGER)
+ *
+ * and, for `r = random()` in [0, 1]:
+ *
+ *     'none'    c                        `random` is never called
+ *     'equal'   min(c, c/2 + r × c/2)    never below half the ceiling
+ *     'full'    r × c                    anywhere from 0 up to it
+ *
+ * Waits are exact milliseconds — nothing is rounded. `random` defaults to
+ * `Math.random`, taken when the function is BUILT; a fixed source makes a test
+ * exact. A `random()` answering outside [0, 1] throws when asked.
+ *
+ * `statedWaitFirst`: when `readStatedWaitMs(error)` answers a finite number
+ * ≥ 0, that is the wait; otherwise `inner` decides. A reader that throws or
+ * answers anything else states nothing, so a malformed `Retry-After` falls back
+ * to the schedule rather than to a wrong wait.
+ *
+ * `maxDelayMs` caps the CEILING, before the draw, so capped waits keep their
+ * jitter: at the cap, equal jitter still spreads between c/2 and c. Capped
+ * after the draw instead, every wait past twice the cap would BE the cap, and
+ * clients refused together would retry in lockstep. A stated wait is never
+ * capped: `statedWaitFirst` hands it back whole.
+ */
+/** How much of an exponential wait is random: none of it, half of it, or all of it. */
+export type BackoffJitter = 'none' | 'equal' | 'full';
+/** The schedule {@link exponentialBackoff} builds a backoff function from. */
+export interface BackoffSpec {
+    /** The ceiling of the first wait (after attempt 1), in milliseconds — a finite number ≥ 0. */
+    readonly baseDelayMs: number;
+    /** How much each ceiling grows over the one before — a finite number ≥ 1. Default `2`. */
+    readonly multiplier?: number;
+    /** How much of each wait is random. Default `'none'`: the wait IS the ceiling. */
+    readonly jitter?: BackoffJitter;
+    /**
+     * The cap on every ceiling, in milliseconds — a number ≥ 0, applied BEFORE
+     * the draw, so capped waits keep their jitter. Default: none.
+     */
+    readonly maxDelayMs?: number;
+    /** The jitter's random source, answering in [0, 1]. Default `Math.random`, taken when built. */
+    readonly random?: () => number;
+}
+/** A `RetryPolicy.backoffMs` function: the wait in milliseconds after failed attempt `attempt` (1-based). */
+export type BackoffFunction = (attempt: number, error?: unknown) => number;
+/** Reads the wait an error states (a parsed `Retry-After`), in milliseconds, or `undefined` when it states none. */
+export type StatedWaitReader = (error: unknown) => number | undefined;
+/**
+ * An exponential schedule: the wait after failed attempt `n` is drawn under
+ * `baseDelayMs × multiplier^(n − 1)` by the declared jitter.
+ *
+ * @throws when built: a `TypeError` for an option of the wrong type, a
+ *   `RangeError` for one out of range — each naming the option.
+ */
+export declare function exponentialBackoff(spec: BackoffSpec): BackoffFunction;
+/**
+ * A wait the outside system stated wins; otherwise `inner` — a backoff
+ * function, or a fixed number of milliseconds — decides.
+ *
+ * @throws when built: a `TypeError` for a reader that is not a function, or an
+ *   `inner` that is neither a function nor a finite number ≥ 0.
+ */
+export declare function statedWaitFirst(readStatedWaitMs: StatedWaitReader, inner: BackoffFunction | number): BackoffFunction;

package/dist/esm/mcp/backoff.js

@@ -0,0 +1,158 @@
+/**
+ * backoff — builders of a `RetryPolicy.backoffMs` function: an exponential
+ * schedule, and a wait the server stated winning over it.
+ *
+ * STAND-IN, TO BE DELETED. footprintjs is adding these two helpers to its
+ * attempt runner (`attempt/backoff.ts`): `exponentialBackoff({ baseDelayMs,
+ * multiplier, jitter, maxDelayMs, random })` and
+ * `statedWaitFirst(readStatedWaitMs, inner)`, with these names, signatures and
+ * laws. Once a footprintjs release
+ * ships them, import them in `throttleRetry.ts` and delete this file; nothing
+ * else changes.
+ *
+ * Pattern: Two pure builders. Each returns `(attempt, error?) => ms`.
+ * Role:    The wait `throttleRetry.ts` plans for each retry.
+ * Emits:   N/A.
+ *
+ * ── THE LAW ──────────────────────────────────────────────────────────────
+ * `exponentialBackoff`: after failed attempt `n` (1-based) the ceiling is
+ *
+ *     c = min(maxDelayMs, baseDelayMs × multiplier^(n − 1))
+ *                                     (saturating at MAX_SAFE_INTEGER)
+ *
+ * and, for `r = random()` in [0, 1]:
+ *
+ *     'none'    c                        `random` is never called
+ *     'equal'   min(c, c/2 + r × c/2)    never below half the ceiling
+ *     'full'    r × c                    anywhere from 0 up to it
+ *
+ * Waits are exact milliseconds — nothing is rounded. `random` defaults to
+ * `Math.random`, taken when the function is BUILT; a fixed source makes a test
+ * exact. A `random()` answering outside [0, 1] throws when asked.
+ *
+ * `statedWaitFirst`: when `readStatedWaitMs(error)` answers a finite number
+ * ≥ 0, that is the wait; otherwise `inner` decides. A reader that throws or
+ * answers anything else states nothing, so a malformed `Retry-After` falls back
+ * to the schedule rather than to a wrong wait.
+ *
+ * `maxDelayMs` caps the CEILING, before the draw, so capped waits keep their
+ * jitter: at the cap, equal jitter still spreads between c/2 and c. Capped
+ * after the draw instead, every wait past twice the cap would BE the cap, and
+ * clients refused together would retry in lockstep. A stated wait is never
+ * capped: `statedWaitFirst` hands it back whole.
+ */
+const JITTERS = ['none', 'equal', 'full'];
+/** Where a ceiling saturates: a wait is never `Infinity` and never `NaN`. */
+const MAX_WAIT_MS = Number.MAX_SAFE_INTEGER;
+/**
+ * An exponential schedule: the wait after failed attempt `n` is drawn under
+ * `baseDelayMs × multiplier^(n − 1)` by the declared jitter.
+ *
+ * @throws when built: a `TypeError` for an option of the wrong type, a
+ *   `RangeError` for one out of range — each naming the option.
+ */
+export function exponentialBackoff(spec) {
+    const { baseDelayMs, multiplier, jitter, maxDelayMs, random } = readSpec(spec);
+    return (attempt) => {
+        // The cap bounds the ceiling, so the draw below still spreads under it.
+        const ceiling = Math.min(maxDelayMs, ceilingOf(baseDelayMs, multiplier, stepOf(attempt)));
+        if (jitter === 'none')
+            return ceiling;
+        const r = draw(random);
+        // Never above the ceiling: halving a subnormal ceiling can round up.
+        return jitter === 'equal' ? Math.min(ceiling, ceiling / 2 + (r * ceiling) / 2) : r * ceiling;
+    };
+}
+/**
+ * A wait the outside system stated wins; otherwise `inner` — a backoff
+ * function, or a fixed number of milliseconds — decides.
+ *
+ * @throws when built: a `TypeError` for a reader that is not a function, or an
+ *   `inner` that is neither a function nor a finite number ≥ 0.
+ */
+export function statedWaitFirst(readStatedWaitMs, inner) {
+    if (typeof readStatedWaitMs !== 'function') {
+        throw new TypeError(`statedWaitFirst: readStatedWaitMs must be a function (got ${shown(readStatedWaitMs)})`);
+    }
+    if (typeof inner !== 'function') {
+        checkNumber('statedWaitFirst: inner', inner, 0, 'a backoff function or a finite number >= 0');
+    }
+    return (attempt, error) => {
+        const stated = statedWaitOf(readStatedWaitMs, error);
+        if (stated !== undefined)
+            return stated;
+        return typeof inner === 'function' ? inner(attempt, error) : inner;
+    };
+}
+/** Each field read once, then checked: what is checked is exactly what the function keeps. */
+function readSpec(spec) {
+    if (spec === null || typeof spec !== 'object') {
+        throw new TypeError(`exponentialBackoff: the spec must be an object ({ baseDelayMs, multiplier?, jitter?, maxDelayMs?, random? }) (got ${shown(spec)})`);
+    }
+    const { baseDelayMs, multiplier = 2, jitter = 'none', maxDelayMs = Infinity, random = Math.random, } = spec;
+    checkNumber('exponentialBackoff: baseDelayMs', baseDelayMs, 0, 'a finite number >= 0');
+    checkNumber('exponentialBackoff: multiplier', multiplier, 1, 'a finite number >= 1');
+    if (typeof maxDelayMs !== 'number') {
+        throw new TypeError(`exponentialBackoff: maxDelayMs must be a number >= 0 (got ${shown(maxDelayMs)})`);
+    }
+    if (!(maxDelayMs >= 0)) {
+        throw new RangeError(`exponentialBackoff: maxDelayMs must be a number >= 0 (got ${shown(maxDelayMs)})`);
+    }
+    if (!JITTERS.includes(jitter)) {
+        throw new RangeError(`exponentialBackoff: jitter must be 'none', 'equal' or 'full' (got ${shown(jitter)})`);
+    }
+    if (typeof random !== 'function') {
+        throw new TypeError(`exponentialBackoff: random must be a function answering in [0, 1] (got ${shown(random)})`);
+    }
+    return { baseDelayMs, multiplier, jitter, maxDelayMs, random };
+}
+/** A finite number ≥ `min`, or the error naming `field`: a `TypeError` for a non-number, else a `RangeError`. */
+function checkNumber(field, value, min, rule) {
+    if (typeof value !== 'number')
+        throw new TypeError(`${field} must be ${rule} (got ${shown(value)})`);
+    if (!Number.isFinite(value) || value < min) {
+        throw new RangeError(`${field} must be ${rule} (got ${shown(value)})`);
+    }
+}
+/** The attempt as a schedule step: its whole part, at least 1 (anything not a finite number reads as 1). */
+function stepOf(attempt) {
+    return typeof attempt === 'number' && Number.isFinite(attempt) && attempt >= 1
+        ? Math.floor(attempt)
+        : 1;
+}
+/** `baseDelayMs × multiplier^(step − 1)`, saturating at {@link MAX_WAIT_MS}. */
+function ceilingOf(baseDelayMs, multiplier, step) {
+    if (baseDelayMs === 0)
+        return 0;
+    const ceiling = baseDelayMs * multiplier ** (step - 1);
+    return ceiling < MAX_WAIT_MS ? ceiling : MAX_WAIT_MS;
+}
+/** One draw from the random source, which must answer a number in [0, 1]. */
+function draw(random) {
+    const r = random();
+    if (typeof r !== 'number' || !(r >= 0 && r <= 1)) {
+        throw new RangeError(`exponentialBackoff: random() must answer a number in [0, 1] (got ${shown(r)})`);
+    }
+    return r;
+}
+/** The wait `error` states, read once — none when the reader throws or answers anything but a finite number ≥ 0. */
+function statedWaitOf(read, error) {
+    let value;
+    try {
+        value = read(error);
+    }
+    catch {
+        return undefined;
+    }
+    return typeof value === 'number' && Number.isFinite(value) && value >= 0 ? value : undefined;
+}
+/** A value as an error message may show it: a number or a short string as itself, anything else by its type. */
+function shown(value) {
+    if (typeof value === 'number')
+        return String(value);
+    if (typeof value === 'string') {
+        return JSON.stringify(value.length > 32 ? `${value.slice(0, 32)}…` : value);
+    }
+    return value === null ? 'null' : typeof value;
+}
+//# sourceMappingURL=backoff.js.map

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

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

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

@@ -0,0 +1,49 @@
+/**
+ * callLifetime — one MCP tool call, from the moment it is sent until it settles:
+ * what cancels it while it runs, and what its settling stops.
+ *
+ * Pattern: open / close around `callTool` (`mcpClient.ts` · `wrapMcpTool`).
+ * Role:    The call's side of the evidence seam (`requestLedger.ts` is the
+ *          transport's). Three things are true of a call while it runs, and
+ *          none of them may outlive it:
+ *
+ *   1. ITS CANCELLATION reaches the SDK. The call's context signal (the run's,
+ *      for a call the agent dispatched) and the client's own `signal` are linked
+ *      into one signal the SDK request is given — so a cancelled run makes the
+ *      SDK reject the call, drop its response handler and send the server
+ *      `notifications/cancelled`, whether or not the request could be matched to
+ *      the call. The link is undone when the call settles: the SDK keeps its
+ *      abort listener on the signal it was given, and a link that outlived the
+ *      call would cancel a request that had already finished.
+ *   2. ITS TICKET is issued, when the call carries the run's evidence port and
+ *      the connection has a ledger, keyed by the request's params object.
+ *   3. ITS SETTLING ENDS ITS SERIES. However `callTool` settles — answered,
+ *      failed, or given up by the SDK (its own timeout) — a retry series still
+ *      sending the request is cut there and then, inside the call: it files
+ *      `cancelled` before the call's result is read, and sends nothing more.
+ *
+ * In dev mode, a ticket that no request was bound to by the time the call
+ * settled, when a `tools/call` request DID go out, is named once per connection: the SDK copied
+ * the params, so the call's attempts could not be matched to it. Its
+ * cancellation still reached the request (1, and the ledger's own watch on
+ * `notifications/cancelled`).
+ */
+import type { RequestLedger } from './requestLedger.js';
+/** A call that has been opened: the signal its SDK request runs under, and how to close it. */
+export interface OpenCall {
+    /** What cancels the SDK request — absent when nothing can. */
+    readonly signal?: AbortSignal;
+    /** The call settled: undo the link, cut a series still sending, check the ticket was bound. */
+    close(): void;
+}
+/**
+ * Open one call.
+ *
+ * @param params the request's params object — the SDK hands this very object to
+ *   the transport, which is how the ledger knows the request is this call's.
+ * @param ctx the call's context: its signal, and the run's evidence port if any.
+ * @param clientSignal the client's own `signal` (`McpClientOptions.signal`).
+ * @param ledger the connection's ledger, when the library built its transport.
+ * @param server the client's name, for the dev-mode note.
+ */
+export declare function openCall(params: object, ctx: unknown, clientSignal: AbortSignal | undefined, ledger: RequestLedger | undefined, server: string): OpenCall;

package/dist/esm/mcp/callLifetime.js

@@ -0,0 +1,99 @@
+/**
+ * callLifetime — one MCP tool call, from the moment it is sent until it settles:
+ * what cancels it while it runs, and what its settling stops.
+ *
+ * Pattern: open / close around `callTool` (`mcpClient.ts` · `wrapMcpTool`).
+ * Role:    The call's side of the evidence seam (`requestLedger.ts` is the
+ *          transport's). Three things are true of a call while it runs, and
+ *          none of them may outlive it:
+ *
+ *   1. ITS CANCELLATION reaches the SDK. The call's context signal (the run's,
+ *      for a call the agent dispatched) and the client's own `signal` are linked
+ *      into one signal the SDK request is given — so a cancelled run makes the
+ *      SDK reject the call, drop its response handler and send the server
+ *      `notifications/cancelled`, whether or not the request could be matched to
+ *      the call. The link is undone when the call settles: the SDK keeps its
+ *      abort listener on the signal it was given, and a link that outlived the
+ *      call would cancel a request that had already finished.
+ *   2. ITS TICKET is issued, when the call carries the run's evidence port and
+ *      the connection has a ledger, keyed by the request's params object.
+ *   3. ITS SETTLING ENDS ITS SERIES. However `callTool` settles — answered,
+ *      failed, or given up by the SDK (its own timeout) — a retry series still
+ *      sending the request is cut there and then, inside the call: it files
+ *      `cancelled` before the call's result is read, and sends nothing more.
+ *
+ * In dev mode, a ticket that no request was bound to by the time the call
+ * settled, when a `tools/call` request DID go out, is named once per connection: the SDK copied
+ * the params, so the call's attempts could not be matched to it. Its
+ * cancellation still reached the request (1, and the ledger's own watch on
+ * `notifications/cancelled`).
+ */
+import { isDevMode } from 'footprintjs';
+import { eitherSignal, linkedController } from '../lib/abort.js';
+import { requestEvidenceOf } from '../tools/requestEvidence.js';
+/**
+ * Open one call.
+ *
+ * @param params the request's params object — the SDK hands this very object to
+ *   the transport, which is how the ledger knows the request is this call's.
+ * @param ctx the call's context: its signal, and the run's evidence port if any.
+ * @param clientSignal the client's own `signal` (`McpClientOptions.signal`).
+ * @param ledger the connection's ledger, when the library built its transport.
+ * @param server the client's name, for the dev-mode note.
+ */
+export function openCall(params, ctx, clientSignal, ledger, server) {
+    const own = signalOf(ctx);
+    const link = own === undefined ? undefined : linkedController(own, clientSignal);
+    const signal = link?.controller.signal ?? clientSignal;
+    const sink = ledger === undefined ? undefined : requestEvidenceOf(ctx);
+    const settled = sink === undefined ? undefined : new AbortController();
+    const ticket = sink === undefined
+        ? undefined
+        : { sink, signal: eitherSignal(signal, settled?.signal) };
+    const sentBefore = ledger?.toolCallsSent ?? 0;
+    if (ticket !== undefined)
+        ledger?.issue(params, ticket);
+    return {
+        ...(signal !== undefined && { signal }),
+        close: () => {
+            settled?.abort(callSettled());
+            link?.unlink();
+            if (ticket !== undefined && ledger !== undefined) {
+                noteUnbound(ledger, ticket, sentBefore, server);
+            }
+        },
+    };
+}
+/** The call's own signal, when its context carries a real one. */
+function signalOf(ctx) {
+    if (ctx === null || typeof ctx !== 'object' || typeof AbortSignal === 'undefined') {
+        return undefined;
+    }
+    let signal;
+    try {
+        signal = ctx.signal;
+    }
+    catch {
+        return undefined;
+    }
+    return signal instanceof AbortSignal ? signal : undefined;
+}
+/** Why a series is cut when its call settled first — a fixed sentence. */
+function callSettled() {
+    return Object.assign(new Error('The tool call settled before its MCP request series did.'), {
+        name: 'AbortError',
+    });
+}
+/** Dev mode, once per connection: a request went out for this call, but the ledger never matched it. */
+function noteUnbound(ledger, ticket, sentBefore, server) {
+    if (!isDevMode() || ledger.wasBound(ticket) || ledger.toolCallsSent <= sentBefore)
+        return;
+    if (!ledger.firstUnbound())
+        return;
+    // eslint-disable-next-line no-console
+    console.warn(`[agentfootprint] mcpClient[${server}]: a tool call's request could not be matched to ` +
+        'the call, so its retry attempts were not recorded in the run. The MCP SDK copied the ' +
+        "request's params before sending them. The call itself is unaffected, and its " +
+        'cancellation still reached the request.');
+}
+//# sourceMappingURL=callLifetime.js.map

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

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

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

@@ -33,7 +33,10 @@
  *          `agentfootprint.stream.tool_start` / `tool_end` events
  *          when the agent calls them. Add `name: '<mcp-server>'` to
  *          `McpClientOptions` so observability surfaces can group
- *          tool calls by server.
+ *          tool calls by server. On a transport this module builds,
+ *          a call the agent dispatched also gets its request's retry
+ *          series as `agentfootprint.tools.request_attempts`, filed by
+ *          the series through the call's own port (`requestLedger.ts`).
  *
  * Lazy-require pattern: the `@modelcontextprotocol/sdk` peer-dep
  * loads only when a consumer actually constructs a client. Tests

package/dist/esm/mcp/mcpClient.js

@@ -33,7 +33,10 @@
  *          `agentfootprint.stream.tool_start` / `tool_end` events
  *          when the agent calls them. Add `name: '<mcp-server>'` to
  *          `McpClientOptions` so observability surfaces can group
- *          tool calls by server.
+ *          tool calls by server. On a transport this module builds,
+ *          a call the agent dispatched also gets its request's retry
+ *          series as `agentfootprint.tools.request_attempts`, filed by
+ *          the series through the call's own port (`requestLedger.ts`).
  *
  * Lazy-require pattern: the `@modelcontextprotocol/sdk` peer-dep
  * loads only when a consumer actually constructs a client. Tests
@@ -42,7 +45,9 @@
 import { callMetaOf, readToolExtras } from './toolExtras.js';
 import { readToolResult, resultModeOf } from './toolResult.js';
 import { createVendingFetch } from './gatewayTransport.js';
-import { retryingFetch } from './throttleRetry.js';
+import { ledgeredFetch, retryingFetch } from './throttleRetry.js';
+import { RequestLedger } from './requestLedger.js';
+import { openCall } from './callLifetime.js';
 import { refuseConflictingOptions } from './connectionRefusals.js';
 import { sdkLoadFailure } from './sdkLoadFailure.js';
 import { transportUrl } from './transportUrl.js';
@@ -82,7 +87,7 @@ export async function mcpClient(opts) {
     // Before anything connects: an option that names a behaviour which cannot
     // happen on the chosen arm is a defect, not a preference.
     refuseConflictingOptions(opts, name);
-    const connection = await openConnection(opts);
+    const { connection, ledger } = await openConnection(opts);
     // Tool cache so consumers calling `.tools()` more than once don't
     // hammer the server. `.refresh()` invalidates it.
     let cache = null;
@@ -98,7 +103,7 @@ export async function mcpClient(opts) {
         const listed = opts.signal
             ? await connection.listTools(undefined, { signal: opts.signal })
             : await connection.listTools();
-        return listed.tools.map((t) => wrapMcpTool(name, connection, t, opts.signal, resultMode));
+        return listed.tools.map((t) => wrapMcpTool(name, connection, t, opts.signal, resultMode, ledger));
     };
     return {
         name,
@@ -122,19 +127,20 @@ export async function mcpClient(opts) {
         },
     };
 }
-// ─── Getting a connection ──────────────────────────────────────────
 /**
  * The one funnel every arm passes through, in precedence order: a connection
  * you handed over, the internal test seam, then the library building one.
+ * Only the last has a ledger: a connection built elsewhere has no retry series
+ * of ours to file a call's attempts.
  *
  * A call with neither `connection` nor `sdk` reaches `resolveClient` with two
  * `undefined` arguments and takes the identical path it always took.
  */
 async function openConnection(opts) {
     if (opts.connection !== undefined)
-        return opts.connection;
+        return { connection: opts.connection };
     if (opts._client !== undefined)
-        return opts._client;
+        return { connection: opts._client };
     // `refuseConflictingOptions` has already refused the case where this is
     // absent, so the assertion documents that guarantee rather than assuming it.
     const transport = opts.transport;
@@ -148,13 +154,13 @@ async function resolveClient(transport, clientInfo, signal, retryOnThrottle, sdk
     const client = new mod.Client(clientInfo ?? DEFAULT_CLIENT_INFO, {
         capabilities: {},
     });
-    const transportImpl = await buildTransport(transport, retryOnThrottle, sdk);
+    const built = await buildTransport(transport, retryOnThrottle, sdk);
     // Same rule as callTool: options ride beside the transport, never inside it.
     if (signal)
-        await client.connect(transportImpl, { signal });
+        await client.connect(built.transport, { signal });
     else
-        await client.connect(transportImpl);
-    return client;
+        await client.connect(built.transport);
+    return { connection: client, ...(built.ledger !== undefined && { ledger: built.ledger }) };
 }
 /**
  * An injected `sdk` is checked before anything is built, so a wrong import (a
@@ -218,12 +224,15 @@ async function buildTransport(t, retryOnThrottle, sdk) {
                     "reach the server over `transport: { transport: 'http', url }` instead.",
             }));
         }
-        return new stdioMod.StdioClientTransport({
-            command: t.command,
-            args: t.args ? [...t.args] : [],
-            ...(t.env && { env: { ...t.env } }),
-            ...(t.cwd !== undefined && { cwd: t.cwd }),
-        });
+        // No fetch, so no retry series: a stdio call has no attempts to file.
+        return {
+            transport: new stdioMod.StdioClientTransport({
+                command: t.command,
+                args: t.args ? [...t.args] : [],
+                ...(t.env && { env: { ...t.env } }),
+                ...(t.cwd !== undefined && { cwd: t.cwd }),
+            }),
+        };
     }
     // http + gateway transports both ride Streamable HTTP. They differ only in
     // WHEN the auth headers are decided: `http` fixes them at construction,
@@ -234,7 +243,15 @@ async function buildTransport(t, retryOnThrottle, sdk) {
     // the wait is simply never the one reused. `retryingFetch` returns its input
     // untouched when retry is off — including `undefined`, so a plain `http`
     // transport with no custom fetch still passes none and behaves exactly as it
-    // did before 8.11.0.
+    // did before 8.11.0. A transport fetch that already runs a retry series of
+    // its own (AgentCore Runtime's) is never wrapped: `retryingFetch` joins the
+    // 429 rule to that series, so one call is one series.
+    //
+    // The ledger joins the same series, so each request a dispatched tool call
+    // sends files its attempts into that call's run; the transport's `send` is
+    // watched to bind each request to its call (`requestLedger.ts`). A fetch that
+    // runs no series (retry off) gets no ledger: there is nothing to file.
+    const ledger = new RequestLedger();
     if (t.transport === 'gateway') {
         // The consumer's own `fetch` (9.32.0) goes UNDERNEATH the vending, not
         // beside it: `createVendingFetch` resolves the credential, applies it to
@@ -243,19 +260,34 @@ async function buildTransport(t, retryOnThrottle, sdk) {
         // credential is still vended per request. Passing `undefined` is the
         // default global `fetch`, which is byte-identical to every release before
         // the seam existed.
-        return new httpMod.StreamableHTTPClientTransport(transportUrl(t.url, 'mcpClient'), {
-            fetch: retryingFetch(createVendingFetch(t, t.fetch), retryOnThrottle),
-        });
+        const gatewayFetch = retryingFetch(createVendingFetch(t, t.fetch), retryOnThrottle);
+        const ledgered = gatewayFetch && ledgeredFetch(gatewayFetch, ledger);
+        return watched(new httpMod.StreamableHTTPClientTransport(transportUrl(t.url, 'mcpClient'), {
+            fetch: ledgered ?? gatewayFetch,
+        }), ledgered && ledger);
     }
     // Both options ride the SAME SDK transport, and both are forwarded when both
     // are given. The SDK folds `requestInit.headers` into the `init.headers` it
     // hands the custom fetch, so a signer sees the static headers and has the
     // final word over the bytes — see `McpHttpTransport.fetch`.
     const httpFetch = retryingFetch(t.fetch, retryOnThrottle);
-    return new httpMod.StreamableHTTPClientTransport(transportUrl(t.url, 'mcpClient'), {
+    const ledgered = httpFetch && ledgeredFetch(httpFetch, ledger);
+    const fetch = ledgered ?? httpFetch;
+    return watched(new httpMod.StreamableHTTPClientTransport(transportUrl(t.url, 'mcpClient'), {
         ...(t.headers && { requestInit: { headers: { ...t.headers } } }),
-        ...(httpFetch && { fetch: httpFetch }),
-    });
+        ...(fetch && { fetch }),
+    }), ledgered && ledger);
+}
+/**
+ * `transport` with its sends watched by `ledger` — the SAME object, its own
+ * `send` installed in place. As it is, with no ledger, when there is none or it
+ * cannot be watched: then no call expects its attempts filed.
+ */
+function watched(transport, ledger) {
+    if (ledger === undefined || transport === null || typeof transport !== 'object') {
+        return { transport };
+    }
+    return ledger.watch(transport) === undefined ? { transport } : { transport, ledger };
 }
 /** The Node loader path for Streamable HTTP — reached only with no `sdk`. */
 function loadHttpModule(transport) {
@@ -275,7 +307,7 @@ function loadHttpModule(transport) {
     }
 }
 // ─── Tool wrapping ─────────────────────────────────────────────────
-function wrapMcpTool(serverName, connection, mcp, signal, resultMode) {
+function wrapMcpTool(serverName, connection, mcp, signal, resultMode, ledger) {
     const tool = {
         schema: {
             name: mcp.name,
@@ -316,10 +348,22 @@ function wrapMcpTool(serverName, connection, mcp, signal, resultMode) {
                 arguments: argsObj,
                 ...(ctx?.time !== undefined && { _meta: callMetaOf(ctx.time) }),
             };
-            const result = signal
-                ? await connection.callTool(params, undefined, { signal })
-                : await connection.callTool(params);
-            return readToolResult(result, mcp.name, serverName, resultMode);
+            // The call's lifetime (`callLifetime.ts`): its context's signal and the
+            // client's cancel the SDK request while it runs; a call the agent
+            // dispatched issues a ticket keyed by THIS params object — the one the
+            // SDK hands the transport — so the retry series that sends it files its
+            // attempts into the call's run; and however the call settles, a series
+            // still sending is cut, inside the call. Nothing is added to the request.
+            const call = openCall(params, ctx, signal, ledger, serverName);
+            try {
+                const result = call.signal
+                    ? await connection.callTool(params, undefined, { signal: call.signal })
+                    : await connection.callTool(params);
+                return readToolResult(result, mcp.name, serverName, resultMode);
+            }
+            finally {
+                call.close();
+            }
         },
     };
     return tool;