docs(ai-chat): session-in-event-id header on turn-complete control records

Document the new sibling header that rides on every turn-complete
record carrying the agent's committed-consume cursor on .in. The
header is what lets the next worker boot seed its .in SSE subscribe
past already-processed user messages without a wall-clock-derived
dedup cutoff.

- client-protocol: new row in the turn-complete header table; updated
  records-on-session-out summary; example block shows the third
  header
- changelog: short paragraph under "what changed on the wire" framing
  the cursor as the seq-based replacement for the prior timestamp
  cutoff, with an explicit "custom transports should ignore" note

Author: ericallam

docs/ai-chat/changelog.mdx

@@ -31,6 +31,8 @@ body: ""
 
 The control event names ("turn-complete", "upgrade-required") are unchanged conceptually — they just moved from `chunk.type` into a `trigger-control` header value. Body is always empty; metadata that previously rode in the chunk (e.g. `publicAccessToken`) now rides on sibling headers.
 
+`turn-complete` also picks up a new optional sibling header — `["session-in-event-id", "<seq>"]` — carrying the agent's committed-consume cursor on `.in` as of this turn. It's an agent-internal contract that lets the next worker boot seed its `.in` SSE subscription past already-processed user messages, without relying on a wall-clock-derived dedup cutoff. Custom transports should ignore the header; it has no client-side meaning.
+
 ### Custom transport implementers
 
 Built-in SDK transports (`TriggerChatTransport`, `AgentChat`) handle this transparently — `onTurnComplete` fires the same way with the same payload. Custom transports filtering on `chunk.type === "trigger:turn-complete"` need to switch to the header-based filter:

docs/ai-chat/client-protocol.mdx

@@ -369,7 +369,7 @@ Three kinds of records can arrive on the wire. They all share the `batch` envelo
 | Kind | `headers[0][0]` | `headers` carries | `body` |
 | --- | --- | --- | --- |
 | **Data record** | _empty array or non-empty name_ | (currently none from the agent) | JSON envelope `{"data": UIMessageChunk, "id": <partId>}` |
-| **Trigger control record** | `"trigger-control"` | `["trigger-control", <subtype>]` plus subtype-specific siblings (e.g. `["public-access-token", <jwt>]` on `turn-complete`) | empty string |
+| **Trigger control record** | `"trigger-control"` | `["trigger-control", <subtype>]` plus subtype-specific siblings (e.g. `["public-access-token", <jwt>]` and `["session-in-event-id", <seq>]` on `turn-complete`) | empty string |
 | **S2 command record** | `""` (empty name) | `["", "<op>"]` (currently `"trim"`) | opaque bytes — S2-interpreted |
 
 **Uniform filter rule for custom readers:**
@@ -583,13 +583,15 @@ Signals that the agent's turn is finished — stop reading and wait for user inp
 headers:
   ["trigger-control", "turn-complete"]
   ["public-access-token", "eyJ..."]   // optional, refreshed JWT
+  ["session-in-event-id", "42"]       // optional, agent-internal resume cursor
 body: ""
 ```
 
 | Header | Description |
 | --- | --- |
 | `trigger-control: turn-complete` | Always present on this record. |
 | `public-access-token: <jwt>` (optional) | A refreshed JWT with the same session + run scopes. If present, replace your stored token. |
+| `session-in-event-id: <seq>` (optional) | Internal cursor used by the agent to resume `.in` across worker boots without replaying already-processed user messages. Custom transports should ignore this header — it carries no client-side meaning. |
 
 When you receive this record:
 1. Update `publicAccessToken` if one is included on the headers.