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

package/src/modules/mcp/downstream-pool.ts

@@ -0,0 +1,256 @@
+/**
+ * The ONE piece of state the stateless MCP endpoint keeps between requests: a
+ * pool of connections to proxied third-party MCP servers (`mcp.json` manuals),
+ * keyed by (user, server).
+ *
+ * Everything else a request needs is re-derived from its own bearer. These
+ * connections are the exception because a downstream MCP server is session-ful
+ * by nature — dialing a fresh handshake on every tool call would add a round
+ * trip per call and hammer the provider. So they are cached, and the pool is
+ * built so that losing any of it costs a reconnect, never correctness:
+ *
+ *   - created LAZILY, on the first request that needs the server;
+ *   - SINGLE-FLIGHT per key: concurrent first calls share one creation, so a
+ *     burst produces one connection instead of N with all but one orphaned;
+ *   - IDLE-EVICTED and SIZE-BOUNDED, with the retired session store's proven
+ *     defaults (4 hours idle, 5000 entries);
+ *   - every eviction CLOSES what it evicts (`dispose`) — the pool is the owner
+ *     of each connection it opened, and nothing else closes them;
+ *   - LEASED: `acquire` hands out a lease the caller releases when its
+ *     operation ends. A leased entry is in use, so it is never idle and never
+ *     the LRU victim; an entry invalidated while leased leaves the pool at once
+ *     but is closed only when its last lease is released. A call in progress
+ *     never has its connection closed underneath it.
+ *
+ * Eviction is lazy, like the store it replaces: `acquire` sweeps idle entries
+ * first and enforces the cap on insert. No background timer, so constructing a
+ * pool never leaks an interval handle (in tests or anywhere else). When every
+ * entry is leased the cap cannot evict anything, and the pool holds more than
+ * `maxEntries` until leases are released — and the release that ends an
+ * entry's last lease re-applies the cap, so the overflow ends with the leases,
+ * not with whenever the next acquire happens to run.
+ *
+ * Healing a connection whose server restarted is NOT this class's job: the
+ * pooled value carries the existing session-recovery wrapper, which
+ * re-registers on the spec's 404 in place. The pool only decides how long a
+ * value lives.
+ */
+
+import { logger } from '../../shared/logging.js';
+
+const log = logger('mcp');
+
+export interface DownstreamPoolOptions<V> {
+  /** Close a value the pool is dropping. Errors are logged, never thrown. */
+  dispose: (value: V) => Promise<void>;
+  /** Drop entries unused for longer than this. Default: 4 hours. */
+  idleTtlMs?: number;
+  /** Hard cap on pooled entries; the least-recently-used is evicted first. Default: 5000. */
+  maxEntries?: number;
+  /** Override `Date.now` — injected only by tests. */
+  now?: () => number;
+}
+
+/** A pooled value in use. `release` ends the use; calling it again is a no-op. */
+export interface Lease<V> {
+  readonly value: V;
+  release(): void;
+}
+
+export const DEFAULT_DOWNSTREAM_IDLE_TTL_MS = 4 * 60 * 60 * 1000;
+export const DEFAULT_DOWNSTREAM_MAX_ENTRIES = 5000;
+
+interface Entry<V> {
+  key: string;
+  value: V;
+  lastUsedAt: number;
+  /** Outstanding leases; an entry with any is in use and not evictable. */
+  leases: number;
+  /** Removed from the pool while leased: close it when the last lease ends. */
+  retired: boolean;
+}
+
+interface Pending<V> {
+  promise: Promise<V>;
+  /** Set by `evictWhere` when the key is invalidated while creation is in flight. */
+  stale: boolean;
+}
+
+export class DownstreamPool<V> {
+  private readonly entries = new Map<string, Entry<V>>();
+  private readonly pending = new Map<string, Pending<V>>();
+  private readonly dispose: (value: V) => Promise<void>;
+  private readonly idleTtlMs: number;
+  private readonly maxEntries: number;
+  private readonly now: () => number;
+
+  constructor(opts: DownstreamPoolOptions<V>) {
+    this.dispose = opts.dispose;
+    this.idleTtlMs = opts.idleTtlMs ?? DEFAULT_DOWNSTREAM_IDLE_TTL_MS;
+    this.maxEntries = Math.max(1, opts.maxEntries ?? DEFAULT_DOWNSTREAM_MAX_ENTRIES);
+    this.now = opts.now ?? Date.now;
+  }
+
+  /**
+   * Lease the pooled value for `key`, creating it with `create` when absent.
+   * The caller MUST release the lease when its operation ends (try/finally).
+   * A creation that rejects is NOT cached — every waiter sees the rejection and
+   * the next `acquire` tries again (retry pacing is the caller's policy, see
+   * ManualFailureMemo).
+   */
+  async acquire(key: string, create: () => Promise<V>): Promise<Lease<V>> {
+    this.sweep();
+    const hit = this.entries.get(key);
+    if (hit) return this.lease(hit);
+    const inflight = this.pending.get(key);
+    if (inflight) return this.awaitPending(key, inflight, create);
+
+    const record: Pending<V> = { promise: create(), stale: false };
+    this.pending.set(key, record);
+    const forget = () => {
+      if (this.pending.get(key) === record) this.pending.delete(key);
+    };
+    let value: V;
+    try {
+      value = await record.promise;
+    } finally {
+      forget();
+    }
+    if (record.stale) {
+      // Invalidated mid-creation (the user's credentials changed): the value
+      // was built from the old state. Close it and build a current one.
+      this.disposeQuietly(key, value);
+      return this.acquire(key, create);
+    }
+    return this.lease(this.insert(key, value));
+  }
+
+  /**
+   * Evict every entry whose key matches — the hook for "this user's
+   * credentials changed". Idle entries are closed now; leased ones leave the
+   * pool now and are closed when released. A creation in flight for a matching
+   * key is marked stale, so its result is closed and rebuilt instead of cached.
+   */
+  evictWhere(predicate: (key: string) => boolean): void {
+    for (const [key, entry] of [...this.entries]) {
+      if (predicate(key)) this.retire(entry);
+    }
+    for (const [key, record] of this.pending) {
+      if (predicate(key)) record.stale = true;
+    }
+  }
+
+  /** Evict and close everything (leased entries close on release). */
+  closeAll(): void {
+    this.evictWhere(() => true);
+  }
+
+  /** Pooled (resolved) entries; diagnostics and tests. Does not sweep. */
+  size(): number {
+    return this.entries.size;
+  }
+
+  private async awaitPending(key: string, record: Pending<V>, create: () => Promise<V>): Promise<Lease<V>> {
+    const value = await record.promise;
+    // The creator owns closing a stale value; a joiner just asks again.
+    if (record.stale) return this.acquire(key, create);
+    // The creator pooled the value before this continuation ran. If it has
+    // already left the pool again, lease whatever the pool holds now.
+    const entry = this.entries.get(key);
+    if (!entry || entry.value !== value) return this.acquire(key, create);
+    return this.lease(entry);
+  }
+
+  private lease(entry: Entry<V>): Lease<V> {
+    entry.leases += 1;
+    entry.lastUsedAt = this.now();
+    let released = false;
+    return {
+      value: entry.value,
+      release: () => {
+        if (released) return;
+        released = true;
+        entry.leases -= 1;
+        // Idleness is measured from the end of the last use.
+        entry.lastUsedAt = this.now();
+        if (entry.retired && entry.leases === 0) this.disposeQuietly(entry.key, entry.value);
+        // An insert that found every entry leased could not evict and let the
+        // pool overflow the cap. The overflow has to end with the leases, not
+        // with whenever the next acquire happens to run — so the release that
+        // ends an entry's last lease re-applies the cap. The entry just
+        // released is the newest by `lastUsedAt`, so older idle entries go
+        // first.
+        if (entry.leases === 0) this.enforceCap();
+      },
+    };
+  }
+
+  private insert(key: string, value: V): Entry<V> {
+    this.sweep();
+    this.enforceCap(1);
+    const entry: Entry<V> = { key, value, lastUsedAt: this.now(), leases: 0, retired: false };
+    this.entries.set(key, entry);
+    return entry;
+  }
+
+  /**
+   * Evict idle entries, least recently used first, until at most
+   * `maxEntries - reserve` remain — or nothing idle is left, in which case
+   * the pool stays over the cap until a lease is released (which calls this
+   * again). `reserve` is the room an insert needs for the entry it is about
+   * to add.
+   */
+  private enforceCap(reserve = 0): void {
+    while (this.entries.size + reserve > this.maxEntries && this.evictLeastRecentlyUsed()) {
+      // each pass evicted one idle entry
+    }
+  }
+
+  private sweep(): void {
+    const cutoff = this.now() - this.idleTtlMs;
+    for (const entry of [...this.entries.values()]) {
+      if (entry.leases === 0 && entry.lastUsedAt < cutoff) this.retire(entry);
+    }
+  }
+
+  /** Evict the least-recently-used entry not in use; false when every entry is leased. */
+  private evictLeastRecentlyUsed(): boolean {
+    let oldest: Entry<V> | undefined;
+    for (const entry of this.entries.values()) {
+      if (entry.leases > 0) continue;
+      if (!oldest || entry.lastUsedAt < oldest.lastUsedAt) oldest = entry;
+    }
+    if (!oldest) return false;
+    this.retire(oldest);
+    return true;
+  }
+
+  /** Take an entry out of the pool; close it now, or on its last release when leased. */
+  private retire(entry: Entry<V>): void {
+    if (this.entries.get(entry.key) === entry) this.entries.delete(entry.key);
+    entry.retired = true;
+    if (entry.leases === 0) this.disposeQuietly(entry.key, entry.value);
+  }
+
+  /**
+   * Fire-and-forget close: a slow downstream teardown must not block the
+   * request that happened to trigger the sweep, and a failing one must not
+   * stop the rest of the sweep.
+   */
+  private disposeQuietly(key: string, value: V): void {
+    void Promise.resolve()
+      .then(() => this.dispose(value))
+      .catch((err) => {
+        log.warn(`closing pooled downstream connection failed (${poolKeyLabel(key)}):`, { err });
+      });
+  }
+}
+
+/** A log-safe rendering of a pool key: user and manual, never the template fingerprint. */
+function poolKeyLabel(key: string): string {
+  const [userId, manual] = key.split(POOL_KEY_SEPARATOR);
+  return `user=${userId ?? '?'} manual=${manual ?? '?'}`;
+}
+
+/** Separator for (user, manual, fingerprint) keys — cannot occur in any of the parts. */
+export const POOL_KEY_SEPARATOR = '\u0000';

package/src/modules/mcp/downstream-token-refresh.ts

@@ -0,0 +1,170 @@
+/**
+ * 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: unknown): boolean {
+  const seen = new Set<unknown>();
+  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 as Record<string, unknown>;
+    // 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: Record<string, unknown>): number | undefined {
+  const asStatus = (v: unknown): number | undefined =>
+    typeof v === 'number' && Number.isInteger(v) && v >= 100 && v <= 599 ? v : undefined;
+  for (const field of ['status', 'statusCode', 'code'] as const) {
+    const status = asStatus(e[field]);
+    if (status !== undefined) return status;
+  }
+  return asStatus((e.response as { status?: unknown } | undefined)?.status);
+}
+
+function saysTokenRejected(message: string): boolean {
+  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<T> {
+  private readonly attempts = new Map<
+    string,
+    { startedAt: number; outcome: Promise<T>; settled: boolean; value?: T }
+  >();
+
+  constructor(
+    private readonly windowMs: number = DOWNSTREAM_REFRESH_WINDOW_MS,
+    private readonly now: () => number = Date.now,
+  ) {}
+
+  /** Run `refresh` for `key` unless the window forbids it; `undefined` when it does. */
+  run(key: string, refresh: () => Promise<T>): Promise<T> | undefined {
+    const at = this.now();
+    this.prune(at);
+    const existing = this.attempts.get(key);
+    if (existing) return existing.settled ? undefined : existing.outcome;
+    const record: { startedAt: number; outcome: Promise<T>; settled: boolean; value?: T } = {
+      startedAt: at,
+      outcome: Promise.resolve() as Promise<unknown> as Promise<T>,
+      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: (key: string, outcome: T | undefined) => boolean): void {
+    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.
+   */
+  private prune(at: number): void {
+    for (const [key, record] of this.attempts) {
+      const age = at - record.startedAt;
+      if (age < 0 || age >= this.windowMs) this.attempts.delete(key);
+    }
+  }
+}

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

@@ -0,0 +1,159 @@
+/**
+ * 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';
+import type { FirstCallProbeOptions, ProbeMode } from './first-call-probe.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',
+} as const satisfies Record<string, 'value' | 'switch'>;
+
+export type FlagName = keyof typeof FLAGS;
+
+/** The flag table as data, so a test can hold the usage text to it. */
+export const FLAG_NAMES = Object.keys(FLAGS) as 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 function parseArgs(argv: readonly string[]): Record<string, string> {
+  const args: Record<string, string> = {};
+  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 as FlagName] === '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: Record<string, string>, key: string): number | undefined {
+  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;
+}
+
+/** 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 function parseCliRequest(argv: readonly string[], env: NodeJS.ProcessEnv = process.env): CliRequest {
+  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') as ProbeMode;
+  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,
+    },
+  };
+}

package/src/modules/mcp/first-call-probe.cli.ts

@@ -0,0 +1,60 @@
+/**
+ * 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(): Promise<void> {
+  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: unknown) => {
+    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;
+  }
+}