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

package/dist/modules/mcp/downstream-token-refresh.js

@@ -0,0 +1,166 @@
+/**
+ * Refresh-and-retry for proxied third-party MCP servers (`mcp.json` manuals)
+ * that reject the caller's OAuth token.
+ *
+ * The vault refreshes a token when its STORED expiry says so. A provider can
+ * disagree — a token revoked early, an expiry the provider never stated, a
+ * clock that drifted — and then the downstream answers 401 / `invalid_token`
+ * while the vault still believes the token is good. The proxy reacts to that
+ * rejection: one forced refresh for (user, manual), one retry of the call, and
+ * the caller sees only the final outcome.
+ *
+ * Two pieces live here, both pure of the proxy so they are testable alone: the
+ * rejection classifier, and the guard that allows one refresh per (user,
+ * manual) per minute so a broken grant can never loop the provider.
+ */
+/** How far up a `cause` chain to look before giving up. */
+const MAX_CAUSE_DEPTH = 8;
+/** The minimum spacing between two forced refreshes of one (user, manual). */
+export const DOWNSTREAM_REFRESH_WINDOW_MS = 60_000;
+/**
+ * Did the downstream reject the credential itself — 401 or an `invalid_token`
+ * error — as opposed to anything else that can go wrong with a call?
+ *
+ * Two shapes reach here. A failed CALL keeps the MCP SDK's
+ * `StreamableHTTPError`, whose `code` is the HTTP status. A failed
+ * REGISTRATION is flattened to prose by `@utcp/mcp`
+ * (`Server 'srv': Streamable HTTP error: Error POSTing to endpoint: <body>`),
+ * where the status is gone and only the response body is left to read.
+ *
+ * 403 is deliberately NOT a rejection: it means the token is valid but not
+ * permitted, and a refreshed token carries the same permissions. An error that
+ * STATES its HTTP status is believed over its prose, so a 403 whose body says
+ * `invalid_token` (or any other non-401 status that mentions one) is not
+ * refreshed: the status is the server's verdict, the message only its wording.
+ */
+export function isDownstreamTokenRejection(err) {
+    const seen = new Set();
+    let current = err;
+    for (let depth = 0; depth < MAX_CAUSE_DEPTH && current != null && !seen.has(current); depth += 1) {
+        seen.add(current);
+        if (typeof current === 'string')
+            return saysTokenRejected(current);
+        if (typeof current !== 'object')
+            return false;
+        const e = current;
+        // A known status decides on its own — and ends the walk, so a 403's own
+        // body can't be re-read as a rejection one link further up the chain.
+        const status = httpStatusOf(e);
+        if (status !== undefined)
+            return status === 401;
+        if (typeof e.message === 'string' && saysTokenRejected(e.message))
+            return true;
+        current = e.cause;
+    }
+    return false;
+}
+/**
+ * The HTTP status this error carries, if it carries one at all — the MCP SDK's
+ * `StreamableHTTPError.code`, a `status`/`statusCode`, or a nested response's.
+ *
+ * `code` doubles as a JSON-RPC code in the SDK (negative, e.g. `-32001`) and
+ * as a syscall string in Node (`'ECONNRESET'`), so only a number inside the
+ * HTTP range counts as a status; anything else leaves the status unknown and
+ * the message is read instead.
+ */
+function httpStatusOf(e) {
+    const asStatus = (v) => typeof v === 'number' && Number.isInteger(v) && v >= 100 && v <= 599 ? v : undefined;
+    for (const field of ['status', 'statusCode', 'code']) {
+        const status = asStatus(e[field]);
+        if (status !== undefined)
+            return status;
+    }
+    return asStatus(e.response?.status);
+}
+function saysTokenRejected(message) {
+    const m = message.toLowerCase();
+    // A status number inside a URL (`/v1/401/…`, a port) proves nothing.
+    const scrubbed = m.replace(/\bhttps?:\/\/\S+/g, ' ');
+    // `unauthorized` as a word (the 401 reason phrase, an `error` value), not
+    // as a substring: `unauthorized_client` is an OAuth error about the CLIENT
+    // registration, which a refreshed token would not change.
+    return (/\b401\b/.test(scrubbed) ||
+        m.includes('invalid_token') ||
+        m.includes('invalid token') ||
+        /\bunauthorized\b/.test(m));
+}
+/**
+ * At most one refresh per key per window, single-flight within it.
+ *
+ * The first rejection in a window runs the refresh; rejections that arrive
+ * WHILE it runs (a burst of calls failing against the same dead token) share
+ * its outcome instead of being refused, so a burst doesn't turn into one
+ * success and N-1 failures. A rejection after the refresh settled but inside
+ * the window gets `undefined` — no refresh, the call's own error stands —
+ * which is what bounds a grant the provider keeps refreshing but the
+ * downstream keeps refusing to one refresh a minute.
+ */
+export class DownstreamRefreshGuard {
+    windowMs;
+    now;
+    attempts = new Map();
+    constructor(windowMs = DOWNSTREAM_REFRESH_WINDOW_MS, now = Date.now) {
+        this.windowMs = windowMs;
+        this.now = now;
+    }
+    /** Run `refresh` for `key` unless the window forbids it; `undefined` when it does. */
+    run(key, refresh) {
+        const at = this.now();
+        this.prune(at);
+        const existing = this.attempts.get(key);
+        if (existing)
+            return existing.settled ? undefined : existing.outcome;
+        const record = {
+            startedAt: at,
+            outcome: Promise.resolve(),
+            settled: false,
+        };
+        record.outcome = (async () => {
+            try {
+                const value = await refresh();
+                record.value = value;
+                return value;
+            }
+            finally {
+                record.settled = true;
+            }
+        })();
+        this.attempts.set(key, record);
+        return record.outcome;
+    }
+    /**
+     * Forget the attempts `predicate` selects — the key, and the outcome it
+     * settled on (`undefined` while it is still running).
+     *
+     * For when something OUTSIDE this guard changed the credential the window was
+     * protecting, so the window no longer describes anything real.
+     */
+    clearWhere(predicate) {
+        for (const [key, record] of this.attempts) {
+            if (predicate(key, record.value))
+                this.attempts.delete(key);
+        }
+    }
+    /**
+     * Forget attempts whose window is over, so the map is bounded by recent
+     * (user, manual) pairs.
+     *
+     * Age alone decides, NOT settlement: a refresh that never settles — a token
+     * request that hangs with no timeout — would otherwise pin its key forever,
+     * so no later rejection for that (user, manual) could ever refresh again and
+     * the entry could never be evicted. Once the window has passed, a new attempt
+     * is within policy whether the previous one finished or not.
+     *
+     * A clock that moved BACKWARD (an NTP step) makes every age negative; such a
+     * window is forgotten too, since otherwise it would hold for the step plus a
+     * minute rather than the minute the policy promises.
+     */
+    prune(at) {
+        for (const [key, record] of this.attempts) {
+            const age = at - record.startedAt;
+            if (age < 0 || age >= this.windowMs)
+                this.attempts.delete(key);
+        }
+    }
+}
+//# sourceMappingURL=downstream-token-refresh.js.map

package/dist/modules/mcp/downstream-token-refresh.js.map

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

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

@@ -0,0 +1,78 @@
+import type { FirstCallProbeOptions } from './first-call-probe.js';
+export declare const USAGE = "probe-first-call \u2014 fresh connections, one first start_session call each\n\n  --base-url <url>      deployment root, e.g. https://core-staging.bevel.software (required)\n  --bearer <token>      connection key or bearer; defaults to $PROBE_BEARER\n  --connections <n>     fresh connections to open (default 50)\n  --concurrency <n>     attempts in flight (default: all of them, one burst)\n  --mode <mcp|tool>     mcp: full client path (default); tool: plain POST, no transport\n  --tool <name>         tool to call (default start_session)\n  --timeout <ms>        per-request ceiling (default 30000)\n  --json                print the full report as JSON instead of the log block\n  --help                print this and exit\n";
+/**
+ * An argument the operator has to fix: printed plainly, exit 2, no stack.
+ *
+ * Its message is composed here and printed straight to a terminal or a CI log,
+ * so every value taken from argv goes through `printable` on the way in. A
+ * flag value is entirely the caller's to choose, and one containing a newline
+ * would otherwise add a line to that log — `--connections "1\n  50/50
+ * succeeded"` reading back as a result the probe never produced — while an
+ * ANSI escape would restyle whatever followed it.
+ */
+export declare class ConfigError extends Error {
+}
+/**
+ * Every flag this command takes, and whether a value has to follow it.
+ *
+ * The list exists so that anything NOT on it can be refused. A probe run is
+ * evidence that goes into a ticket log, and the way a mistyped flag fails is
+ * the worst way anything can fail here: `--concurency 1` used to be dropped on
+ * the floor and the default fifty-wide burst run instead, reported as the
+ * one-at-a-time run the operator thought they had asked for. A wrong number
+ * that looks right is worse than no number.
+ */
+declare const FLAGS: {
+    readonly 'base-url': "value";
+    readonly bearer: "value";
+    readonly connections: "value";
+    readonly concurrency: "value";
+    readonly mode: "value";
+    readonly tool: "value";
+    readonly timeout: "value";
+    readonly json: "switch";
+    readonly help: "switch";
+    readonly h: "switch";
+};
+export type FlagName = keyof typeof FLAGS;
+/** The flag table as data, so a test can hold the usage text to it. */
+export declare const FLAG_NAMES: FlagName[];
+/**
+ * `--flag value` pairs plus bare `--flag` switches, with no dependency.
+ *
+ * Nothing is ignored. An unknown flag, a stray word, and a value flag left
+ * without its value are all refused: `--bearer` with nothing after it used to
+ * become the literal bearer `"true"`, so every attempt came back 401 and the
+ * report read as fifty platform failures — a reproduction of a bug that was
+ * never there.
+ */
+export declare function parseArgs(argv: readonly string[]): Record<string, string>;
+/**
+ * A count flag, or `undefined` when absent so the probe's own default stands.
+ *
+ * Every numeric flag this CLI takes is a count: connections, attempts in
+ * flight, milliseconds. None of them has a meaning at zero or below —
+ * `--concurrency 0` in particular would reach `runPooled`'s `Math.max(1, …)`
+ * and run one worker at a time, so the operator would get a report of a
+ * one-at-a-time run labelled as the burst they asked for. Garbage and
+ * out-of-range are both refused, before anything is opened.
+ */
+export declare function count(args: Record<string, string>, key: string): number | undefined;
+/** What one invocation asked for: the usage text, or a probe to run. */
+export type CliRequest = {
+    help: true;
+} | {
+    help: false;
+    json: boolean;
+    options: FirstCallProbeOptions;
+};
+/**
+ * argv → what to do, or a {@link ConfigError} naming the flag to fix.
+ *
+ * Only the arguments this file can judge are judged here. Whether the base URL
+ * parses is `probeFirstCall`'s to say — it checks that before opening anything
+ * — and the entrypoint turns its refusal into the same exit as these.
+ */
+export declare function parseCliRequest(argv: readonly string[], env?: NodeJS.ProcessEnv): CliRequest;
+export {};
+//# sourceMappingURL=first-call-probe.cli-args.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"first-call-probe.cli-args.d.ts","sourceRoot":"","sources":["../../../src/modules/mcp/first-call-probe.cli-args.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,qBAAqB,EAAa,MAAM,uBAAuB,CAAC;AAE9E,eAAO,MAAM,KAAK,+tBAWjB,CAAC;AAEF;;;;;;;;;GASG;AACH,qBAAa,WAAY,SAAQ,KAAK;CAAG;AAEzC;;;;;;;;;GASG;AACH,QAAA,MAAM,KAAK;;;;;;;;;;;CAW4C,CAAC;AAExD,MAAM,MAAM,QAAQ,GAAG,MAAM,OAAO,KAAK,CAAC;AAE1C,uEAAuE;AACvE,eAAO,MAAM,UAAU,EAAyB,QAAQ,EAAE,CAAC;AAE3D;;;;;;;;GAQG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CA0BzE;AAED;;;;;;;;;GASG;AACH,wBAAgB,KAAK,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAQnF;AAED,wEAAwE;AACxE,MAAM,MAAM,UAAU,GAAG;IAAE,IAAI,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,KAAK,CAAC;IAAC,IAAI,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,qBAAqB,CAAA;CAAE,CAAC;AAEzG;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,UAAU,CA0BzG"}

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

@@ -0,0 +1,151 @@
+/**
+ * Argument handling for `first-call-probe.cli.ts`, kept apart from it.
+ *
+ * The entrypoint is a top-level-`await` script: importing it runs a probe, so
+ * nothing there can be tested. Everything that decides what the probe is asked
+ * to do lives here instead, as plain functions over an argv array — which is
+ * how the refusals below are covered by a suite rather than by remembering to
+ * try them by hand.
+ */
+import { printable } from '../../shared/printable.js';
+export const USAGE = `probe-first-call — fresh connections, one first start_session call each
+
+  --base-url <url>      deployment root, e.g. https://core-staging.bevel.software (required)
+  --bearer <token>      connection key or bearer; defaults to $PROBE_BEARER
+  --connections <n>     fresh connections to open (default 50)
+  --concurrency <n>     attempts in flight (default: all of them, one burst)
+  --mode <mcp|tool>     mcp: full client path (default); tool: plain POST, no transport
+  --tool <name>         tool to call (default start_session)
+  --timeout <ms>        per-request ceiling (default 30000)
+  --json                print the full report as JSON instead of the log block
+  --help                print this and exit
+`;
+/**
+ * An argument the operator has to fix: printed plainly, exit 2, no stack.
+ *
+ * Its message is composed here and printed straight to a terminal or a CI log,
+ * so every value taken from argv goes through `printable` on the way in. A
+ * flag value is entirely the caller's to choose, and one containing a newline
+ * would otherwise add a line to that log — `--connections "1\n  50/50
+ * succeeded"` reading back as a result the probe never produced — while an
+ * ANSI escape would restyle whatever followed it.
+ */
+export class ConfigError extends Error {
+}
+/**
+ * Every flag this command takes, and whether a value has to follow it.
+ *
+ * The list exists so that anything NOT on it can be refused. A probe run is
+ * evidence that goes into a ticket log, and the way a mistyped flag fails is
+ * the worst way anything can fail here: `--concurency 1` used to be dropped on
+ * the floor and the default fifty-wide burst run instead, reported as the
+ * one-at-a-time run the operator thought they had asked for. A wrong number
+ * that looks right is worse than no number.
+ */
+const FLAGS = {
+    'base-url': 'value',
+    bearer: 'value',
+    connections: 'value',
+    concurrency: 'value',
+    mode: 'value',
+    tool: 'value',
+    timeout: 'value',
+    json: 'switch',
+    help: 'switch',
+    h: 'switch',
+};
+/** The flag table as data, so a test can hold the usage text to it. */
+export const FLAG_NAMES = Object.keys(FLAGS);
+/**
+ * `--flag value` pairs plus bare `--flag` switches, with no dependency.
+ *
+ * Nothing is ignored. An unknown flag, a stray word, and a value flag left
+ * without its value are all refused: `--bearer` with nothing after it used to
+ * become the literal bearer `"true"`, so every attempt came back 401 and the
+ * report read as fifty platform failures — a reproduction of a bug that was
+ * never there.
+ */
+export function parseArgs(argv) {
+    const args = {};
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        // The conventional end-of-options separator. `pnpm run … -- --base-url x`
+        // normally eats it, but not every runner does and it is not a mistake.
+        if (arg === '--')
+            continue;
+        if (!arg.startsWith('--')) {
+            throw new ConfigError(`unexpected argument ${printable(arg)} — every input to this command is a --flag`);
+        }
+        const key = arg.slice(2);
+        if (!(key in FLAGS))
+            throw new ConfigError(`unknown option ${printable(arg)}`);
+        if (FLAGS[key] === 'switch') {
+            args[key] = 'true';
+            continue;
+        }
+        const next = argv[i + 1];
+        // A following `--something` is the next flag, not this one's value: taking
+        // it would swallow the flag as well as leaving this one unset.
+        if (next === undefined || next.startsWith('--')) {
+            throw new ConfigError(`--${key} needs a value`);
+        }
+        args[key] = next;
+        i++;
+    }
+    return args;
+}
+/**
+ * A count flag, or `undefined` when absent so the probe's own default stands.
+ *
+ * Every numeric flag this CLI takes is a count: connections, attempts in
+ * flight, milliseconds. None of them has a meaning at zero or below —
+ * `--concurrency 0` in particular would reach `runPooled`'s `Math.max(1, …)`
+ * and run one worker at a time, so the operator would get a report of a
+ * one-at-a-time run labelled as the burst they asked for. Garbage and
+ * out-of-range are both refused, before anything is opened.
+ */
+export function count(args, key) {
+    const raw = args[key];
+    if (raw === undefined)
+        return undefined;
+    const parsed = Number(raw);
+    if (!Number.isInteger(parsed) || parsed < 1) {
+        throw new ConfigError(`--${key} must be a positive integer, got ${printable(raw)}`);
+    }
+    return parsed;
+}
+/**
+ * argv → what to do, or a {@link ConfigError} naming the flag to fix.
+ *
+ * Only the arguments this file can judge are judged here. Whether the base URL
+ * parses is `probeFirstCall`'s to say — it checks that before opening anything
+ * — and the entrypoint turns its refusal into the same exit as these.
+ */
+export function parseCliRequest(argv, env = process.env) {
+    const args = parseArgs(argv);
+    if (args.help || args.h)
+        return { help: true };
+    const baseUrl = args['base-url'];
+    const bearer = args.bearer ?? env.PROBE_BEARER ?? '';
+    if (!baseUrl || !bearer) {
+        throw new ConfigError(!baseUrl ? '--base-url is required' : '--bearer (or $PROBE_BEARER) is required');
+    }
+    const mode = (args.mode ?? 'mcp');
+    if (mode !== 'mcp' && mode !== 'tool') {
+        throw new ConfigError(`--mode must be mcp or tool, got ${printable(args.mode ?? '')}`);
+    }
+    return {
+        help: false,
+        json: args.json === 'true',
+        options: {
+            baseUrl,
+            bearer,
+            mode,
+            connections: count(args, 'connections'),
+            concurrency: count(args, 'concurrency'),
+            timeoutMs: count(args, 'timeout'),
+            toolName: args.tool,
+        },
+    };
+}
+//# sourceMappingURL=first-call-probe.cli-args.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"first-call-probe.cli-args.js","sourceRoot":"","sources":["../../../src/modules/mcp/first-call-probe.cli-args.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AAGtD,MAAM,CAAC,MAAM,KAAK,GAAG;;;;;;;;;;;CAWpB,CAAC;AAEF;;;;;;;;;GASG;AACH,MAAM,OAAO,WAAY,SAAQ,KAAK;CAAG;AAEzC;;;;;;;;;GASG;AACH,MAAM,KAAK,GAAG;IACZ,UAAU,EAAE,OAAO;IACnB,MAAM,EAAE,OAAO;IACf,WAAW,EAAE,OAAO;IACpB,WAAW,EAAE,OAAO;IACpB,IAAI,EAAE,OAAO;IACb,IAAI,EAAE,OAAO;IACb,OAAO,EAAE,OAAO;IAChB,IAAI,EAAE,QAAQ;IACd,IAAI,EAAE,QAAQ;IACd,CAAC,EAAE,QAAQ;CAC0C,CAAC;AAIxD,uEAAuE;AACvE,MAAM,CAAC,MAAM,UAAU,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAe,CAAC;AAE3D;;;;;;;;GAQG;AACH,MAAM,UAAU,SAAS,CAAC,IAAuB;IAC/C,MAAM,IAAI,GAA2B,EAAE,CAAC;IACxC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACrC,MAAM,GAAG,GAAG,IAAI,CAAC,CAAC,CAAE,CAAC;QACrB,0EAA0E;QAC1E,uEAAuE;QACvE,IAAI,GAAG,KAAK,IAAI;YAAE,SAAS;QAC3B,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;YAC1B,MAAM,IAAI,WAAW,CAAC,uBAAuB,SAAS,CAAC,GAAG,CAAC,4CAA4C,CAAC,CAAC;QAC3G,CAAC;QACD,MAAM,GAAG,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;QACzB,IAAI,CAAC,CAAC,GAAG,IAAI,KAAK,CAAC;YAAE,MAAM,IAAI,WAAW,CAAC,kBAAkB,SAAS,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAC/E,IAAI,KAAK,CAAC,GAAe,CAAC,KAAK,QAAQ,EAAE,CAAC;YACxC,IAAI,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC;YACnB,SAAS;QACX,CAAC;QACD,MAAM,IAAI,GAAG,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;QACzB,2EAA2E;QAC3E,+DAA+D;QAC/D,IAAI,IAAI,KAAK,SAAS,IAAI,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;YAChD,MAAM,IAAI,WAAW,CAAC,KAAK,GAAG,gBAAgB,CAAC,CAAC;QAClD,CAAC;QACD,IAAI,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC;QACjB,CAAC,EAAE,CAAC;IACN,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,KAAK,CAAC,IAA4B,EAAE,GAAW;IAC7D,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC;IACtB,IAAI,GAAG,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IACxC,MAAM,MAAM,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;IAC3B,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,MAAM,GAAG,CAAC,EAAE,CAAC;QAC5C,MAAM,IAAI,WAAW,CAAC,KAAK,GAAG,oCAAoC,SAAS,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IACtF,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAKD;;;;;;GAMG;AACH,MAAM,UAAU,eAAe,CAAC,IAAuB,EAAE,MAAyB,OAAO,CAAC,GAAG;IAC3F,MAAM,IAAI,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC;IAC7B,IAAI,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,CAAC;QAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;IAE/C,MAAM,OAAO,GAAG,IAAI,CAAC,UAAU,CAAC,CAAC;IACjC,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,IAAI,GAAG,CAAC,YAAY,IAAI,EAAE,CAAC;IACrD,IAAI,CAAC,OAAO,IAAI,CAAC,MAAM,EAAE,CAAC;QACxB,MAAM,IAAI,WAAW,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,wBAAwB,CAAC,CAAC,CAAC,yCAAyC,CAAC,CAAC;IACzG,CAAC;IACD,MAAM,IAAI,GAAG,CAAC,IAAI,CAAC,IAAI,IAAI,KAAK,CAAc,CAAC;IAC/C,IAAI,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,MAAM,EAAE,CAAC;QACtC,MAAM,IAAI,WAAW,CAAC,mCAAmC,SAAS,CAAC,IAAI,CAAC,IAAI,IAAI,EAAE,CAAC,EAAE,CAAC,CAAC;IACzF,CAAC;IACD,OAAO;QACL,IAAI,EAAE,KAAK;QACX,IAAI,EAAE,IAAI,CAAC,IAAI,KAAK,MAAM;QAC1B,OAAO,EAAE;YACP,OAAO;YACP,MAAM;YACN,IAAI;YACJ,WAAW,EAAE,KAAK,CAAC,IAAI,EAAE,aAAa,CAAC;YACvC,WAAW,EAAE,KAAK,CAAC,IAAI,EAAE,aAAa,CAAC;YACvC,SAAS,EAAE,KAAK,CAAC,IAAI,EAAE,SAAS,CAAC;YACjC,QAAQ,EAAE,IAAI,CAAC,IAAI;SACpB;KACF,CAAC;AACJ,CAAC"}

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

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=first-call-probe.cli.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"first-call-probe.cli.d.ts","sourceRoot":"","sources":["../../../src/modules/mcp/first-call-probe.cli.ts"],"names":[],"mappings":""}

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

@@ -0,0 +1,62 @@
+/**
+ * Command-line front end for {@link probeFirstCall} — the reproduction this
+ * ticket's log is written from. Nothing imports this file; it exists to be run:
+ *
+ *   pnpm --filter @bevel-software/platform-core-backend probe:first-call \
+ *     -- --base-url https://core-staging.bevel.software --bearer bevel_…
+ *
+ * The bearer may come from `--bearer` or from `PROBE_BEARER`, so a throwaway
+ * connection key does not have to be typed into a shell history.
+ *
+ * Exit code is 1 when any attempt failed, so a run can be used as a check and
+ * not only read; 2 when the command itself was wrong. `--json` prints the
+ * whole report, every attempt included, for a run whose numbers want keeping
+ * rather than summarizing.
+ *
+ * What to run and whether the flags make sense is decided in
+ * `first-call-probe.cli-args.ts`, where it can be tested. All that is left
+ * here is the part that cannot be: reading argv, printing, and the exit code.
+ */
+import { probeFirstCall, formatProbeReport, ProbeOptionsError } from './first-call-probe.js';
+import { ConfigError, parseCliRequest, USAGE } from './first-call-probe.cli-args.js';
+import { terminalSafeJson } from '../../shared/printable.js';
+async function main() {
+    const request = parseCliRequest(process.argv.slice(2));
+    if (request.help) {
+        console.log(USAGE);
+        return;
+    }
+    // `probeFirstCall` checks the arguments it cannot probe with — a malformed
+    // `--base-url` above all — and does it before opening anything, so its
+    // refusal is the operator's typo too and leaves by the same door as the
+    // rest. ONLY that refusal: anything else it throws is the probe crashing,
+    // which must not come out dressed as a mistyped command.
+    const report = await probeFirstCall(request.options).catch((err) => {
+        throw err instanceof ProbeOptionsError ? new ConfigError(err.message) : err;
+    });
+    // The report quotes what the remote said, so the JSON is made terminal-safe
+    // the way every other operator-facing text is (see `terminalSafeJson`).
+    console.log(request.json ? terminalSafeJson(JSON.stringify(report, null, 2)) : formatProbeReport(report));
+    if (report.failed > 0)
+        process.exitCode = 1;
+}
+try {
+    await main();
+}
+catch (err) {
+    // Every way of mis-invoking this ends the same way: the sentence that says
+    // what to fix, the usage block, exit 2. A bad flag used to escape the
+    // top-level `await` as an unhandled rejection — a stack trace and exit 1,
+    // which reads like the probe crashed rather than like the command was typed
+    // wrong. A real crash still looks like one: exit 1, no usage block
+    // pretending the operator mistyped something.
+    if (err instanceof ConfigError) {
+        console.error(`${err.message}\n\n${USAGE}`);
+        process.exitCode = 2;
+    }
+    else {
+        console.error(err);
+        process.exitCode = 1;
+    }
+}
+//# sourceMappingURL=first-call-probe.cli.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"first-call-probe.cli.js","sourceRoot":"","sources":["../../../src/modules/mcp/first-call-probe.cli.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,EAAE,cAAc,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAC7F,OAAO,EAAE,WAAW,EAAE,eAAe,EAAE,KAAK,EAAE,MAAM,gCAAgC,CAAC;AACrF,OAAO,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAE7D,KAAK,UAAU,IAAI;IACjB,MAAM,OAAO,GAAG,eAAe,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IACvD,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC;QACjB,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QACnB,OAAO;IACT,CAAC;IACD,2EAA2E;IAC3E,uEAAuE;IACvE,wEAAwE;IACxE,0EAA0E;IAC1E,yDAAyD;IACzD,MAAM,MAAM,GAAG,MAAM,cAAc,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,KAAK,CAAC,CAAC,GAAY,EAAE,EAAE;QAC1E,MAAM,GAAG,YAAY,iBAAiB,CAAC,CAAC,CAAC,IAAI,WAAW,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC;IAC9E,CAAC,CAAC,CAAC;IACH,4EAA4E;IAC5E,wEAAwE;IACxE,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,gBAAgB,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,iBAAiB,CAAC,MAAM,CAAC,CAAC,CAAC;IAC1G,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;AAC9C,CAAC;AAED,IAAI,CAAC;IACH,MAAM,IAAI,EAAE,CAAC;AACf,CAAC;AAAC,OAAO,GAAG,EAAE,CAAC;IACb,2EAA2E;IAC3E,sEAAsE;IACtE,0EAA0E;IAC1E,4EAA4E;IAC5E,mEAAmE;IACnE,8CAA8C;IAC9C,IAAI,GAAG,YAAY,WAAW,EAAE,CAAC;QAC/B,OAAO,CAAC,KAAK,CAAC,GAAG,GAAG,CAAC,OAAO,OAAO,KAAK,EAAE,CAAC,CAAC;QAC5C,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;IACvB,CAAC;SAAM,CAAC;QACN,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QACnB,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;IACvB,CAAC;AACH,CAAC"}

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