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

package/dist/modules/mcp/downstream-pool.js.map

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

package/dist/modules/mcp/downstream-token-refresh.d.ts

@@ -0,0 +1,77 @@
+/**
+ * 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.
+ */
+/** The minimum spacing between two forced refreshes of one (user, manual). */
+export declare const DOWNSTREAM_REFRESH_WINDOW_MS = 60000;
+/**
+ * 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 declare function isDownstreamTokenRejection(err: unknown): boolean;
+/**
+ * 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 declare class DownstreamRefreshGuard<T> {
+    private readonly windowMs;
+    private readonly now;
+    private readonly attempts;
+    constructor(windowMs?: number, now?: () => number);
+    /** Run `refresh` for `key` unless the window forbids it; `undefined` when it does. */
+    run(key: string, refresh: () => Promise<T>): Promise<T> | undefined;
+    /**
+     * 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: (key: string, outcome: T | undefined) => boolean): void;
+    /**
+     * 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.
+     */
+    private prune;
+}
+//# sourceMappingURL=downstream-token-refresh.d.ts.map

package/dist/modules/mcp/downstream-token-refresh.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"downstream-token-refresh.d.ts","sourceRoot":"","sources":["../../../src/modules/mcp/downstream-token-refresh.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAKH,8EAA8E;AAC9E,eAAO,MAAM,4BAA4B,QAAS,CAAC;AAEnD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,0BAA0B,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAgBhE;AAoCD;;;;;;;;;;GAUG;AACH,qBAAa,sBAAsB,CAAC,CAAC;IAOjC,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,GAAG;IAPtB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAGrB;gBAGe,QAAQ,GAAE,MAAqC,EAC/C,GAAG,GAAE,MAAM,MAAiB;IAG/C,sFAAsF;IACtF,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GAAG,SAAS;IAuBnE;;;;;;OAMG;IACH,UAAU,CAAC,SAAS,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,GAAG,SAAS,KAAK,OAAO,GAAG,IAAI;IAM7E;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,KAAK;CAMd"}

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

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