agentfootprint 11.3.0 → 11.5.0

package/dist/esm/mcp/seriesEvidence.js

@@ -28,44 +28,76 @@
  * 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.
+ * THREE FACTS PER ATTEMPT, NONE READ FROM ANOTHER (`replay.ts`): the failure
+ * (footprintjs's category), what is known of its effect (`unknown` for every
+ * attempt sent that did not complete — a refusal included; `applied` when the
+ * call completed, never proof of a write; `none` only for what was never
+ * sent), and — on an attempt the series asked again after — what permitted it.
+ * Each row also says how long it took. The end says how many requests were
+ * sent and what is known of the whole series' effect; uncertainty survives
+ * (`SeriesKnowledge`).
+ *
+ * WHEN IT FILES. When the call settles — the series has ended by then, and the
+ * call's verdict is what says whether an answered attempt completed (a 200 can
+ * carry a tool error) — 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'`. A series ended and waiting for its
+ * call files at once if the call is cancelled first, with what it knows.
+ * 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';
+import { SeriesKnowledge } from './replay.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;
+    settlement;
     rows = [];
     omitted = 0;
     last;
     filed = false;
-    constructor(sink, where) {
+    waiting = false;
+    /** What is known of the series' effect, attempt by attempt — the answer's excepted. */
+    knowledge = new SeriesKnowledge();
+    /** The answered attempt, while its effect waits for the call's verdict. */
+    answer;
+    constructor(sink, where, settlement) {
         this.sink = sink;
         this.where = where;
+        this.settlement = settlement;
     }
-    /** One attempt as the runner recorded it. */
-    attempt(record, seen, declined) {
+    /** One attempt as the runner recorded it, with what the series knows of it. */
+    attempt(record, seen, declined, facts) {
         if (this.filed)
             return;
-        this.add(rowOf(record, seen, declined));
+        const row = withFacts(rowOf(record, seen, declined), facts);
+        if (facts !== undefined && row.effect === undefined && row.outcome === 'answered') {
+            this.answer = row;
+        }
+        this.add(row);
     }
     /**
      * 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) {
+    cutInFlight(n, durationMs) {
         if (this.filed)
             return;
-        this.add({ attempt: n, outcome: 'cut', reason: 'cancelled', remote: 'unknown' });
+        this.add({
+            attempt: n,
+            outcome: 'cut',
+            reason: 'cancelled',
+            remote: 'unknown',
+            effect: 'unknown',
+            ...(durationMs !== undefined && { durationMs }),
+        });
         this.file({ outcome: 'cut', reason: 'cancelled', during: 'request', remote: 'unknown' });
     }
     /**
@@ -91,15 +123,15 @@ export class SeriesEvidence {
      * 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`).
+     * the `wait`). Filed when the call has read it.
      */
     delivered() {
         const last = this.last;
         if (last === undefined) {
-            this.file(UNACCOUNTED);
+            this.fileWhenSettled(UNACCOUNTED);
             return;
         }
-        this.file(last.reason === 'retryable'
+        this.fileWhenSettled(last.reason === 'retryable'
             ? { ...endOf(last), reason: 'no-time-left', during: 'wait' }
             : endOf(last));
     }
@@ -110,19 +142,19 @@ export class SeriesEvidence {
      * 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.
+     * account for, so a request is never left unfiled. Filed when the call settles.
      */
     threw(outOfTime) {
         const last = this.last;
         if (last !== undefined && last.reason !== 'retryable') {
-            this.file(endOf(last));
+            this.fileWhenSettled(endOf(last));
             return;
         }
         if (!outOfTime) {
-            this.file(UNACCOUNTED);
+            this.fileWhenSettled(UNACCOUNTED);
             return;
         }
-        this.file({
+        this.fileWhenSettled({
             outcome: 'timed-out',
             reason: 'no-time-left',
             failure: 'timeout',
@@ -132,22 +164,67 @@ export class SeriesEvidence {
     }
     add(row) {
         this.last = row;
+        if (row.effect !== undefined)
+            this.knowledge.note(row.effect);
         if (this.rows.length < MAX_REQUEST_ATTEMPT_ROWS)
             this.rows.push(row);
         else
             this.omitted += 1;
     }
+    /**
+     * File `end` once the call has settled — its verdict is what says whether an
+     * answered attempt completed — or at once, when the call is already settled
+     * or cancelled, or there is no call to wait for.
+     */
+    fileWhenSettled(end) {
+        const signal = this.settlement?.signal;
+        if (signal === undefined || signal.aborted) {
+            this.file(end);
+            return;
+        }
+        if (this.waiting)
+            return;
+        this.waiting = true;
+        signal.addEventListener('abort', () => this.file(end), { once: true });
+    }
     file(end) {
         if (this.filed)
             return;
         this.filed = true;
+        const replay = this.settlement?.replay;
+        const rows = this.settleAnswer(replay);
         try {
-            this.sink.file({ ...this.where, attempts: [...this.rows], omitted: this.omitted, end });
+            this.sink.file({
+                ...this.where,
+                attempts: rows,
+                omitted: this.omitted,
+                end: {
+                    ...end,
+                    attempts: this.rows.length + this.omitted,
+                    effect: this.knowledge.effect,
+                    ...(replay?.mayHaveRun === true && { mayHaveRun: true }),
+                },
+            });
         }
         catch {
             // The library's sink never throws; one that does must not fail the call.
         }
     }
+    /**
+     * The rows, the answered one given its effect: `applied` when the call
+     * completed — the server answered it, and not with an error — else `unknown`
+     * (a 5xx, a JSON-RPC error, a tool error, a call cancelled before it read the
+     * answer). The answer's effect joins the series' knowledge here.
+     */
+    settleAnswer(replay) {
+        const answer = this.answer;
+        if (answer === undefined)
+            return [...this.rows];
+        const effect = replay?.verdict === 'completed' ? 'applied' : 'unknown';
+        this.knowledge.note(effect);
+        const settled = { ...answer, effect };
+        return this.rows.map((row) => (row === answer ? settled : row));
+    }
 }
 /**
  * An end no attempt accounts for — never seen; kept so a request is never left
@@ -183,6 +260,22 @@ export function rowOf(record, seen, declined) {
         ...(noAnswer(outcome) && { remote: 'unknown' }),
     };
 }
+/**
+ * `row` with what the series knows of its attempt beyond the record — its
+ * effect, what permitted the next attempt, how long it took. Without `facts`,
+ * the row as the record alone says it.
+ */
+export function withFacts(row, facts) {
+    if (facts === undefined)
+        return row;
+    return {
+        ...row,
+        ...(facts.effect !== undefined && { effect: facts.effect }),
+        ...(row.reason === 'retryable' &&
+            facts.permission !== undefined && { permission: facts.permission }),
+        durationMs: facts.durationMs,
+    };
+}
 /** 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';

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

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

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

@@ -10,27 +10,33 @@
  * tool, or invents an answer. A designed, transient, self-clearing condition
  * was being turned into a wrong answer.
  *
- * ── 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.
+ * ── Who may ask again: the app, by declaration (`replay.ts`) ─────────────────
+ * HTTP 429 says only that the request was rate-limited (RFC 6585 §4). It does
+ * not prove the server ran nothing, and `Retry-After` says when to ask again,
+ * not that asking is safe. So permission to send a tool call again is the
+ * APP's, declared per (server, tool) when the client is built (`mcpClient({
+ * replay })`), and kept apart from what is known of an attempt's effect. Before
+ * every repeat the series asks `permit`; the record keeps its answer.
  *
- * 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.
+ *   - `'compatibility'` (the 11.x default) keeps today's behaviour by name: a
+ *     429 is repeated for every tool, ASSUMING the server refused it before
+ *     running it — and every such repeat records that assumption.
+ *   - `'app-authorized'` (opt-in, the next major's default) repeats a 429 only
+ *     for a tool the app declared repeatable on it.
+ *   - A request that failed in transport without an answer (footprintjs's
+ *     `network`: a lost connection, a timeout below the series) is repeated
+ *     only when the app declared that for the tool. A 5xx is an answer, never
+ *     repeated. A cut or a deadline ends the series.
+ *   - Under both, a tool the app declares as making changes is never repeated
+ *     automatically unless the server is declared to deduplicate by a key the
+ *     call carries — footprintjs's side-effect guard, now wired here.
  *
  * The loop takes its question as a {@link RetryDecision}, so the one other
  * 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.
+ * That decision is applied only by that vendor's own transport, and its rule
+ * carries the adapter's retry assumption (`RetryRule.assumes`) — a policy,
+ * never evidence: its attempts record effect `unknown`, as a 429's do.
  *
  * ── Why it lives at the fetch seam and not around `Tool.execute` ─────────────
  * Because `Retry-After` is only reachable here. The MCP SDK reads the response,
@@ -58,12 +64,17 @@
  * 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.
+ * its kind, and the policy's `retryOn` accepts those refusals — and a network
+ * failure the app declared for the tool — when the replay rule permits them,
+ * and nothing else: a 5xx 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, no permission), the refusal's response is delivered
+ * as the server sent it: the caller sees the 429, never an error of ours. The
+ * call decides what that means for it (`callLifetime.ts`): under
+ * 'app-authorized', a call that genuinely lacked an answer somewhere and does
+ * not complete fails as "may have run". This series reports the HTTP half of
+ * that — an attempt that got no response at all, and the status it delivered;
+ * a received refusal is an answer, its effect still unknown.
  *
  * ── A fetch that already retries is JOINED, never wrapped ────────────────────
  * A transport whose own fetch runs a series (AgentCore Runtime's session-busy
@@ -90,6 +101,7 @@
  *
  * Pattern: Decorator over `fetch`. Role: Layer-3 tool transport.
  */
+import { type ReplayDeclaration } from './replay.js';
 import type { RequestLedger } from './requestLedger.js';
 /**
  * The fetch shape the MCP SDK's `fetch` hook uses — deliberately NARROWER
@@ -107,8 +119,12 @@ export type ThrottleFetch = (input: string | URL, init?: RequestInit) => Promise
 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;
+    /**
+     * Which refusal this retry answers — or `'network'`, a tool call the app
+     * declared repeatable after a request that failed without an answer
+     * (`McpClientOptions.replay`). It is reported to the series' first rule.
+     */
+    readonly kind: RetryKind | 'network';
     /** The attempt about to START. `2` is the first retry. */
     readonly attempt: number;
     /** Ceiling in force for this refusal, including the first attempt. */
@@ -240,16 +256,18 @@ 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 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 each attempt is written down as one footprintjs attempt
- * record.
+ * A decision RECOGNISES a refusal; whether the request is sent again is the
+ * replay rule's (`replay.ts`), never the decision's. It may recognise only a
+ * response that is a refusal — never one that could be the record of
+ * half-done work. The library holds exactly two: {@link throttled} below, a
+ * 429, and AgentCore Runtime's "session operation in progress" refusal, which
+ * lives with that vendor's adapter (`adapters/mcp/agentcoreRuntime/`) and whose
+ * rule carries the adapter's retry assumption (`RetryRule.assumes`). Either
+ * one's effect stays unknown: a 429 says the request was rate-limited, and the
+ * busy body is matched by its code and words, which a server behind the
+ * runtime can send after it ran the call. Each stays ONE small function, so a
+ * refusal has exactly one place it is recognised — and each attempt is written
+ * down as one footprintjs attempt record.
  */
 export type RetryDecision = (response: Response, 
 /**
@@ -297,6 +315,13 @@ export interface RetryRule {
     /** The caller's own name for the endpoint, reported as `endpoint`. */
     readonly endpointLabel?: string;
     readonly onRetry?: (info: ThrottleRetryInfo) => void;
+    /**
+     * Set only by an adapter that retries this refusal as its own policy
+     * (`sessionBusy.ts`): what it assumes in doing so. The assumption is recorded
+     * beside each repeat (`permission: { by: 'adapter', assumes }`) — never as
+     * evidence: the attempt's effect stays `unknown`.
+     */
+    readonly assumes?: 'refused-before-execution';
 }
 /**
  * @internal A rule from a caller's options — `undefined` when retry is off
@@ -307,7 +332,7 @@ export interface RetryRule {
  * @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;
+export declare function retryRule(kind: RetryKind, decide: RetryDecision, config: RetryOnThrottle | undefined, defaults: RetryDefaults, where: string, assumes?: 'refused-before-execution'): RetryRule | undefined;
 /**
  * Wrap a `fetch` so HTTP 429 responses are retried, honouring `Retry-After`.
  *
@@ -346,19 +371,37 @@ export declare function retryRule(kind: RetryKind, decide: RetryDecision, config
  */
 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`).
+ * @internal The series for a transport whose 429 rule is off (`retryOnThrottle:
+ * false`) while the app's replay declaration still needs one (`replay.ts` ·
+ * `needsSeries`): a tool declared repeatable on `'network'`, or the
+ * `'app-authorized'` policy, whose record and "may have run" rest on the series.
+ * `retryOnThrottle: false` turns off the 429 rule and nothing else, so its one
+ * rule is that rule switched off: it recognises no response and holds the
+ * call's budget (`retryOnThrottle`'s defaults). A transport fetch that already
+ * runs a series is joined, as `retryingFetch` joins it.
+ */
+export declare function seriesWithoutThrottle(inner: ThrottleFetch | undefined): ThrottleFetch;
+/**
+ * @internal What one call's series is built from: the rules it asks, in order;
+ * 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`); and
+ * the app's replay declaration — who may send a tool call again (`replay.ts`).
+ * No declaration is the compatibility policy, naming no tool.
  */
 export interface SeriesSpec {
     readonly rules: readonly RetryRule[];
     readonly ledger?: RequestLedger;
+    readonly replay?: ReplayDeclaration;
 }
-/** @internal What a joinable fetch's series can be rebuilt with: one more rule, or a ledger. */
+/**
+ * @internal What a joinable fetch's series can be rebuilt with: one more rule,
+ * or a ledger and the replay declaration (they arrive together, from `mcpClient`).
+ */
 export type SeriesJoin = {
     readonly rule: RetryRule;
 } | {
     readonly ledger: RequestLedger;
+    readonly replay?: ReplayDeclaration;
 };
 /** @internal `spec` with `join` in it. */
 export declare function joinedSpec(spec: SeriesSpec, join: SeriesJoin): SeriesSpec;
@@ -372,10 +415,11 @@ export declare function joinedSpec(spec: SeriesSpec, join: SeriesJoin): SeriesSp
 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.
+ * `ledger`, and asks `replay` before sending a tool call again — 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;
+export declare function ledgeredFetch(fetch: ThrottleFetch, ledger: RequestLedger, replay?: ReplayDeclaration): 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;