agentfootprint 11.2.0 → 11.3.0

package/dist/esm/mcp/seriesEvidence.js

@@ -0,0 +1,246 @@
+/**
+ * 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 { MAX_REQUEST_ATTEMPT_ROWS, } from '../tools/requestEvidence.js';
+const FAILED = 'The request failed before an answer arrived. Its error is not kept.';
+const OUT_OF_TIME = 'The call ran out of time before an answer arrived.';
+/** One request's evidence, collected as its series runs and filed once. */
+export class SeriesEvidence {
+    sink;
+    where;
+    rows = [];
+    omitted = 0;
+    last;
+    filed = false;
+    constructor(sink, where) {
+        this.sink = sink;
+        this.where = where;
+    }
+    /** One attempt as the runner recorded it. */
+    attempt(record, seen, declined) {
+        if (this.filed)
+            return;
+        this.add(rowOf(record, seen, declined));
+    }
+    /**
+     * 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) {
+        if (this.filed)
+            return;
+        this.add({ attempt: n, outcome: 'cut', reason: 'cancelled', remote: 'unknown' });
+        this.file({ outcome: 'cut', reason: 'cancelled', during: 'request', remote: 'unknown' });
+    }
+    /**
+     * 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() {
+        const last = this.last;
+        if (last !== undefined && last.reason !== 'retryable') {
+            this.file(endOf(last));
+            return;
+        }
+        this.file({
+            outcome: 'cancelled',
+            reason: 'cancelled',
+            ...(last !== undefined && { during: 'wait' }),
+        });
+    }
+    /**
+     * 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() {
+        const last = this.last;
+        if (last === undefined) {
+            this.file(UNACCOUNTED);
+            return;
+        }
+        this.file(last.reason === 'retryable'
+            ? { ...endOf(last), reason: 'no-time-left', during: 'wait' }
+            : endOf(last));
+    }
+    /**
+     * 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) {
+        const last = this.last;
+        if (last !== undefined && last.reason !== 'retryable') {
+            this.file(endOf(last));
+            return;
+        }
+        if (!outOfTime) {
+            this.file(UNACCOUNTED);
+            return;
+        }
+        this.file({
+            outcome: 'timed-out',
+            reason: 'no-time-left',
+            failure: 'timeout',
+            ...(last !== undefined && { during: 'wait' }),
+            error: { message: OUT_OF_TIME, code: 'timeout' },
+        });
+    }
+    add(row) {
+        this.last = row;
+        if (this.rows.length < MAX_REQUEST_ATTEMPT_ROWS)
+            this.rows.push(row);
+        else
+            this.omitted += 1;
+    }
+    file(end) {
+        if (this.filed)
+            return;
+        this.filed = true;
+        try {
+            this.sink.file({ ...this.where, attempts: [...this.rows], omitted: this.omitted, end });
+        }
+        catch {
+            // The library's sink never throws; one that does must not fail the call.
+        }
+    }
+}
+/**
+ * An end no attempt accounts for — never seen; kept so a request is never left
+ * unfiled, and never claiming more than is known.
+ */
+const UNACCOUNTED = {
+    outcome: 'failed',
+    reason: 'not-retryable',
+    failure: 'unknown',
+    error: { message: FAILED, code: 'unknown' },
+    remote: 'unknown',
+};
+/** One record as a row — see the module note for what a row may say. */
+export function rowOf(record, seen, declined) {
+    const outcome = outcomeOf(record, seen);
+    const reason = reasonOf(record, declined);
+    const refusal = outcome === 'refused' ? seen?.refusal : undefined;
+    return {
+        attempt: record.attempt,
+        outcome,
+        reason,
+        ...((outcome === 'answered' || outcome === 'refused') &&
+            seen?.status !== undefined && { status: seen.status }),
+        ...(refusal !== undefined && { kind: refusal.kind }),
+        ...(outcome !== 'answered' &&
+            outcome !== 'cut' &&
+            record.category !== undefined && { failure: record.category }),
+        ...(reason === 'retryable' && { waitMs: record.delayMs ?? 0 }),
+        ...(refusal?.retryAfterMs !== undefined && { retryAfterMs: refusal.retryAfterMs }),
+        ...((outcome === 'failed' || outcome === 'timed-out') && {
+            error: errorOf(outcome, record.category),
+        }),
+        ...(noAnswer(outcome) && { remote: 'unknown' }),
+    };
+}
+/** An attempt that ended without an answer — the server may have run it, or not. */
+function noAnswer(outcome) {
+    return outcome === 'failed' || outcome === 'timed-out' || outcome === 'cut';
+}
+function outcomeOf(record, seen) {
+    switch (record.outcome) {
+        case 'ok':
+            return 'answered';
+        case 'timeout':
+            return 'timed-out';
+        case 'failed':
+            return seen?.refusal !== undefined ? 'refused' : 'failed';
+        case 'aborted':
+            // Cut in flight by the series' cancellation. The cancellation itself files
+            // this row first (`cutInFlight`), so the record is seen only if it did not.
+            return 'cut';
+        default:
+            // `paused` cannot happen inside a fetch.
+            return 'failed';
+    }
+}
+function reasonOf(record, declined) {
+    if (record.outcome === 'ok')
+        return 'answered';
+    if (record.next === 'retry')
+        return 'retryable';
+    if (record.outcome === 'timeout')
+        return 'no-time-left';
+    switch (record.reason) {
+        case 'exhausted':
+            return 'exhausted';
+        case 'no-time-left':
+            return 'no-time-left';
+        case 'aborted':
+            return 'cancelled';
+        case 'declined':
+            return declined ?? 'not-retryable';
+        default:
+            return 'not-retryable';
+    }
+}
+function errorOf(outcome, category) {
+    return outcome === 'timed-out'
+        ? { message: OUT_OF_TIME, code: category ?? 'timeout' }
+        : { message: FAILED, code: category ?? 'unknown' };
+}
+/** How a request ended, when it ended with its last attempt. */
+function endOf(last) {
+    const { outcome, reason, status, kind, failure, error, remote } = last;
+    return {
+        outcome,
+        reason,
+        ...(status !== undefined && { status }),
+        ...(kind !== undefined && { kind }),
+        ...(failure !== undefined && { failure }),
+        ...((outcome === 'timed-out' || outcome === 'cut') && { during: 'request' }),
+        ...(error !== undefined && { error }),
+        ...(remote !== undefined && { remote }),
+    };
+}
+//# sourceMappingURL=seriesEvidence.js.map

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

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

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