agentfootprint 11.1.0 → 11.2.0

package/dist/esm/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 before running it, wait
+ * and ask again.
  *
  * ── Why this exists ──────────────────────────────────────────────────────────
  * Managed MCP gateways enforce per-principal rate limits. A throttled
@@ -43,6 +44,43 @@
  * 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; they stay inside this module for
+ * now — only `onRetry`, before each wait, reaches a caller. 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.
+ * 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.
  */
 /**
@@ -54,22 +92,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 +150,62 @@ 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. 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 — and, today, the ONLY retry report a
+     * caller gets. 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. The series' final outcome and the
+     * attempt records footprintjs's runner makes for each try are NOT passed on
+     * yet. The contract matches what `withRetry` and `withCredentialRetry`
+     * already use: a decorator at a transport boundary reports to its consumer,
+     * and emits no events of its own.
      *
      * 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;
 }
@@ -123,12 +236,66 @@ export interface RetryVerdict {
  * 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 +303,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 +328,25 @@ 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 Declare that `fetch` runs its retries in ONE series, and how to
+ * rebuild it with one more rule 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, join: (rule: RetryRule) => ThrottleFetch): ThrottleFetch;
+/**
+ * @internal The one series per call over `inner`, asking `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, rules: readonly RetryRule[]): 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