fix(chat,sdk): drop dead claim-kind docs and quiet the drain on known kinds

Removes a JSDoc block and a `{@link}` reference to a claim-kinds helper that
is not part of this change, which also left `chat.createStopSignal` carrying
two doc comments.

The drain also warned on every record it discarded, including a stop that the
stop facade had already handled: all handlers are invoked for a record
regardless of whether an earlier one consumed it, so a stop with an active
stop signal is both aborted and drained. A known kind with no active consumer
is an expected state, so the warning is now limited to kinds this SDK version
does not recognise, which is the case that indicates a newer server.

Also corrects the docs and changeset, which claimed `next()` returning
`undefined` always means the mailbox is idle. A control record that does have
its own consumer can sit at the head while `next()` times out.

Author: ericallam

.changeset/tidy-mailboxes-wait.md

@@ -5,4 +5,4 @@
 
 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.
 
-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` now always means the mailbox is idle.
+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.

docs/ai-chat/custom-agents.mdx

@@ -269,8 +269,11 @@ becomes pending.
 
 A control record that nothing on the run consumes is discarded rather than left
 at the head of the channel. `hasPending()` and `next()` only look at the head, so
-a record parked there would make every message behind it undeliverable. This
-means `next()` returning `undefined` always means the mailbox is idle.
+a record parked there would make every message behind it undeliverable.
+
+`next()` still returns `undefined` whenever no message became consumable before
+the timeout, including while a control record that does have its own consumer
+sits at the head.
 
 A complete loop:
 

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

@@ -1920,6 +1920,19 @@ const chatClaimedKindsKey = locals.create<Set<string>>("chat.claimedKinds");
 /** Kinds carried on `.in` that are not user messages. @internal */
 const CHAT_HANDOVER_KINDS = ["handover", "handover-skip"] as const;
 
+/**
+ * Every `ChatInputChunk` kind this SDK version knows about. A known kind with
+ * no active consumer on this boot is an expected, documented state; an unknown
+ * one means a newer server is sending something this worker cannot handle,
+ * which is worth surfacing.
+ * @internal
+ */
+const KNOWN_CHAT_INPUT_KINDS: ReadonlySet<string> = new Set([
+  "message",
+  "stop",
+  ...CHAT_HANDOVER_KINDS,
+]);
+
 /** The run's attached drain subscription, so it can be re-offered the buffer. @internal */
 const chatInputDrainKey = locals.create<{ off: () => void }>("chat.inputDrain");
 
@@ -1957,9 +1970,9 @@ function attachUnclaimedChatInputDrain(): { off: () => void } {
       return true;
     }
     if (chatClaimedKinds().has(kind)) return undefined;
-    logger.warn("chat: discarded a session.in record that no consumer handled on this boot", {
-      kind,
-    });
+    if (!KNOWN_CHAT_INPUT_KINDS.has(kind)) {
+      logger.warn("chat: discarded a session.in record of an unrecognised kind", { kind });
+    }
     return true;
   });
 }
@@ -1987,16 +2000,6 @@ function releaseChatInputKinds(kinds: readonly string[]): void {
   locals.set(chatInputDrainKey, attachUnclaimedChatInputDrain());
 }
 
-/**
- * Declare that this run will consume the given `session.in` record kinds
- * itself (via raw `session.in` reads). Claimed kinds are never discarded by
- * the unclaimed-control drain: they stay buffered, block
- * `chat.messages.next()` at the head of the channel, and hold the resume
- * cursor behind them until consumed. Call `release()` when the loop stops
- * consuming them — any still-buffered records of those kinds are then
- * discarded and the cursor advances.
- */
-
 /**
  * Per-turn deferred promises. Registered via `chat.defer()`, awaited
  * before `onTurnComplete` fires. Reset each turn.
@@ -10861,7 +10864,6 @@ export const chat = {
   response: chatResponse,
   /** Pre-built input stream for receiving messages from the transport. */
   messages: messagesInput,
-  /** Declare `session.in` record kinds this run consumes itself. See {@link chatClaimInputKinds}. */
   /** Create a managed stop signal wired to the stop input stream. See {@link createStopSignal}. */
   createStopSignal,
   /** Signal the frontend that the current turn is complete. See {@link chatWriteTurnComplete}. */