feat(sdk): return lastEventId from writeTurnComplete and typed capture result (#4304)

## Summary

Two ergonomic additions for custom chat-agent loops that own the turn
loop (`chat.customAgent`, `chat.createSession`, and the hand-rolled
primitives).

`chat.writeTurnComplete()` now resolves to `{ lastEventId }`, the resume
cursor for the start of the next turn. A custom loop can persist it
straight from the task instead of round-tripping it back from the client
after the turn ends. The value was already produced internally by the
turn-complete write; the public wrapper simply discarded it.

`chat.pipeAndCapture()` no longer throws when a stream is stopped or
fails. It now resolves to a `PipeAndCaptureResult` carrying any partial
`message` captured before the stop or failure, a typed `status`
(`"complete" | "aborted" | "error"`), and the `error` on failure.
Previously a failed stream threw and the partial was lost, and an abort
was captured only when the AI SDK happened to fire `onFinish` in time.

```ts
const { message, status, error } = await chat.pipeAndCapture(result, { signal });
if (message) conversation.addResponse(message);
if (status === "error") logger.error("turn failed", { error });

const { lastEventId } = await chat.writeTurnComplete();
await db.chats.update(chatId, { lastEventId });
```

## Design

`pipeAndCapture` wraps the pipe in a `try/catch` and classifies the
outcome from the abort signal (a stop drains the source stream cleanly
rather than throwing) versus a thrown error. It also races the
`onFinish` capture against a timeout so a hard stop that prevents
`onFinish` from firing can't hang the caller. This mirrors the capture
path `chat.agent` already uses internally.

The `finishReason` from `onFinish` is surfaced too, since it was already
captured on the built-in path.

The internal `turn.complete()` helper keeps its existing contract: it
still returns `UIMessage | undefined`, still throws on a genuine stream
failure, and still discards output on a full run cancel.

## Breaking change

`chat.pipeAndCapture` previously resolved to `UIMessage | undefined`.
Call sites now read `.message` off the result. This is a young,
low-level API; the docs examples are updated in this PR.

Author: matt-aitken

.changeset/chat-custom-agent-capture.md

@@ -0,0 +1,22 @@
+---
+"@trigger.dev/sdk": patch
+---
+
+Custom chat agent loops get two ergonomic wins for owning the turn loop.
+
+`chat.writeTurnComplete()` now returns the turn boundary's resume cursors (`lastEventId` for the output stream and `sessionInEventId` for the input stream), so you can persist them straight from the task instead of round-tripping them back from the client.
+
+```ts
+const { lastEventId, sessionInEventId } = await chat.writeTurnComplete();
+await db.chats.update(chatId, { lastEventId, sessionInEventId });
+```
+
+`chat.pipeAndCapture()` no longer throws when a stream is stopped or fails. It now returns a `PipeAndCaptureResult` whose `message` holds any partial output captured before the stop or failure, alongside a typed `status` (`"complete" | "aborted" | "error"`) and, on failure, the `error`. Read the message off the result:
+
+```ts
+const { message, status, error } = await chat.pipeAndCapture(result, { signal });
+if (message) conversation.addResponse(message);
+if (status === "error") logger.error("turn failed", { error });
+```
+
+Note: `pipeAndCapture` previously resolved to `UIMessage | undefined`. Update call sites to read `.message` from the returned result.

docs/ai-chat/changelog.mdx

@@ -55,10 +55,10 @@ if (isFinal) {
   const result = streamText({ model, messages: conversation.modelMessages, tools });
   // Pass originalMessages so the handed-over tool round merges into the
   // step-1 assistant instead of starting a new message.
-  const response = await chat.pipeAndCapture(result, {
+  const { message } = await chat.pipeAndCapture(result, {
     originalMessages: conversation.uiMessages,
   });
-  if (response) await conversation.addResponse(response);
+  if (message) await conversation.addResponse(message);
 }
 ```
 

docs/ai-chat/compaction.mdx

@@ -365,8 +365,8 @@ for (let turn = 0; turn < 100; turn++) {
     stopWhen: stepCountIs(15),
   });
 
-  const response = await chat.pipeAndCapture(result);
-  if (response) await conversation.addResponse(response);
+  const { message } = await chat.pipeAndCapture(result);
+  if (message) await conversation.addResponse(message);
 
   // Outer-loop compaction
   const usage = await result.totalUsage;

docs/ai-chat/custom-agents.mdx

@@ -160,11 +160,11 @@ for await (const turn of session) {
   });
 
   // Manual: pipe and capture separately
-  const response = await chat.pipeAndCapture(result, { signal: turn.signal });
+  const { message } = await chat.pipeAndCapture(result, { signal: turn.signal });
 
-  if (response) {
+  if (message) {
     // Custom processing before accumulating
-    await turn.addResponse(response);
+    await turn.addResponse(message);
   }
 
   // Custom persistence, analytics, etc.
@@ -215,8 +215,8 @@ For full control, skip `createSession` and compose the primitives directly:
 | ------------------------------- | -------------------------------------------------------------------------------------------- |
 | `chat.messages`                 | Input stream for incoming messages — use `.waitWithIdleTimeout()` to wait for the next turn  |
 | `chat.createStopSignal()`       | Create a managed stop signal wired to the stop input stream                                  |
-| `chat.pipeAndCapture(result)`   | Pipe a `StreamTextResult` to the chat stream and capture the response                        |
-| `chat.writeTurnComplete()`      | Signal the frontend that the current turn is complete                                        |
+| `chat.pipeAndCapture(result)`   | Pipe a stream and capture the response; returns `{ message, status, error }`                 |
+| `chat.writeTurnComplete()`      | Signal turn complete; returns `{ lastEventId, sessionInEventId }` resume cursors             |
 | `chat.MessageAccumulator`       | Accumulates conversation messages across turns                                               |
 | `chat.pipe(stream)`             | Pipe a stream to the frontend (no response capture)                                          |
 | `chat.cleanupAbortedParts(msg)` | Clean up incomplete parts from a stopped response                                            |
@@ -285,21 +285,16 @@ export const myChat = chat.customAgent({
         stopWhen: stepCountIs(15),
       });
 
-      let response;
-      try {
-        response = await chat.pipeAndCapture(result, { signal: combinedSignal });
-      } catch (error) {
-        if (error instanceof Error && error.name === "AbortError") {
-          if (runSignal.aborted) break;
-          // Stop — fall through to accumulate partial
-        } else {
-          throw error;
-        }
-      }
+      const { message, status, error } = await chat.pipeAndCapture(result, {
+        signal: combinedSignal,
+      });
+      // pipeAndCapture never throws: a user stop returns status "aborted" with
+      // the partial message, and a failure returns status "error" with `error`.
+      if (status === "error") throw error;
 
-      if (response) {
+      if (message) {
         const cleaned =
-          stop.signal.aborted && !runSignal.aborted ? chat.cleanupAbortedParts(response) : response;
+          stop.signal.aborted && !runSignal.aborted ? chat.cleanupAbortedParts(message) : message;
         await conversation.addResponse(cleaned);
       }
 
@@ -346,8 +341,8 @@ const messages = await conversation.addIncoming(
 );
 
 // After piping, add the response
-const response = await chat.pipeAndCapture(result);
-if (response) await conversation.addResponse(response);
+const { message } = await chat.pipeAndCapture(result);
+if (message) await conversation.addResponse(message);
 
 // Access accumulated messages for persistence
 conversation.uiMessages; // UIMessage[]

docs/ai-chat/fast-starts.mdx

@@ -589,10 +589,10 @@ if (turn === 0 && payload.trigger === "handover-prepare") {
       messages: conversation.modelMessages,
       stopWhen: stepCountIs(10),
     });
-    const response = await chat.pipeAndCapture(result, {
+    const { message } = await chat.pipeAndCapture(result, {
       originalMessages: conversation.uiMessages,
     });
-    if (response) await conversation.addResponse(response);
+    if (message) await conversation.addResponse(message);
   }
   await chat.writeTurnComplete(); // on isFinal the warm partial is already the response
   return;

docs/ai-chat/pending-messages.mdx

@@ -179,10 +179,14 @@ for (let turn = 0; turn < 100; turn++) {
     stopWhen: stepCountIs(15),
   });
 
-  const response = await chat.pipeAndCapture(result);
+  const { message, status, error } = await chat.pipeAndCapture(result);
   sub.off();
 
-  if (response) await conversation.addResponse(response);
+  // Keep any partial output, then branch on the outcome: pipeAndCapture no
+  // longer throws, so rethrow a real failure and don't complete a failed turn.
+  if (message) await conversation.addResponse(message);
+  if (status === "error") throw error;
+
   await chat.writeTurnComplete();
 }
 ```

docs/ai-chat/reference.mdx

@@ -503,8 +503,8 @@ All methods available on the `chat` object from `@trigger.dev/sdk/ai`.
 | `chat.agent(options)`                       | Create a chat agent                                                                                                          |
 | `chat.createSession(payload, options)`      | Create an async iterator for chat turns                                                                                      |
 | `chat.pipe(source, options?)`               | Pipe a stream to the frontend (from anywhere inside a task)                                                                  |
-| `chat.pipeAndCapture(source, options?)`     | Pipe and capture the response `UIMessage`                                                                                    |
-| `chat.writeTurnComplete(options?)`          | Signal the frontend that the current turn is complete                                                                        |
+| `chat.pipeAndCapture(source, options?)`     | Pipe and capture the response; returns `{ message, status, error }`                                                         |
+| `chat.writeTurnComplete(options?)`          | Signal turn complete; returns `{ lastEventId, sessionInEventId }` resume cursors                                            |
 | `chat.createStopSignal()`                   | Create a managed stop signal wired to the stop input stream                                                                  |
 | `chat.messages`                             | Input stream for incoming messages — use `.waitWithIdleTimeout()`                                                            |
 | `chat.local<T>({ id })`                     | Create a per-run typed local (see [`chat.local`](/ai-chat/chat-local))                             |