docs(chat): describe the resume cursor accurately in the changeset and API docs

The changeset only mentioned the new mailbox helpers, and led with them. The
change a user is most likely to care about is that a chat could silently lose a
message, which affected the managed agent too, so the release note now leads
with that and with the retried-send duplicate.

`chat.writeTurnComplete()` also promised that `sessionInEventId` identified the
exact input record the turn acknowledged. It does not: it is the cursor that is
safe to resume from, held back behind any message still waiting to be handled,
so a value below the record just handled is expected rather than a fault.

Author: ericallam

.changeset/tidy-mailboxes-wait.md

@@ -3,6 +3,19 @@
 "@trigger.dev/sdk": patch
 ---
 
-Custom agent loops can now inspect pending chat input without consuming it and consume one mailbox record at a time with `chat.messages.hasPending()` and `chat.messages.next()`. Mailbox records include stable identifiers for tracing and redelivery.
+Fixes a case where a chat could silently lose a message. If a message arrived while the agent was between turns and a stop arrived after it, the cursor the next boot resumed from could point past that message, so it was never answered and no error was raised. This affected `chat.agent`, not just custom agents.
 
-A control record that nothing on the run consumes is now discarded rather than left at the head of the `.in` channel, where it would have made every message queued behind it undeliverable. `chat.messages.next()` returning `undefined` means no message became consumable before the timeout.
+Also fixes a retried send being answered twice. When a send was retried and its idempotency claim was lost, the agent could consume the same message a second time.
+
+Custom agent loops can now inspect pending chat input without consuming it, and consume one mailbox record at a time, with `chat.messages.hasPending()` and `chat.messages.next()`. Records carry stable identifiers so a redelivery is recognisable.
+
+```ts
+if (await chat.messages.hasPending()) {
+  const record = await chat.messages.next({ timeoutInSeconds: 0 });
+  if (record) handle(record.payload);
+}
+```
+
+A control record that nothing on the run consumes is now discarded rather than left at the head of the input channel, where it would have made every message queued behind it undeliverable. `chat.messages.next()` returning `undefined` means no message became consumable before the timeout.
+
+`chat.writeTurnComplete()`'s `sessionInEventId` is the cursor that is safe to resume from, not the sequence of the record the turn answered. It is held back behind any message still waiting to be handled, so a value below the record you just handled is expected.

packages/trigger-sdk/src/v3/ai.ts

@@ -9131,10 +9131,14 @@ function createStopSignal(): {
  * task instead of round-tripping them back from the client:
  * - `lastEventId` — the turn-complete control record's seq_num on
  *   `session.out`; where the next turn's output stream resumes.
- * - `sessionInEventId` — the committed-consume cursor on `session.in` as of
- *   this turn-complete, letting a raw loop correlate the boundary with the
- *   exact input record it acknowledged. Trigger owns input-cursor recovery,
- *   so this is for correlation / out-of-sync detection, not required.
+ * - `sessionInEventId` — the safe-to-resume-from cursor on `session.in` as of
+ *   this turn-complete. It is the highest sequence that can be resumed past
+ *   without skipping an unhandled message, so it is held back behind any
+ *   message still buffered unconsumed and is NOT necessarily the sequence of
+ *   the record this turn answered. Trigger owns input-cursor recovery, so this
+ *   is for correlation / out-of-sync detection, not required. Treat it as a
+ *   lower bound: a value below the record you just handled is expected, not a
+ *   sign of a lost turn.
  *
  * Either is `undefined` when the corresponding cursor isn't available.
  *