The webapp's peek-tail-settled shortcut on /realtime/v1/sessions/:id/out
previously fired on every io=out subscription. That race-tripped active
send-a-message paths: the SSE peek would see the prior turn's
trigger:turn-complete record before the newly-triggered run wrote its
first chunk, return wait=0 + X-Session-Settled:true, and close the
stream before any of the new turn's records landed.
Make the peek opt-in via an X-Peek-Settled: 1 request header. Only
TriggerChatTransport.reconnectToStream sets it (true reload-resume case
where settling early is fine); sendMessages and the rest leave it off
and stay on the normal long-poll. On the server side,
streamResponseFromSessionStream gates the peek on options.peekSettled
and skips it otherwise.
- apps/webapp: read X-Peek-Settled from the request, thread to
streamResponseFromSessionStream
- packages/trigger-sdk/chat.ts: peekSettled option on
subscribeToSessionStream + reconnectToStream sets it; sendMessages
does not
- docs/ai-chat/client-protocol.mdx + docs/sessions/reference.mdx:
document the opt-in semantics
- .server-changes/session-out-settled-signal.md: record the change
Eric Allam
5164aab0a1