fix(sdk): re-dispatch a single in-flight user on recovery boot

The recovery-boot smart default spliced the partial assistant plus the
user it was answering into the seed chain whenever a partial existed and
there was at least one in-flight user. With exactly one in-flight user —
the plain OOM / crash-mid-answer shape — that consumed the only message
there was to dispatch: `recoveredTurns` came out empty, the boot queue
stayed empty, the session.in cursor was advanced past the message
anyway, and on a preload or continuation boot (no message on the wire
payload) neither dispatch site fired. The interrupted question was never
answered and the run idled until its timeout.

Require two or more in-flight users for the splice, on both the chain
and the recoveredTurns branch. With n >= 2 nothing changes. With n = 1
the orphan partial is dropped and the interrupted user is re-dispatched
as a fresh turn, which is what the OOM-resilience docs promise. The
submit-message boot is unaffected: the existing dedup skips a queued
message identical to the one already on the wire payload.

Also corrects the docstrings and the recovery-boot docs, which described
the default as "re-dispatch every user" without mentioning the splice.

Co-Authored-By: Claude <noreply@anthropic.com>

Author: claude

.changeset/brave-otters-recover.md

@@ -0,0 +1,5 @@
+---
+"@trigger.dev/sdk": patch
+---
+
+Fixed a chat agent hanging after an interrupted turn: when a run was killed mid-answer (out of memory, crash, or eviction) and only the one message it was answering was still outstanding, the new run never replied to it. That message is now re-answered on the new run.

docs/ai-chat/patterns/recovery-boot.mdx

@@ -32,7 +32,7 @@ On a continuation boot, the runtime reads:
 - **`session.out` tail past the snapshot cursor** — closed assistant turns plus, optionally, a `partialAssistant` (the trailing message whose stream never received a `finish` chunk). `cleanupAbortedParts` has already stripped streaming-in-progress fragments.
 - **`session.in` tail past the last `turn-complete` cursor** — user messages the dead run hadn't acknowledged.
 
-If both `partialAssistant` and `inFlightUsers` are non-empty, the runtime splices `[firstInFlightUser, partialAssistant]` onto the chain. The remaining in-flight users dispatch as fresh turns. The model sees:
+If there's a `partialAssistant` and two or more `inFlightUsers`, the runtime splices `[firstInFlightUser, partialAssistant]` onto the chain. The remaining in-flight users dispatch as fresh turns. The model sees:
 
 ```
 [ ...settledMessages,  // chain through the last completed turn
@@ -138,10 +138,17 @@ type RecoveryBootResult<TUIM extends UIMessage = UIMessage> = {
 };
 ```
 
-- **`chain`** — replaces the seed chain. Defaults to `[...settledMessages, firstInFlightUser, partialAssistant]` when both partial and in-flight users exist, otherwise `settledMessages` alone.
+- **`chain`** — replaces the seed chain. Defaults to `[...settledMessages, firstInFlightUser, partialAssistant]` when there's a partial **and two or more** in-flight users, otherwise `settledMessages` alone.
 - **`recoveredTurns`** — user messages to dispatch as fresh turns after the chain is restored. Defaults to `inFlightUsers.slice(1)` when the smart default consumed the first user, otherwise `inFlightUsers`.
 - **`beforeBoot`** — runs after the writer flushes and before the first recovered turn fires. Use for blocking persistence (write the partial to your DB so a later turn can reference it). Errors bubble — wrap your own try/catch if you want to soft-fail.
 
+<Note>
+  The splice needs a follow-up user to answer, so it only applies with two or
+  more in-flight users. With exactly one — the plain OOM or crash-mid-answer
+  case — the orphan partial is dropped and that single user is re-dispatched as
+  a fresh turn, so the interrupted question still gets answered.
+</Note>
+
 ## Examples
 
 ### Drop the partial — strict "cancel means discard"

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

@@ -4239,8 +4239,11 @@ export type RecoveryBootEvent<TUIM extends UIMessage = UIMessage> = {
   /**
    * User messages that arrived on `session.in` past the cursor — i.e.
    * the message(s) the predecessor was processing or had queued when
-   * it died. The runtime's default is to re-dispatch each as a fresh
-   * turn after the chain is restored. Return a different list via
+   * it died. The runtime's default re-dispatches each as a fresh turn
+   * after the chain is restored, except when a `partialAssistant` is
+   * present AND there are two or more of them: the first is then
+   * spliced into the chain (as the question the partial was answering)
+   * rather than dispatched. Return a different list via
    * `recoveredTurns` to skip / reorder / collapse them.
    */
   inFlightUsers: TUIM[];
@@ -4285,8 +4288,12 @@ export type RecoveryBootResult<TUIM extends UIMessage = UIMessage> = {
   chain?: TUIM[];
   /**
    * The user messages to re-dispatch as fresh turns after the chain is
-   * restored. Default: `inFlightUsers` (re-process every in-flight
-   * user). Return `[]` to suppress all of them; return a filtered /
+   * restored. Default: `inFlightUsers.slice(1)` when a
+   * `partialAssistant` is present and there are two or more in-flight
+   * users (the first one is spliced into the chain instead), otherwise
+   * `inFlightUsers` — including the single-user case, where the
+   * interrupted user is re-dispatched and the orphan partial is
+   * dropped. Return `[]` to suppress all of them; return a filtered /
    * reordered subset to skip specific ones.
    */
   recoveredTurns?: TUIM[];
@@ -4853,8 +4860,13 @@ export type ChatAgentOptions<
    * customer's DB.
    *
    * Defaults (returned when the hook is omitted or returns no field):
-   *   - `chain` = `settledMessages` (drop the orphan partial)
-   *   - `recoveredTurns` = `inFlightUsers` (re-dispatch every user)
+   *   - With two or more in-flight users, the partial and the user it
+   *     was answering are spliced into the chain:
+   *     `chain` = `[...settledMessages, inFlightUsers[0], partialAssistant]`
+   *     and `recoveredTurns` = `inFlightUsers.slice(1)`.
+   *   - Otherwise `chain` = `settledMessages` (drop the orphan partial)
+   *     and `recoveredTurns` = `inFlightUsers` (re-dispatch every user)
+   *     — so a single interrupted user is answered on the new run.
    *
    * @example
    * ```ts
@@ -5840,20 +5852,29 @@ function chatAgent<
           }
         }
 
-        // Default: splice partial + the user it was answering into
-        // the chain so follow-ups like "keep going" still have context.
+        // Default: splice partial + the user it was answering into the chain
+        // so follow-ups like "keep going" still have context, and re-dispatch
+        // the users that arrived after it.
+        //
+        // The splice needs a follow-up user to answer — it consumes
+        // `inFlightUsers[0]` into the chain instead of dispatching it. With
+        // exactly ONE in-flight user (the plain OOM / crash-mid-answer case)
+        // there is nothing left to dispatch, so splicing would strand that
+        // user unanswered and idle the run. Require `length > 1` on both
+        // branches: at n=1 the orphan partial is dropped and the interrupted
+        // user is re-dispatched as a fresh turn instead.
         let seedChain: TUIMessage[];
         let recoveredTurns: TUIMessage[];
         if (hookChain !== undefined) {
           seedChain = hookChain;
-        } else if (partialAssistant !== undefined && inFlightUsers.length > 0) {
+        } else if (partialAssistant !== undefined && inFlightUsers.length > 1) {
           seedChain = [...settledMessages, inFlightUsers[0]!, partialAssistant];
         } else {
           seedChain = settledMessages;
         }
         if (hookRecoveredTurns !== undefined) {
           recoveredTurns = hookRecoveredTurns;
-        } else if (partialAssistant !== undefined && inFlightUsers.length > 0) {
+        } else if (partialAssistant !== undefined && inFlightUsers.length > 1) {
           recoveredTurns = inFlightUsers.slice(1);
         } else {
           recoveredTurns = inFlightUsers;

packages/trigger-sdk/test/recovery-boot.test.ts

@@ -295,6 +295,54 @@ describe("onRecoveryBoot — chat.agent recovery hook", () => {
     }
   });
 
+  it("smart default: a single in-flight user is re-dispatched, not swallowed by the splice", async () => {
+    // The plain OOM / crash-mid-answer shape: the run died while answering
+    // the only outstanding user message. Splicing that user into the chain
+    // would leave nothing to dispatch, so the run would boot and idle with
+    // the message unanswered. The default must re-dispatch it instead (and
+    // drop the orphan partial).
+    let observedChain: Array<{ role: string; idHead: string }> = [];
+    let turnCount = 0;
+    const model = new MockLanguageModelV3({
+      doStream: async () => {
+        turnCount++;
+        return { stream: textStream("ok") };
+      },
+    });
+    const partial = assistantMessage("partial answer in progress", "a-partial");
+    const u1 = userMessage("the question that OOM'd", "u-1");
+    const agent = chat.agent({
+      id: "recovery-boot.single-inflight-user",
+      // NO onRecoveryBoot — exercise the default path
+      onTurnStart: async ({ uiMessages }) => {
+        if (turnCount === 0) {
+          observedChain = uiMessages.map((m) => ({
+            role: m.role,
+            idHead: m.id.slice(0, 10),
+          }));
+        }
+      },
+      run: async ({ messages, signal }) => streamText({ model, messages, abortSignal: signal }),
+    });
+    const harness = mockChatAgent(agent, {
+      chatId: "single-inflight-user",
+      continuation: true,
+      previousRunId: "run_prior",
+    });
+    harness.seedSessionOutPartial(partial as never);
+    harness.seedSessionInTail([u1 as never]);
+    try {
+      await new Promise((r) => setTimeout(r, 100));
+      // One turn fires, for the interrupted user.
+      expect(turnCount).toBe(1);
+      // The orphan partial is dropped — the chain is just the re-dispatched user.
+      expect(observedChain.map((m) => m.role)).toEqual(["user"]);
+      expect(observedChain[0]!.idHead).toBe("u-1");
+    } finally {
+      await harness.close();
+    }
+  });
+
   it("hook's recoveredTurns: [] suppresses re-dispatch of in-flight users", async () => {
     let turnCount = 0;
     const model = new MockLanguageModelV3({