@bevel-software/platform-core-backend 0.14.0 → 0.19.0

package/dist/modules/mcp/first-call-probe.d.ts

@@ -0,0 +1,165 @@
+/**
+ * The reproduction probe behind "the first `start_session` on a fresh
+ * connection failed; the immediate retry worked".
+ *
+ * The report that opened the ticket carried a generic error tagged `req_011…`
+ * — the Anthropic API's request-id shape, which nothing on this side mints —
+ * so the failure was most likely raised between the model and the tool rather
+ * than by the tool. That was a hypothesis, and a hypothesis is not evidence:
+ * this probe is how the platform side gets measured instead of assumed.
+ *
+ * What it reproduces, deliberately:
+ *   - FRESH connections, not one connection reused. Each attempt builds its own
+ *     `Client` and its own Streamable-HTTP transport, so each one pays for its
+ *     own `initialize` before the call — the exact shape of the report.
+ *   - The FIRST call on each, and only the first. A retry would hide the very
+ *     failure being hunted.
+ *   - All of them AT ONCE by default, because a busy agent tester opens
+ *     connections in bursts and a first-call failure that only shows under
+ *     contention would never appear one connection at a time.
+ *
+ * Two modes, because the answer the ticket needs is *where* a failure lives:
+ *   - `'mcp'` (default) — the whole client path: transport handshake, then one
+ *     `tools/call`. This is what the tester's client does.
+ *   - `'tool'` — one plain POST to the tool route, no MCP transport at all.
+ *     If `'mcp'` fails where `'tool'` does not, the fault is in the transport
+ *     or in front of it; if both fail, it is the handler.
+ *
+ * The probe never retries: it records. Timings and every failure's own error
+ * text land in the report, so what goes into the ticket log is the platform's
+ * own message rather than a client-side id.
+ */
+/** Which path to the tool a single attempt takes. See the module comment. */
+export type ProbeMode = 'mcp' | 'tool';
+/** Where an attempt died. `parse` means the call answered but carried no id. */
+export type ProbeStage = 'connect' | 'call' | 'parse';
+/** One fresh connection's one first call. */
+export interface FirstCallAttempt {
+    /** 0-based position in the burst, so a failure can be located in the log. */
+    index: number;
+    ok: boolean;
+    /** Handshake time. Always 0 in `'tool'` mode, which has no handshake. */
+    connectMs: number;
+    /** The `start_session` call itself, measured from after the handshake. */
+    callMs: number;
+    /** Connection open → id in hand (or failure): what the caller actually waits. */
+    totalMs: number;
+    /** The minted id, on success. */
+    sessionId?: string;
+    /** Set only on failure. */
+    stage?: ProbeStage;
+    /** The error exactly as the platform (or the transport) worded it. */
+    error?: string;
+}
+/** Nearest-rank summary of one timing series, in milliseconds. */
+export interface ProbeTimings {
+    min: number;
+    p50: number;
+    p95: number;
+    max: number;
+}
+export interface FirstCallProbeReport {
+    /** The endpoint probed, as given — this is what names the run in the log. */
+    target: string;
+    mode: ProbeMode;
+    toolName: string;
+    connections: number;
+    ok: number;
+    failed: number;
+    /**
+     * Distinct ids across the successful attempts. Anything below `ok` means two
+     * fresh connections were handed the same session id — a far worse bug than
+     * the one being hunted, so it is counted even though nobody expects it.
+     */
+    distinctSessionIds: number;
+    /** How long the whole burst took, start to last attempt settled. */
+    wallClockMs: number;
+    /**
+     * Timings over the SUCCESSFUL attempts only: a failure's elapsed time
+     * measures how long the failure took, which would distort the percentiles
+     * of the healthy path. Each failure carries its own timings in `failures`.
+     */
+    connect: ProbeTimings;
+    call: ProbeTimings;
+    total: ProbeTimings;
+    /** Every failed attempt, with its stage and the error text as received. */
+    failures: FirstCallAttempt[];
+    /** Every attempt in burst order, successes included. */
+    attempts: FirstCallAttempt[];
+}
+export interface FirstCallProbeOptions {
+    /** Deployment root, e.g. `https://core-staging.bevel.software` (no `/api`). */
+    baseUrl: string;
+    /** A connection key (`bevel_…`) or another bearer the MCP surface accepts. */
+    bearer: string;
+    /** Fresh connections to open. The ticket's number is fifty. */
+    connections?: number;
+    /** Cap on attempts in flight. Defaults to `connections`: one single burst. */
+    concurrency?: number;
+    mode?: ProbeMode;
+    /** Overridable only so a test can point the probe at a stand-in tool. */
+    toolName?: string;
+    /** Per-request ceiling, so a hung connection is a recorded failure. */
+    timeoutMs?: number;
+    /** Injectable clock (milliseconds), for tests that assert on timings. */
+    now?: () => number;
+}
+/**
+ * Nearest-rank percentiles: the smallest sample with at least p% of samples at
+ * or below it. Same convention as the MCP latency measurement in
+ * `mcp.e2e.test.ts`, so numbers from the two are comparable. An empty series
+ * (every attempt failed) reports zeros rather than NaN — a log full of NaN
+ * hides the failure list underneath it.
+ */
+export declare function timingsOf(samples: readonly number[]): ProbeTimings;
+/**
+ * Turn a settled burst into the report. Pure: `probeFirstCall` runs the
+ * attempts, this decides what they mean, and the two are separable so the
+ * arithmetic can be tested without opening a socket.
+ */
+export declare function summarizeProbe(attempts: readonly FirstCallAttempt[], meta: {
+    target: string;
+    mode: ProbeMode;
+    toolName: string;
+    wallClockMs: number;
+}): FirstCallProbeReport;
+/**
+ * The report as the block that goes into the ticket log: the counts, the
+ * timings, and then every failure spelled out with the stage it died at and
+ * the error as the platform worded it. A run with no failures says so in as
+ * many words — "no failure reproduced" is this ticket's most likely finding
+ * and it has to be as legible as a failure would be.
+ *
+ * Every value that did not come from this file goes through `printable`: the
+ * error text is whatever a remote endpoint chose to send, and the target and
+ * tool name are whatever the operator typed. A newline or an ANSI escape in
+ * any of them would otherwise forge or restyle the lines around it, in the one
+ * output a reader trusts to say what the platform actually did.
+ */
+export declare function formatProbeReport(report: FirstCallProbeReport): string;
+/**
+ * The id out of a `tools/call` result. The tool answers `{ sessionId }`, which
+ * reaches a client either as `structuredContent` or — the shape the KB surface
+ * actually sends — as one JSON text block. Read both rather than betting on
+ * one, and treat "answered, but with no id in it" as a failure of its own
+ * (`parse`): a 200 carrying nothing usable is not a success.
+ */
+export declare function readSessionId(result: unknown): string | undefined;
+/**
+ * An option the probe cannot run with — a malformed base URL, a count that is
+ * not a count. Its own class so a front end can tell the operator's typo
+ * (usage, exit 2) from a probe that crashed (exit 1) without reading prose.
+ */
+export declare class ProbeOptionsError extends Error {
+}
+/**
+ * Open `connections` fresh connections, make exactly one first call on each,
+ * and report. Never throws for a failed attempt — a thrown probe would lose
+ * the other forty-nine results, and those are the evidence. It DOES throw for
+ * arguments it cannot probe with at all (a count that is not a positive
+ * integer, a base URL that is not an absolute http(s) URL), and it throws
+ * before the burst starts, so
+ * there is never a half-run whose numbers mean nothing.
+ */
+export declare function probeFirstCall(options: FirstCallProbeOptions): Promise<FirstCallProbeReport>;
+//# sourceMappingURL=first-call-probe.d.ts.map

package/dist/modules/mcp/first-call-probe.d.ts.map

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

package/dist/modules/mcp/first-call-probe.js

@@ -0,0 +1,298 @@
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import { printable } from '../../shared/printable.js';
+const DEFAULT_CONNECTIONS = 50;
+const DEFAULT_TIMEOUT_MS = 30_000;
+/** The platform's own wording, whatever was thrown. */
+function errorText(err) {
+    if (err instanceof Error)
+        return err.message;
+    if (typeof err === 'string')
+        return err;
+    try {
+        return JSON.stringify(err);
+    }
+    catch {
+        return String(err);
+    }
+}
+/**
+ * Nearest-rank percentiles: the smallest sample with at least p% of samples at
+ * or below it. Same convention as the MCP latency measurement in
+ * `mcp.e2e.test.ts`, so numbers from the two are comparable. An empty series
+ * (every attempt failed) reports zeros rather than NaN — a log full of NaN
+ * hides the failure list underneath it.
+ */
+export function timingsOf(samples) {
+    if (samples.length === 0)
+        return { min: 0, p50: 0, p95: 0, max: 0 };
+    const sorted = [...samples].sort((a, b) => a - b);
+    const pct = (p) => sorted[Math.min(sorted.length - 1, Math.max(0, Math.ceil(sorted.length * p) - 1))];
+    return { min: sorted[0], p50: pct(0.5), p95: pct(0.95), max: sorted[sorted.length - 1] };
+}
+/**
+ * Turn a settled burst into the report. Pure: `probeFirstCall` runs the
+ * attempts, this decides what they mean, and the two are separable so the
+ * arithmetic can be tested without opening a socket.
+ */
+export function summarizeProbe(attempts, meta) {
+    const ok = attempts.filter((a) => a.ok);
+    const failures = attempts.filter((a) => !a.ok);
+    return {
+        ...meta,
+        connections: attempts.length,
+        ok: ok.length,
+        failed: failures.length,
+        distinctSessionIds: new Set(ok.map((a) => a.sessionId)).size,
+        connect: timingsOf(ok.map((a) => a.connectMs)),
+        call: timingsOf(ok.map((a) => a.callMs)),
+        total: timingsOf(ok.map((a) => a.totalMs)),
+        failures,
+        attempts: [...attempts],
+    };
+}
+/** `41.2ms` — one decimal is the resolution the numbers actually carry. */
+const ms = (n) => `${n.toFixed(1)}ms`;
+const line = (label, t) => `  ${label.padEnd(8)} p50 ${ms(t.p50)}  p95 ${ms(t.p95)}  min ${ms(t.min)}  max ${ms(t.max)}`;
+/**
+ * The report as the block that goes into the ticket log: the counts, the
+ * timings, and then every failure spelled out with the stage it died at and
+ * the error as the platform worded it. A run with no failures says so in as
+ * many words — "no failure reproduced" is this ticket's most likely finding
+ * and it has to be as legible as a failure would be.
+ *
+ * Every value that did not come from this file goes through `printable`: the
+ * error text is whatever a remote endpoint chose to send, and the target and
+ * tool name are whatever the operator typed. A newline or an ANSI escape in
+ * any of them would otherwise forge or restyle the lines around it, in the one
+ * output a reader trusts to say what the platform actually did.
+ */
+export function formatProbeReport(report) {
+    const lines = [
+        `${report.connections} fresh connections, one first ${printable(report.toolName)} call each — ${printable(report.target)} (${report.mode} mode)`,
+        `  ${report.ok}/${report.connections} succeeded, ${report.failed} failed, ` +
+            `${report.distinctSessionIds} distinct session ids, ${ms(report.wallClockMs)} wall clock`,
+        line('connect', report.connect),
+        line('call', report.call),
+        line('total', report.total),
+    ];
+    if (report.failures.length === 0) {
+        lines.push('  no failure reproduced');
+    }
+    else {
+        for (const f of report.failures) {
+            lines.push(`  FAILED #${f.index} at ${f.stage} after ${ms(f.totalMs)}: ${printable(f.error ?? '')}`);
+        }
+    }
+    return lines.join('\n');
+}
+/**
+ * The id out of a `tools/call` result. The tool answers `{ sessionId }`, which
+ * reaches a client either as `structuredContent` or — the shape the KB surface
+ * actually sends — as one JSON text block. Read both rather than betting on
+ * one, and treat "answered, but with no id in it" as a failure of its own
+ * (`parse`): a 200 carrying nothing usable is not a success.
+ */
+export function readSessionId(result) {
+    const res = (result ?? {});
+    const structured = res.structuredContent?.sessionId;
+    if (typeof structured === 'string' && structured)
+        return structured;
+    const blocks = Array.isArray(res.content) ? res.content : [];
+    for (const block of blocks) {
+        const b = block;
+        if (b.type !== 'text' || typeof b.text !== 'string')
+            continue;
+        try {
+            const parsed = JSON.parse(b.text);
+            if (typeof parsed?.sessionId === 'string' && parsed.sessionId)
+                return parsed.sessionId;
+        }
+        catch {
+            // Not JSON — an error string, or prose. Keep looking at the other blocks.
+        }
+    }
+    return undefined;
+}
+/** A fresh MCP client and transport per attempt: handshake, then one call. */
+async function mcpAttempt(index, ctx) {
+    const started = ctx.now();
+    const transport = new StreamableHTTPClientTransport(new URL(`${ctx.baseUrl}/api/mcp`), {
+        requestInit: { headers: { Authorization: `Bearer ${ctx.bearer}` } },
+    });
+    const client = new Client({ name: 'first-call-probe', version: '1.0.0' }, { capabilities: {} });
+    let connectMs = 0;
+    try {
+        await client.connect(transport, { timeout: ctx.timeoutMs });
+        connectMs = ctx.now() - started;
+    }
+    catch (err) {
+        // The handshake never completed, so there is no client to close beyond the
+        // transport the failed connect already owns.
+        await transport.close().catch(() => { });
+        return { index, ok: false, connectMs: ctx.now() - started, callMs: 0, totalMs: ctx.now() - started, stage: 'connect', error: errorText(err) };
+    }
+    const calledAt = ctx.now();
+    try {
+        const result = await client.callTool({ name: ctx.toolName, arguments: {} }, undefined, { timeout: ctx.timeoutMs });
+        const callMs = ctx.now() - calledAt;
+        const totalMs = ctx.now() - started;
+        // A tool-level error comes back as a RESULT with `isError`, not as a throw:
+        // unwrap it, or the probe would score a platform failure as a success.
+        if (result.isError) {
+            const text = Array.isArray(result.content)
+                ? result.content.find((c) => c.type === 'text')?.text
+                : undefined;
+            return { index, ok: false, connectMs, callMs, totalMs, stage: 'call', error: text ?? 'tool returned isError with no text' };
+        }
+        const sessionId = readSessionId(result);
+        if (!sessionId) {
+            return { index, ok: false, connectMs, callMs, totalMs, stage: 'parse', error: 'result carried no sessionId' };
+        }
+        return { index, ok: true, connectMs, callMs, totalMs, sessionId };
+    }
+    catch (err) {
+        return { index, ok: false, connectMs, callMs: ctx.now() - calledAt, totalMs: ctx.now() - started, stage: 'call', error: errorText(err) };
+    }
+    finally {
+        await client.close().catch(() => { });
+    }
+}
+/** One plain POST to the tool route — the same call with the transport removed. */
+async function toolAttempt(index, ctx) {
+    const started = ctx.now();
+    try {
+        const res = await fetch(`${ctx.baseUrl}/api/agent/tools/${ctx.toolName}`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${ctx.bearer}` },
+            body: '{}',
+            signal: AbortSignal.timeout(ctx.timeoutMs),
+        });
+        const text = await res.text();
+        const elapsed = ctx.now() - started;
+        if (!res.ok) {
+            return { index, ok: false, connectMs: 0, callMs: elapsed, totalMs: elapsed, stage: 'call', error: `HTTP ${res.status}: ${text.slice(0, 200)}` };
+        }
+        // The route answers the tool's JSON directly, so the id is one level up
+        // from where a `tools/call` result keeps it.
+        let sessionId;
+        try {
+            const parsed = JSON.parse(text);
+            if (typeof parsed?.sessionId === 'string' && parsed.sessionId)
+                sessionId = parsed.sessionId;
+        }
+        catch {
+            // Left undefined: reported as `parse` below, with the body in the error.
+        }
+        if (!sessionId) {
+            return { index, ok: false, connectMs: 0, callMs: elapsed, totalMs: elapsed, stage: 'parse', error: `no sessionId in: ${text.slice(0, 200)}` };
+        }
+        return { index, ok: true, connectMs: 0, callMs: elapsed, totalMs: elapsed, sessionId };
+    }
+    catch (err) {
+        const elapsed = ctx.now() - started;
+        return { index, ok: false, connectMs: 0, callMs: elapsed, totalMs: elapsed, stage: 'call', error: errorText(err) };
+    }
+}
+/**
+ * An option the probe cannot run with — a malformed base URL, a count that is
+ * not a count. Its own class so a front end can tell the operator's typo
+ * (usage, exit 2) from a probe that crashed (exit 1) without reading prose.
+ */
+export class ProbeOptionsError extends Error {
+}
+/**
+ * A count the probe can actually run with, or a refusal naming the option.
+ *
+ * `runPooled` clamps its limit with `Math.max(1, …)`, so a `concurrency` of 0
+ * or -5 would quietly become a one-at-a-time run — the opposite of the burst
+ * the caller asked for, reported as though it were the burst. A number that
+ * cannot be honoured is answered, not reinterpreted.
+ */
+function positiveInt(name, value, fallback) {
+    if (value === undefined)
+        return fallback;
+    if (!Number.isInteger(value) || value < 1) {
+        throw new ProbeOptionsError(`${name} must be a positive integer, got ${value}`);
+    }
+    return value;
+}
+/**
+ * The base URL, trailing slashes removed, checked once.
+ *
+ * `new URL(...)` throws synchronously, and `mcpAttempt` builds one before its
+ * own `try` — inside a pool worker. Left there, an empty or malformed
+ * `--base-url` would reject `Promise.all` and take all fifty results down
+ * with it, which is exactly what this probe promises never to do. It is also
+ * not an attempt failure: nothing was attempted. So it is raised here, before
+ * the burst, in the same class as a bad `connections` — and both modes answer
+ * a bad URL the same way, rather than `'tool'` recording fifty copies of a
+ * parse error while `'mcp'` threw.
+ */
+function normalizeBaseUrl(baseUrl) {
+    // A trailing slash would make the joined path `//api/mcp`, which some
+    // proxies answer differently from `/api/mcp`.
+    const trimmed = baseUrl.replace(/\/+$/, '');
+    let parsed;
+    try {
+        parsed = new URL(trimmed);
+    }
+    catch {
+        throw new ProbeOptionsError(`baseUrl must be an absolute URL, got ${printable(baseUrl)}`);
+    }
+    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+        throw new ProbeOptionsError(`baseUrl must be http or https, got ${printable(baseUrl)}`);
+    }
+    return trimmed;
+}
+/**
+ * Run `count` tasks with at most `limit` in flight. At the default
+ * `limit === count` every task starts in the same tick, which is the burst the
+ * probe is for; a smaller limit is there for an endpoint one would rather not
+ * hit fifty-wide.
+ */
+async function runPooled(count, limit, task) {
+    const results = new Array(count);
+    let next = 0;
+    const worker = async () => {
+        for (;;) {
+            const index = next++;
+            if (index >= count)
+                return;
+            results[index] = await task(index);
+        }
+    };
+    await Promise.all(Array.from({ length: Math.max(1, Math.min(limit, count)) }, worker));
+    return results;
+}
+/**
+ * Open `connections` fresh connections, make exactly one first call on each,
+ * and report. Never throws for a failed attempt — a thrown probe would lose
+ * the other forty-nine results, and those are the evidence. It DOES throw for
+ * arguments it cannot probe with at all (a count that is not a positive
+ * integer, a base URL that is not an absolute http(s) URL), and it throws
+ * before the burst starts, so
+ * there is never a half-run whose numbers mean nothing.
+ */
+export async function probeFirstCall(options) {
+    const connections = positiveInt('connections', options.connections, DEFAULT_CONNECTIONS);
+    // Clamped to `connections` further down, so asking for more in flight than
+    // there are attempts is merely the default; asking for zero or less is not a
+    // smaller burst, it is a request the probe cannot honour.
+    const concurrency = positiveInt('concurrency', options.concurrency, connections);
+    const timeoutMs = positiveInt('timeoutMs', options.timeoutMs, DEFAULT_TIMEOUT_MS);
+    const mode = options.mode ?? 'mcp';
+    const now = options.now ?? (() => performance.now());
+    const ctx = {
+        baseUrl: normalizeBaseUrl(options.baseUrl),
+        bearer: options.bearer,
+        toolName: options.toolName ?? 'start_session',
+        timeoutMs,
+        now,
+    };
+    const attempt = mode === 'mcp' ? mcpAttempt : toolAttempt;
+    const startedAt = now();
+    const attempts = await runPooled(connections, concurrency, (index) => attempt(index, ctx));
+    return summarizeProbe(attempts, { target: ctx.baseUrl, mode, toolName: ctx.toolName, wallClockMs: now() - startedAt });
+}
+//# sourceMappingURL=first-call-probe.js.map

package/dist/modules/mcp/first-call-probe.js.map

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

package/dist/modules/mcp/manual-failure-memo.d.ts

@@ -3,16 +3,18 @@
  *
  * Registering a `.tool` manual with a present-but-broken credential (an
  * expired OAuth session, a revoked key) fails with a live network round-trip —
- * and sessions are rebuilt constantly (every external MCP connection runs a
- * full discovery), so one stale credential otherwise re-dials its provider on
- * every build, forever. Besides the log noise, each failed attempt on the
- * MCP transport layer's long-lived shared session leaks an abort listener
- * upstream — the memo starves that loop.
+ * and the tool surface is rebuilt on every MCP request, so one stale credential
+ * otherwise re-dials its provider on every request, forever.
+ *
+ * The "manual" key is whatever the caller passes; the MCP service passes the
+ * manual's name plus a fingerprint of its definition, so editing a manual that
+ * just failed (a corrected URL in `mcp.json`) is retried on the next request
+ * instead of waiting out the TTL.
  *
  * Failures are remembered for a few minutes only: a repaired credential is
  * picked up at the next build after expiry (or immediately after a restart).
  * Successes are never cached here — this is a circuit breaker, not a catalog
- * cache. Expired entries are pruned opportunistically so the map stays
+ * cache. Expired failures are pruned opportunistically so the map stays
  * bounded by the number of DISTINCT recently-failing (user, manual) pairs.
  */
 export declare class ManualFailureMemo {
@@ -20,23 +22,42 @@ export declare class ManualFailureMemo {
     private readonly now;
     private readonly failures;
     /**
-     * Advanced by every clear operation. A registration attempt captures the
-     * generation BEFORE its (slow, awaited) network call and hands it back to
-     * {@link recordFailure} — if a clear happened in between (the user just
-     * repaired the credential), the stale in-flight failure is discarded instead
-     * of resurrecting a memo entry the clear was meant to remove.
+     * Out-of-order protection. Every clear takes the next value of a monotonic
+     * counter and remembers it for the scope it cleared: one pair, one user, or
+     * everyone. A registration attempt starts with {@link beginAttempt}, which
+     * captures the counter BEFORE its (slow, awaited) network call; its failure is
+     * discarded only when a clear covering THAT pair ran in between. A success of
+     * an unrelated manual, or a clear for another user, never discards it — no
+     * matter how long the attempt takes.
+     */
+    private counter;
+    private allClearedAt;
+    private readonly userClears;
+    private readonly pairClears;
+    /**
+     * Generations captured by attempts still in flight (generation → count). A
+     * clear record matters only to an attempt that started before it, so a record
+     * is kept exactly while such an attempt is running — which bounds the clear
+     * maps by what concurrent attempts can still observe.
      */
-    private generation;
+    private readonly inFlight;
     constructor(ttlMs?: number, now?: () => number);
-    /** Capture before an awaited registration attempt; pass to {@link recordFailure}. */
-    get currentGeneration(): number;
+    /**
+     * Start a registration attempt. Pass the returned generation to
+     * {@link recordFailure}, and ALWAYS to {@link endAttempt} when the attempt is
+     * over (try/finally) — an attempt never ended keeps later clear records alive.
+     */
+    beginAttempt(): number;
+    /** The attempt started at `generation` is over (after any `recordFailure`/`clear` it made). */
+    endAttempt(generation: number): void;
     private key;
     /** The remembered failure message when (user, manual) failed recently; undefined otherwise. */
     recentFailure(userId: string, manualName: string): string | undefined;
     /**
-     * Record a failure — unless `generation` (captured before the attempt) is
-     * stale, meaning a clear ran while the attempt was in flight. Dropping the
-     * record is the conservative direction: the worst case is one extra retry.
+     * Record a failure — unless `generation` (from {@link beginAttempt}) is stale
+     * for this pair, meaning a clear covering it ran while the attempt was in
+     * flight. Dropping the record is the conservative direction: the worst case
+     * is one extra retry.
      */
     recordFailure(userId: string, manualName: string, message: string, generation?: number): void;
     /** Forget a pair (e.g. after a successful registration proves the credential works again). */
@@ -49,5 +70,9 @@ export declare class ManualFailureMemo {
     clearUser(userId: string): void;
     /** Forget everything — a SHARED secret changed, which can affect any user. */
     clearAll(): void;
+    private nextGeneration;
+    private clearedSince;
+    /** Drop clear records no in-flight attempt predates: none of them can ever be consulted again. */
+    private pruneClears;
 }
 //# sourceMappingURL=manual-failure-memo.d.ts.map

package/dist/modules/mcp/manual-failure-memo.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"manual-failure-memo.d.ts","sourceRoot":"","sources":["../../../src/modules/mcp/manual-failure-memo.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,iBAAiB;IAY1B,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,GAAG;IAZtB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA6D;IACtF;;;;;;OAMG;IACH,OAAO,CAAC,UAAU,CAAK;gBAGJ,KAAK,GAAE,MAAmB,EAC1B,GAAG,GAAE,MAAM,MAAiB;IAG/C,qFAAqF;IACrF,IAAI,iBAAiB,IAAI,MAAM,CAE9B;IAED,OAAO,CAAC,GAAG;IAIX,+FAA+F;IAC/F,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAQrE;;;;OAIG;IACH,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI;IAQ7F,8FAA8F;IAC9F,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI;IAK/C;;;;OAIG;IACH,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAQ/B,8EAA8E;IAC9E,QAAQ,IAAI,IAAI;CAIjB"}
+{"version":3,"file":"manual-failure-memo.d.ts","sourceRoot":"","sources":["../../../src/modules/mcp/manual-failure-memo.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,iBAAiB;IAyB1B,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,GAAG;IAzBtB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA6D;IAEtF;;;;;;;;OAQG;IACH,OAAO,CAAC,OAAO,CAAK;IACpB,OAAO,CAAC,YAAY,CAAK;IACzB,OAAO,CAAC,QAAQ,CAAC,UAAU,CAA6B;IACxD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAA6B;IACxD;;;;;OAKG;IACH,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA6B;gBAGnC,KAAK,GAAE,MAAmB,EAC1B,GAAG,GAAE,MAAM,MAAiB;IAG/C;;;;OAIG;IACH,YAAY,IAAI,MAAM;IAMtB,+FAA+F;IAC/F,UAAU,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI;IAQpC,OAAO,CAAC,GAAG;IAIX,+FAA+F;IAC/F,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAQrE;;;;;OAKG;IACH,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI;IAQ7F,8FAA8F;IAC9F,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI;IAO/C;;;;OAIG;IACH,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAS/B,8EAA8E;IAC9E,QAAQ,IAAI,IAAI;IAKhB,OAAO,CAAC,cAAc;IAKtB,OAAO,CAAC,YAAY;IAQpB,kGAAkG;IAClG,OAAO,CAAC,WAAW;CASpB"}