fix(chat): correct the wiring caveat, deferral does not need the spread

The previous commit said a `pendingMessages` config without
`chat.toStreamTextOptions()` still loses mid-turn messages. That was true
before this branch and is not true on it: the arrival path only observes now,
so the record stays queued on the channel whatever happens to the steering
queue, and the next turn takes it.

Injection is the part that needs the spread. Without it nothing injects, so
every mid-turn message is answered as the next turn, which is the documented
default rather than a loss.

Covers the shape a developer reaches by following the docs for `onReceived`
alone, with no `shouldInject` and no spread, so nothing can drain the queue.

Author: ericallam

.changeset/spry-steers-defer.md

@@ -18,7 +18,8 @@ chat.agent({
       model,
       messages,
       abortSignal: signal,
-      // Required for pendingMessages to be wired up at all.
+      // Required for injection. Without it nothing injects, and every
+      // mid-turn message is answered as the next turn instead.
       ...chat.toStreamTextOptions(),
     }),
 });

docs/ai-chat/pending-messages.mdx

@@ -12,7 +12,7 @@ By default (without `pendingMessages`), a message sent while the agent is respon
 
 The `pendingMessages` option enables steering instead, injecting user messages between tool-call steps via the AI SDK's `prepareStep`. Messages that arrive during streaming are queued and injected at the next step boundary. A message that is not injected becomes the next turn instead, whether that is because `shouldInject` returned `false` or because there were no more step boundaries (single-step response or final text generation). The backend handles that, so no client-side re-send is involved.
 
-This requires the `pendingMessages` options to actually reach `streamText`, by spreading `chat.toStreamTextOptions()` (or passing `prepareStep`). Configuring `pendingMessages` without that wiring leaves nothing to drain the queue, and mid-turn messages are lost.
+Injection is what needs wiring: the `pendingMessages` options only reach `streamText` if you spread `chat.toStreamTextOptions()` (or pass `prepareStep`). Without that, nothing injects, so every mid-turn message is answered as the next turn. Deferral does not depend on it.
 
 ## How it works
 

docs/ai-chat/reference.mdx

@@ -396,7 +396,7 @@ Options for the `pendingMessages` field. See [Pending Messages](/ai-chat/pending
 
 | Option         | Type                                                                              | Required | Description                                                                               |
 | -------------- | --------------------------------------------------------------------------------- | -------- | ----------------------------------------------------------------------------------------- |
-| `shouldInject` | `(event: PendingMessagesBatchEvent) => boolean \| Promise<boolean>`               | No       | Decide whether to inject the batch between tool-call steps. If absent, nothing is injected and the messages are answered as the next turn. Requires `chat.toStreamTextOptions()` (or `prepareStep`) to be passed to `streamText`. |
+| `shouldInject` | `(event: PendingMessagesBatchEvent) => boolean \| Promise<boolean>`               | No       | Decide whether to inject the batch between tool-call steps. If absent, nothing is injected and the messages are answered as the next turn. Only consulted when `chat.toStreamTextOptions()` (or `prepareStep`) reaches `streamText`; without that nothing is injected and every mid-turn message becomes the next turn. |
 | `prepare`      | `(event: PendingMessagesBatchEvent) => ModelMessage[] \| Promise<ModelMessage[]>` | No       | Transform the batch before injection. Default: convert each via `convertToModelMessages`. |
 | `onReceived`   | `(event: PendingMessageReceivedEvent) => void \| Promise<void>`                   | No       | Called when a message arrives during streaming (per-message).                             |
 | `onInjected`   | `(event: PendingMessagesInjectedEvent) => void \| Promise<void>`                  | No       | Called after a batch is injected via prepareStep.                                         |

packages/trigger-sdk/test/pending-message-drain.test.ts

@@ -224,6 +224,46 @@ describe("chat.agent declined steering message", () => {
   });
 });
 
+/**
+ * The shape a developer reaches by following the docs for `onReceived` alone:
+ * a `pendingMessages` config, no `shouldInject`, and no
+ * `chat.toStreamTextOptions()` spread, so nothing can ever drain the steering
+ * queue. The message must still be answered. It used to be taken off the
+ * channel by the arrival handler and then stranded in a queue with no consumer.
+ */
+describe("chat.agent pendingMessages with nothing wired to drain it", () => {
+  it("still answers a mid-turn message as its own turn", async () => {
+    const received: string[] = [];
+
+    const agent = chat.agent({
+      id: "pending-drain.unwired",
+      pendingMessages: {
+        onReceived: ({ message }) => {
+          received.push(message.id);
+        },
+      },
+      run: async ({ messages, signal }) => {
+        return streamText({ model: echoModel(), messages, abortSignal: signal });
+      },
+    });
+
+    const harness = mockChatAgent(agent, { chatId: "pending-drain-unwired" });
+    try {
+      const first = harness.sendMessage(userMessage("m1", "u-1"));
+      await waitFor(() => streamedText(harness).includes("ANSWER(m1)"));
+      void harness.sendMessage(userMessage("m2", "u-2"));
+      await first;
+
+      await waitFor(() => turnCompleteCount(harness) >= 2);
+
+      expect(received).toContain("u-2");
+      expect(streamedText(harness)).toContain("ANSWER(m2)");
+    } finally {
+      await harness.close();
+    }
+  });
+});
+
 describe("chat.agent errored turn", () => {
   it(
     "does not duplicate messages buffered after a turn that threw",