agentfootprint 11.2.0 → 11.3.0

package/dist/mcp/seriesEvidence.js

@@ -0,0 +1,251 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.rowOf = exports.SeriesEvidence = void 0;
+const requestEvidence_js_1 = require("../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. */
+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 < requestEvidence_js_1.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.
+        }
+    }
+}
+exports.SeriesEvidence = SeriesEvidence;
+/**
+ * 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. */
+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' }),
+    };
+}
+exports.rowOf = rowOf;
+/** 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/mcp/seriesEvidence.js.map

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