agentfootprint 11.3.0 → 11.5.0

package/dist/esm/mcp/requestLedger.js

@@ -1,73 +1,146 @@
 /**
  * requestLedger — which dispatched tool call an MCP request belongs to, so the
- * retry series that sends it files its attempts into THAT call's run; and when
- * the MCP SDK cancels a request, so the series sending it stops.
+ * retry series that sends it files its attempts into THAT call's run; when the
+ * MCP SDK cancels a request, so the series sending it stops; and whether the
+ * request's JSON-RPC answer arrived.
  *
  * Pattern: a per-connection ledger + the SDK transport's `send`, watched in place.
  * Role:    The middle of the evidence seam (`tools/requestEvidence.ts` is its
  *          door). The retry series runs inside the transport's `fetch`, which
  *          the MCP SDK calls with a serialized body and nothing else — no tool
- *          call, no run. Three hops carry the call down to it, each by an
- *          identity the hop already holds:
+ *          call, no run. Three hops carry the call down to it:
  *
- *   1. call → params    `issue`: the MCP tool keys its ticket by the request's
- *                       params OBJECT. The SDK puts that very object into the
- *                       JSON-RPC message it hands the transport.
- *   2. params → id      the watched `send` finds the ticket by `message.params`
- *                       and keys it by the JSON-RPC `id` the SDK assigned, until
- *                       that send settles.
+ *   1. call → marker    `issue`: the MCP tool gets a library-private marker and
+ *                       puts it in its request's `_meta` (`callMarker.ts`). It
+ *                       survives an SDK that copies the params.
+ *   2. marker → id      the watched `send` takes the marker out of the message
+ *                       — the server receives the bytes it always did — and
+ *                       keys the call by the JSON-RPC `id` the SDK assigned.
  *   3. id → series      `claim`: the series reads the `id` back out of the body
  *                       it is about to send.
  *
  * CANCELLATION DOES NOT WAIT ON ATTRIBUTION. Every `tools/call` in flight gets
- * an entry, ticket or not, and the SDK says when it gives a request up: it sends
- * `notifications/cancelled` naming the request's id — on its own timeout, or
- * when the call's signal fires — through this same `send`. The ledger aborts
- * that request's series there and then, so a request nobody waits for is never
- * asked again, even when its params could not be matched to a call.
+ * an entry, matched or not, and the SDK says when it gives a request up: it
+ * sends `notifications/cancelled` naming the request's id — on its own
+ * timeout, or when the call's signal fires — through this same `send`. The
+ * ledger aborts that request's series there and then, so a request nobody waits
+ * for is never asked again, even when it could not be matched to a call.
  *
- * Nothing is added to the wire: the request the server receives is
- * byte-identical, and the SDK's own options keep their meanings. Ids are the
- * client's, one ledger per connection, so concurrent calls — and concurrent
- * runs sharing one client — can never claim each other's request. A request
- * that is not a `tools/call` (a `tools/list`, a notification, a response)
- * claims nothing.
+ * Under `'app-authorized'` (`strict`), two more things hold:
+ *   - A `tools/call` that reaches `send` without a marker this ledger issued
+ *     and has not used is REFUSED there (`replayUnavailable.ts`,
+ *     `'request-unmatched'`): its answer could not be tied to any call, so it
+ *     is never sent rather than guessed at.
+ *   - Each matched request's answer is AWAITED, by its id: the connection's
+ *     incoming messages are observed for the JSON-RPC response to it. A 202, or
+ *     a stream, is not that answer. The watch ends when the answer arrives,
+ *     when the SDK cancels the request, when the call settles (found by its
+ *     marker, never by its params object) or when the connection closes —
+ *     never when only the HTTP send finished, since a 202 or a stream can still
+ *     carry the answer later.
+ *
+ * Whether the answers are observed at all is established once, at
+ * initialization: the `initialize` answer must pass the observer
+ * (`answersObserved`). An SDK whose `connect` replaces the transport's
+ * `onmessage` instead of keeping it leaves the observer out, and a call under
+ * `'app-authorized'` is then refused before it is sent (`replayUnavailable.ts`).
+ *
+ * Ids are the client's, one ledger per connection, so concurrent calls — and
+ * concurrent runs sharing one client — can never claim each other's request. A
+ * request that is not a `tools/call` (a `tools/list`, a notification, a
+ * response) claims nothing.
  *
  * `send` is installed as an OWN property of the transport instance — the same
  * object, its own `send` bound to it, so a transport class with `#private`
  * fields works as it always did. Assigning `send` again afterwards THROWS: a
  * send that bypassed the ledger would quietly lose every call's attempts.
  *
+ * Each matched `tools/call` also gets ONE `RequestReplay` (`replay.ts`), the
+ * facts its series, this ledger and its call share: the series' claim hands it
+ * over by the request's id, the call reads it from the entry it was issued
+ * (`IssuedCall`), which outlives the connection's close. The
+ * series writes what HTTP showed; this ledger writes whether the JSON-RPC
+ * answer arrived; the call writes how it settled.
+ *
  * What it does NOT do: retry, wait, or decide anything. The series is the one
  * retry owner; this only tells it whose attempts it is making, and when the SDK
  * has stopped waiting for them.
  */
-/** The method whose requests a tool call issues tickets for. */
+import { takeMarker } from './callMarker.js';
+import { RequestReplay } from './replay.js';
+import { McpReplayUnavailableError } from './replayUnavailable.js';
+/** The method whose requests a tool call issues markers for. */
 const TOOLS_CALL = 'tools/call';
 /** The notification the SDK sends when it gives up one of its own requests. */
 const CANCELLED = 'notifications/cancelled';
-/** Per connection: the tickets issued and not yet sent, and the requests being sent. */
+/** The request whose answer proves the observer sees this connection's answers. */
+const INITIALIZE = 'initialize';
+const LENIENT = { server: 'mcp', strict: false };
+/** Per connection: the calls issued and not yet settled, the requests being sent, the answers awaited. */
 export class RequestLedger {
-    /** Issued, not yet sent — keyed by the request's params object. Collected with it. */
-    issued = new WeakMap();
-    /** Tickets a request was bound to. */
-    bound = new WeakSet();
+    options;
+    /** Every call issued and not yet settled — keyed by its marker. */
+    issued = new Map();
     /** Every `tools/call` sent and not yet settled — keyed by its JSON-RPC id. */
     sending = new Map();
+    /** Matched requests whose JSON-RPC answer is awaited (`strict` only) — by id. */
+    awaiting = new Map();
+    initializeId;
+    initializeAnswered = false;
+    markers = 0;
     calls = 0;
     unboundNamed = false;
-    /** The call about to send `params` files its attempts through `ticket`. */
-    issue(params, ticket) {
-        this.issued.set(params, ticket);
+    constructor(options = LENIENT) {
+        this.options = options;
     }
-    /** Whether a request the transport sent was bound to `ticket`. */
-    wasBound(ticket) {
-        return this.bound.has(ticket);
+    /**
+     * A call is about to send its request: its entry, whose `marker` the call
+     * puts in the request's `_meta` (`callMarker.ts` · `markParams`). `ticket`
+     * is where its attempts are filed, when the call carries the run's evidence
+     * port.
+     */
+    issue(ticket) {
+        this.markers += 1;
+        const call = {
+            marker: `call-${this.markers}`,
+            ...(ticket !== undefined && { ticket }),
+        };
+        this.issued.set(call.marker, call);
+        return call;
+    }
+    /** `call` settled: forget it, and stop awaiting its request's answer. */
+    settle(call) {
+        if (this.issued.get(call.marker) === call)
+            this.issued.delete(call.marker);
+        const request = call.request;
+        if (request !== undefined && this.awaiting.get(request.id) === request.replay) {
+            this.awaiting.delete(request.id);
+        }
+    }
+    /** The connection closed: nothing it sent is awaited, and no call is pending, any more. */
+    close() {
+        this.issued.clear();
+        this.sending.clear();
+        this.awaiting.clear();
+    }
+    /**
+     * Whether this connection's answers pass the observer: the `initialize`
+     * answer did. Read once the connection is initialized.
+     */
+    get answersObserved() {
+        return this.initializeAnswered;
     }
     /** How many `tools/call` requests the watched transport has sent — matched to a call or not. */
     get toolCallsSent() {
         return this.calls;
     }
+    /**
+     * @internal How many entries the ledger holds: calls issued and not settled,
+     * requests being sent, answers awaited. Zero once every call settled.
+     */
+    get retained() {
+        return this.issued.size + this.sending.size + this.awaiting.size;
+    }
     /** `true` the first time it is asked, then never again: an unmatched request is named once per connection. */
     firstUnbound() {
         if (this.unboundNamed)
@@ -80,6 +153,11 @@ export class RequestLedger {
      * original bound to the instance itself. Returns the SAME object — or
      * `undefined` when it has no `send` to watch or refuses the property, and
      * then nothing is watched and no call should expect its attempts filed.
+     *
+     * Its incoming messages are watched too: an `onmessage` set before the
+     * client connects, which the current MCP SDK's `Protocol.connect` keeps and
+     * calls before its own dispatch. Whether it was kept is known once the
+     * `initialize` answer has, or has not, passed it (`answersObserved`).
      */
     watch(transport) {
         const send = Reflect.get(transport, 'send');
@@ -102,8 +180,37 @@ export class RequestLedger {
         catch {
             return undefined;
         }
+        this.watchMessages(transport);
         return transport;
     }
+    /** Observe incoming messages before whatever handled them already — never instead of it. */
+    watchMessages(transport) {
+        try {
+            const before = Reflect.get(transport, 'onmessage');
+            const handled = typeof before === 'function' ? before : undefined;
+            const observing = (message, extra) => {
+                this.observe(message);
+                handled?.(message, extra);
+            };
+            Reflect.set(transport, 'onmessage', observing);
+        }
+        catch {
+            // A transport that refuses it is never observed: `answersObserved` stays false.
+        }
+    }
+    /** One incoming message: the `initialize` answer, or the answer to an awaited request. */
+    observe(message) {
+        const id = responseIdOf(message);
+        if (id === undefined)
+            return;
+        if (id === this.initializeId)
+            this.initializeAnswered = true;
+        const replay = this.awaiting.get(id);
+        if (replay === undefined)
+            return;
+        this.awaiting.delete(id);
+        replay.answered();
+    }
     /**
      * The `tools/call` request `body` carries, while its send runs — its ticket
      * when a call issued one, and the signal its cancellation fires. `undefined`
@@ -126,44 +233,60 @@ export class RequestLedger {
         return {
             ...(entry.ticket !== undefined && { ticket: entry.ticket }),
             cancelled: entry.cut.signal,
+            replay: entry.replay,
         };
     }
     /** One message through the watched transport. */
     send(original, message, options) {
         this.cancelIfAsked(message);
-        const id = this.bind(message);
+        this.noteInitialize(message);
+        const id = requestIdOf(message);
         if (id === undefined)
             return original(message, options);
-        const entry = this.sending.get(id);
+        // The marker comes out before anything else: the server never sees it.
+        const taken = takeMarker(message);
+        const call = taken.marker === undefined ? undefined : this.issued.get(taken.marker);
+        // One request per marker: a second message carrying it is not this call's.
+        const matched = call !== undefined && call.request === undefined ? call : undefined;
+        if (matched === undefined && this.options.strict) {
+            return Promise.reject(new McpReplayUnavailableError('request-unmatched', this.options.server, toolNameOf(message)));
+        }
+        this.calls += 1;
+        const replay = new RequestReplay(id, this.initializeAnswered);
+        if (matched !== undefined) {
+            matched.request = { id, replay };
+            if (this.options.strict)
+                this.awaiting.set(id, replay);
+        }
+        const entry = {
+            ...(matched?.ticket !== undefined && { ticket: matched.ticket }),
+            cut: new AbortController(),
+            replay,
+        };
+        this.sending.set(id, entry);
         const release = () => {
             if (this.sending.get(id) === entry)
                 this.sending.delete(id);
         };
         try {
-            return Promise.resolve(original(message, options)).finally(release);
+            return Promise.resolve(original(taken.message, options)).finally(release);
         }
         catch (err) {
             release();
             throw err;
         }
     }
-    /** Register a `tools/call` in flight, with the ticket its params were issued — if any. */
-    bind(message) {
-        const id = requestIdOf(message);
-        if (id === undefined)
-            return undefined;
-        this.calls += 1;
-        const params = message.params;
-        const ticket = params !== null && typeof params === 'object' ? this.issued.get(params) : undefined;
-        if (ticket !== undefined) {
-            // One request per ticket: a second message reusing these params is not this call's.
-            this.issued.delete(params);
-            this.bound.add(ticket);
-        }
-        this.sending.set(id, { ...(ticket !== undefined && { ticket }), cut: new AbortController() });
-        return id;
+    /** The `initialize` request: its answer is the one that proves the observer is in place. */
+    noteInitialize(message) {
+        if (message === null || typeof message !== 'object' || Array.isArray(message))
+            return;
+        const { method, id } = message;
+        if (method !== INITIALIZE || (typeof id !== 'string' && typeof id !== 'number'))
+            return;
+        this.initializeId = id;
+        this.initializeAnswered = false;
     }
-    /** The SDK gave a request up: stop the series still sending it. */
+    /** The SDK gave a request up: stop the series still sending it, and stop awaiting its answer. */
     cancelIfAsked(message) {
         if (message === null || typeof message !== 'object' || Array.isArray(message))
             return;
@@ -174,12 +297,30 @@ export class RequestLedger {
         if (typeof requestId !== 'string' && typeof requestId !== 'number')
             return;
         this.sending.get(requestId)?.cut.abort(sdkCancelled());
+        this.awaiting.delete(requestId);
     }
 }
 /** The reason a series stops when the SDK cancelled its request — a fixed sentence. */
 function sdkCancelled() {
     return Object.assign(new Error('The MCP SDK cancelled this request.'), { name: 'AbortError' });
 }
+/** The tool a `tools/call` names — what a refusal names. Never its arguments. */
+function toolNameOf(message) {
+    const params = message.params;
+    const name = params !== null && typeof params === 'object'
+        ? params.name
+        : undefined;
+    return typeof name === 'string' ? name : 'tools/call';
+}
+/** The id of a JSON-RPC RESPONSE — a result or an error, never a request or a notification. */
+function responseIdOf(message) {
+    if (message === null || typeof message !== 'object' || Array.isArray(message))
+        return undefined;
+    const fields = message;
+    if (fields.method !== undefined || !('result' in fields || 'error' in fields))
+        return undefined;
+    return typeof fields.id === 'string' || typeof fields.id === 'number' ? fields.id : undefined;
+}
 /** The id of a `tools/call` REQUEST — a response or a notification has none to claim. */
 function requestIdOf(message) {
     if (message === null || typeof message !== 'object' || Array.isArray(message))

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

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

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

@@ -28,17 +28,31 @@
  * 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 type { AttemptRecord } from 'footprintjs';
-import type { ToolRequestAttempt, ToolRequestReason } from '../events/payloads.js';
+import type { ToolRequestAttempt, ToolRequestEffect, ToolRequestPermission, ToolRequestReason } from '../events/payloads.js';
 import { type RequestEvidence, type RequestEvidenceSink } from '../tools/requestEvidence.js';
+import { type RequestReplay } from './replay.js';
 /** Where the request went, as a row may say it: the app's label for it, or its origin. */
 export type RequestWhere = Pick<RequestEvidence, 'endpoint' | 'origin'>;
 /** What the series saw of one attempt that its record does not hold. */
@@ -52,24 +66,49 @@ export interface AttemptSeen {
     };
 }
 /** Why the series' `retryOn` said no — the reasons the runner calls `declined`. */
-export type DeclineReason = Extract<ToolRequestReason, 'exhausted' | 'wait-limit' | 'no-time-left' | 'not-replayable' | 'not-retryable'>;
+export type DeclineReason = Extract<ToolRequestReason, 'exhausted' | 'wait-limit' | 'no-time-left' | 'not-replayable' | 'not-retryable' | 'not-permitted' | 'changes-without-key'>;
+/**
+ * What the series knows of one attempt beyond the runner's record (`replay.ts`):
+ * its effect — absent for an answered attempt, which the call's verdict decides
+ * when the record is filed — what permitted the next attempt, and how long it
+ * took.
+ */
+export interface AttemptFacts {
+    readonly effect?: ToolRequestEffect;
+    readonly permission?: ToolRequestPermission;
+    readonly durationMs: number;
+}
+/**
+ * Where the record waits for its call: the call's signal (it fires when the
+ * call settles or is cancelled), and the facts the call leaves there.
+ */
+export interface Settlement {
+    readonly signal: AbortSignal;
+    readonly replay: RequestReplay;
+}
 /** One request's evidence, collected as its series runs and filed once. */
 export declare class SeriesEvidence {
     private readonly sink;
     private readonly where;
+    private readonly settlement?;
     private readonly rows;
     private omitted;
     private last;
     private filed;
-    constructor(sink: RequestEvidenceSink, where: RequestWhere);
-    /** One attempt as the runner recorded it. */
-    attempt(record: AttemptRecord, seen: AttemptSeen | undefined, declined?: DeclineReason): void;
+    private waiting;
+    /** What is known of the series' effect, attempt by attempt — the answer's excepted. */
+    private readonly knowledge;
+    /** The answered attempt, while its effect waits for the call's verdict. */
+    private answer;
+    constructor(sink: RequestEvidenceSink, where: RequestWhere, settlement?: Settlement | undefined);
+    /** One attempt as the runner recorded it, with what the series knows of it. */
+    attempt(record: AttemptRecord, seen: AttemptSeen | undefined, declined?: DeclineReason, facts?: AttemptFacts): void;
     /**
      * The caller's cancellation cut attempt `n` in flight. It was sent — the
      * server may have it, and may have run it — so it is a row, `cut`, with the
      * remote outcome `unknown`; then the request's end says the same.
      */
-    cutInFlight(n: number): void;
+    cutInFlight(n: number, durationMs?: number): void;
     /**
      * The caller's cancellation landed with NO request in flight: between two —
      * `during: 'wait'`, the next request never sent — or before the first, when
@@ -82,7 +121,7 @@ export declare 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(): void;
     /**
@@ -92,11 +131,30 @@ export declare 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: boolean): void;
     private add;
+    /**
+     * 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.
+     */
+    private fileWhenSettled;
     private file;
+    /**
+     * 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.
+     */
+    private settleAnswer;
 }
 /** One record as a row — see the module note for what a row may say. */
 export declare function rowOf(record: AttemptRecord, seen: AttemptSeen | undefined, declined?: DeclineReason): ToolRequestAttempt;
+/**
+ * `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 declare function withFacts(row: ToolRequestAttempt, facts: AttemptFacts | undefined): ToolRequestAttempt;