agentfootprint 11.1.1 → 11.3.0

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

@@ -0,0 +1,98 @@
+/**
+ * requestLedger — which dispatched tool call an MCP request belongs to, so the
+ * retry series that sends it files its attempts into THAT call's run; and when
+ * the MCP SDK cancels a request, so the series sending it stops.
+ *
+ * Pattern: a per-connection ledger + the SDK transport's `send`, watched in place.
+ * Role:    The middle of the evidence seam (`tools/requestEvidence.ts` is its
+ *          door). The retry series runs inside the transport's `fetch`, which
+ *          the MCP SDK calls with a serialized body and nothing else — no tool
+ *          call, no run. Three hops carry the call down to it, each by an
+ *          identity the hop already holds:
+ *
+ *   1. call → params    `issue`: the MCP tool keys its ticket by the request's
+ *                       params OBJECT. The SDK puts that very object into the
+ *                       JSON-RPC message it hands the transport.
+ *   2. params → id      the watched `send` finds the ticket by `message.params`
+ *                       and keys it by the JSON-RPC `id` the SDK assigned, until
+ *                       that send settles.
+ *   3. id → series      `claim`: the series reads the `id` back out of the body
+ *                       it is about to send.
+ *
+ * CANCELLATION DOES NOT WAIT ON ATTRIBUTION. Every `tools/call` in flight gets
+ * an entry, ticket or not, and the SDK says when it gives a request up: it sends
+ * `notifications/cancelled` naming the request's id — on its own timeout, or
+ * when the call's signal fires — through this same `send`. The ledger aborts
+ * that request's series there and then, so a request nobody waits for is never
+ * asked again, even when its params could not be matched to a call.
+ *
+ * Nothing is added to the wire: the request the server receives is
+ * byte-identical, and the SDK's own options keep their meanings. Ids are the
+ * client's, one ledger per connection, so concurrent calls — and concurrent
+ * runs sharing one client — can never claim each other's request. A request
+ * that is not a `tools/call` (a `tools/list`, a notification, a response)
+ * claims nothing.
+ *
+ * `send` is installed as an OWN property of the transport instance — the same
+ * object, its own `send` bound to it, so a transport class with `#private`
+ * fields works as it always did. Assigning `send` again afterwards THROWS: a
+ * send that bypassed the ledger would quietly lose every call's attempts.
+ *
+ * What it does NOT do: retry, wait, or decide anything. The series is the one
+ * retry owner; this only tells it whose attempts it is making, and when the SDK
+ * has stopped waiting for them.
+ */
+import type { RequestEvidenceSink } from '../tools/requestEvidence.js';
+/** One call's claim on the request it sends. */
+export interface RequestTicket {
+    /** Where the request's attempts are filed. */
+    readonly sink: RequestEvidenceSink;
+    /** What cancels the call's series — the call's own signal, the client's, the call settling. */
+    readonly signal?: AbortSignal;
+}
+/** What a series claims for the `tools/call` request it sends. */
+export interface ClaimedRequest {
+    /** The ticket a dispatched call issued for this request — absent when none was matched. */
+    readonly ticket?: RequestTicket;
+    /** Fires when the MCP SDK cancels this request (`notifications/cancelled`). */
+    readonly cancelled: AbortSignal;
+}
+/** Per connection: the tickets issued and not yet sent, and the requests being sent. */
+export declare class RequestLedger {
+    /** Issued, not yet sent — keyed by the request's params object. Collected with it. */
+    private readonly issued;
+    /** Tickets a request was bound to. */
+    private readonly bound;
+    /** Every `tools/call` sent and not yet settled — keyed by its JSON-RPC id. */
+    private readonly sending;
+    private calls;
+    private unboundNamed;
+    /** The call about to send `params` files its attempts through `ticket`. */
+    issue(params: object, ticket: RequestTicket): void;
+    /** Whether a request the transport sent was bound to `ticket`. */
+    wasBound(ticket: RequestTicket): boolean;
+    /** How many `tools/call` requests the watched transport has sent — matched to a call or not. */
+    get toolCallsSent(): number;
+    /** `true` the first time it is asked, then never again: an unmatched request is named once per connection. */
+    firstUnbound(): boolean;
+    /**
+     * Watch `transport`'s `send`: install a wrapped `send` as its OWN property, the
+     * original bound to the instance itself. Returns the SAME object — or
+     * `undefined` when it has no `send` to watch or refuses the property, and
+     * then nothing is watched and no call should expect its attempts filed.
+     */
+    watch<T extends object>(transport: T): T | undefined;
+    /**
+     * The `tools/call` request `body` carries, while its send runs — its ticket
+     * when a call issued one, and the signal its cancellation fires. `undefined`
+     * for any other body. Parses only while some request is being sent.
+     */
+    claim(body: unknown): ClaimedRequest | undefined;
+    /** One message through the watched transport. */
+    private send;
+    /** Register a `tools/call` in flight, with the ticket its params were issued — if any. */
+    private bind;
+    /** The SDK gave a request up: stop the series still sending it. */
+    private cancelIfAsked;
+}
+//# sourceMappingURL=requestLedger.d.ts.map

package/dist/types/mcp/requestLedger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"requestLedger.d.ts","sourceRoot":"","sources":["../../../src/mcp/requestLedger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAEvE,gDAAgD;AAChD,MAAM,WAAW,aAAa;IAC5B,8CAA8C;IAC9C,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAC;IACnC,+FAA+F;IAC/F,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;CAC/B;AAED,kEAAkE;AAClE,MAAM,WAAW,cAAc;IAC7B,2FAA2F;IAC3F,QAAQ,CAAC,MAAM,CAAC,EAAE,aAAa,CAAC;IAChC,+EAA+E;IAC/E,QAAQ,CAAC,SAAS,EAAE,WAAW,CAAC;CACjC;AAgBD,wFAAwF;AACxF,qBAAa,aAAa;IACxB,sFAAsF;IACtF,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAwC;IAC/D,sCAAsC;IACtC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAgC;IACtD,8EAA8E;IAC9E,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAkC;IAC1D,OAAO,CAAC,KAAK,CAAK;IAClB,OAAO,CAAC,YAAY,CAAS;IAE7B,2EAA2E;IAC3E,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,aAAa,GAAG,IAAI;IAIlD,kEAAkE;IAClE,QAAQ,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO;IAIxC,gGAAgG;IAChG,IAAI,aAAa,IAAI,MAAM,CAE1B;IAED,8GAA8G;IAC9G,YAAY,IAAI,OAAO;IAMvB;;;;;OAKG;IACH,KAAK,CAAC,CAAC,SAAS,MAAM,EAAE,SAAS,EAAE,CAAC,GAAG,CAAC,GAAG,SAAS;IAwBpD;;;;OAIG;IACH,KAAK,CAAC,IAAI,EAAE,OAAO,GAAG,cAAc,GAAG,SAAS;IAiBhD,iDAAiD;IACjD,OAAO,CAAC,IAAI;IAgBZ,0FAA0F;IAC1F,OAAO,CAAC,IAAI;IAgBZ,mEAAmE;IACnE,OAAO,CAAC,aAAa;CAQtB"}

package/dist/types/mcp/seriesEvidence.d.ts

@@ -0,0 +1,103 @@
+/**
+ * seriesEvidence — one MCP request's retry series, written down for its run.
+ *
+ * Pattern: a collector over footprintjs's attempt records, filed once.
+ * Role:    The series (`throttleRetry.ts` · `Series`) is the one retry owner and
+ *          the attempt runner makes one record per try; this turns each record
+ *          into an allow-listed row and files the request's whole story — its
+ *          rows, how many were not listed, and how it ended — to the call's sink
+ *          (`tools/requestEvidence.ts`) exactly ONCE.
+ *
+ * WHAT A ROW MAY SAY. Numbers and the library's own words; never the server's
+ * answer, the call's arguments or an error's text. A failure is a fixed sentence
+ * and its category — a network or SDK error message can carry a URL with a token
+ * in it, a host's internal name or a server's reply.
+ *
+ * A RESPONSE IS NOT A SUCCESS. The runner records an attempt that returned a
+ * response as `ok` with the reason `succeeded`; here it is `answered`, with the
+ * status the server sent — a 503 delivered is `answered` + `503`, never success.
+ *
+ * EVERY REQUEST SENT IS COUNTED. Each attempt the series started is a row — or,
+ * past the cap, one more in `omitted` — so `rows + omitted` is the number of
+ * requests the series sent. An attempt a cancellation cuts in flight is a row
+ * too (`cut`), exactly as an attempt the deadline cuts is (`timed-out`). A
+ * request the series never sent — the next one after a cancelled wait — has no
+ * row.
+ *
+ * A CUT IS NOT A "NOT RUN". An attempt that ended without an answer — cut,
+ * timed out, or failed — was sent, and the server may have received it and run
+ * it. Its row says so (`remote: 'unknown'`); nothing here records it as not run.
+ *
+ * WHEN IT FILES. When the series ends — and, for a cancellation, at the moment the
+ * signal fires: a cancelled run stops waiting for its stage at once, so a record
+ * filed when the series later unwinds would land after the run was saved. The
+ * runner makes no record for an attempt it abandons at that moment or for a wait
+ * it was cut out of, so those are written here: the cut attempt's row and
+ * `during: 'request'`, or `during: 'wait'`. Anything the series reports after it
+ * has filed is not part of the request's story any more and is ignored.
+ */
+import type { AttemptRecord } from 'footprintjs';
+import type { ToolRequestAttempt, ToolRequestReason } from '../events/payloads.js';
+import { type RequestEvidence, type RequestEvidenceSink } from '../tools/requestEvidence.js';
+/** Where the request went, as a row may say it: the app's label for it, or its origin. */
+export type RequestWhere = Pick<RequestEvidence, 'endpoint' | 'origin'>;
+/** What the series saw of one attempt that its record does not hold. */
+export interface AttemptSeen {
+    /** The response's status, when a response arrived. */
+    readonly status?: number;
+    /** The refusal a rule recognised in that response, when one did. */
+    readonly refusal?: {
+        readonly kind: 'throttle' | 'session-busy';
+        readonly retryAfterMs?: number;
+    };
+}
+/** Why the series' `retryOn` said no — the reasons the runner calls `declined`. */
+export type DeclineReason = Extract<ToolRequestReason, 'exhausted' | 'wait-limit' | 'no-time-left' | 'not-replayable' | 'not-retryable'>;
+/** One request's evidence, collected as its series runs and filed once. */
+export declare class SeriesEvidence {
+    private readonly sink;
+    private readonly where;
+    private readonly rows;
+    private omitted;
+    private last;
+    private filed;
+    constructor(sink: RequestEvidenceSink, where: RequestWhere);
+    /** One attempt as the runner recorded it. */
+    attempt(record: AttemptRecord, seen: AttemptSeen | undefined, declined?: DeclineReason): void;
+    /**
+     * The caller's cancellation cut attempt `n` in flight. It was sent — the
+     * server may have it, and may have run it — so it is a row, `cut`, with the
+     * remote outcome `unknown`; then the request's end says the same.
+     */
+    cutInFlight(n: number): void;
+    /**
+     * The caller's cancellation landed with NO request in flight: between two —
+     * `during: 'wait'`, the next request never sent — or before the first, when
+     * nothing was sent and there is no `during`. No row is added: there is no
+     * request to account for. A request that had already ended keeps its end.
+     */
+    cancelled(): void;
+    /**
+     * The series delivered a response. It is the last attempt's — an answer, or a
+     * refusal it will not ask again after. A refusal it MEANT to ask again after
+     * is delivered when the deadline lands inside the wait: the runner's wait
+     * ends early, the series stops, and the end says so (`no-time-left`, during
+     * the `wait`).
+     */
+    delivered(): void;
+    /**
+     * The series threw. The end is the last attempt's when that attempt ended it
+     * (a failure, a timed-out request). The rest is defensive — footprintjs 10.6's
+     * runner never throws without a record but for a cancellation, which is filed
+     * as one: a deadline that had passed before the first request (`timed-out`,
+     * no `during`, nothing sent) or one a future runner reports from inside a wait
+     * (`during: 'wait'`); anything else is filed as a failure the record cannot
+     * account for, so a request is never left unfiled.
+     */
+    threw(outOfTime: boolean): void;
+    private add;
+    private file;
+}
+/** One record as a row — see the module note for what a row may say. */
+export declare function rowOf(record: AttemptRecord, seen: AttemptSeen | undefined, declined?: DeclineReason): ToolRequestAttempt;
+//# sourceMappingURL=seriesEvidence.d.ts.map

package/dist/types/mcp/seriesEvidence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"seriesEvidence.d.ts","sourceRoot":"","sources":["../../../src/mcp/seriesEvidence.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEjD,OAAO,KAAK,EACV,kBAAkB,EAGlB,iBAAiB,EAClB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAEL,KAAK,eAAe,EACpB,KAAK,mBAAmB,EACzB,MAAM,6BAA6B,CAAC;AAErC,0FAA0F;AAC1F,MAAM,MAAM,YAAY,GAAG,IAAI,CAAC,eAAe,EAAE,UAAU,GAAG,QAAQ,CAAC,CAAC;AAExE,wEAAwE;AACxE,MAAM,WAAW,WAAW;IAC1B,sDAAsD;IACtD,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,oEAAoE;IACpE,QAAQ,CAAC,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,UAAU,GAAG,cAAc,CAAC;QAAC,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CACnG;AAED,mFAAmF;AACnF,MAAM,MAAM,aAAa,GAAG,OAAO,CACjC,iBAAiB,EACjB,WAAW,GAAG,YAAY,GAAG,cAAc,GAAG,gBAAgB,GAAG,eAAe,CACjF,CAAC;AAOF,2EAA2E;AAC3E,qBAAa,cAAc;IAMb,OAAO,CAAC,QAAQ,CAAC,IAAI;IAAuB,OAAO,CAAC,QAAQ,CAAC,KAAK;IAL9E,OAAO,CAAC,QAAQ,CAAC,IAAI,CAA4B;IACjD,OAAO,CAAC,OAAO,CAAK;IACpB,OAAO,CAAC,IAAI,CAAiC;IAC7C,OAAO,CAAC,KAAK,CAAS;gBAEO,IAAI,EAAE,mBAAmB,EAAmB,KAAK,EAAE,YAAY;IAE5F,6CAA6C;IAC7C,OAAO,CAAC,MAAM,EAAE,aAAa,EAAE,IAAI,EAAE,WAAW,GAAG,SAAS,EAAE,QAAQ,CAAC,EAAE,aAAa,GAAG,IAAI;IAK7F;;;;OAIG;IACH,WAAW,CAAC,CAAC,EAAE,MAAM,GAAG,IAAI;IAM5B;;;;;OAKG;IACH,SAAS,IAAI,IAAI;IAajB;;;;;;OAMG;IACH,SAAS,IAAI,IAAI;IAajB;;;;;;;;OAQG;IACH,KAAK,CAAC,SAAS,EAAE,OAAO,GAAG,IAAI;IAmB/B,OAAO,CAAC,GAAG;IAMX,OAAO,CAAC,IAAI;CASb;AAcD,wEAAwE;AACxE,wBAAgB,KAAK,CACnB,MAAM,EAAE,aAAa,EACrB,IAAI,EAAE,WAAW,GAAG,SAAS,EAC7B,QAAQ,CAAC,EAAE,aAAa,GACvB,kBAAkB,CAqBpB"}

package/dist/types/mcp/throttleRetry.d.ts

@@ -1,5 +1,6 @@
 /**
- * throttleRetry — when an MCP server says "too many requests", wait and ask again.
+ * throttleRetry — when an MCP server refuses a request with a response the
+ * retry policy recognises (HTTP 429), wait and ask again.
  *
  * ── Why this exists ──────────────────────────────────────────────────────────
  * Managed MCP gateways enforce per-principal rate limits. A throttled
@@ -9,20 +10,24 @@
  * tool, or invents an answer. A designed, transient, self-clearing condition
  * was being turned into a wrong answer.
  *
- * ── Why retrying a 429 is safe, and why the policy is 429-ONLY ───────────────
- * **A 429 is a pre-execution rejection.** The rate limiter refused the request
- * at the edge; the server never ran the tool. Retrying therefore cannot
- * double-execute anything — which is exactly what is NOT true of a 500 or a
+ * ── What retrying a 429 assumes, and why the policy is 429-ONLY ─────────────
+ * **Automatic 429 retries assume the server rejected the request before
+ * executing it.** A rate limiter that refuses at the edge has not run the tool —
+ * but HTTP 429 says only that the request was rate-limited (RFC 6585 §4), so the
+ * saved response records the assumption's basis (the server's 429), not proof
+ * that nothing ran. There is no side-effect guard here: a tool with side
+ * effects is retried on 429 like any other today, and `retryOnThrottle: false`
+ * turns that off per server. What is certain is the contrast with a 500 or a
  * timeout, where the call may have half-run and a retry could charge a card
  * twice.
  *
- * That asymmetry is the whole license for this module, so the policy must never
- * widen. Only HTTP 429 retries here. Not 5xx, not network errors, not timeouts
+ * That assumption is the whole license for this module, so the policy must
+ * never widen. Only HTTP 429 retries here. Not 5xx, not network errors, not timeouts
  * — those belong to a caller who knows whether the specific tool is idempotent,
  * and this seam does not. A property test pins the boundary.
  *
  * The loop takes its question as a {@link RetryDecision}, so the one other
- * refusal a service DOCUMENTS as pre-execution — AgentCore Runtime's "session
+ * refusal a service documents as one to retry — AgentCore Runtime's "session
  * operation in progress" — reuses this loop rather than growing a second one.
  * That decision is applied only by that vendor's own transport; what
  * `mcpClient` and `retryingFetch` retry is still a 429 and nothing else.
@@ -43,8 +48,49 @@
  * that would have died during the wait is simply never the one reused. The
  * gateway secrecy invariant is untouched: each attempt vends, applies, drops.
  *
+ * ── The loop is footprintjs's attempt runner, one series per call ────────────
+ * Each call runs ONE `attempt()` series (footprintjs, used as it ships). Its
+ * runner makes an attempt record per try. `onRetry`, before each wait, is what
+ * reaches a caller; the RUN gets the records: for a call the agent dispatched,
+ * the series files every attempt and how the request ended into that call's
+ * run (`seriesEvidence.ts`, through the connection's `requestLedger.ts`). An
+ * attempt sends the request once, and an attempt that got a RESPONSE is not an
+ * operation that succeeded: a 503 is delivered as the answer it was, never
+ * retried — and written down as `answered` with its status, never success.
+ * A response a rule's decision recognises is thrown as a refusal that names
+ * its kind, and the policy's `retryOn` accepts those refusals and nothing
+ * else — so a 5xx, a dropped connection or a timeout ends the series on the
+ * attempt it happened in, as it always did. When the
+ * series ends on a refusal (attempts spent, a ceiling reached, no time left),
+ * the refusal's response is delivered as the server sent it: the caller sees
+ * the 429, never an error of ours.
+ *
+ * ── A fetch that already retries is JOINED, never wrapped ────────────────────
+ * A transport whose own fetch runs a series (AgentCore Runtime's session-busy
+ * retry) says how to rebuild itself with one more rule (`joinableRetry`).
+ * `retryingFetch` over such a fetch — what `mcpClient` applies to every http
+ * transport — adds its 429 rule to THAT series instead of starting a second
+ * one around it. One series means one attempt count, one waiting total and one
+ * deadline per call, by construction: the layers can never multiply requests.
+ * The series' FIRST rule holds the call's budget — its `maxAttempts`,
+ * `maxWaitMs` and `maxElapsedMs` bound every attempt and wait, whatever the
+ * reason. A rule that joins keeps its own values as limits on its own kind:
+ * they can stop its retries sooner, never make the call longer.
+ *
+ * ── The wait: a stated one wins, whole ───────────────────────────────────────
+ * Each retry's wait is `statedWaitFirst(retry-after, exponentialBackoff({ …,
+ * maxDelayMs }))`: the server's `Retry-After` when it sent one, else our
+ * jittered backoff, whose CEILING is capped at `maxDelayMs` before the draw
+ * (so capped waits keep their jitter). The cap is on the SCHEDULE only —
+ * never on a stated wait — so the footprintjs policy's `maxBackoffMs`,
+ * which would cut every wait and send the request again before the server
+ * said it may, is left unset. A stated wait too long for `maxWaitMs` or the
+ * deadline is never shortened either: the series stops, and the 429 is
+ * delivered as the server sent it.
+ *
  * Pattern: Decorator over `fetch`. Role: Layer-3 tool transport.
  */
+import type { RequestLedger } from './requestLedger.js';
 /**
  * The fetch shape the MCP SDK's `fetch` hook uses — deliberately NARROWER
  * than `gatewayTransport`'s `FetchLike` (no `Request` input), because that is
@@ -54,22 +100,50 @@
  * supplies fewer.
  */
 export type ThrottleFetch = (input: string | URL, init?: RequestInit) => Promise<Response>;
+/**
+ * Which refusal a retry answers: HTTP 429 (`'throttle'`), or AgentCore
+ * Runtime's "session operation in progress" (`'session-busy'`).
+ */
+export type RetryKind = 'throttle' | 'session-busy';
 /** Reported to {@link ThrottleRetryOptions.onRetry} before each wait. */
 export interface ThrottleRetryInfo {
+    /** Which refusal this retry answers. */
+    readonly kind: RetryKind;
     /** The attempt about to START. `2` is the first retry. */
     readonly attempt: number;
-    /** Ceiling in force for this call, including the first attempt. */
+    /** Ceiling in force for this refusal, including the first attempt. */
     readonly maxAttempts: number;
     /** How long we are about to wait, in milliseconds. */
     readonly waitMs: number;
     /** What the server's `Retry-After` asked for, when it sent one. Absent
      *  means the wait below is our own jittered backoff. */
     readonly retryAfterMs?: number;
-    /** The endpoint being retried. Carries no credential: the URL is the URL
-     *  the transport was built with, never a signed or tokenised variant. */
+    /**
+     * The ORIGIN of the endpoint being retried — scheme, host and port, nothing
+     * else. Never its path, user info (`user:pass@`), query or fragment: a
+     * token, a credential or a customer id can ride in any of them. The empty
+     * string when the URL has no origin (a relative one).
+     */
     readonly url: string;
+    /**
+     * The {@link ThrottleRetryOptions.endpointLabel} you declared for this
+     * endpoint — absent when you declared none. Never derived from the URL.
+     */
+    readonly endpoint?: string;
 }
-/** Fine-tuning for {@link McpClientOptions.retryOnThrottle}. */
+/**
+ * Fine-tuning for {@link McpClientOptions.retryOnThrottle}, and — with its own
+ * defaults — for `agentCoreRuntimeMcpTransport`'s `retry`. The defaults below
+ * are `retryOnThrottle`'s.
+ *
+ * Every limit here is the CALL's — unless this retry joins a series a
+ * transport already runs (an AgentCore Runtime transport under `mcpClient`).
+ * Then the transport's own values are the call's limits, and these limit only
+ * the 429 retries inside them: each can stop a 429 retry sooner (a 429 is
+ * retried only while the call has made fewer attempts than `maxAttempts`, has
+ * waited less than `maxWaitMs`, …), never make the call longer. The deadline
+ * that cuts a request in flight is the transport's `maxElapsedMs`.
+ */
 export interface ThrottleRetryOptions {
     /** Total attempts including the first. Default 3. Minimum 1. */
     readonly maxAttempts?: number;
@@ -84,15 +158,65 @@ export interface ThrottleRetryOptions {
      */
     readonly maxWaitMs?: number;
     /**
-     * Called before each wait. The per-attempt visibility hook, matching the
-     * contract `withRetry` and `withCredentialRetry` already use — a decorator
-     * at a transport boundary reports to its consumer, and emits no events of
-     * its own.
+     * A deadline for the whole call, in milliseconds from its start — requests
+     * included, not just waits. A wait that would end past it is never begun
+     * (the refusal is delivered at once), and a request still waiting for its
+     * answer when it passes is cut: the call fails with the deadline's error.
+     * Default: none — `maxWaitMs` is the default rail.
+     */
+    readonly maxElapsedMs?: number;
+    /**
+     * The ceiling of the first wait our own backoff draws, in milliseconds, when
+     * the server stated none. Default 200.
+     */
+    readonly baseDelayMs?: number;
+    /** How much each backoff ceiling grows over the last. Default 2. At least 1. */
+    readonly multiplier?: number;
+    /**
+     * How a backoff wait is drawn below its ceiling: `'equal'` (the default)
+     * waits between half the ceiling and all of it, `'full'` anywhere from zero
+     * up to it, `'none'` exactly it. Jitter is what keeps clients refused at the
+     * same moment from asking again at the same moment.
+     */
+    readonly jitter?: 'none' | 'equal' | 'full';
+    /**
+     * The most one of OUR backoff waits may last, in milliseconds. Default: none.
+     *
+     * It caps the scheduled wait's ceiling before the jittered draw, so capped
+     * waits still spread between half the cap and the cap. It never caps a
+     * server's `Retry-After` — unlike footprintjs's `RetryPolicy.maxBackoffMs`,
+     * which caps every wait. A stated wait is waited whole; asking sooner than
+     * the server said would only spend an attempt on a refusal it announced.
+     */
+    readonly maxDelayMs?: number;
+    /**
+     * A name for this endpoint, declared by you, that `onRetry` reports as
+     * `endpoint` — so a log line can say which server was retried without
+     * carrying any part of its URL past the origin. A dispatched call's saved
+     * attempts name the endpoint by it too, in place of the origin. 1–128
+     * characters, none of them control characters. Absent, `onRetry` has no
+     * `endpoint` field; the library never makes one up from the URL.
+     */
+    readonly endpointLabel?: string;
+    /**
+     * A notification before each wait. It is told the refusal's kind, the
+     * attempt about to start, the wait, the endpoint's origin and the label you
+     * declared for it (`endpointLabel`) — never the URL's path, the request's
+     * arguments or the server's answer. It is not told how the call ended. The
+     * contract matches what `withRetry` and `withCredentialRetry` already use: a
+     * decorator at a transport boundary reports to its consumer.
+     *
+     * What the RUN keeps is separate and needs no hook: for a call the agent
+     * dispatched, the series files every attempt — its outcome, its reason, its
+     * wait — and how the request ended, as `agentfootprint.tools.request_attempts`
+     * (the label is reported there as `endpoint`).
      *
      * A retried call is not invisible without this: the wait lands inside the
      * tool's `stream.tool_end` `durationMs`, and an exhausted retry still
      * reaches the model with `error: true`. This hook is what turns "that call
      * was slow" into "that call was throttled twice".
+     *
+     * A throw from it is isolated: the call goes on as if it had returned.
      */
     readonly onRetry?: (info: ThrottleRetryInfo) => void;
 }
@@ -116,19 +240,74 @@ export interface RetryVerdict {
  * The one question the loop asks of each response.
  *
  * ── The license every decision must hold ─────────────────────────────────────
- * A decision may answer "again" ONLY for a refusal the server made BEFORE it
- * ran anything — the property that makes a 429 safe to repeat (see the module
- * note). A response that could be the record of half-done work is never one.
+ * A decision may answer "again" ONLY for a response the library treats as a
+ * refusal made before anything ran — the assumption a 429 retry rests on (see
+ * the module note: the 429 is its basis, not proof). A response that could be
+ * the record of half-done work is never one.
  * The library holds exactly two such decisions: {@link throttled} below, and
  * AgentCore Runtime's documented "session operation in progress" refusal,
  * which lives with that vendor's adapter (`adapters/mcp/agentcoreRuntime/`).
  * Each stays ONE small function, so a retry has exactly one place it is
- * decided — and one place to route it when retries are written down as
- * attempts.
+ * decided — and each attempt is written down as one footprintjs attempt
+ * record.
+ */
+export type RetryDecision = (response: Response, 
+/**
+ * The request's signal. It fires when the caller cancels or the call's
+ * deadline passes; a decision that reads the body must stop reading then,
+ * and release what it read from.
  */
-export type RetryDecision = (response: Response) => RetryVerdict | undefined | Promise<RetryVerdict | undefined>;
+signal?: AbortSignal) => RetryVerdict | undefined | Promise<RetryVerdict | undefined>;
 /** HTTP 429, with the server's own `Retry-After` when it sent one. */
 export declare function throttled(response: Response): RetryVerdict | undefined;
+/**
+ * @internal What a rule's options fall back to. `Infinity` means none: no
+ * deadline (`maxElapsedMs`), no cap on the scheduled wait (`maxDelayMs`).
+ */
+export interface RetryDefaults {
+    readonly maxAttempts: number;
+    readonly maxWaitMs: number;
+    readonly maxElapsedMs: number;
+    readonly baseDelayMs: number;
+    readonly multiplier: number;
+    readonly jitter: 'none' | 'equal' | 'full';
+    readonly maxDelayMs: number;
+}
+/**
+ * `retryOnThrottle`'s defaults — unchanged since 8.11.0: 3 attempts, a 200 ms
+ * backoff doubling with equal jitter (100–200 ms, then 200–400 ms), never more
+ * than 10 s of waiting in total. No deadline and no cap on one wait.
+ */
+export declare const THROTTLE_RETRY_DEFAULTS: RetryDefaults;
+/**
+ * @internal One refusal a series may retry: the decision that recognises it,
+ * the kind it reports as, and the limits and backoff it retries by.
+ */
+export interface RetryRule {
+    readonly kind: RetryKind;
+    readonly decide: RetryDecision;
+    /** Total attempts while this refusal is the reason to go on. ≥ 1; `Infinity` is no count. */
+    readonly maxAttempts: number;
+    readonly maxWaitMs: number;
+    readonly maxElapsedMs: number;
+    readonly maxDelayMs: number;
+    readonly baseDelayMs: number;
+    readonly multiplier: number;
+    readonly jitter: 'none' | 'equal' | 'full';
+    /** The caller's own name for the endpoint, reported as `endpoint`. */
+    readonly endpointLabel?: string;
+    readonly onRetry?: (info: ThrottleRetryInfo) => void;
+}
+/**
+ * @internal A rule from a caller's options — `undefined` when retry is off
+ * (`false`). An option field left out, or set to `undefined`, takes its
+ * default. `maxAttempts` and `maxWaitMs` keep the clamps they always had (below
+ * 1 reads as 1, below 0 as 0).
+ *
+ * @throws TypeError, when the rule is BUILT, for a value the schedule cannot
+ *   mean — named by option, never echoing a value that is not a number.
+ */
+export declare function retryRule(kind: RetryKind, decide: RetryDecision, config: RetryOnThrottle | undefined, defaults: RetryDefaults, where: string): RetryRule | undefined;
 /**
  * Wrap a `fetch` so HTTP 429 responses are retried, honouring `Retry-After`.
  *
@@ -136,6 +315,10 @@ export declare function throttled(response: Response): RetryVerdict | undefined;
  * so a transport that passed no custom fetch keeps passing none and its
  * behaviour is byte-identical to before this existed.
  *
+ * When `inner` already runs a retry series of its own (an AgentCore Runtime
+ * transport's fetch), the 429 rule JOINS that series rather than wrapping it,
+ * so the two can never multiply requests — see the module note.
+ *
  * ── Why this is public ───────────────────────────────────────────────────────
  * `mcpClient({ transport })` applies it for you, ON by default. `mcpClient({
  * connection })` cannot: the library builds no transport on that arm, so there
@@ -157,26 +340,48 @@ export declare function throttled(response: Response): RetryVerdict | undefined;
  * @param inner the fetch to wrap. `undefined` means the global `fetch`,
  *   resolved at CALL time so a later polyfill still wins.
  * @param config `true` / `undefined` for the defaults, `false` to get `inner`
- *   back unchanged, or an object to tune the ceilings.
+ *   back unchanged, or an object to tune the ceilings and the backoff.
+ * @throws TypeError when an option is outside its range — here, when the fetch
+ *   is built, never at the first call.
  */
 export declare function retryingFetch(inner: ThrottleFetch | undefined, config: RetryOnThrottle | undefined): ThrottleFetch | undefined;
 /**
- * The bounded loop itself, asking `decide` of every response.
- *
- * {@link retryingFetch} is this loop asking {@link throttled}. A vendor adapter
- * whose service documents a refusal of its own — one made before anything ran —
- * passes its decision here instead of writing a second loop, so the ceilings,
- * the `Retry-After` rail, the replay check, the abort and the `onRetry` report
- * stay one implementation.
- *
- * `decide` is asked only when a retry could actually follow — attempts left, a
- * body that can be sent again, no abort — so a decision that has to read the
- * response pays for that only when its answer can matter.
- *
- * @internal Public to adapters, not to the door: the decision is the vendor's
- *   fact, and each one is reviewed against the license on {@link RetryDecision}.
+ * @internal What one call's series is built from: the rules it asks, in order,
+ * and the connection's ledger — which tool call each request belongs to, so the
+ * series can file its attempts into that call's run (`requestLedger.ts`).
+ */
+export interface SeriesSpec {
+    readonly rules: readonly RetryRule[];
+    readonly ledger?: RequestLedger;
+}
+/** @internal What a joinable fetch's series can be rebuilt with: one more rule, or a ledger. */
+export type SeriesJoin = {
+    readonly rule: RetryRule;
+} | {
+    readonly ledger: RequestLedger;
+};
+/** @internal `spec` with `join` in it. */
+export declare function joinedSpec(spec: SeriesSpec, join: SeriesJoin): SeriesSpec;
+/**
+ * @internal Declare that `fetch` runs its retries in ONE series, and how to
+ * rebuild it with one more rule — or with a ledger — in that same series.
+ * `retryingFetch` joins such a fetch instead of wrapping it. A transport whose
+ * public fetch wraps its series (a session applied around it, its answers
+ * rewritten after it) uses this so the rule lands INSIDE that wrapping.
+ */
+export declare function joinableRetry(fetch: ThrottleFetch, rebuild: (join: SeriesJoin) => ThrottleFetch): ThrottleFetch;
+/**
+ * @internal `fetch` rebuilt so its series files each request's attempts through
+ * `ledger` — or `undefined` when `fetch` runs no series (retry off), so there
+ * is nothing to file and the caller keeps `fetch` as it is.
+ */
+export declare function ledgeredFetch(fetch: ThrottleFetch, ledger: RequestLedger): ThrottleFetch | undefined;
+/**
+ * @internal The one series per call over `inner`, asking `spec.rules` in order —
+ * `inner` itself when there are none. The first rule holds the call's budget;
+ * see the module note. The result is joinable.
  */
-export declare function retryingFetchWhen(inner: ThrottleFetch | undefined, config: RetryOnThrottle | undefined, decide: RetryDecision): ThrottleFetch | undefined;
+export declare function retryingFetchFor(inner: ThrottleFetch, spec: SeriesSpec): ThrottleFetch;
 /**
  * `Retry-After` in either legal form: delta-seconds (`"2"`) or an HTTP-date
  * (`"Wed, 21 Oct 2026 07:28:00 GMT"`). Anything else is treated as absent so a

package/dist/types/mcp/throttleRetry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"throttleRetry.d.ts","sourceRoot":"","sources":["../../../src/mcp/throttleRetry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AAIH;;;;;;;GAOG;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,GAAG,EAAE,IAAI,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;AAI3F,yEAAyE;AACzE,MAAM,WAAW,iBAAiB;IAChC,0DAA0D;IAC1D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,mEAAmE;IACnE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,sDAAsD;IACtD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB;4DACwD;IACxD,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B;6EACyE;IACzE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAED,gEAAgE;AAChE,MAAM,WAAW,oBAAoB;IACnC,gEAAgE;IAChE,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B;;;;;;;;OAQG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,iBAAiB,KAAK,IAAI,CAAC;CACtD;AAED;;;GAGG;AACH,MAAM,MAAM,eAAe,GAAG,OAAO,GAAG,oBAAoB,CAAC;AA4B7D;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B;;;OAGG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;CAChC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,aAAa,GAAG,CAC1B,QAAQ,EAAE,QAAQ,KACf,YAAY,GAAG,SAAS,GAAG,OAAO,CAAC,YAAY,GAAG,SAAS,CAAC,CAAC;AAElE,sEAAsE;AACtE,wBAAgB,SAAS,CAAC,QAAQ,EAAE,QAAQ,GAAG,YAAY,GAAG,SAAS,CAItE;AAID;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,aAAa,CAC3B,KAAK,EAAE,aAAa,GAAG,SAAS,EAChC,MAAM,EAAE,eAAe,GAAG,SAAS,GAClC,aAAa,GAAG,SAAS,CAE3B;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,aAAa,GAAG,SAAS,EAChC,MAAM,EAAE,eAAe,GAAG,SAAS,EACnC,MAAM,EAAE,aAAa,GACpB,aAAa,GAAG,SAAS,CA2C3B;AAID;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAOpF"}
+{"version":3,"file":"throttleRetry.d.ts","sourceRoot":"","sources":["../../../src/mcp/throttleRetry.ts"],"names":[],"mappings":"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"}