@0xinsider/mcp 2.1.0 → 2.4.0

package/dist/sdk/stream.js

@@ -21,8 +21,105 @@
  *
  * Filters (per-connection, subscribe-time): `event` (comma-separated frame
  * types), `condition_id`, and `min_grade` (S|A|B|C|D|F).
+ *
+ * Protocol validity (#16248). The decoder is bounded and fails visibly:
+ *   - A successful response whose media type is not `text/event-stream` is
+ *     `StreamProtocolError` (`unexpected_media_type`), not an empty stream.
+ *   - A data frame whose payload is not JSON, not an object, or has no usable
+ *     sequence (a finite `seq` in the envelope, or a finite SSE `id`) is a
+ *     `StreamProtocolError` (`invalid_json`, `invalid_envelope`,
+ *     `unusable_sequence`); a resync frame whose payload is not an object is
+ *     `invalid_resync`. Before #16248 such frames were skipped or yielded with
+ *     `NaN`, and the next valid frame moved the cursor past the gap.
+ *   - A frame larger than `maxFrameBytes` (default 1 MiB), whether or not its
+ *     blank-line delimiter has arrived, is `frame_too_large` before it is
+ *     parsed (#16644); the reader is released and the connection closed.
+ *   - The error carries `lastSeq`, the last sequence delivered before it, so a
+ *     malformed frame never moves the cursor and a caller can decide whether
+ *     to resume from there (which replays the frame while it is retained),
+ *     skip past `frameId`, or refetch state. No raw payload is on the error.
+ *   - A terminal `event: error` frame (the key was revoked, the account
+ *     lapsed, or the credential store could not confirm the key) throws the
+ *     typed `OxinsiderApiError` it carries and is never yielded (#16546);
+ *     `retry: false` is permanent to the resilient consumers.
+ *   Comment lines (`: keep-alive`), LF and CRLF framing, unknown SSE fields
+ *   and unknown-but-valid envelope `type`s are compatible as before.
  */
+import { resolveApiUrl } from "./client.js";
 import { errorFromResponse, OxinsiderApiError } from "./errors.js";
+import { RETRY_AFTER_CEILING_MS, retryAfterSeconds, waitUnlessAborted, } from "./retry.js";
+/** Default for `StreamOptions.maxFrameBytes`: 1 MiB. */
+export const DEFAULT_MAX_STREAM_FRAME_BYTES = 1_048_576;
+/**
+ * The stream broke the SSE contract (#16248). The connection is closed and
+ * the reader released before this is thrown. `lastSeq` is the last sequence
+ * delivered on this connection, or `undefined` when none was: no malformed
+ * frame moves the cursor. `frameId` is the SSE `id` of the offending frame
+ * when it carried one, `event` its SSE event name, `bytes` its size, and
+ * `mediaType` the response's `Content-Type` for `unexpected_media_type`. The
+ * raw payload is deliberately not carried: it may hold data you would not
+ * want in a log, and `frameId` plus `lastSeq` name the frame exactly.
+ *
+ * `streamFeedResilient` treats this as permanent: reconnecting from
+ * `lastSeq` would replay the same frame while the server retains it. Decide:
+ * resume from `lastSeq` later, resume after `frameId` to skip it, or refetch
+ * state and attach live.
+ */
+export class StreamProtocolError extends Error {
+    reason;
+    lastSeq;
+    frameId;
+    event;
+    bytes;
+    mediaType;
+    constructor(reason, detail) {
+        super(streamProtocolMessage(reason, detail));
+        this.name = "StreamProtocolError";
+        this.reason = reason;
+        this.lastSeq = detail.lastSeq;
+        this.frameId = detail.frameId;
+        this.event = detail.event;
+        this.bytes = detail.bytes;
+        this.mediaType = detail.mediaType ?? undefined;
+    }
+}
+function streamProtocolMessage(reason, detail) {
+    const where = detail.frameId === undefined
+        ? "a frame"
+        : `frame id ${String(detail.frameId)}`;
+    const after = detail.lastSeq === undefined
+        ? "before any event was delivered"
+        : `after seq ${String(detail.lastSeq)}`;
+    switch (reason) {
+        case "unexpected_media_type":
+            return `0xinsider stream answered ${detail.mediaType ? `Content-Type ${detail.mediaType}` : "with no Content-Type"} instead of text/event-stream; not an SSE stream`;
+        case "invalid_json":
+            return `0xinsider stream sent ${where} whose data is not JSON (${String(detail.bytes ?? 0)} bytes) ${after}`;
+        case "invalid_envelope":
+            return `0xinsider stream sent ${where} whose data is not an envelope object ${after}`;
+        case "unusable_sequence":
+            return `0xinsider stream sent ${where} with no finite seq and no finite id ${after}`;
+        case "invalid_resync":
+            return `0xinsider stream sent a resync marker (${where}) whose data is not a resync object ${after}`;
+        case "frame_too_large":
+            return `0xinsider stream sent a frame past ${String(detail.bytes ?? 0)} bytes with no delimiter ${after}; the connection was closed`;
+        default:
+            return `0xinsider stream protocol error ${after}`;
+    }
+}
+function assertMaxFrameBytes(value) {
+    if (!Number.isInteger(value) || value < 1) {
+        throw new Error(`maxFrameBytes must be a positive integer, got ${String(value)}`);
+    }
+    return value;
+}
+/** `Content-Type` names an event stream: `text/event-stream`, with or without parameters. */
+export function isEventStreamMediaType(contentType) {
+    if (contentType === null)
+        return false;
+    const essence = contentType.split(";", 1)[0]?.trim().toLowerCase();
+    return essence === "text/event-stream";
+}
 /**
  * Open the stream and async-iterate its frames. Yields a discriminated
  * `StreamEvent`: `kind: "event"` carries the `FeedEnvelope`, `kind: "resync"`
@@ -38,13 +135,18 @@ import { errorFromResponse, OxinsiderApiError } from "./errors.js";
  * }
  */
 export async function* streamFeed(client, options = {}) {
+    const maxFrameBytes = assertMaxFrameBytes(options.maxFrameBytes ?? DEFAULT_MAX_STREAM_FRAME_BYTES);
     const apiKey = client.getApiKey();
-    if (!apiKey) {
+    // The sandbox takes no credential; it answers the stream route with a 400
+    // saying streams are not simulated, and that answer is the server's to
+    // give (#16138). Production refuses a keyless stream, so say so locally.
+    if (!apiKey && !client.isSandbox()) {
         throw new Error("getStream requires an API key (oxi_sk_*)");
     }
     const url = buildStreamUrl(client, options);
     const headers = new Headers({ accept: "text/event-stream" });
-    headers.set("authorization", `Bearer ${apiKey}`);
+    if (apiKey)
+        headers.set("authorization", `Bearer ${apiKey}`);
     if (options.lastEventId !== undefined) {
         headers.set("last-event-id", String(options.lastEventId));
     }
@@ -58,45 +160,80 @@ export async function* streamFeed(client, options = {}) {
         const body = await safeText(response);
         throw errorFromResponse(response.status, tryParse(body), retryAfterSeconds(response));
     }
+    // A 2xx that is not an event stream (an HTML page from a proxy, a JSON body
+    // from a route that moved) used to read as an empty stream that closed
+    // cleanly, which the reconnect loop then retried as an outage (#16248).
+    const mediaType = response.headers.get("content-type");
+    if (!isEventStreamMediaType(mediaType)) {
+        await response.body?.cancel().catch(() => undefined);
+        throw new StreamProtocolError("unexpected_media_type", {
+            lastSeq: undefined,
+            mediaType,
+        });
+    }
     if (!response.body) {
         throw new Error("Stream response has no readable body");
     }
     const reader = response.body.getReader();
     const decoder = new TextDecoder();
+    const encoder = new TextEncoder();
     let buffer = "";
+    // Bytes of `buffer`: exact, since every chunk adds its own byte length and
+    // a cut re-measures the remainder. Bounded by `maxFrameBytes`.
+    let bufferedBytes = 0;
+    let lastSeq;
     try {
         for (;;) {
             const { value, done } = await reader.read();
             if (done)
                 break;
             buffer += decoder.decode(value, { stream: true });
+            bufferedBytes += value.byteLength;
             // SSE frames are separated by a blank line. Handle CRLF and LF.
             let sepIndex = nextFrameBoundary(buffer);
+            if (sepIndex.index === -1 && bufferedBytes > maxFrameBytes) {
+                throw new StreamProtocolError("frame_too_large", {
+                    lastSeq,
+                    bytes: bufferedBytes,
+                });
+            }
             while (sepIndex.index !== -1) {
                 const rawFrame = buffer.slice(0, sepIndex.index);
+                // A complete frame is held to the same ceiling as an incomplete one,
+                // before it is parsed, advances the cursor, or is yielded: a chunk
+                // carrying an oversized frame and its delimiter together never reaches
+                // the no-delimiter check above (#16644). `lastSeq` stays the last
+                // delivered event.
+                const frameBytes = encoder.encode(rawFrame).byteLength;
+                if (frameBytes > maxFrameBytes) {
+                    throw new StreamProtocolError("frame_too_large", {
+                        lastSeq,
+                        bytes: frameBytes,
+                    });
+                }
                 buffer = buffer.slice(sepIndex.index + sepIndex.length);
                 const parsed = parseSseFrame(rawFrame);
                 if (parsed) {
-                    if (parsed.event === "resync") {
-                        const marker = (tryParse(parsed.data) ?? {});
-                        options.onResync?.(marker);
-                        yield { kind: "resync", seq: parsed.id ?? null, marker };
+                    const frame = decodeStreamFrame(parsed, lastSeq);
+                    if (frame.kind === "resync") {
+                        options.onResync?.(frame.marker);
                     }
                     else {
-                        const envelope = tryParse(parsed.data);
-                        if (envelope && typeof envelope === "object") {
-                            const seq = typeof envelope.seq === "number"
-                                ? envelope.seq
-                                : (parsed.id ?? NaN);
-                            if (Number.isFinite(seq) && options.cursor) {
-                                options.cursor.seq = seq;
-                            }
-                            yield { kind: "event", seq, envelope };
-                        }
+                        lastSeq = frame.seq;
+                        if (options.cursor)
+                            options.cursor.seq = frame.seq;
                     }
+                    yield frame;
                 }
                 sepIndex = nextFrameBoundary(buffer);
             }
+            bufferedBytes = buffer === "" ? 0 : encoder.encode(buffer).byteLength;
+            if (bufferedBytes > maxFrameBytes) {
+                throw new StreamProtocolError("frame_too_large", {
+                    lastSeq,
+                    bytes: bufferedBytes,
+                });
+            }
         }
     }
     finally {
@@ -115,6 +252,8 @@ export async function* streamFeed(client, options = {}) {
 }
 /** Default for `ResilientStreamOptions.maxReconnects`. */
 export const DEFAULT_MAX_STREAM_RECONNECTS = 10;
+/** Default for `ResilientStreamOptions.maxRetryAfterMs`. */
+export const DEFAULT_MAX_STREAM_RETRY_AFTER_MS = RETRY_AFTER_CEILING_MS;
 const STREAM_RECONNECT_BASE_MS = 1_000;
 const STREAM_RECONNECT_MAX_MS = 30_000;
 const STREAM_RECONNECT_JITTER_MS = 250;
@@ -133,6 +272,35 @@ export class StreamReconnectsExhaustedError extends Error {
         this.lastSeq = lastSeq;
     }
 }
+/**
+ * `streamFeedResilient` was refused with a `Retry-After` longer than
+ * `maxRetryAfterMs`, so the wait is yours to schedule (#16249). `retryAt` is
+ * the server's not-before instant as this client read it (the header's
+ * seconds added to the local clock, or the header's HTTP-date); `cause` is
+ * the refusal, whose `retryAt` (from the body's `retry_at`) is the server's
+ * own clock reading of the same instant. `lastSeq` is the seq to resume after:
+ * pass it as `lastEventId` when you reconnect at `retryAt`. `attempts` is how
+ * many consecutive failed connections preceded this one; the refusal itself
+ * spent none of `maxReconnects`.
+ *
+ * Nothing here was clamped: a wait the timer cannot hold is never shortened
+ * into an earlier reconnect.
+ */
+export class StreamRetryDeferredError extends Error {
+    retryAt;
+    retryAfterMs;
+    lastSeq;
+    attempts;
+    constructor(retryAfterMs, lastSeq, attempts, cause) {
+        const retryAt = new Date(Date.now() + retryAfterMs);
+        super(`0xinsider stream refused with Retry-After ${String(Math.round(retryAfterMs / 1000))} s, past the in-process ceiling; reconnect after ${retryAt.toISOString()}${lastSeq === undefined ? "" : ` with lastEventId ${String(lastSeq)}`}`, { cause });
+        this.name = "StreamRetryDeferredError";
+        this.retryAt = retryAt;
+        this.retryAfterMs = retryAfterMs;
+        this.lastSeq = lastSeq;
+        this.attempts = attempts;
+    }
+}
 /**
  * A 4xx other than 429 will fail the same way on every reconnect: a bad filter
  * (400), a key that is invalid (401), lapsed (402), refused (403), or locked
@@ -140,40 +308,49 @@ export class StreamReconnectsExhaustedError extends Error {
  * has to fix.
  */
 function isPermanentStreamError(error) {
+    // A protocol error is permanent too (#16248): reconnecting from `lastSeq`
+    // replays the same frame while the server retains it, and a wrong media
+    // type is the same answer on every connection.
+    if (error instanceof StreamProtocolError)
+        return true;
+    // A terminal frame that said `retry: false` (#16546).
+    if (error instanceof OxinsiderApiError && permanentTerminalErrors.has(error)) {
+        return true;
+    }
     return (error instanceof OxinsiderApiError &&
         error.status >= 400 &&
         error.status < 500 &&
         error.status !== 429);
 }
-function streamReconnectDelayMs(attempt, cause) {
-    const retryAfter = cause instanceof OxinsiderApiError &&
+/**
+ * The wait the server asked for, in ms, or `null` when the refusal carried
+ * no usable `Retry-After` (a network error, a clean close, a 5xx without the
+ * header). The header is parsed once, by `retry.ts`, when the error is built.
+ */
+function serverRequestedWaitMs(cause) {
+    return cause instanceof OxinsiderApiError &&
         "retryAfterSeconds" in cause &&
-        typeof cause.retryAfterSeconds === "number"
-        ? cause.retryAfterSeconds
+        typeof cause.retryAfterSeconds === "number" &&
+        Number.isFinite(cause.retryAfterSeconds) &&
+        cause.retryAfterSeconds >= 0
+        ? cause.retryAfterSeconds * 1000
         : null;
-    if (retryAfter !== null) {
-        return Math.max(0, retryAfter * 1000) + Math.random() * STREAM_RECONNECT_JITTER_MS;
-    }
+}
+/**
+ * Milliseconds before reconnect `attempt` (1-based) when the server did not
+ * say: a jittered exponential backoff from 1 s capped at 30 s. A server-
+ * requested wait is handled by the loop, which checks it against
+ * `maxRetryAfterMs` before adding jitter.
+ */
+function streamBackoffMs(attempt) {
     const ceiling = Math.min(STREAM_RECONNECT_MAX_MS, STREAM_RECONNECT_BASE_MS * 2 ** (attempt - 1));
     return ceiling / 2 + Math.random() * (ceiling / 2);
 }
-/** Resolve `true` after `ms`, or `false` the moment `signal` aborts. */
-function waitUnlessAborted(ms, signal) {
-    return new Promise((resolve) => {
-        if (signal?.aborted) {
-            resolve(false);
-            return;
-        }
-        const onAbort = () => {
-            clearTimeout(timer);
-            resolve(false);
-        };
-        const timer = setTimeout(() => {
-            signal?.removeEventListener("abort", onAbort);
-            resolve(true);
-        }, ms);
-        signal?.addEventListener("abort", onAbort, { once: true });
-    });
+function assertMaxRetryAfterMs(value) {
+    if (Number.isNaN(value) || value < 0) {
+        throw new Error(`maxRetryAfterMs must be a non-negative number of milliseconds or Infinity, got ${String(value)}`);
+    }
+    return value;
 }
 /**
  * `streamFeed` with the reconnect-and-resume loop built in (#14286).
@@ -181,10 +358,15 @@ function waitUnlessAborted(ms, signal) {
  * - A clean server close, a network error, a 429 or a 5xx reconnects,
  *   resuming after the last delivered seq (`Last-Event-ID`). Before any frame
  *   arrives it resumes from `lastEventId`, or attaches live when that is unset.
- * - The wait is `Retry-After` plus jitter when the refusal carries one,
- *   otherwise a jittered backoff from 1 s capped at 30 s.
+ * - The wait is `Retry-After` (delta-seconds or an HTTP-date) plus jitter when
+ *   the refusal carries one, otherwise a jittered backoff from 1 s capped at
+ *   30 s. A `Retry-After` past `maxRetryAfterMs` (60 s by default) is not
+ *   waited out: the loop throws `StreamRetryDeferredError` with `retryAt` and
+ *   `lastSeq`, spending no reconnect, and never clamps the wait to an earlier
+ *   one (#16249).
  * - Any other 4xx (400, 401, 402, 403, 423) is thrown at once: it cannot heal
- *   on its own.
+ *   on its own. So is `StreamProtocolError` (#16248): a resume from
+ *   `lastSeq` would replay the malformed frame, so the decision is yours.
  * - After `maxReconnects` consecutive connections that delivered nothing, it
  *   throws `StreamReconnectsExhaustedError` carrying `lastSeq`.
  * - `resync` markers are yielded unchanged, and `onResync` still fires. The
@@ -196,7 +378,10 @@ function waitUnlessAborted(ms, signal) {
  * - No request deadline applies, as with `streamFeed`.
  *
  * `options.cursor`, when passed, tracks the last delivered seq across every
- * connection.
+ * connection -- delivered, not processed (#16247). This loop resumes from it,
+ * so a consumer whose handler can fail should drive the stream with
+ * `consumeStreamCheckpointed` instead, which resumes from an acknowledged
+ * checkpoint and replays the event it failed on.
  *
  * @example
  * const controller = new AbortController();
@@ -210,13 +395,14 @@ function waitUnlessAborted(ms, signal) {
  * }
  */
 export async function* streamFeedResilient(client, options = {}) {
-    const { maxReconnects = DEFAULT_MAX_STREAM_RECONNECTS, onReconnect, ...streamOptions } = options;
+    const { maxReconnects = DEFAULT_MAX_STREAM_RECONNECTS, maxRetryAfterMs = DEFAULT_MAX_STREAM_RETRY_AFTER_MS, onReconnect, ...streamOptions } = options;
     if (!Number.isInteger(maxReconnects) || maxReconnects < 0) {
         throw new Error(`maxReconnects must be a non-negative integer, got ${String(maxReconnects)}`);
     }
+    const retryAfterCeilingMs = assertMaxRetryAfterMs(maxRetryAfterMs);
     // The one configuration error `streamFeed` throws before any request; it
     // would otherwise count as a transport failure and burn every reconnect.
-    if (!client.getApiKey()) {
+    if (!client.getApiKey() && !client.isSandbox()) {
         throw new Error("streamFeedResilient requires an API key (oxi_sk_*)");
     }
     const signal = streamOptions.signal;
@@ -249,13 +435,24 @@ export async function* streamFeedResilient(client, options = {}) {
         }
         if (signal?.aborted)
             return;
-        attempt += 1;
         const lastSeq = cursor.seq ?? toSeq(initialLastEventId);
+        // A server-requested wait past the ceiling is deferred to the caller
+        // BEFORE it counts as a reconnect: the server said when, and burning the
+        // short reconnect budget on a wait we will not hold would be spending it
+        // on nothing.
+        const requestedMs = serverRequestedWaitMs(cause);
+        if (requestedMs !== null && requestedMs > retryAfterCeilingMs) {
+            throw new StreamRetryDeferredError(requestedMs, lastSeq, attempt, cause);
+        }
+        attempt += 1;
         if (attempt > maxReconnects) {
             throw new StreamReconnectsExhaustedError(attempt - 1, lastSeq, cause);
         }
         onReconnect?.(attempt, lastSeq, cause);
-        if (!(await waitUnlessAborted(streamReconnectDelayMs(attempt, cause), signal))) {
+        const delayMs = requestedMs === null
+            ? streamBackoffMs(attempt)
+            : requestedMs + Math.random() * STREAM_RECONNECT_JITTER_MS;
+        if (!(await waitUnlessAborted(delayMs, signal))) {
             return;
         }
     }
@@ -270,6 +467,13 @@ function toSeq(value) {
  * Callback-style stream consumer for environments where an async iterator is
  * awkward. Returns a promise that resolves when the stream ends (or rejects on
  * error / abort). Pass a `signal` to stop it.
+ *
+ * Delivery, not processing (#16247): `options.cursor` is written by
+ * `streamFeed` BEFORE the frame is yielded, so it has already moved past an
+ * event whose `onEvent` then throws. Reconnecting from it skips that event.
+ * For a consumer that must not lose work, use `consumeStreamCheckpointed`,
+ * which advances an acknowledged checkpoint only after the handler and your
+ * own durable write have both resolved.
  */
 export async function consumeStream(client, handlers, options = {}) {
     for await (const frame of streamFeed(client, options)) {
@@ -281,8 +485,230 @@ export async function consumeStream(client, handlers, options = {}) {
         }
     }
 }
+/**
+ * `consumeStreamCheckpointed` gave up after `maxHandlerRetries` consecutive
+ * failures at the same sequence (#16247). `checkpoint` is the acknowledged
+ * sequence, still behind the failing one, and `replayFrom` is the point a
+ * later resume should pass as `lastEventId` to deliver the failed frame
+ * again while the server retains it. `cause` is the last rejection your
+ * handler produced.
+ */
+export class StreamHandlerFailedError extends Error {
+    seq;
+    stage;
+    attempts;
+    checkpoint;
+    replayFrom;
+    constructor(detail, cause) {
+        super(`0xinsider stream handler failed ${String(detail.attempts)} time(s) at ${detail.seq === undefined ? "a resync marker" : `seq ${String(detail.seq)}`} (${detail.stage}); the acknowledged checkpoint is ${detail.checkpoint === undefined ? "unset" : String(detail.checkpoint)}`, { cause });
+        this.name = "StreamHandlerFailedError";
+        this.seq = detail.seq;
+        this.stage = detail.stage;
+        this.attempts = detail.attempts;
+        this.checkpoint = detail.checkpoint;
+        this.replayFrom = detail.replayFrom;
+    }
+}
+/** Default for `CheckpointedStreamOptions.maxHandlerRetries`. */
+export const DEFAULT_MAX_HANDLER_RETRIES = 3;
+/**
+ * The resume point that replays `seq` itself when nothing has been
+ * acknowledged yet.
+ *
+ * `Last-Event-ID` is an EXCLUSIVE lower bound on the server: the replay
+ * window is `latest - requested` entries taken from the tail of the retained
+ * history, so a resume at `S - 1` delivers `S` onward and nothing older
+ * (`shared_feed_history_since`, `backend/crates/app-core/src/feed_publisher.rs`;
+ * `backend/src/api_v1/handlers/stream.rs` builds the plan from it, read
+ * 2026-09-22). Sequences are a cluster-wide integer counter, so nothing sits
+ * between `S - 1` and `S`. A non-integer or non-positive sequence gets no
+ * step-back: there is no id we can name that is certainly below it.
+ */
+function replayPointBefore(seq) {
+    return seq !== undefined && Number.isInteger(seq) && seq >= 1
+        ? seq - 1
+        : undefined;
+}
+/**
+ * The stream consumer for work that must not be silently dropped (#16247):
+ * it separates the received cursor from an acknowledged processing
+ * checkpoint, and only the checkpoint decides where a reconnect resumes.
+ *
+ * Ordering, per frame, for `kind: "event"`:
+ *   1. `onEvent` is awaited. Nothing is read from the connection while it
+ *      runs, so a slow handler is backpressure on the socket, never a queue:
+ *      at most one frame is ever in flight and nothing is buffered on your
+ *      behalf.
+ *   2. `onCheckpoint(seq, "event")` is awaited -- your durable write.
+ *   3. Only then does `checkpoint.seq` become `seq`, and only then does the
+ *      next reconnect resume after it.
+ * A rejection at step 1 or 2 leaves the checkpoint BEFORE the event: the
+ * connection is closed, a jittered backoff runs, and the consumer reconnects
+ * from the checkpoint, which replays the unacknowledged event while the
+ * server retains it. `onHandlerError` reports each failure with its attempt
+ * number, the replay point and whether another attempt follows. After
+ * `maxHandlerRetries` consecutive failures at the same sequence it throws
+ * `StreamHandlerFailedError`, carrying the unadvanced checkpoint.
+ *
+ * A `resync` marker is the same barrier: `onResync` is awaited, then
+ * `onCheckpoint(seq, "resync")`, and an interrupted refresh commits nothing,
+ * so the recovery is retried instead of being recorded as done. (The
+ * fire-and-forget `StreamOptions.onResync` notification is not awaited and is
+ * not a barrier -- do not use it as one.)
+ *
+ * Delivery is AT-LEAST-ONCE. A replay re-delivers every unacknowledged frame,
+ * and a handler that succeeded but whose `onCheckpoint` write failed sees its
+ * event again. Deduplicate on `seq` (it is monotonic per cluster) or make the
+ * side effect idempotent; nothing here can promise exactly-once side effects.
+ *
+ * `options.cursor` is untouched in meaning: it still tracks the last
+ * DELIVERED seq, including frames whose handler later failed, and it rewinds
+ * when a replay re-delivers them. Read it for transport progress; never as
+ * proof that the work was done.
+ *
+ * Transport recovery, `Retry-After` handling, permanent 4xx and
+ * `StreamProtocolError` behave exactly as in `streamFeedResilient`, which
+ * this drives. `StreamReconnectsExhaustedError` and
+ * `StreamRetryDeferredError` surface unchanged; their `lastSeq` is the
+ * acknowledged checkpoint, because a reconnect can only happen between
+ * handlers. Aborting `signal` ends the consumer without throwing: a handler
+ * already running is awaited (it is not cancelled for you -- pass the same
+ * signal into your own work if you want that), and if it succeeds its
+ * checkpoint is committed before the consumer returns.
+ *
+ * @example
+ * const checkpoint = { seq: await loadCheckpoint() };
+ * await consumeStreamCheckpointed(client, {
+ *   onEvent: async (envelope, seq) => { await applyOnce(seq, envelope); },
+ *   onResync: async () => { await refetchCurrentState(); },
+ *   onCheckpoint: async (seq) => { await saveCheckpoint(seq); },
+ * }, {
+ *   event: ["WhaleTradesInserted"],
+ *   lastEventId: checkpoint.seq,
+ *   checkpoint,
+ *   signal: controller.signal,
+ *   onHandlerError: (error, failure) =>
+ *     console.warn("replaying", failure.seq, failure.attempt, failure.willRetry, error),
+ * });
+ */
+export async function consumeStreamCheckpointed(client, handlers, options = {}) {
+    const { checkpoint = {}, maxHandlerRetries = DEFAULT_MAX_HANDLER_RETRIES, onHandlerError, ...streamOptions } = options;
+    if (!Number.isInteger(maxHandlerRetries) || maxHandlerRetries < 0) {
+        throw new Error(`maxHandlerRetries must be a non-negative integer, got ${String(maxHandlerRetries)}`);
+    }
+    const signal = streamOptions.signal;
+    // The caller's received cursor, if they passed one. It keeps its delivery
+    // meaning: this consumer mirrors every frame into it and never reads it
+    // back as a resume point.
+    const received = streamOptions.cursor;
+    const initialLastEventId = toSeq(streamOptions.lastEventId);
+    // Where the next connection resumes. It starts at the acknowledged
+    // checkpoint (or the caller's `lastEventId`) and only ever moves to a
+    // sequence whose processing completed.
+    let resumeAfter = checkpoint.seq ?? initialLastEventId;
+    let failingSeq;
+    let failures = 0;
+    for (;;) {
+        if (signal?.aborted)
+            return;
+        let pending;
+        // A cursor private to this connection: `streamFeedResilient` reads it
+        // back as its own resume point across transport reconnects, so the
+        // caller's received cursor must never be handed to it -- that cursor has
+        // already moved past an unacknowledged event, and lending it would make
+        // the replay resume after the frame it exists to redeliver.
+        const delivered = { seq: resumeAfter };
+        for await (const frame of streamFeedResilient(client, {
+            ...streamOptions,
+            cursor: delivered,
+            lastEventId: resumeAfter,
+        })) {
+            if (received && delivered.seq !== undefined)
+                received.seq = delivered.seq;
+            if (frame.kind === "event") {
+                try {
+                    await handlers.onEvent(frame.envelope, frame.seq);
+                }
+                catch (error) {
+                    pending = { error, stage: "event", seq: frame.seq };
+                    break;
+                }
+                try {
+                    await handlers.onCheckpoint?.(frame.seq, "event");
+                }
+                catch (error) {
+                    pending = { error, stage: "checkpoint", seq: frame.seq };
+                    break;
+                }
+                checkpoint.seq = frame.seq;
+                resumeAfter = frame.seq;
+            }
+            else {
+                try {
+                    await handlers.onResync?.(frame.marker, frame.seq);
+                }
+                catch (error) {
+                    pending = { error, stage: "resync", seq: frame.seq ?? undefined };
+                    break;
+                }
+                if (frame.seq !== null) {
+                    try {
+                        await handlers.onCheckpoint?.(frame.seq, "resync");
+                    }
+                    catch (error) {
+                        pending = { error, stage: "checkpoint", seq: frame.seq };
+                        break;
+                    }
+                    checkpoint.seq = frame.seq;
+                    resumeAfter = frame.seq;
+                }
+            }
+            failures = 0;
+            failingSeq = undefined;
+            if (signal?.aborted)
+                return;
+        }
+        // `streamFeedResilient` only ends without throwing when the signal was
+        // aborted, so a loop that ends with nothing pending is a clean stop.
+        if (!pending)
+            return;
+        const failedSeq = pending.seq;
+        if (failures > 0 && failedSeq === failingSeq) {
+            failures += 1;
+        }
+        else {
+            failingSeq = failedSeq;
+            failures = 1;
+        }
+        resumeAfter =
+            checkpoint.seq ?? initialLastEventId ?? replayPointBefore(failedSeq);
+        const willRetry = failures <= maxHandlerRetries;
+        onHandlerError?.(pending.error, {
+            seq: failedSeq,
+            stage: pending.stage,
+            attempt: failures,
+            willRetry,
+            replayFrom: resumeAfter,
+            checkpoint: checkpoint.seq,
+        });
+        if (!willRetry) {
+            throw new StreamHandlerFailedError({
+                seq: failedSeq,
+                stage: pending.stage,
+                attempts: failures,
+                checkpoint: checkpoint.seq,
+                replayFrom: resumeAfter,
+            }, pending.error);
+        }
+        if (!(await waitUnlessAborted(streamBackoffMs(failures), signal))) {
+            return;
+        }
+    }
+}
 function buildStreamUrl(client, options) {
-    const url = new URL("api/v1/stream", `${client.getBaseUrl()}/`);
+    // Through the same resolver as `buildUrl`, so a path-bearing base such as
+    // the sandbox's `/sandbox` lands in the same place for REST and SSE.
+    const url = resolveApiUrl(client.getBaseUrl(), "/api/v1/stream");
     if (options.event && options.event.length > 0) {
         url.searchParams.set("event", options.event.join(","));
     }
@@ -363,6 +789,113 @@ function nextFrameBoundary(buffer) {
         ? candidate
         : best);
 }
+/**
+ * Turn one parsed SSE frame into a `StreamEvent`, or throw
+ * `StreamProtocolError` (#16248). `lastSeq` is only carried onto the error.
+ */
+export function decodeStreamFrame(parsed, lastSeq) {
+    const detail = {
+        lastSeq,
+        frameId: parsed.id,
+        event: parsed.event,
+        bytes: new TextEncoder().encode(parsed.data).byteLength,
+    };
+    let payload;
+    try {
+        payload = parsed.data === "" ? undefined : JSON.parse(parsed.data);
+    }
+    catch {
+        throw new StreamProtocolError("invalid_json", detail);
+    }
+    if (parsed.event === "error") {
+        throw terminalStreamError(payload, detail);
+    }
+    if (parsed.event === "resync") {
+        if (!isPlainObject(payload)) {
+            throw new StreamProtocolError("invalid_resync", detail);
+        }
+        if ("type" in payload && payload.type !== "resync") {
+            throw new StreamProtocolError("invalid_resync", detail);
+        }
+        return {
+            kind: "resync",
+            seq: parsed.id ?? null,
+            marker: payload,
+        };
+    }
+    if (payload === undefined) {
+        throw new StreamProtocolError("invalid_json", detail);
+    }
+    if (!isPlainObject(payload)) {
+        throw new StreamProtocolError("invalid_envelope", detail);
+    }
+    const seq = typeof payload.seq === "number" && Number.isFinite(payload.seq)
+        ? payload.seq
+        : parsed.id;
+    if (seq === undefined || !Number.isFinite(seq)) {
+        throw new StreamProtocolError("unusable_sequence", detail);
+    }
+    return { kind: "event", seq, envelope: payload };
+}
+/**
+ * The HTTP status the reconnect is answered with, for each code a terminal
+ * `event: error` frame carries (#16546). The frame has no status of its own;
+ * this mirrors `ApiError::status_code` in `backend/crates/api-core`, so the
+ * error thrown mid-stream is the one the next request would get.
+ */
+const STREAM_ERROR_CODE_STATUS = {
+    bad_request: 400,
+    invalid_api_key: 401,
+    subscription_required: 402,
+    forbidden: 403,
+    insufficient_scope: 403,
+    not_found: 404,
+    request_timeout: 408,
+    account_locked: 423,
+    rate_limited: 429,
+    internal_error: 500,
+    rate_limit_unavailable: 503,
+};
+const STREAM_ERROR_UNAVAILABLE_REASONS = new Set([
+    "database_unavailable",
+    "read_model_warming",
+    "request_accounting_unavailable",
+]);
+/**
+ * Errors built from a terminal frame that said `retry: false`: permanent
+ * whatever their status, so no consumer reconnects on them (#16546).
+ */
+const permanentTerminalErrors = new WeakSet();
+/**
+ * The typed error a terminal `event: error` frame stands for (#16546).
+ *
+ * The backend ends `/api/v1/stream` with `{ "type": "error", "error": {...},
+ * "retry": <bool> }` when the key is revoked, the account lapses, or the
+ * credential store cannot confirm the key. The frame is never a feed event:
+ * it is thrown, so it reaches no handler and moves no cursor or checkpoint.
+ * `retry: false` is permanent; `retry: true` goes through the resilient
+ * consumer's reconnect path like any 5xx.
+ */
+function terminalStreamError(payload, detail) {
+    if (!isPlainObject(payload) || !isPlainObject(payload.error)) {
+        return new StreamProtocolError("invalid_envelope", detail);
+    }
+    const body = payload.error;
+    const retry = payload.retry === true;
+    const code = typeof body.code === "string" ? body.code : undefined;
+    const reason = typeof body.reason === "string" ? body.reason : undefined;
+    const status = reason !== undefined && STREAM_ERROR_UNAVAILABLE_REASONS.has(reason)
+        ? 503
+        : ((code !== undefined ? STREAM_ERROR_CODE_STATUS[code] : undefined) ??
+            (retry ? 503 : 400));
+    const error = errorFromResponse(status, { object: "error", error: body });
+    if (!retry)
+        permanentTerminalErrors.add(error);
+    return error;
+}
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
 function tryParse(text) {
     if (text === null || text === "")
         return null;
@@ -381,11 +914,4 @@ async function safeText(response) {
         return "";
     }
 }
-function retryAfterSeconds(response) {
-    const header = response.headers.get("retry-after");
-    if (!header)
-        return null;
-    const seconds = Number(header);
-    return Number.isFinite(seconds) ? seconds : null;
-}
 //# sourceMappingURL=stream.js.map