agentfootprint 11.2.0 → 11.4.0

package/dist/esm/mcp/requestLedger.js

@@ -0,0 +1,192 @@
+/**
+ * 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.
+ *
+ * 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:
+ *
+ *   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.
+ *   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.
+ *
+ * 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.
+ *
+ * `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.
+ *
+ * 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. */
+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. */
+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();
+    /** Every `tools/call` sent and not yet settled — keyed by its JSON-RPC id. */
+    sending = new Map();
+    calls = 0;
+    unboundNamed = false;
+    /** The call about to send `params` files its attempts through `ticket`. */
+    issue(params, ticket) {
+        this.issued.set(params, ticket);
+    }
+    /** Whether a request the transport sent was bound to `ticket`. */
+    wasBound(ticket) {
+        return this.bound.has(ticket);
+    }
+    /** How many `tools/call` requests the watched transport has sent — matched to a call or not. */
+    get toolCallsSent() {
+        return this.calls;
+    }
+    /** `true` the first time it is asked, then never again: an unmatched request is named once per connection. */
+    firstUnbound() {
+        if (this.unboundNamed)
+            return false;
+        this.unboundNamed = true;
+        return true;
+    }
+    /**
+     * Watch `transport`'s `send`: install a wrapped `send` as its OWN property, the
+     * 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.
+     */
+    watch(transport) {
+        const send = Reflect.get(transport, 'send');
+        if (typeof send !== 'function')
+            return undefined;
+        const original = send.bind(transport);
+        const watched = (message, options) => this.send(original, message, options);
+        try {
+            Object.defineProperty(transport, 'send', {
+                configurable: false,
+                enumerable: false,
+                get: () => watched,
+                set: () => {
+                    throw new TypeError("mcpClient: this transport's `send` is watched by its request ledger, which " +
+                        'matches each tools/call request to the call that sent it. Assigning `send` ' +
+                        'again would send requests the ledger never sees, so it is refused.');
+                },
+            });
+        }
+        catch {
+            return undefined;
+        }
+        return transport;
+    }
+    /**
+     * The `tools/call` request `body` carries, while its send runs — its ticket
+     * when a call issued one, and the signal its cancellation fires. `undefined`
+     * for any other body. Parses only while some request is being sent.
+     */
+    claim(body) {
+        if (this.sending.size === 0 || typeof body !== 'string')
+            return undefined;
+        let message;
+        try {
+            message = JSON.parse(body);
+        }
+        catch {
+            return undefined;
+        }
+        const id = requestIdOf(message);
+        const entry = id === undefined ? undefined : this.sending.get(id);
+        if (entry === undefined)
+            return undefined;
+        return {
+            ...(entry.ticket !== undefined && { ticket: entry.ticket }),
+            cancelled: entry.cut.signal,
+        };
+    }
+    /** One message through the watched transport. */
+    send(original, message, options) {
+        this.cancelIfAsked(message);
+        const id = this.bind(message);
+        if (id === undefined)
+            return original(message, options);
+        const entry = this.sending.get(id);
+        const release = () => {
+            if (this.sending.get(id) === entry)
+                this.sending.delete(id);
+        };
+        try {
+            return Promise.resolve(original(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 SDK gave a request up: stop the series still sending it. */
+    cancelIfAsked(message) {
+        if (message === null || typeof message !== 'object' || Array.isArray(message))
+            return;
+        const { method, params } = message;
+        if (method !== CANCELLED || params === null || typeof params !== 'object')
+            return;
+        const requestId = params.requestId;
+        if (typeof requestId !== 'string' && typeof requestId !== 'number')
+            return;
+        this.sending.get(requestId)?.cut.abort(sdkCancelled());
+    }
+}
+/** 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 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))
+        return undefined;
+    const { method, id } = message;
+    if (method !== TOOLS_CALL)
+        return undefined;
+    return typeof id === 'string' || typeof id === 'number' ? id : undefined;
+}
+//# sourceMappingURL=requestLedger.js.map

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

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

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

@@ -0,0 +1,102 @@
+/**
+ * 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 type { AttemptRecord } from 'footprintjs';
+import type { ToolRequestAttempt, ToolRequestReason } from '../events/payloads.js';
+import { type RequestEvidence, type RequestEvidenceSink } from '../tools/requestEvidence.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. */
+export interface AttemptSeen {
+    /** The response's status, when a response arrived. */
+    readonly status?: number;
+    /** The refusal a rule recognised in that response, when one did. */
+    readonly refusal?: {
+        readonly kind: 'throttle' | 'session-busy';
+        readonly retryAfterMs?: number;
+    };
+}
+/** 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'>;
+/** One request's evidence, collected as its series runs and filed once. */
+export declare class SeriesEvidence {
+    private readonly sink;
+    private readonly where;
+    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;
+    /**
+     * 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;
+    /**
+     * 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(): void;
+    /**
+     * 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(): void;
+    /**
+     * 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: boolean): void;
+    private add;
+    private file;
+}
+/** 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;

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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"}