@superblocksteam/gateway 2.0.155-next.0

package/dist/events/snapshot.js

@@ -0,0 +1,57 @@
+import { advanceEventCursor, cursorPosition, } from "./cursor.js";
+import { PRODUCERS_IN_ORDER, sortEvents } from "./merge.js";
+import { EVENT_SNAPSHOT_TAIL } from "./types.js";
+/**
+ * Assembles a snapshot from a store's three reads.
+ *
+ * Shared rather than written twice so the memory and Redis stores cannot drift
+ * into disagreeing about what resuming means — the same reason both build
+ * their keys from one builder. Each store supplies only the reads; the cursor
+ * arithmetic and the staleness rule live here.
+ */
+export async function buildSnapshot(input, reads) {
+    const collected = [];
+    const tail = [];
+    const lost = [];
+    for (const producer of PRODUCERS_IN_ORDER) {
+        const resumedAfterSequence = cursorPosition(input.cursor, producer);
+        const afterEvents = await reads.readAfter({
+            afterSequence: resumedAfterSequence,
+            ...(input.limit === undefined ? {} : { limit: input.limit }),
+            producer,
+        });
+        collected.push(...afterEvents);
+        tail.push(...(await reads.readTail({ count: EVENT_SNAPSHOT_TAIL, producer })));
+        const firstRetainedSequence = await reads.firstRetainedSequence(producer);
+        // readAfter and firstRetainedSequence are two separate reads, not one
+        // atomic one, so retention can advance between them: firstRetainedSequence
+        // can then report a boundary past events readAfter had already captured
+        // moments earlier. A delivered sequence below that boundary proves the
+        // read beat the eviction, so what looks like a gap here never actually
+        // reached the caller as one.
+        const minDelivered = afterEvents.length > 0
+            ? Math.min(...afterEvents.map((event) => event.sequence))
+            : undefined;
+        const provenByDelivery = firstRetainedSequence !== undefined &&
+            minDelivered !== undefined &&
+            minDelivered < firstRetainedSequence;
+        // A gap only exists when the stream starts *past* the next sequence the
+        // cursor expects. An empty stream is not a gap: nothing was produced yet.
+        if (firstRetainedSequence !== undefined &&
+            firstRetainedSequence > resumedAfterSequence + 1 &&
+            !provenByDelivery) {
+            lost.push({ firstRetainedSequence, producer, resumedAfterSequence });
+        }
+    }
+    const events = sortEvents(collected);
+    const limited = input.limit === undefined ? events : events.slice(0, input.limit);
+    return {
+        // Advanced past what is actually being handed over, never past what was
+        // read and then cut by the limit — otherwise the remainder is skipped.
+        cursor: advanceEventCursor(input.cursor, limited),
+        events: limited,
+        lost,
+        tail: sortEvents(tail),
+    };
+}
+//# sourceMappingURL=snapshot.js.map

package/dist/events/snapshot.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot.js","sourceRoot":"","sources":["../../src/events/snapshot.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,kBAAkB,EAClB,cAAc,GAEf,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,kBAAkB,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE5D,OAAO,EAAE,mBAAmB,EAAuB,MAAM,YAAY,CAAC;AAqBtE;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,KAA+C,EAC/C,KAAoB;IAEpB,MAAM,SAAS,GAAoB,EAAE,CAAC;IACtC,MAAM,IAAI,GAAoB,EAAE,CAAC;IACjC,MAAM,IAAI,GAAqB,EAAE,CAAC;IAElC,KAAK,MAAM,QAAQ,IAAI,kBAAkB,EAAE,CAAC;QAC1C,MAAM,oBAAoB,GAAG,cAAc,CAAC,KAAK,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;QACpE,MAAM,WAAW,GAAG,MAAM,KAAK,CAAC,SAAS,CAAC;YACxC,aAAa,EAAE,oBAAoB;YACnC,GAAG,CAAC,KAAK,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,CAAC;YAC5D,QAAQ;SACT,CAAC,CAAC;QACH,SAAS,CAAC,IAAI,CAAC,GAAG,WAAW,CAAC,CAAC;QAC/B,IAAI,CAAC,IAAI,CACP,GAAG,CAAC,MAAM,KAAK,CAAC,QAAQ,CAAC,EAAE,KAAK,EAAE,mBAAmB,EAAE,QAAQ,EAAE,CAAC,CAAC,CACpE,CAAC;QAEF,MAAM,qBAAqB,GAAG,MAAM,KAAK,CAAC,qBAAqB,CAAC,QAAQ,CAAC,CAAC;QAC1E,sEAAsE;QACtE,2EAA2E;QAC3E,wEAAwE;QACxE,uEAAuE;QACvE,uEAAuE;QACvE,6BAA6B;QAC7B,MAAM,YAAY,GAChB,WAAW,CAAC,MAAM,GAAG,CAAC;YACpB,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;YACzD,CAAC,CAAC,SAAS,CAAC;QAChB,MAAM,gBAAgB,GACpB,qBAAqB,KAAK,SAAS;YACnC,YAAY,KAAK,SAAS;YAC1B,YAAY,GAAG,qBAAqB,CAAC;QAEvC,wEAAwE;QACxE,0EAA0E;QAC1E,IACE,qBAAqB,KAAK,SAAS;YACnC,qBAAqB,GAAG,oBAAoB,GAAG,CAAC;YAChD,CAAC,gBAAgB,EACjB,CAAC;YACD,IAAI,CAAC,IAAI,CAAC,EAAE,qBAAqB,EAAE,QAAQ,EAAE,oBAAoB,EAAE,CAAC,CAAC;QACvE,CAAC;IACH,CAAC;IAED,MAAM,MAAM,GAAG,UAAU,CAAC,SAAS,CAAC,CAAC;IACrC,MAAM,OAAO,GACX,KAAK,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC;IACpE,OAAO;QACL,wEAAwE;QACxE,uEAAuE;QACvE,MAAM,EAAE,kBAAkB,CAAC,KAAK,CAAC,MAAM,EAAE,OAAO,CAAC;QACjD,MAAM,EAAE,OAAO;QACf,IAAI;QACJ,IAAI,EAAE,UAAU,CAAC,IAAI,CAAC;KACvB,CAAC;AACJ,CAAC"}

package/dist/events/stream-key.d.ts

@@ -0,0 +1,2 @@
+import type { EventProducer, EventScope } from "./types.js";
+export declare function streamSuffix(scope: EventScope, producer: EventProducer): string;

package/dist/events/stream-key.js

@@ -0,0 +1,31 @@
+import { createHash } from "node:crypto";
+/**
+ * Builds the stream address shared by every event store, so the two
+ * implementations cannot drift into addressing streams differently.
+ *
+ * Tenant identifiers (organization, application, live edit) are length-
+ * prefixed and SHA-256-digested before they reach Redis. Length-prefixing
+ * keeps `a:b`+`c` and `a`+`b:c` from colliding; digesting keeps the
+ * identifiers themselves out of key listings — ProgressStore already does
+ * the same for caller/org/app. The producer stays in the clear: it is a
+ * closed enum (`dev_server` | `sabs`), cannot identify a tenant, and naming
+ * the stream at a glance is worth more than the nothing it discloses.
+ *
+ * v0 has not shipped this key format, so there is no dual-read. Existing
+ * local Redis event keys from earlier builds are orphaned after deploy.
+ */
+function digest(parts) {
+    const hash = createHash("sha256");
+    for (const part of parts) {
+        hash.update(`${part.length}:${part}`);
+    }
+    return hash.digest("hex");
+}
+export function streamSuffix(scope, producer) {
+    return `${digest([
+        scope.organizationId,
+        scope.applicationId,
+        scope.liveEditId,
+    ])}:${producer}`;
+}
+//# sourceMappingURL=stream-key.js.map

package/dist/events/stream-key.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream-key.js","sourceRoot":"","sources":["../../src/events/stream-key.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAIzC;;;;;;;;;;;;;;GAcG;AACH,SAAS,MAAM,CAAC,KAAwB;IACtC,MAAM,IAAI,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC;IAClC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC,MAAM,IAAI,IAAI,EAAE,CAAC,CAAC;IACxC,CAAC;IACD,OAAO,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAC5B,CAAC;AAED,MAAM,UAAU,YAAY,CAC1B,KAAiB,EACjB,QAAuB;IAEvB,OAAO,GAAG,MAAM,CAAC;QACf,KAAK,CAAC,cAAc;QACpB,KAAK,CAAC,aAAa;QACnB,KAAK,CAAC,UAAU;KACjB,CAAC,IAAI,QAAQ,EAAE,CAAC;AACnB,CAAC"}

package/dist/events/types.d.ts

@@ -0,0 +1,179 @@
+import type { EventCursor } from "./cursor.js";
+/**
+ * The versioned event contract SABS pushes over the direct authenticated
+ * callback. This mirrors `sabs/internal/gateway/event.go`; the two are kept in
+ * step by hand because the channel is deliberately not proto, and the bounds
+ * below are the only thing standing between a producer bug and unbounded
+ * Redis growth.
+ */
+export declare const EVENT_CONTRACT_VERSION = 1;
+export declare const MAX_IDENTIFIER_LENGTH = 128;
+export declare const MAX_LABEL_LENGTH = 512;
+export declare const MAX_TEXT_LENGTH = 8192;
+/**
+ * Ceiling on an inbound sequence number. Every consumer of `sequence`
+ * (cursor comparisons, gap detection) does so with ordinary JS number
+ * arithmetic, which stops being exact past this point; a producer sequence
+ * that reached it would silently corrupt ordering rather than fail loudly.
+ */
+export declare const MAX_SEQUENCE: number;
+/** Kinds of fact a live-edit session reports. */
+export declare const EVENT_KINDS: readonly ["auth_required", "chat_message", "generation_state", "progress", "session"];
+export type LiveEditEventKind = (typeof EVENT_KINDS)[number];
+/**
+ * Which stream a sequence number belongs to. The SABS control plane and the
+ * dev server both push about the same live edit and neither can see the
+ * other's counter, so ordering is defined per producer and Gateway keeps the
+ * two streams apart.
+ */
+export declare const EVENT_PRODUCERS: readonly ["dev_server", "sabs"];
+export type EventProducer = (typeof EVENT_PRODUCERS)[number];
+export declare const GENERATION_STATES: readonly ["awaiting_user_input", "cancelled", "completed", "debugging", "generating", "idle", "summarizing"];
+export declare const CHAT_ROLES: readonly ["assistant", "user"];
+export declare const SESSION_STATUSES: readonly ["created", "terminated"];
+export type LiveEditEventPayload = {
+    kind: "auth_required";
+    reason?: string;
+} | {
+    kind: "chat_message";
+    messageId?: string;
+    messageType?: string;
+    role: (typeof CHAT_ROLES)[number];
+    text: string;
+} | {
+    kind: "generation_state";
+    hasError?: boolean;
+    hasSuggestions?: boolean;
+    state: (typeof GENERATION_STATES)[number];
+} | {
+    kind: "progress";
+    label: string;
+} | {
+    kind: "session";
+    status: (typeof SESSION_STATUSES)[number];
+};
+/**
+ * One accepted event. `occurredAtMs` replaces the wire's ISO string so
+ * ordering never depends on re-parsing, and `payload` is narrowed by `kind`.
+ */
+export type LiveEditEvent = {
+    applicationId: string;
+    eventId: string;
+    gatewayTurnId?: string;
+    kind: LiveEditEventKind;
+    liveEditId: string;
+    occurredAtMs: number;
+    organizationId: string;
+    payload: LiveEditEventPayload;
+    producer: EventProducer;
+    sequence: number;
+    version: typeof EVENT_CONTRACT_VERSION;
+};
+/**
+ * Why an event was refused. These values reach a metric label, so the set is
+ * closed and carries nothing derived from the event's content.
+ */
+export type EventRejectionReason = "malformed_event" | "unsupported_version";
+export type ParseResult = {
+    ok: true;
+    event: LiveEditEvent;
+} | {
+    ok: false;
+    reason: EventRejectionReason;
+};
+/** Outcome of persisting one event. */
+export type AppendOutcome = "accepted" | "duplicate";
+/**
+ * The whole tenant path to one live-edit stream.
+ *
+ * A live-edit id alone would be enough to address a stream, and that is
+ * exactly the problem: it makes the store's isolation depend entirely on
+ * every caller having validated ownership first. Carrying the tenant in the
+ * key means a read cannot reach another tenant's history even if something
+ * upstream let the wrong id through.
+ */
+export type EventScope = {
+    applicationId: string;
+    liveEditId: string;
+    organizationId: string;
+};
+/**
+ * A producer whose retention boundary overtook a caller's cursor.
+ *
+ * Reported rather than hidden: the caller asked to continue from a position
+ * that no longer exists, and answering with only the events that survived
+ * would present a stream with a hole in it as a complete one. Naming the
+ * producer and both boundaries lets a caller say exactly what it lost.
+ */
+export type LostEventRange = {
+    /** Lowest sequence this producer's stream still holds. */
+    firstRetainedSequence: number;
+    producer: EventProducer;
+    /** Last sequence the caller's cursor had consumed. */
+    resumedAfterSequence: number;
+};
+/**
+ * How many events at the end of each producer's stream a snapshot carries.
+ *
+ * Current state has to be read from the stream's end rather than from the
+ * window after the cursor: a caller that already consumed the terminal event
+ * would otherwise be told nothing is known and would poll a build that ended.
+ * A tail bounds that read so it does not grow with the length of the session.
+ */
+export declare const EVENT_SNAPSHOT_TAIL = 64;
+/**
+ * What one caller sees when it resumes reading a live edit.
+ *
+ * `events` is what is new for this caller and `tail` is where the session
+ * currently stands; the two overlap freely and a reader is expected to take
+ * activity from the first and state from the second.
+ */
+export type EventSnapshot = {
+    /** Advanced past every event in {@link EventSnapshot.events}. */
+    cursor: EventCursor;
+    /** Strictly after the incoming cursor, ordered deterministically. */
+    events: LiveEditEvent[];
+    /** Empty when the cursor was still inside every stream's retention. */
+    lost: LostEventRange[];
+    /** Newest {@link EVENT_SNAPSHOT_TAIL} events per producer, cursor aside. */
+    tail: LiveEditEvent[];
+};
+/**
+ * Durable, bounded record of what happened in a live-edit session.
+ *
+ * Retention is bounded twice over: a stream holds at most
+ * {@link MAX_EVENTS_PER_STREAM} events and expires after
+ * {@link EVENT_STREAM_TTL_MS} of silence. This is the source a resumed caller
+ * reads. Live turns hear Clark over the editor websocket.
+ */
+export type EventStore = {
+    /** The event carries its own scope, so an append cannot be misfiled. */
+    append(event: LiveEditEvent): Promise<AppendOutcome>;
+    /** Events for a live edit, ordered deterministically across producers. */
+    list(input: EventScope & {
+        afterSequence?: number;
+        limit?: number;
+        producer?: EventProducer;
+    }): Promise<LiveEditEvent[]>;
+    /**
+     * Everything one caller needs to continue from where it left off, read
+     * without consuming anything: two callers resuming the same live edit each
+     * get their own view of it.
+     */
+    snapshot(input: EventScope & {
+        cursor?: EventCursor;
+        limit?: number;
+    }): Promise<EventSnapshot>;
+};
+/**
+ * Per-(live edit, producer) retention bound. A runaway producer overwrites its
+ * own oldest events rather than growing Redis without limit. The trade-off is
+ * explicit: an event evicted by count loses its de-duplication record, so a
+ * redelivery arriving after eviction is accepted again. Bounded memory is
+ * worth more than perfect de-duplication of an event nobody can still read.
+ */
+export declare const MAX_EVENTS_PER_STREAM = 500;
+/** How long a silent stream is kept before Redis reclaims it. */
+export declare const EVENT_STREAM_TTL_MS = 3600000;
+/** Cap on one inbound batch, matching the SABS publish bound. */
+export declare const MAX_EVENTS_PER_REQUEST = 64;

package/dist/events/types.js

@@ -0,0 +1,66 @@
+/**
+ * The versioned event contract SABS pushes over the direct authenticated
+ * callback. This mirrors `sabs/internal/gateway/event.go`; the two are kept in
+ * step by hand because the channel is deliberately not proto, and the bounds
+ * below are the only thing standing between a producer bug and unbounded
+ * Redis growth.
+ */
+export const EVENT_CONTRACT_VERSION = 1;
+export const MAX_IDENTIFIER_LENGTH = 128;
+export const MAX_LABEL_LENGTH = 512;
+export const MAX_TEXT_LENGTH = 8192;
+/**
+ * Ceiling on an inbound sequence number. Every consumer of `sequence`
+ * (cursor comparisons, gap detection) does so with ordinary JS number
+ * arithmetic, which stops being exact past this point; a producer sequence
+ * that reached it would silently corrupt ordering rather than fail loudly.
+ */
+export const MAX_SEQUENCE = Number.MAX_SAFE_INTEGER;
+/** Kinds of fact a live-edit session reports. */
+export const EVENT_KINDS = [
+    "auth_required",
+    "chat_message",
+    "generation_state",
+    "progress",
+    "session",
+];
+/**
+ * Which stream a sequence number belongs to. The SABS control plane and the
+ * dev server both push about the same live edit and neither can see the
+ * other's counter, so ordering is defined per producer and Gateway keeps the
+ * two streams apart.
+ */
+export const EVENT_PRODUCERS = ["dev_server", "sabs"];
+export const GENERATION_STATES = [
+    "awaiting_user_input",
+    "cancelled",
+    "completed",
+    "debugging",
+    "generating",
+    "idle",
+    "summarizing",
+];
+export const CHAT_ROLES = ["assistant", "user"];
+export const SESSION_STATUSES = ["created", "terminated"];
+/**
+ * How many events at the end of each producer's stream a snapshot carries.
+ *
+ * Current state has to be read from the stream's end rather than from the
+ * window after the cursor: a caller that already consumed the terminal event
+ * would otherwise be told nothing is known and would poll a build that ended.
+ * A tail bounds that read so it does not grow with the length of the session.
+ */
+export const EVENT_SNAPSHOT_TAIL = 64;
+/**
+ * Per-(live edit, producer) retention bound. A runaway producer overwrites its
+ * own oldest events rather than growing Redis without limit. The trade-off is
+ * explicit: an event evicted by count loses its de-duplication record, so a
+ * redelivery arriving after eviction is accepted again. Bounded memory is
+ * worth more than perfect de-duplication of an event nobody can still read.
+ */
+export const MAX_EVENTS_PER_STREAM = 500;
+/** How long a silent stream is kept before Redis reclaims it. */
+export const EVENT_STREAM_TTL_MS = 3_600_000;
+/** Cap on one inbound batch, matching the SABS publish bound. */
+export const MAX_EVENTS_PER_REQUEST = 64;
+//# sourceMappingURL=types.js.map

package/dist/events/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/events/types.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,CAAC;AAExC,MAAM,CAAC,MAAM,qBAAqB,GAAG,GAAG,CAAC;AACzC,MAAM,CAAC,MAAM,gBAAgB,GAAG,GAAG,CAAC;AACpC,MAAM,CAAC,MAAM,eAAe,GAAG,IAAI,CAAC;AAEpC;;;;;GAKG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,MAAM,CAAC,gBAAgB,CAAC;AAEpD,iDAAiD;AACjD,MAAM,CAAC,MAAM,WAAW,GAAG;IACzB,eAAe;IACf,cAAc;IACd,kBAAkB;IAClB,UAAU;IACV,SAAS;CACD,CAAC;AAGX;;;;;GAKG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,YAAY,EAAE,MAAM,CAAU,CAAC;AAG/D,MAAM,CAAC,MAAM,iBAAiB,GAAG;IAC/B,qBAAqB;IACrB,WAAW;IACX,WAAW;IACX,WAAW;IACX,YAAY;IACZ,MAAM;IACN,aAAa;CACL,CAAC;AAEX,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,WAAW,EAAE,MAAM,CAAU,CAAC;AAEzD,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,SAAS,EAAE,YAAY,CAAU,CAAC;AAkFnE;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,EAAE,CAAC;AAiDtC;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,GAAG,CAAC;AAEzC,iEAAiE;AACjE,MAAM,CAAC,MAAM,mBAAmB,GAAG,SAAS,CAAC;AAE7C,iEAAiE;AACjE,MAAM,CAAC,MAAM,sBAAsB,GAAG,EAAE,CAAC"}

package/dist/health/readiness.d.ts

@@ -0,0 +1,99 @@
+import type { GatewayFault } from "../process/fault-barrier.js";
+/**
+ * What the gateway's own request path is doing.
+ *
+ * `unmounted` is not a degenerate case: `createApp` builds the HTTP surface
+ * before the MCP transport is mounted onto it, and a gateway in that window has
+ * no way to serve a tool call. Reporting it as healthy is the ENG-5809 bug in
+ * miniature.
+ */
+export type DispatchState = "faulted" | "ok" | "unmounted" | "wedged";
+export type UpstreamState = "reachable" | "unknown" | "unreachable";
+export type ReadinessVerdict = {
+    dispatch: DispatchState;
+    /** Human-readable cause, present only when something is wrong. */
+    detail?: string;
+    /** Whether callers should be routed here. */
+    ready: boolean;
+    upstream: UpstreamState;
+};
+/**
+ * Proves the gateway can still take a request all the way through its own
+ * dispatch path. Resolving means it can; throwing or hanging means it cannot.
+ */
+export type DispatchProbe = () => Promise<void>;
+export type UpstreamProbe = () => Promise<UpstreamState>;
+export type GatewayReadinessOptions = {
+    cacheMs?: number;
+    dispatchDeadlineMs?: number;
+    /** Where the cause behind a bounded `detail` goes. */
+    log?: (message: string, cause: unknown) => void;
+    now?: () => number;
+    /** The Superblocks origin this gateway fronts, named in the verdict. */
+    serverUrl: string;
+    upstreamProbe?: UpstreamProbe;
+};
+/**
+ * Probes an origin for reachability rather than for authorization.
+ *
+ * Any HTTP status is a pass, including 401: a server that refuses an
+ * unauthenticated probe has still proved it is answering, which is the only
+ * question a health check can ask without a caller's credential. Only a
+ * transport failure or a timeout means unreachable.
+ */
+export declare function createUpstreamProbe(input: {
+    fetchImpl?: typeof fetch;
+    serverUrl: string;
+    timeoutMs?: number;
+}): UpstreamProbe;
+/**
+ * The gateway's honest answer to "are you working".
+ *
+ * Two questions, deliberately kept apart, because during the ENG-5809 outage
+ * nothing on the wire told the difference:
+ *
+ * - {@link liveness} asks whether *this process* can still serve. It fails on a
+ *   broken or wedged dispatch path and on a fault it decided not to survive.
+ *   An unreachable platform never fails it, because restarting this gateway
+ *   cannot fix the platform, and a supervisor acting on liveness would restart
+ *   a working process every few seconds until the platform came back.
+ * - {@link readiness} asks whether tool calls should be routed here, so an
+ *   unreachable platform does fail it: nothing can be served through it.
+ *
+ * Both report `dispatch` and `upstream` as separate fields either way, so a
+ * caller reads which side to act on instead of inferring it from a bare "ok".
+ */
+export declare class GatewayReadiness {
+    private cached;
+    private dispatchProbe;
+    private fatal;
+    private inFlight;
+    private readonly options;
+    constructor(options: GatewayReadinessOptions);
+    /**
+     * Hands over the real dispatch path, once there is one. Called by the MCP
+     * transport as it mounts; until then the gateway reports `unmounted`.
+     */
+    useDispatchProbe(probe: DispatchProbe): void;
+    /**
+     * Records what the process-level barrier caught.
+     *
+     * Only a fatal fault changes the verdict. A rejection the barrier absorbed
+     * cost one caller their call; failing liveness for it would hand a working
+     * process to a restart loop, which is the outage the barrier prevents.
+     */
+    recordFault(fault: GatewayFault): void;
+    liveness(): Promise<ReadinessVerdict>;
+    readiness(): Promise<ReadinessVerdict>;
+    private verdict;
+    /**
+     * One probe run per cache window, shared by however many pollers arrive
+     * while it is running. Eight concurrent agents polling health must not stack
+     * eight MCP servers onto a gateway that is already struggling.
+     */
+    private probe;
+    private runProbe;
+    private probeDispatch;
+    private log;
+    private probeUpstream;
+}

package/dist/health/readiness.js

@@ -0,0 +1,202 @@
+import { recordReadinessVerdict } from "../telemetry/metrics.js";
+/** How long the dispatch path gets to answer before it counts as wedged. */
+const DEFAULT_DISPATCH_DEADLINE_MS = 5_000;
+/** How long the upstream origin gets to answer before it counts as down. */
+const DEFAULT_UPSTREAM_DEADLINE_MS = 3_000;
+/** How long one probe run answers for. Health endpoints get polled hard. */
+const DEFAULT_CACHE_MS = 2_000;
+async function withDeadline(work, deadlineMs, onDeadline) {
+    let timer;
+    try {
+        return await Promise.race([
+            work,
+            new Promise((resolve) => {
+                timer = setTimeout(() => resolve(onDeadline()), deadlineMs);
+                timer.unref?.();
+            }),
+        ]);
+    }
+    finally {
+        if (timer) {
+            clearTimeout(timer);
+        }
+    }
+}
+/**
+ * Probes an origin for reachability rather than for authorization.
+ *
+ * Any HTTP status is a pass, including 401: a server that refuses an
+ * unauthenticated probe has still proved it is answering, which is the only
+ * question a health check can ask without a caller's credential. Only a
+ * transport failure or a timeout means unreachable.
+ */
+export function createUpstreamProbe(input) {
+    const fetchImpl = input.fetchImpl ?? fetch;
+    return async () => {
+        try {
+            await fetchImpl(input.serverUrl, {
+                method: "GET",
+                signal: AbortSignal.timeout(input.timeoutMs ?? DEFAULT_UPSTREAM_DEADLINE_MS),
+            });
+            return "reachable";
+        }
+        catch {
+            return "unreachable";
+        }
+    };
+}
+/**
+ * The gateway's honest answer to "are you working".
+ *
+ * Two questions, deliberately kept apart, because during the ENG-5809 outage
+ * nothing on the wire told the difference:
+ *
+ * - {@link liveness} asks whether *this process* can still serve. It fails on a
+ *   broken or wedged dispatch path and on a fault it decided not to survive.
+ *   An unreachable platform never fails it, because restarting this gateway
+ *   cannot fix the platform, and a supervisor acting on liveness would restart
+ *   a working process every few seconds until the platform came back.
+ * - {@link readiness} asks whether tool calls should be routed here, so an
+ *   unreachable platform does fail it: nothing can be served through it.
+ *
+ * Both report `dispatch` and `upstream` as separate fields either way, so a
+ * caller reads which side to act on instead of inferring it from a bare "ok".
+ */
+export class GatewayReadiness {
+    cached;
+    dispatchProbe;
+    fatal;
+    inFlight;
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    /**
+     * Hands over the real dispatch path, once there is one. Called by the MCP
+     * transport as it mounts; until then the gateway reports `unmounted`.
+     */
+    useDispatchProbe(probe) {
+        this.dispatchProbe = probe;
+    }
+    /**
+     * Records what the process-level barrier caught.
+     *
+     * Only a fatal fault changes the verdict. A rejection the barrier absorbed
+     * cost one caller their call; failing liveness for it would hand a working
+     * process to a restart loop, which is the outage the barrier prevents.
+     */
+    recordFault(fault) {
+        if (fault.fatal) {
+            this.fatal = fault;
+        }
+    }
+    async liveness() {
+        return this.verdict("liveness");
+    }
+    async readiness() {
+        return this.verdict("readiness");
+    }
+    async verdict(probe) {
+        const probed = await this.probe();
+        const upstreamCounts = probe === "readiness";
+        const upstreamDown = upstreamCounts && probed.upstream === "unreachable";
+        const verdict = {
+            dispatch: probed.dispatch,
+            ready: probed.dispatch === "ok" && !upstreamDown,
+            upstream: probed.upstream,
+            ...detailOf(probed, upstreamDown, this.options.serverUrl),
+        };
+        recordReadinessVerdict({
+            dispatch: verdict.dispatch,
+            probe,
+            ready: verdict.ready,
+            upstream: verdict.upstream,
+        });
+        return verdict;
+    }
+    /**
+     * One probe run per cache window, shared by however many pollers arrive
+     * while it is running. Eight concurrent agents polling health must not stack
+     * eight MCP servers onto a gateway that is already struggling.
+     */
+    async probe() {
+        const now = (this.options.now ?? Date.now)();
+        const cacheMs = this.options.cacheMs ?? DEFAULT_CACHE_MS;
+        if (this.cached && now - this.cached.at < cacheMs) {
+            return this.cached;
+        }
+        this.inFlight ??= this.runProbe(now).finally(() => {
+            this.inFlight = undefined;
+        });
+        return this.inFlight;
+    }
+    async runProbe(at) {
+        const [dispatch, upstream] = await Promise.all([
+            this.probeDispatch(),
+            this.probeUpstream(),
+        ]);
+        const probed = { at, upstream, ...dispatch };
+        this.cached = probed;
+        return probed;
+    }
+    async probeDispatch() {
+        // A fault the process did not survive outranks anything a probe could say:
+        // the heap it left behind is what the probe would be running on.
+        if (this.fatal) {
+            // The kind and not the message. Both probes are unauthenticated, and an
+            // exception message can carry an internal route, a query, or an id that
+            // a caller cannot act on anyway. The message went to the log when the
+            // barrier caught it.
+            return {
+                dispatch: "faulted",
+                dispatchDetail: `The gateway recorded a fatal ${this.fatal.kind} and is waiting to be restarted.`,
+            };
+        }
+        const probe = this.dispatchProbe;
+        if (!probe) {
+            return {
+                dispatch: "unmounted",
+                dispatchDetail: "No MCP transport is mounted on this gateway yet.",
+            };
+        }
+        const deadlineMs = this.options.dispatchDeadlineMs ?? DEFAULT_DISPATCH_DEADLINE_MS;
+        try {
+            return await withDeadline(probe().then(() => ({ dispatch: "ok" })), deadlineMs, () => ({
+                dispatch: "wedged",
+                dispatchDetail: `The gateway's own dispatch path did not answer within ${deadlineMs}ms.`,
+            }));
+        }
+        catch (error) {
+            // Same reason as the fatal branch: the cause is for the operator reading
+            // logs, not for an unauthenticated caller reading a health endpoint.
+            this.log("gateway dispatch probe failed", error);
+            return {
+                dispatch: "wedged",
+                dispatchDetail: "The gateway's own dispatch path failed.",
+            };
+        }
+    }
+    log(message, cause) {
+        (this.options.log ?? ((text, err) => console.error(text, err)))(message, cause);
+    }
+    async probeUpstream() {
+        const probe = this.options.upstreamProbe;
+        if (!probe) {
+            return "unknown";
+        }
+        try {
+            return await probe();
+        }
+        catch {
+            return "unreachable";
+        }
+    }
+}
+function detailOf(probed, upstreamDown, serverUrl) {
+    const reasons = [
+        probed.dispatchDetail,
+        upstreamDown ? `${serverUrl} did not answer.` : undefined,
+    ].filter((reason) => reason !== undefined);
+    return reasons.length > 0 ? { detail: reasons.join(" ") } : {};
+}
+//# sourceMappingURL=readiness.js.map

package/dist/health/readiness.js.map

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