docs(sdk): note AgentChat.reconnect resumes a stream, not a fresh turn

Author: ericallam

packages/trigger-sdk/src/v3/chat-client.ts

@@ -577,10 +577,18 @@ export class AgentChat<TAgent = unknown> {
   }
 
   /**
-   * Reconnect to the response stream (e.g. after a disconnect). Requests the
-   * caught-up settle probe (`X-Peek-Settled`) so a resumed stream already at a
-   * turn-complete tail closes promptly instead of holding the full SSE window,
-   * mirroring the browser transport's `reconnectToStream`.
+   * Reconnect to the response stream to resume an already-established session
+   * after a disconnect. Requests the caught-up settle probe (`X-Peek-Settled`)
+   * so a resumed stream already at a turn-complete tail closes promptly instead
+   * of holding the full SSE window, mirroring the browser transport's
+   * `reconnectToStream`.
+   *
+   * Do not call this immediately after `sendMessage()` to read a fresh turn: the
+   * settle probe can race the newly-triggered turn's first record, see the prior
+   * turn's `turn-complete` tail, and hand back an empty stream (unlike the
+   * browser transport, there is no auto-resubscribe). `sendMessage()` already
+   * returns the turn's stream; use `reconnect()` only to resume an idle or
+   * mid-turn stream.
    */
   async reconnect(abortSignal?: AbortSignal): Promise<ReadableStream<UIMessageChunk> | null> {
     if (!this.state.started) return null;