@opengeni/api-router 0.30.1 → 1.0.0

package/src/http/sse.ts

@@ -5,23 +5,29 @@ import {
 } from "@opengeni/contracts";
 import {
   getWorkspaceInteractionRevisionState,
-  listSessionEvents,
+  listSessionEventPage,
   listWorkspaceControlEvents,
   type Database,
 } from "@opengeni/db";
 import {
+  coalesceSessionEventDeltasWithCoverage,
   formatSessionEventSse,
   formatWorkspaceControlEventSse,
+  requireSessionEventDurableFanoutCapability,
   SESSION_EVENT_SSE_FRAME_MAX_BYTES,
   type EventBus,
 } from "@opengeni/events";
 import type { Observability } from "@opengeni/observability";
+import { MANAGED_AUTH_ACTOR_EPOCH_HEADER } from "@opengeni/core/managed-auth-session-sets";
 
 const SESSION_REPLAY_PAGE_SIZE = 100;
+const SESSION_REPLAY_PAGE_MAX_BYTES = 8 * 1024 * 1024;
 const WORKSPACE_CONTROL_REPLAY_PAGE_SIZE = 100;
 export const SSE_QUEUED_FRAME_MAX_COUNT = 1;
 export const SSE_WRITE_STALL_TIMEOUT_MS = 30_000;
 export const SSE_HEARTBEAT_INTERVAL_MS = 15_000;
+export const HTTP1_BROWSER_SSE_BATCH_MAX_BYTES = 512 * 1024;
+export const HTTP1_BROWSER_SSE_BATCH_CONTENT_TYPE = "application/vnd.opengeni.sse-batch";
 type SseStreamKind = "session" | "workspace_control" | "workspace_interaction";
 const activeSseStreams: Record<SseStreamKind, number> = {
   session: 0,
@@ -37,6 +43,7 @@ export type SseDeliveryBoundObservation = {
 };
 
 export type ByteBoundedSseStreamOptions = {
+  connectionLifetimeMs?: number | undefined;
   maxQueuedBytes?: number;
   stallTimeoutMs?: number;
   onStop?: () => void;
@@ -57,27 +64,36 @@ export type ByteBoundedSseStream = {
  * checking `desiredSize` can still accumulate an unbounded server-side queue.
  *
  * One writer is expected per stream. The Web Streams queue holds at most one
- * complete frame, and that frame must fit inside the byte cap. A second write
+ * complete frame. One oversized frame is delivered intact rather than lost;
+ * the byte budget is a batching target, not a content limit. A second write
  * waits for consumer pull only for a bounded interval; cancellation or a stalled
  * reader wakes it and terminates upstream delivery before another durable page is
- * read. One frame is deliberate: it makes both queued-frame count and queued
- * bytes independently bounded instead of relying on byte accounting alone.
+ * read. One frame is deliberate: queued memory is bounded by one event, not
+ * by the size of the session, without imposing a lossy per-message limit.
  */
 export function createByteBoundedSseStream(
   options: ByteBoundedSseStreamOptions = {},
 ): ByteBoundedSseStream {
   const maxQueuedBytes = options.maxQueuedBytes ?? SESSION_EVENT_SSE_FRAME_MAX_BYTES;
   const stallTimeoutMs = options.stallTimeoutMs ?? SSE_WRITE_STALL_TIMEOUT_MS;
+  const connectionLifetimeMs = options.connectionLifetimeMs;
   if (!Number.isSafeInteger(maxQueuedBytes) || maxQueuedBytes <= 0) {
     throw new RangeError("SSE byte high-water mark must be a positive safe integer");
   }
   if (!Number.isSafeInteger(stallTimeoutMs) || stallTimeoutMs <= 0) {
     throw new RangeError("SSE write stall timeout must be a positive safe integer");
   }
+  if (
+    connectionLifetimeMs !== undefined &&
+    (!Number.isSafeInteger(connectionLifetimeMs) || connectionLifetimeMs <= 0)
+  ) {
+    throw new RangeError("SSE connection lifetime must be a positive safe integer");
+  }
   const encoder = new TextEncoder();
   let controller!: ReadableStreamDefaultController<Uint8Array>;
   let stopped = false;
   let capacityWake: (() => void) | null = null;
+  let lifetimeTimer: ReturnType<typeof setTimeout> | null = null;
   let queuedFrames = 0;
   let queuedBytes = 0;
 
@@ -89,6 +105,10 @@ export function createByteBoundedSseStream(
   const stop = (settle: () => void) => {
     if (stopped) return;
     stopped = true;
+    if (lifetimeTimer !== null) {
+      clearTimeout(lifetimeTimer);
+      lifetimeTimer = null;
+    }
     wakeWriter();
     options.onStop?.();
     try {
@@ -123,29 +143,19 @@ export function createByteBoundedSseStream(
       size: () => 1,
     },
   );
+  if (connectionLifetimeMs !== undefined) {
+    lifetimeTimer = setTimeout(() => stop(() => controller.close()), connectionLifetimeMs);
+  }
 
   return {
     stream,
     write: async (frame) => {
-      const chunk = encoder.encode(frame);
-      if (chunk.byteLength > maxQueuedBytes) {
-        const error = new RangeError(
-          `SSE frame cannot fit in the configured queue (${chunk.byteLength} > ${maxQueuedBytes} bytes)`,
-        );
-        options.onObservation?.({
-          reason: "frame_too_large",
-          desiredSize: controller.desiredSize,
-          queuedFrames,
-          queuedBytes,
-        });
-        stop(() => controller.error(error));
-        throw error;
-      }
       for (;;) {
         if (stopped) return false;
         const desired = controller.desiredSize;
         if (desired === null) return false;
         if (desired >= 1 && queuedFrames === 0) {
+          const chunk = encoder.encode(frame);
           controller.enqueue(chunk);
           queuedFrames = 1;
           queuedBytes = chunk.byteLength;
@@ -267,32 +277,42 @@ export async function sseSessionStream(
   signal: AbortSignal,
   options: SessionSseDeliveryOptions = {},
 ): Promise<Response> {
-  const heartbeatIntervalMs = resolveHeartbeatInterval(options.heartbeatIntervalMs);
-  if (
-    options.reauthorize &&
-    options.reauthorizeAfterMs !== undefined &&
-    (!Number.isSafeInteger(options.reauthorizeAfterMs) ||
-      options.reauthorizeAfterMs < 1_000 ||
-      options.reauthorizeAfterMs > 60_000)
-  ) {
-    throw new RangeError("session stream reauthorization must be between 1000 and 60000ms");
+  if (isHttp1BrowserBatch(options)) {
+    const { events } = await listSessionEventPage(db, workspaceId, sessionId, {
+      after,
+      limit: SESSION_REPLAY_PAGE_SIZE,
+      maxBytes: options.finiteResponseMaxBytes ?? HTTP1_BROWSER_SSE_BATCH_MAX_BYTES,
+    });
+    await options.reauthorize?.();
+    const compactProjection = coalesceSessionEventDeltasWithCoverage(events);
+    return finiteSseBatchResponse(
+      compactProjection.events.map((event) =>
+        formatSessionEventSse(
+          event,
+          compactProjection.coveredThroughBySequence.get(event.sequence) ?? event.sequence,
+        ),
+      ),
+      options,
+    );
   }
+  const durableFanout = requireSessionEventDurableFanoutCapability(bus);
+  const heartbeatIntervalMs = resolveHeartbeatInterval(options.heartbeatIntervalMs);
   let lastSent = after;
   let bootstrapping = true;
   let newestBuffered: SessionEvent | null = null;
   let unsubscribe: (() => void) | null = null;
   let delivery: LatestWinsDelivery<SessionEvent> | null = null;
-  let reauthorizationTimer: ReturnType<typeof setTimeout> | null = null;
+  let stopReconnectObservation = () => {};
+  let stopReauthorization = () => {};
   let heartbeatTimer: ReturnType<typeof setTimeout> | null = null;
   let detachAbortListener = () => {};
   let closeMetrics = () => {};
   const stopUpstream = () => {
     closeMetrics();
     detachAbortListener();
-    if (reauthorizationTimer) {
-      clearTimeout(reauthorizationTimer);
-      reauthorizationTimer = null;
-    }
+    stopReconnectObservation();
+    stopReconnectObservation = () => {};
+    stopReauthorization();
     if (heartbeatTimer) {
       clearTimeout(heartbeatTimer);
       heartbeatTimer = null;
@@ -303,6 +323,7 @@ export async function sseSessionStream(
     release?.();
   };
   const channel = createByteBoundedSseStream({
+    connectionLifetimeMs: options.connectionLifetimeMs,
     maxQueuedBytes: options.maxQueuedBytes ?? SESSION_EVENT_SSE_FRAME_MAX_BYTES,
     ...(options.stallTimeoutMs === undefined ? {} : { stallTimeoutMs: options.stallTimeoutMs }),
     onObservation: sseObservationReporter("session", options),
@@ -313,25 +334,111 @@ export async function sseSessionStream(
   const fail = (error: unknown) => {
     channel.fail(retryableSseFailure("session event stream delivery failed", error));
   };
-  const scheduleReauthorization = () => {
-    if (!options.reauthorize || channel.stopped()) return;
-    const interval = options.reauthorizeAfterMs ?? 15_000;
-    reauthorizationTimer = setTimeout(() => {
-      reauthorizationTimer = null;
-      void options.reauthorize!()
-        .then(scheduleReauthorization)
-        .catch((error) => fail(error));
-    }, interval);
-  };
-  scheduleReauthorization();
+  stopReauthorization = startSseReauthorization(options, channel.stopped, channel.close);
   let writeTail = Promise.resolve();
   const writeFrame = (frame: string): Promise<void> => {
     const write = writeTail.then(async () => {
+      // A periodic check closes an idle stream, while this exact pre-delivery
+      // check prevents a buffered/replayed event from crossing a revocation
+      // boundary merely because its timer has not fired yet.
+      await reauthorizeSseOrClose(options, channel);
       if (!(await channel.write(frame))) throw new SseStreamStoppedError();
     });
     writeTail = write.catch(() => {});
     return write;
   };
+  const deliverDurableThrough = async (targetSequence?: number) => {
+    while (true) {
+      if (targetSequence !== undefined && lastSent >= targetSequence) return;
+      const previousLastSent = lastSent;
+      const limit =
+        targetSequence === undefined
+          ? SESSION_REPLAY_PAGE_SIZE
+          : Math.min(SESSION_REPLAY_PAGE_SIZE, targetSequence - lastSent);
+      const replayPage = await listSessionEventPage(db, workspaceId, sessionId, {
+        after: lastSent,
+        limit,
+        maxBytes: SESSION_REPLAY_PAGE_MAX_BYTES,
+      });
+      const page = replayPage.events;
+      const eligible =
+        targetSequence === undefined
+          ? page
+          : page.filter((event) => event.sequence <= targetSequence);
+      if (eligible.length === 0) {
+        if (targetSequence === undefined) return;
+        throw new Error(
+          `Session event replay stalled before sequence ${targetSequence}; last sent ${lastSent}`,
+        );
+      }
+      // The durable audit log remains exact. The browser transport combines
+      // adjacent text deltas into lossless batches carrying `coalescedUntil`, so
+      // a long answer cannot create thousands of React renders and starve
+      // command acknowledgements behind its own token stream.
+      const compactProjection = coalesceSessionEventDeltasWithCoverage(eligible);
+      for (const projected of compactProjection.events) {
+        const coveredThrough =
+          compactProjection.coveredThroughBySequence.get(projected.sequence) ?? projected.sequence;
+        await writeFrame(formatSessionEventSse(projected, coveredThrough));
+        lastSent = coveredThrough;
+      }
+      if (lastSent <= previousLastSent) {
+        throw new Error(`Session event replay made no progress after sequence ${lastSent}`);
+      }
+      if (targetSequence !== undefined && lastSent >= targetSequence) return;
+      if (targetSequence === undefined && !replayPage.hasMore) return;
+      // A byte-selected page may contain fewer rows than requested, especially
+      // when one large message travels alone. Use explicit continuation rather
+      // than page length; live publication covers appends after the snapshot.
+    }
+  };
+  let durableDeliveryTail = Promise.resolve();
+  const reconcileDurableThrough = (targetSequence?: number): Promise<void> => {
+    const deliveryRun = durableDeliveryTail.then(() => deliverDurableThrough(targetSequence));
+    durableDeliveryTail = deliveryRun.catch(() => {});
+    return deliveryRun;
+  };
+  let newestReconnectGeneration = 0;
+  let reconnectReconcilePending = false;
+  let reconnectReconcileRunning = false;
+  const drainReconnectReconciliation = () => {
+    if (
+      bootstrapping ||
+      reconnectReconcileRunning ||
+      !reconnectReconcilePending ||
+      channel.stopped()
+    ) {
+      return;
+    }
+    reconnectReconcileRunning = true;
+    void (async () => {
+      while (reconnectReconcilePending && !channel.stopped()) {
+        // Multiple reconnects during one durable read collapse into one newest
+        // catch-up. Postgres is authoritative, so that later read covers every
+        // disconnect window without one query per heartbeat or buffered event.
+        reconnectReconcilePending = false;
+        await reconcileDurableThrough();
+      }
+    })()
+      .catch((error) => {
+        if (!(error instanceof SseStreamStoppedError)) fail(error);
+      })
+      .finally(() => {
+        reconnectReconcileRunning = false;
+        drainReconnectReconciliation();
+      });
+  };
+  const scheduleReconnectReconciliation = (generation: number) => {
+    if (generation <= newestReconnectGeneration || channel.stopped()) return;
+    newestReconnectGeneration = generation;
+    reconnectReconcilePending = true;
+    drainReconnectReconciliation();
+  };
+  const send = async (event: SessionEvent) => {
+    const targetSequence = event.sequence;
+    if (targetSequence <= lastSent) return;
+    await reconcileDurableThrough(targetSequence);
+  };
   const scheduleHeartbeat = () => {
     if (channel.stopped()) return;
     heartbeatTimer = setTimeout(() => {
@@ -343,66 +450,43 @@ export async function sseSessionStream(
         });
     }, heartbeatIntervalMs);
   };
-  const send = async (event: SessionEvent) => {
-    if (event.sequence <= lastSent) return;
-    if (event.sequence > lastSent + 1) {
-      while (lastSent + 1 < event.sequence) {
-        const previousLastSent = lastSent;
-        const missing = await listSessionEvents(db, workspaceId, sessionId, {
-          after: lastSent,
-          limit: Math.min(SESSION_REPLAY_PAGE_SIZE, event.sequence - lastSent - 1),
-        });
-        if (missing.length === 0) {
-          throw new Error(
-            `Session event replay stalled before sequence ${event.sequence}; last sent ${lastSent}`,
-          );
-        }
-        for (const missed of missing) {
-          if (missed.sequence >= event.sequence) break;
-          if (missed.sequence > lastSent) {
-            await writeFrame(formatSessionEventSse(missed));
-            lastSent = missed.sequence;
-          }
-        }
-        if (lastSent === previousLastSent) {
-          throw new Error(
-            `Session event replay made no progress before sequence ${event.sequence}; last sent ${lastSent}`,
-          );
-        }
-      }
-    }
-    await writeFrame(formatSessionEventSse(event));
-    lastSent = event.sequence;
-  };
   delivery = createLatestWinsDelivery(send, fail);
+  stopReconnectObservation = durableFanout.subscribeRecovery(scheduleReconnectReconciliation);
 
   void (async () => {
-    const release = await bus.subscribe(workspaceId, sessionId, (events) => {
-      if (bootstrapping) {
-        for (const event of events) {
-          if (!newestBuffered || event.sequence > newestBuffered.sequence) {
-            newestBuffered = event;
+    const release = await bus.subscribe(
+      workspaceId,
+      sessionId,
+      (events) => {
+        if (bootstrapping) {
+          for (const event of events) {
+            if (!newestBuffered || event.sequence > newestBuffered.sequence) {
+              newestBuffered = event;
+            }
           }
+        } else {
+          delivery?.publish(events);
         }
-      } else {
-        delivery?.publish(events);
-      }
-    });
+      },
+      {
+        // Live fanout stopped while this stream still held it. Heartbeats alone
+        // would keep a silently stale timeline open; fail retryably so the
+        // client reconnects and replays from the durable Postgres cursor.
+        onTerminated: (error) =>
+          fail(retryableSseFailure("session live fanout subscription ended", error)),
+      },
+    );
     if (channel.stopped()) {
       release();
       return;
     }
     unsubscribe = release;
 
-    await replaySessionEvents(
-      (cursor, limit) => listSessionEvents(db, workspaceId, sessionId, cursor, limit),
-      send,
-      after,
-      SESSION_REPLAY_PAGE_SIZE,
-    );
+    await reconcileDurableThrough();
     await writeFrame(": connected\n\n");
     scheduleHeartbeat();
     bootstrapping = false;
+    drainReconnectReconciliation();
     const buffered = newestBuffered;
     newestBuffered = null;
     if (buffered) delivery.publish([buffered]);
@@ -419,13 +503,7 @@ export async function sseSessionStream(
     detachAbortListener = () => signal.removeEventListener("abort", abort);
   }
 
-  return new Response(channel.stream, {
-    headers: {
-      "Content-Type": "text/event-stream; charset=utf-8",
-      "Cache-Control": "no-cache, no-transform",
-      Connection: "keep-alive",
-    },
-  });
+  return await sseHttpResponse(channel.stream, options);
 }
 
 export async function replaySessionEvents(
@@ -465,18 +543,35 @@ export async function sseWorkspaceControlStream(
   signal: AbortSignal,
   options: SseDeliveryOptions = {},
 ): Promise<Response> {
+  if (isHttp1BrowserBatch(options)) {
+    const events = await listWorkspaceControlEvents(
+      db,
+      workspaceId,
+      after,
+      WORKSPACE_CONTROL_REPLAY_PAGE_SIZE,
+    );
+    await options.reauthorize?.();
+    return finiteSseBatchResponse(
+      events
+        .sort((left, right) => left.sequence - right.sequence)
+        .map(formatWorkspaceControlEventSse),
+      options,
+    );
+  }
   const heartbeatIntervalMs = resolveHeartbeatInterval(options.heartbeatIntervalMs);
   let lastSent = after;
   let bootstrapping = true;
   let newestBuffered: WorkspaceControlEvent | null = null;
   let unsubscribe: (() => void) | null = null;
   let delivery: LatestWinsDelivery<WorkspaceControlEvent> | null = null;
+  let stopReauthorization = () => {};
   let heartbeatTimer: ReturnType<typeof setTimeout> | null = null;
   let detachAbortListener = () => {};
   let closeMetrics = () => {};
   const stopUpstream = () => {
     closeMetrics();
     detachAbortListener();
+    stopReauthorization();
     if (heartbeatTimer) {
       clearTimeout(heartbeatTimer);
       heartbeatTimer = null;
@@ -487,6 +582,7 @@ export async function sseWorkspaceControlStream(
     release?.();
   };
   const channel = createByteBoundedSseStream({
+    connectionLifetimeMs: options.connectionLifetimeMs,
     maxQueuedBytes: options.maxQueuedBytes ?? SESSION_EVENT_SSE_FRAME_MAX_BYTES,
     ...(options.stallTimeoutMs === undefined ? {} : { stallTimeoutMs: options.stallTimeoutMs }),
     onObservation: sseObservationReporter("workspace_control", options),
@@ -497,9 +593,11 @@ export async function sseWorkspaceControlStream(
   const fail = (error: unknown) => {
     channel.fail(retryableSseFailure("workspace control stream delivery failed", error));
   };
+  stopReauthorization = startSseReauthorization(options, channel.stopped, channel.close);
   let writeTail = Promise.resolve();
   const writeFrame = (frame: string): Promise<void> => {
     const write = writeTail.then(async () => {
+      await reauthorizeSseOrClose(options, channel);
       if (!(await channel.write(frame))) throw new SseStreamStoppedError();
     });
     writeTail = write.catch(() => {});
@@ -551,13 +649,22 @@ export async function sseWorkspaceControlStream(
   delivery = createLatestWinsDelivery(send, fail);
 
   void (async () => {
-    const release = await bus.subscribeWorkspaceControl(workspaceId, (event) => {
-      if (bootstrapping) {
-        if (!newestBuffered || event.sequence > newestBuffered.sequence) newestBuffered = event;
-      } else {
-        delivery?.publish([event]);
-      }
-    });
+    const release = await bus.subscribeWorkspaceControl(
+      workspaceId,
+      (event) => {
+        if (bootstrapping) {
+          if (!newestBuffered || event.sequence > newestBuffered.sequence) newestBuffered = event;
+        } else {
+          delivery?.publish([event]);
+        }
+      },
+      {
+        // Same contract as session SSE: a dead live subscription must reconnect
+        // and replay the durable control cursor, not idle on heartbeats.
+        onTerminated: (error) =>
+          fail(retryableSseFailure("workspace control live subscription ended", error)),
+      },
+    );
     if (channel.stopped()) {
       release();
       return;
@@ -588,13 +695,7 @@ export async function sseWorkspaceControlStream(
     detachAbortListener = () => signal.removeEventListener("abort", abort);
   }
 
-  return new Response(channel.stream, {
-    headers: {
-      "Content-Type": "text/event-stream; charset=utf-8",
-      "Cache-Control": "no-cache, no-transform",
-      Connection: "keep-alive",
-    },
-  });
+  return await sseHttpResponse(channel.stream, options);
 }
 
 export type WorkspaceInteractionSseOptions = SseDeliveryOptions & {
@@ -618,12 +719,42 @@ export async function sseWorkspaceLiveStream(
   signal: AbortSignal,
   options: WorkspaceInteractionSseOptions = {},
 ): Promise<Response> {
+  if (isHttp1BrowserBatch(options)) {
+    const [controlEvents, interactionState] = await Promise.all([
+      listWorkspaceControlEvents(db, workspaceId, controlAfter, WORKSPACE_CONTROL_REPLAY_PAGE_SIZE),
+      getWorkspaceInteractionRevisionState(db, { accountId, workspaceId }),
+    ]);
+    await options.reauthorize?.();
+    const frames: string[] = [];
+    if (interactionState.revision > interactionAfter) {
+      frames.push(
+        formatWorkspaceInteractionRevisionSse(
+          WorkspaceInteractionRevisionEvent.parse({
+            workspaceId,
+            sequence: interactionState.revision,
+            revision: interactionState.revision,
+            type: "workspace.interaction.changed",
+            occurredAt: (interactionState.updatedAt ?? new Date()).toISOString(),
+          }),
+        ),
+      );
+    }
+    frames.push(
+      ...controlEvents
+        .sort((left, right) => left.sequence - right.sequence)
+        .map(formatWorkspaceControlEventSse),
+    );
+    return finiteSseBatchResponse(frames, options);
+  }
   const upstream = new AbortController();
+  let stopReauthorization = () => {};
   const channel = createByteBoundedSseStream({
+    connectionLifetimeMs: options.connectionLifetimeMs,
     maxQueuedBytes: options.maxQueuedBytes ?? SESSION_EVENT_SSE_FRAME_MAX_BYTES,
     ...(options.stallTimeoutMs === undefined ? {} : { stallTimeoutMs: options.stallTimeoutMs }),
     onObservation: sseObservationReporter("workspace_interaction", options),
     onStop: () => {
+      stopReauthorization();
       signal.removeEventListener("abort", abort);
       upstream.abort();
     },
@@ -634,10 +765,23 @@ export async function sseWorkspaceLiveStream(
   };
   if (signal.aborted) abort();
   else signal.addEventListener("abort", abort, { once: true });
+  stopReauthorization = startSseReauthorization(options, channel.stopped, channel.close);
+
+  const upstreamOptions: WorkspaceInteractionSseOptions = {
+    ...options,
+    connectionLifetimeMs: undefined,
+    finiteResponseMaxBytes: undefined,
+    finiteResponseMediaType: undefined,
+    reauthorize: undefined,
+    reauthorizeAfterMs: undefined,
+  };
 
   let writeTail = Promise.resolve(true);
   const write = (frame: string): Promise<boolean> => {
-    const pending = writeTail.then(() => channel.write(frame));
+    const pending = writeTail.then(async () => {
+      await reauthorizeSseOrClose(options, channel);
+      return await channel.write(frame);
+    });
     writeTail = pending.catch(() => false);
     return pending;
   };
@@ -665,14 +809,21 @@ export async function sseWorkspaceLiveStream(
   void (async () => {
     try {
       const [control, interaction] = await Promise.all([
-        sseWorkspaceControlStream(db, bus, workspaceId, controlAfter, upstream.signal, options),
+        sseWorkspaceControlStream(
+          db,
+          bus,
+          workspaceId,
+          controlAfter,
+          upstream.signal,
+          upstreamOptions,
+        ),
         sseWorkspaceInteractionRevisionStream(
           db,
           accountId,
           workspaceId,
           interactionAfter,
           upstream.signal,
-          options,
+          upstreamOptions,
         ),
       ]);
       const pumps = [pump(control), pump(interaction)];
@@ -694,13 +845,7 @@ export async function sseWorkspaceLiveStream(
     }
   })();
 
-  return new Response(channel.stream, {
-    headers: {
-      "Content-Type": "text/event-stream; charset=utf-8",
-      "Cache-Control": "no-cache, no-transform",
-      Connection: "keep-alive",
-    },
-  });
+  return await sseHttpResponse(channel.stream, options);
 }
 
 /**
@@ -716,26 +861,53 @@ export async function sseWorkspaceInteractionRevisionStream(
   signal: AbortSignal,
   options: WorkspaceInteractionSseOptions = {},
 ): Promise<Response> {
+  if (isHttp1BrowserBatch(options)) {
+    const state = await getWorkspaceInteractionRevisionState(db, {
+      accountId,
+      workspaceId,
+    });
+    await options.reauthorize?.();
+    const frames =
+      state.revision > after
+        ? [
+            formatWorkspaceInteractionRevisionSse(
+              WorkspaceInteractionRevisionEvent.parse({
+                workspaceId,
+                sequence: state.revision,
+                revision: state.revision,
+                type: "workspace.interaction.changed",
+                occurredAt: (state.updatedAt ?? new Date()).toISOString(),
+              }),
+            ),
+          ]
+        : [];
+    return finiteSseBatchResponse(frames, options);
+  }
   const heartbeatIntervalMs = resolveHeartbeatInterval(options.heartbeatIntervalMs);
   const pollIntervalMs = resolveInteractionPollInterval(options.pollIntervalMs);
   let lastSent = after;
   let lastWriteAt = Date.now();
   let stopRequested = false;
+  let stopReauthorization = () => {};
   let detachAbortListener = () => {};
   let closeMetrics = () => {};
   const channel = createByteBoundedSseStream({
+    connectionLifetimeMs: options.connectionLifetimeMs,
     maxQueuedBytes: options.maxQueuedBytes ?? SESSION_EVENT_SSE_FRAME_MAX_BYTES,
     ...(options.stallTimeoutMs === undefined ? {} : { stallTimeoutMs: options.stallTimeoutMs }),
     onObservation: sseObservationReporter("workspace_interaction", options),
     onStop: () => {
       stopRequested = true;
+      stopReauthorization();
       closeMetrics();
       detachAbortListener();
     },
   });
   closeMetrics = observeSseConnection("workspace_interaction", after, options.observability);
+  stopReauthorization = startSseReauthorization(options, channel.stopped, channel.close);
 
   const write = async (frame: string): Promise<boolean> => {
+    await reauthorizeSseOrClose(options, channel);
     const accepted = await channel.write(frame);
     if (accepted) lastWriteAt = Date.now();
     return accepted;
@@ -746,7 +918,10 @@ export async function sseWorkspaceInteractionRevisionStream(
       if (!(await write(": connected\n\n"))) return;
       for (;;) {
         if (stopRequested || signal.aborted || channel.stopped()) return;
-        const state = await getWorkspaceInteractionRevisionState(db, { accountId, workspaceId });
+        const state = await getWorkspaceInteractionRevisionState(db, {
+          accountId,
+          workspaceId,
+        });
         if (state.revision > lastSent) {
           const event = WorkspaceInteractionRevisionEvent.parse({
             workspaceId,
@@ -776,13 +951,7 @@ export async function sseWorkspaceInteractionRevisionStream(
     detachAbortListener = () => signal.removeEventListener("abort", abort);
   }
 
-  return new Response(channel.stream, {
-    headers: {
-      "Content-Type": "text/event-stream; charset=utf-8",
-      "Cache-Control": "no-cache, no-transform",
-      Connection: "keep-alive",
-    },
-  });
+  return await sseHttpResponse(channel.stream, options);
 }
 
 function observeSseConnection(
@@ -843,20 +1012,179 @@ async function replayWorkspaceControlEvents(
 
 class SseStreamStoppedError extends Error {}
 
+async function reauthorizeSseOrClose(
+  options: SseDeliveryOptions,
+  channel: ByteBoundedSseStream,
+): Promise<void> {
+  try {
+    await options.reauthorize?.();
+  } catch {
+    // Authorization loss is an expected fail-closed terminal condition, not a
+    // delivery fault. End the HTTP response cleanly so Bun and Chromium retire
+    // the HTTP/1 socket even if the initiating document is being replaced.
+    // No frame crosses the failed check; a still-live SDK may reconnect and is
+    // fenced again at request admission, while a destroyed realm cannot leave
+    // an errored response occupying the per-origin connection pool.
+    channel.close();
+    throw new SseStreamStoppedError();
+  }
+}
+
 export type SseDeliveryOptions = {
+  connectionLifetimeMs?: number | undefined;
+  /** Return a known-length batch instead of a chunked response. HTTP/1 only. */
+  finiteResponseMaxBytes?: number | undefined;
+  /** Browser transport classification for a finite response. */
+  finiteResponseMediaType?: "event-stream" | "http1-browser-batch" | undefined;
   maxQueuedBytes?: number;
   stallTimeoutMs?: number;
   heartbeatIntervalMs?: number;
   observability?: Observability | undefined;
   onObservation?: ((observation: SseDeliveryBoundObservation) => void) | undefined;
-};
-
-export type SessionSseDeliveryOptions = SseDeliveryOptions & {
-  /** Host ACL re-check, run even while the event stream is otherwise idle. */
+  /** Current ACL re-check, run even while the event stream is idle. */
   reauthorize?: (() => Promise<void>) | undefined;
   reauthorizeAfterMs?: number | undefined;
+  /** Exact selected actor emitted on the stream response for cross-tab fencing. */
+  actorEpoch?: string | undefined;
 };
 
+export function browserSseDeliveryOptions(
+  transport: string | undefined,
+): Pick<
+  SseDeliveryOptions,
+  "connectionLifetimeMs" | "finiteResponseMaxBytes" | "finiteResponseMediaType"
+> {
+  return transport === "http1-bounded"
+    ? {
+        finiteResponseMaxBytes: HTTP1_BROWSER_SSE_BATCH_MAX_BYTES,
+        finiteResponseMediaType: "http1-browser-batch",
+      }
+    : {};
+}
+
+async function sseHttpResponse(
+  stream: ReadableStream<Uint8Array>,
+  options: SseDeliveryOptions,
+): Promise<Response> {
+  const maxBytes = options.finiteResponseMaxBytes;
+  let body: ReadableStream<Uint8Array> | ArrayBuffer = stream;
+  let contentLength: number | null = null;
+  if (maxBytes !== undefined) {
+    if (
+      !Number.isSafeInteger(maxBytes) ||
+      maxBytes < SESSION_EVENT_SSE_FRAME_MAX_BYTES ||
+      maxBytes > HTTP1_BROWSER_SSE_BATCH_MAX_BYTES
+    ) {
+      throw new RangeError(
+        `finite SSE batch limit must be between ${SESSION_EVENT_SSE_FRAME_MAX_BYTES} and ${HTTP1_BROWSER_SSE_BATCH_MAX_BYTES} bytes`,
+      );
+    }
+    body = await collectFiniteSseBatch(stream, maxBytes);
+    contentLength = body.byteLength;
+  }
+  return new Response(body, {
+    headers: {
+      // A bounded HTTP/1 poll carries the same SSE-framed bytes the SDK
+      // already parses, but it is an ordinary finite response at the browser
+      // transport boundary. Keeping `text/event-stream` here lets Chromium
+      // retain an orphaned fetch in its shared per-origin SSE pool after the
+      // initiating document is replaced, starving unrelated finite reads in
+      // every tab. HTTP/2 and other unbounded streams keep the standard media
+      // type; only the explicit `http1-bounded` fallback uses this vendor type.
+      "Content-Type":
+        contentLength !== null && options.finiteResponseMediaType === "http1-browser-batch"
+          ? `${HTTP1_BROWSER_SSE_BATCH_CONTENT_TYPE}; charset=utf-8`
+          : "text/event-stream; charset=utf-8",
+      "Cache-Control": "no-cache, no-transform",
+      // A known-length response is already terminal and leaves the HTTP/1
+      // socket reusable. Only a genuinely live SSE response needs an explicit
+      // close when its stream ends.
+      ...(contentLength === null
+        ? { Connection: "close" }
+        : { "Content-Length": String(contentLength) }),
+      ...(options.actorEpoch ? { [MANAGED_AUTH_ACTOR_EPOCH_HEADER]: options.actorEpoch } : {}),
+    },
+  });
+}
+
+function isHttp1BrowserBatch(options: SseDeliveryOptions): boolean {
+  return (
+    options.finiteResponseMediaType === "http1-browser-batch" &&
+    options.finiteResponseMaxBytes !== undefined
+  );
+}
+
+function finiteSseBatchResponse(frames: readonly string[], options: SseDeliveryOptions): Response {
+  const maxBytes = options.finiteResponseMaxBytes;
+  if (
+    maxBytes === undefined ||
+    !Number.isSafeInteger(maxBytes) ||
+    maxBytes < SESSION_EVENT_SSE_FRAME_MAX_BYTES ||
+    maxBytes > HTTP1_BROWSER_SSE_BATCH_MAX_BYTES
+  ) {
+    throw new RangeError(
+      `finite SSE batch limit must be between ${SESSION_EVENT_SSE_FRAME_MAX_BYTES} and ${HTTP1_BROWSER_SSE_BATCH_MAX_BYTES} bytes`,
+    );
+  }
+  const encoder = new TextEncoder();
+  const chunks: Uint8Array[] = [];
+  let length = 0;
+  for (const frame of frames) {
+    const chunk = encoder.encode(frame);
+    if (chunks.length > 0 && length + chunk.byteLength > maxBytes) break;
+    chunks.push(chunk);
+    length += chunk.byteLength;
+  }
+  const body = new Uint8Array(length);
+  let offset = 0;
+  for (const chunk of chunks) {
+    body.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return new Response(body, {
+    headers: {
+      "Content-Type": `${HTTP1_BROWSER_SSE_BATCH_CONTENT_TYPE}; charset=utf-8`,
+      "Cache-Control": "no-cache, no-transform",
+      "Content-Length": String(body.byteLength),
+      ...(options.actorEpoch ? { [MANAGED_AUTH_ACTOR_EPOCH_HEADER]: options.actorEpoch } : {}),
+    },
+  });
+}
+
+async function collectFiniteSseBatch(
+  stream: ReadableStream<Uint8Array>,
+  maxBytes: number,
+): Promise<ArrayBuffer> {
+  const reader = stream.getReader();
+  const chunks: Uint8Array[] = [];
+  let length = 0;
+  try {
+    for (;;) {
+      const next = await reader.read();
+      if (next.done) break;
+      // Each source chunk is one complete SSE frame. End before an overflowing
+      // frame so reconnect replay starts from the consumer's last whole cursor.
+      if (chunks.length > 0 && length + next.value.byteLength > maxBytes) {
+        await reader.cancel("finite SSE batch reached its byte limit");
+        break;
+      }
+      chunks.push(next.value);
+      length += next.value.byteLength;
+    }
+  } finally {
+    reader.releaseLock();
+  }
+  const bytes = new Uint8Array(length);
+  let offset = 0;
+  for (const chunk of chunks) {
+    bytes.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return bytes.buffer;
+}
+
+export type SessionSseDeliveryOptions = SseDeliveryOptions;
+
 function sseObservationReporter(
   stream: SseStreamKind,
   options: SseDeliveryOptions,
@@ -900,6 +1228,32 @@ function resolveInteractionPollInterval(value: number | undefined): number {
   return interval;
 }
 
+function startSseReauthorization(
+  options: SseDeliveryOptions,
+  stopped: () => boolean,
+  fail: (error: unknown) => void,
+): () => void {
+  if (!options.reauthorize) return () => {};
+  const interval = options.reauthorizeAfterMs ?? 15_000;
+  if (!Number.isSafeInteger(interval) || interval < 1_000 || interval > 60_000) {
+    throw new RangeError("SSE reauthorization must be between 1000 and 60000ms");
+  }
+  let timer: ReturnType<typeof setTimeout> | null = null;
+  const schedule = () => {
+    if (stopped()) return;
+    timer = setTimeout(() => {
+      timer = null;
+      void options.reauthorize!().then(schedule).catch(fail);
+    }, interval);
+  };
+  schedule();
+  return () => {
+    if (!timer) return;
+    clearTimeout(timer);
+    timer = null;
+  };
+}
+
 function formatWorkspaceInteractionRevisionSse(event: WorkspaceInteractionRevisionEvent): string {
   return `id: ${event.sequence}\nevent: ${event.type}\ndata: ${JSON.stringify(event)}\n\n`;
 }