agentfootprint 11.2.0 → 11.4.0

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

@@ -1,6 +1,6 @@
 /**
- * throttleRetry — when an MCP server refuses a request before running it, 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
@@ -10,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.
@@ -46,10 +50,13 @@
  *
  * ── 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.
+ * 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
@@ -83,6 +90,7 @@
  *
  * 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
@@ -184,21 +192,24 @@ export interface ThrottleRetryOptions {
     /**
      * 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.
+     * 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 — 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 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
@@ -229,9 +240,10 @@ 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/`).
@@ -333,20 +345,43 @@ export declare function retryRule(kind: RetryKind, decide: RetryDecision, config
  *   is built, never at the first call.
  */
 export declare function retryingFetch(inner: ThrottleFetch | undefined, config: RetryOnThrottle | undefined): ThrottleFetch | undefined;
+/**
+ * @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 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.
+ * 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 joinableRetry(fetch: ThrottleFetch, join: (rule: RetryRule) => ThrottleFetch): ThrottleFetch;
+export declare function ledgeredFetch(fetch: ThrottleFetch, ledger: RequestLedger): ThrottleFetch | undefined;
 /**
- * @internal The one series per call over `inner`, asking `rules` in order —
+ * @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 retryingFetchFor(inner: ThrottleFetch, rules: readonly RetryRule[]): ThrottleFetch;
+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/esm/mcp/throttleRetry.js

@@ -1,6 +1,6 @@
 /**
- * throttleRetry — when an MCP server refuses a request before running it, 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
@@ -10,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.
@@ -46,10 +50,13 @@
  *
  * ── 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.
+ * 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
@@ -86,6 +93,7 @@
 import { attempt, } from 'footprintjs';
 import { abortErrorOf, eitherSignal, linkedController } from '../lib/abort.js';
 import { exponentialBackoff, statedWaitFirst } from './backoff.js';
+import { SeriesEvidence, } from './seriesEvidence.js';
 /** HTTP 429, with the server's own `Retry-After` when it sent one. */
 export function throttled(response) {
     if (response.status !== 429)
@@ -177,37 +185,54 @@ export function retryingFetch(inner, config) {
     const rule = retryRule('throttle', throttled, config, THROTTLE_RETRY_DEFAULTS, 'retryOnThrottle');
     if (rule === undefined)
         return inner;
-    const join = inner === undefined ? undefined : JOINS.get(inner);
-    return join !== undefined ? join(rule) : retryingFetchFor(inner ?? platformFetch, [rule]);
+    const rebuild = inner === undefined ? undefined : JOINS.get(inner);
+    return rebuild !== undefined
+        ? rebuild({ rule })
+        : retryingFetchFor(inner ?? platformFetch, { rules: [rule] });
+}
+/** @internal `spec` with `join` in it. */
+export function joinedSpec(spec, join) {
+    return 'rule' in join
+        ? { ...spec, rules: [...spec.rules, join.rule] }
+        : { ...spec, ledger: join.ledger };
 }
 /**
  * Fetches that run their retries in one series, each with the way to rebuild
- * it with one more rule. Module-private: only `joinableRetry` adds to it, so a
- * caller cannot make a fetch claim a series it does not run.
+ * it with one more rule or a ledger. Module-private: only `joinableRetry` adds
+ * to it, so a caller cannot make a fetch claim a series it does not run.
  */
 const JOINS = new WeakMap();
 /**
  * @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.
+ * 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 function joinableRetry(fetch, join) {
-    JOINS.set(fetch, join);
+export function joinableRetry(fetch, rebuild) {
+    JOINS.set(fetch, rebuild);
     return fetch;
 }
 /**
- * @internal The one series per call over `inner`, asking `rules` in order —
+ * @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 function ledgeredFetch(fetch, ledger) {
+    return JOINS.get(fetch)?.({ ledger });
+}
+/**
+ * @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 function retryingFetchFor(inner, rules) {
+export function retryingFetchFor(inner, spec) {
+    const { rules, ledger } = spec;
     const [owner] = rules;
     if (owner === undefined)
         return inner;
     const bound = rules.map((rule) => boundRule(rule, owner));
-    return joinableRetry((input, init) => new Series(bound, input, init).run(inner), (rule) => retryingFetchFor(inner, [...rules, rule]));
+    return joinableRetry((input, init) => new Series(bound, input, init, ledger).run(inner), (join) => retryingFetchFor(inner, joinedSpec(spec, join)));
 }
 /** The platform's fetch, looked up at call time so a later polyfill still wins. */
 const platformFetch = (input, init) => globalThis.fetch(input, init);
@@ -237,7 +262,8 @@ function retryAfterOf(error) {
 const SERIES_TARGET = 'mcp-request';
 /**
  * One call: one `attempt()` series, and what its policy's functions share while
- * it runs — the waiting so far, and the latest refusal.
+ * it runs — the waiting so far, the latest refusal, and, for a call the agent
+ * dispatched, where its attempts are filed.
  */
 class Series {
     rules;
@@ -246,13 +272,31 @@ class Series {
     owner;
     startedAt = Date.now();
     deadline;
+    /** The transport's own signal — what the request carried before this series existed. */
     signal;
+    /**
+     * What ends the series as a CANCELLATION: the transport's signal; the MCP
+     * SDK cancelling this request (`notifications/cancelled`, seen by the ledger,
+     * whether or not the request was matched to a call); and, for a call the
+     * agent dispatched, the call's own — its signal, the client's, its settling.
+     */
+    cancel;
+    /** Whether a request in flight is cut by more than the transport's own signal. */
+    cutsInFlight;
+    /** Where this request's attempts are filed — a call the agent dispatched. */
+    evidence;
     replayable;
     attemptNo = 0;
     waitedMs = 0;
     plannedWaitMs = 0;
     latest;
-    constructor(rules, input, init) {
+    /** The current attempt's response status, before the runner records it. */
+    seen;
+    /** Why `retryOn` last said no. */
+    declined;
+    /** The attempt sent and not yet recorded — what a cancellation cuts in flight. */
+    inFlight;
+    constructor(rules, input, init, ledger) {
         this.rules = rules;
         this.input = input;
         this.init = init;
@@ -261,14 +305,50 @@ class Series {
         this.replayable = isReplayable(input, init);
         const { maxElapsedMs } = this.owner;
         this.deadline = Number.isFinite(maxElapsedMs) ? this.startedAt + maxElapsedMs : undefined;
+        const claimed = ledger?.claim(init?.body);
+        const ticket = claimed?.ticket;
+        this.cancel = eitherSignal(this.signal, ticket?.signal, claimed?.cancelled);
+        this.cutsInFlight = this.deadline !== undefined || claimed !== undefined;
+        this.evidence =
+            ticket === undefined ? undefined : new SeriesEvidence(ticket.sink, whereOf(rules, input));
     }
     async run(inner) {
+        const unwatch = this.watchCancel();
         try {
-            return await attempt((t) => this.send(inner, t), this.policy(), this.options());
+            const response = await attempt((t) => this.send(inner, t), this.policy(), this.options());
+            this.evidence?.delivered();
+            return response;
         }
         catch (error) {
             return this.settle(error);
         }
+        finally {
+            unwatch();
+        }
+    }
+    /**
+     * File a cancellation the MOMENT it lands. A cancelled run stops waiting for
+     * its stage at once; a record filed when this series later unwinds would land
+     * after the run was saved. The runner records nothing for the attempt it
+     * abandons then, or for a wait it was cut out of, so this is also the only
+     * place those are written down.
+     */
+    watchCancel() {
+        const { cancel } = this;
+        if (cancel === undefined || this.evidence === undefined || cancel.aborted) {
+            return () => undefined;
+        }
+        const onAbort = () => this.fileCancellation();
+        cancel.addEventListener('abort', onAbort, { once: true });
+        return () => cancel.removeEventListener('abort', onAbort);
+    }
+    /** A cancellation, written down: the attempt it cut in flight, or the wait. */
+    fileCancellation() {
+        const { evidence, inFlight } = this;
+        if (inFlight !== undefined)
+            evidence?.cutInFlight(inFlight);
+        else
+            evidence?.cancelled();
     }
     /**
      * The owner's budget as footprintjs reads it; the rest is this series'
@@ -288,7 +368,7 @@ class Series {
     options() {
         return {
             target: SERIES_TARGET,
-            ...(this.signal !== undefined && { signal: this.signal }),
+            ...(this.cancel !== undefined && { signal: this.cancel }),
             ...(this.deadline !== undefined && { deadline: this.deadline }),
             onAttempt: (record) => this.report(record),
         };
@@ -297,25 +377,30 @@ class Series {
      * One attempt: the request, sent once, and its answer classified. A refusal
      * a rule recognises is thrown for the runner to decide on.
      *
-     * With no deadline of ours the request carries the caller's own `init`,
-     * exactly as before this series existed. Under a deadline the runner can cut
-     * the attempt before it is ANSWERED — and an answer is not in until it has
-     * been classified, which can mean reading its body (a session-busy reply is
-     * JSON in a 200). So the cut stays connected through the classification: a
-     * stall in the request or in that body stops the request and releases the
-     * body. Only then does it let go: an answer handed back to the caller keeps
+     * With no deadline of ours and no call to answer to, the request carries the
+     * caller's own `init`, exactly as before this series existed. Otherwise the
+     * runner can cut the attempt before it is ANSWERED — the deadline, or the
+     * dispatched call's cancellation — and an answer is not in until it has been
+     * classified, which can mean reading its body (a session-busy reply is JSON
+     * in a 200). So the cut stays connected through the classification: a stall
+     * in the request or in that body stops the request and releases the body.
+     * Only then does it let go: an answer handed back to the caller keeps
      * streaming for as long as the caller's own signal allows.
      */
     async send(inner, t) {
         this.attemptNo = t.attempt;
+        // From here the request is SENT — counted, as a row, however the attempt ends.
+        this.inFlight = t.attempt;
+        this.seen = undefined;
         // The previous attempt's refusal will not be delivered: release its body, so
         // a keep-alive connection is not pinned by an unread stream.
         this.supersede();
-        const cut = this.deadline === undefined ? undefined : linkedController(t.signal);
+        const cut = this.cutsInFlight ? linkedController(t.signal) : undefined;
         const signal = eitherSignal(this.signal, cut?.controller.signal);
         try {
             const init = cut === undefined ? this.init : { ...this.init, ...(signal && { signal }) };
             const response = await inner(this.input, init);
+            this.seen = { attempt: t.attempt, status: response.status };
             const refused = await this.recognise(response, signal);
             if (refused === undefined)
                 return response;
@@ -348,44 +433,59 @@ class Series {
     }
     /**
      * The runner's `retryOn`: is this attempt's error a refusal worth another
-     * attempt? Plans the wait as it answers, because the ceilings need its length.
+     * attempt? Plans the wait as it answers, because the ceilings need its length,
+     * and keeps why it said no, for the record.
      */
     retryOn(error) {
         this.plannedWaitMs = 0;
         const refused = this.latest;
-        // The license: only a refusal made before the server ran anything. A 5xx, a
-        // dropped connection or a timeout may be the record of work that ran.
+        // The license: only a response a rule recognises as a refusal (the 429
+        // assumption — see the module note). A 5xx, a dropped connection or a
+        // timeout may be the record of work that ran.
         if (refused === undefined || error !== refused.refusal)
-            return false;
+            return this.decline('not-retryable');
         // A body we cannot send twice makes a retry a different request. Rare for
         // MCP (JSON strings), but silently replaying half a stream would be worse
         // than surfacing the refusal.
         if (!this.replayable)
-            return false;
+            return this.decline('not-replayable');
         const { rule } = refused;
         if (this.attemptNo >= rule.maxAttempts)
-            return false;
+            return this.decline('exhausted');
         // The stated wait whole, else the schedule under `maxDelayMs`.
         const waitMs = rule.backoffMs(this.attemptNo, error);
         // The rail on Retry-After: never let a server talk us into a wait that
         // breaks the caller's budget. It stops the series; it never shortens the
         // wait. Past the deadline, the runner stops it the same way (`no-time-left`).
         if (this.waitedMs + waitMs > rule.maxWaitMs)
-            return false;
+            return this.decline('wait-limit');
         // A joined rule's own, sooner deadline. The owner's is the runner's to hold.
         if (rule.maxElapsedMs < this.owner.maxElapsedMs &&
             this.elapsedAfter(waitMs) > rule.maxElapsedMs) {
-            return false;
+            return this.decline('no-time-left');
         }
+        this.declined = undefined;
         this.plannedWaitMs = waitMs;
         return true;
     }
+    decline(reason) {
+        this.declined = reason;
+        return false;
+    }
     elapsedAfter(waitMs) {
         return Date.now() - this.startedAt + waitMs;
     }
-    /** Each record as the runner ends an attempt: a retry is counted and reported to its rule. */
+    /**
+     * Each record as the runner ends an attempt: written down for the call's run
+     * first, then — for a retry — counted and reported to its rule. The record
+     * goes first because `onRetry` is the caller's, and a throw from it must not
+     * cost the run its evidence.
+     */
     report(record) {
         const refused = this.latest;
+        if (this.inFlight === record.attempt)
+            this.inFlight = undefined;
+        this.evidence?.attempt(record, this.seenOf(record, refused), this.declined);
         if (record.next !== 'retry' || refused === undefined)
             return;
         const waitMs = record.delayMs ?? 0;
@@ -401,18 +501,37 @@ class Series {
             ...(rule.endpointLabel !== undefined && { endpoint: rule.endpointLabel }),
         });
     }
+    /** What this series saw of the attempt `record` ends: its status, and the refusal it threw. */
+    seenOf(record, refused) {
+        const seen = this.seen;
+        if (seen === undefined || seen.attempt !== record.attempt)
+            return undefined;
+        // `latest` is cleared as each attempt starts, so a refusal here is this attempt's.
+        const { kind } = refused?.rule ?? {};
+        const retryAfterMs = refused?.verdict.retryAfterMs;
+        return {
+            status: seen.status,
+            ...(kind !== undefined && {
+                refusal: { kind, ...(retryAfterMs !== undefined && { retryAfterMs }) },
+            }),
+        };
+    }
     /** How the call ends when the series did not answer. */
     settle(error) {
         // The caller's cancellation wins: the call ends with their reason, and the
         // refusal nobody is waiting for any more is released.
-        if (this.signal?.aborted) {
+        if (this.cancel?.aborted) {
+            this.fileCancellation();
             this.supersede();
-            throw abortErrorOf(this.signal);
+            throw abortErrorOf(this.cancel);
         }
         // The series ended on a refusal — attempts spent, a ceiling reached, no
         // time left. The server's answer is delivered as it sent it.
-        if (this.latest !== undefined && error === this.latest.refusal)
+        if (this.latest !== undefined && error === this.latest.refusal) {
+            this.evidence?.delivered();
             return this.latest.response;
+        }
+        this.evidence?.threw(this.deadline !== undefined && Date.now() >= this.deadline);
         throw error;
     }
     supersede() {
@@ -421,9 +540,17 @@ class Series {
         this.latest = undefined;
     }
 }
+/** Where a series' requests go, as its evidence may say it: a label the app declared, or the origin. */
+function whereOf(rules, input) {
+    const label = rules.find((rule) => rule.endpointLabel !== undefined)?.endpointLabel;
+    if (label !== undefined)
+        return { endpoint: label };
+    const origin = originOf(input);
+    return origin === '' ? {} : { origin };
+}
 /**
- * A response a rule recognised as a refusal made before anything ran, thrown so
- * the attempt runner decides on it. It carries only what an attempt record may
+ * A response a rule recognised as a refusal (a 429, a session-busy reply), thrown
+ * so the attempt runner decides on it. It carries only what an attempt record may
  * keep: a fixed sentence, its kind as `code`, a 429's status and the wait the
  * server stated. Never the server's text, the request or the response — the
  * series holds the response, not the error.
@@ -442,8 +569,8 @@ class RetryableRefusal extends Error {
     }
 }
 const REFUSAL_SENTENCES = {
-    throttle: 'The server refused the request with HTTP 429 before running it.',
-    'session-busy': 'AgentCore Runtime refused the request while its session was starting or stopping, before running it.',
+    throttle: 'The server answered with HTTP 429, a response the retry policy recognises as a refusal. It is recorded as sent, which is not proof that nothing ran.',
+    'session-busy': 'AgentCore Runtime answered that its session was starting or stopping, a response the retry policy recognises as a refusal. It is recorded as sent, which is not proof that nothing ran.',
 };
 // ─── Helpers ─────────────────────────────────────────────────────────
 /** Reads one rule's numeric options, refusing by name what the schedule cannot mean. */