x-peek-settled header

Author: ericallam

.server-changes/session-out-settled-signal.md

@@ -3,6 +3,8 @@ area: webapp
 type: improvement
 ---
 
-`/realtime/v1/sessions/:session/out` now peeks the tail record in S2 at connection time. If the last chunk is `trigger:turn-complete` (agent finished a turn and is either idle-waiting on `.in` or has exited), the downstream S2 read uses `wait=0` so the SSE drains and closes immediately instead of holding the connection open for 60s. The response also carries `X-Session-Settled: true` so the client can tell the close is terminal rather than a normal long-poll cycle.
+`/realtime/v1/sessions/:session/out` accepts an opt-in `X-Peek-Settled: 1` request header. When set, the route peeks the tail record in S2 before proxying; if the last chunk is `trigger:turn-complete`, it switches the downstream read to `wait=0` and returns `X-Session-Settled: true` so the SSE drains-and-closes in ~1s instead of long-polling for 60s.
 
-Lets `TriggerChatTransport.reconnectToStream` return quickly on page reloads of settled chats without requiring callers to persist an `isStreaming` flag — the server decides from the stream's own tail. Mid-turn tails still take the 60s long-poll path unchanged.
+Without the header, the route behaves exactly as before the settled work — unconditional `wait=60`. This matters because the peek races a newly-triggered turn's first chunk: the active `sendMessages → subscribeToSessionStream` path would otherwise see the previous turn's `trigger:turn-complete` at the tail and close the SSE before the new turn's chunks land on S2. The smoke test confirmed this race was failing every turn-2 response.
+
+`TriggerChatTransport.reconnectToStream` opts in via the header (that's the reload-on-a-settled-chat case where the fast close is a real UX win). Active send paths don't set the header and keep long-poll semantics.

apps/webapp/app/routes/realtime.v1.sessions.$session.$io.ts

@@ -124,12 +124,20 @@ const loader = createLoaderApiRoute(
       timeoutInSeconds = parsed;
     }
 
+    // Opt-in: only consider the settled-peek shortcut when the client
+    // asks for it via `X-Peek-Settled: 1`. Reconnect-on-reload paths
+    // (`TriggerChatTransport.reconnectToStream`) set this; the active
+    // send-a-message path (`sendMessages → subscribeToSessionStream`)
+    // does not — otherwise the peek races with the newly-triggered
+    // turn's first chunk and the SSE closes before records land.
+    const peekSettled = request.headers.get("X-Peek-Settled") === "1";
+
     return realtimeStream.streamResponseFromSessionStream(
       request,
       session.friendlyId,
       params.io,
       getRequestAbortSignal(),
-      { lastEventId, timeoutInSeconds }
+      { lastEventId, timeoutInSeconds, peekSettled }
     );
   }
 );

apps/webapp/app/services/realtime/s2realtimeStreams.server.ts

@@ -318,8 +318,17 @@ export class S2RealtimeStreams implements StreamResponder, StreamIngestor {
     let waitSeconds = options?.timeoutInSeconds ?? this.s2WaitSeconds;
     let settled = false;
 
-    if (io === "out") {
+    // Only peek + settle when the client opts in via `options.peekSettled`.
+    // Reconnect-on-reload paths (`TriggerChatTransport.reconnectToStream`)
+    // set it; active send-a-message paths don't — otherwise the peek
+    // races the newly-triggered turn's first chunk and the SSE closes
+    // before records land.
+    if (io === "out" && options?.peekSettled) {
       const lastChunk = await this.#peekLastChunkBody(s2Stream);
+      const lastChunkType =
+        lastChunk != null && typeof lastChunk === "object"
+          ? (lastChunk as { type?: unknown }).type
+          : null;
       if (
         lastChunk != null &&
         typeof lastChunk === "object" &&

apps/webapp/app/services/realtime/types.ts

@@ -33,6 +33,17 @@ export interface StreamIngestor {
 export type StreamResponseOptions = {
   timeoutInSeconds?: number;
   lastEventId?: string;
+  /**
+   * Session-stream-only. When `true`, the responder MAY peek the tail
+   * of `.out` and short-circuit to `wait=0` + `X-Session-Settled: true`
+   * if the last chunk is a terminal marker (e.g. `trigger:turn-complete`).
+   * Used by `TriggerChatTransport.reconnectToStream` on page reload.
+   *
+   * When absent/false, the responder keeps the unconditional long-poll
+   * behavior — required on the active send-a-message path where the
+   * peek would race the newly-triggered turn's first chunk.
+   */
+  peekSettled?: boolean;
 };
 
 // Interface for stream response