document the writer stuff

Author: ericallam

docs/ai-chat/backend.mdx

@@ -101,6 +101,9 @@ export const myChat = chat.task({
 | `runId` | `string` | The Trigger.dev run ID |
 | `chatAccessToken` | `string` | Scoped access token for this run |
 | `clientData` | Typed by `clientDataSchema` | Custom data from the frontend |
+| `writer` | [`ChatWriter`](/ai-chat/reference#chatwriter) | Stream writer for custom chunks |
+
+Every lifecycle callback receives a `writer` — a lazy stream writer that lets you send custom `UIMessageChunk` parts (like `data-*` parts) to the frontend without the ceremony of `chat.stream.writer()`. See [ChatWriter](/ai-chat/reference#chatwriter).
 
 #### onChatStart
 
@@ -145,6 +148,7 @@ Fires at the start of every turn, after message accumulation and `onChatStart` (
 | `continuation` | `boolean` | Whether this run is continuing an existing chat |
 | `preloaded` | `boolean` | Whether this run was preloaded |
 | `clientData` | Typed by `clientDataSchema` | Custom data from the frontend |
+| `writer` | [`ChatWriter`](/ai-chat/reference#chatwriter) | Stream writer for custom chunks |
 
 ```ts
 export const myChat = chat.task({
@@ -170,9 +174,41 @@ export const myChat = chat.task({
   By persisting in `onTurnStart`, the user's message is saved to your database before the AI starts streaming. If the user refreshes mid-stream, the message is already there.
 </Tip>
 
+#### onBeforeTurnComplete
+
+Fires after the response is captured but **before** the stream closes. The `writer` can send custom chunks that appear in the current turn — use this for post-processing indicators, compaction progress, or any data the user should see before the turn ends.
+
+```ts
+export const myChat = chat.task({
+  id: "my-chat",
+  onBeforeTurnComplete: async ({ writer, usage, uiMessages }) => {
+    // Write a custom data part while the stream is still open
+    writer.write({
+      type: "data-usage-summary",
+      data: {
+        tokens: usage?.totalTokens,
+        messageCount: uiMessages.length,
+      },
+    });
+
+    // You can also compact messages here and write progress
+    if (usage?.totalTokens && usage.totalTokens > 50_000) {
+      writer.write({ type: "data-compaction", data: { status: "compacting" } });
+      chat.setMessages(compactedMessages);
+      writer.write({ type: "data-compaction", data: { status: "complete" } });
+    }
+  },
+  run: async ({ messages, signal }) => {
+    return streamText({ model: openai("gpt-4o"), messages, abortSignal: signal });
+  },
+});
+```
+
+Receives the same fields as [`TurnCompleteEvent`](/ai-chat/reference#turncompleteevent), plus a [`writer`](/ai-chat/reference#chatwriter).
+
 #### onTurnComplete
 
-Fires after each turn completes — after the response is captured, before waiting for the next message. This is the primary hook for persisting the assistant's response.
+Fires after each turn completes — after the response is captured and the stream is closed. This is the primary hook for persisting the assistant's response. Does not include a `writer` since the stream is already closed.
 
 | Field | Type | Description |
 |-------|------|-------------|

docs/ai-chat/features.mdx

@@ -207,6 +207,10 @@ export const myChat = chat.task({
   Use `data-*` chunk types (e.g. `data-status`, `data-progress`) for custom data. The AI SDK processes these into `DataUIPart` objects in `message.parts` on the frontend. Writing the same `type` + `id` again updates the existing part instead of creating a new one — useful for live progress.
 </Tip>
 
+<Tip>
+  Inside lifecycle callbacks (`onPreload`, `onChatStart`, `onTurnStart`, `onBeforeTurnComplete`, `onCompacted`), you can use the `writer` parameter instead of `chat.stream.writer()` — it's simpler and avoids the `execute` + `waitUntilComplete` boilerplate. See [ChatWriter](/ai-chat/reference#chatwriter).
+</Tip>
+
 `chat.stream` exposes the full stream API:
 
 | Method | Description |

docs/ai-chat/reference.mdx

@@ -16,8 +16,9 @@ Options for `chat.task()`.
 | `onPreload` | `(event: PreloadEvent) => Promise<void> \| void` | — | Fires on preloaded runs before the first message |
 | `onChatStart` | `(event: ChatStartEvent) => Promise<void> \| void` | — | Fires on turn 0 before `run()` |
 | `onTurnStart` | `(event: TurnStartEvent) => Promise<void> \| void` | — | Fires every turn before `run()` |
-| `onTurnComplete` | `(event: TurnCompleteEvent) => Promise<void> \| void` | — | Fires after each turn completes |
-| `onCompacted` | `(event: CompactedEvent) => Promise<void> \| void` | — | Fires when compaction occurs. See [Compaction](/ai-chat/compaction) |
+| `onBeforeTurnComplete` | `(event: BeforeTurnCompleteEvent) => Promise<void> \| void` | — | Fires after response but before stream closes. Includes `writer`. |
+| `onTurnComplete` | `(event: TurnCompleteEvent) => Promise<void> \| void` | — | Fires after each turn completes (stream closed) |
+| `onCompacted` | `(event: CompactedEvent) => Promise<void> \| void` | — | Fires when compaction occurs. Includes `writer`. See [Compaction](/ai-chat/compaction) |
 | `compaction` | `ChatTaskCompactionOptions` | — | Automatic context compaction. See [Compaction](/ai-chat/compaction) |
 | `pendingMessages` | `PendingMessagesOptions` | — | Mid-execution message injection. See [Pending Messages](/ai-chat/pending-messages) |
 | `prepareMessages` | `(event: PrepareMessagesEvent) => ModelMessage[]` | — | Transform model messages before use (cache breaks, context injection, etc.) |
@@ -57,6 +58,7 @@ Passed to the `onPreload` callback.
 | `runId` | `string` | The Trigger.dev run ID |
 | `chatAccessToken` | `string` | Scoped access token for this run |
 | `clientData` | Typed by `clientDataSchema` | Custom data from the frontend |
+| `writer` | [`ChatWriter`](#chatwriter) | Stream writer for custom chunks. Lazy — no overhead if unused. |
 
 ## ChatStartEvent
 
@@ -72,6 +74,7 @@ Passed to the `onChatStart` callback.
 | `continuation` | `boolean` | Whether this run is continuing an existing chat |
 | `previousRunId` | `string \| undefined` | Previous run ID (only when `continuation` is true) |
 | `preloaded` | `boolean` | Whether this run was preloaded before the first message |
+| `writer` | [`ChatWriter`](#chatwriter) | Stream writer for custom chunks. Lazy — no overhead if unused. |
 
 ## TurnStartEvent
 
@@ -89,6 +92,7 @@ Passed to the `onTurnStart` callback.
 | `continuation` | `boolean` | Whether this run is continuing an existing chat |
 | `previousRunId` | `string \| undefined` | Previous run ID (only when `continuation` is true) |
 | `preloaded` | `boolean` | Whether this run was preloaded |
+| `writer` | [`ChatWriter`](#chatwriter) | Stream writer for custom chunks. Lazy — no overhead if unused. |
 
 ## TurnCompleteEvent
 
@@ -112,6 +116,37 @@ Passed to the `onTurnComplete` callback.
 | `usage` | `LanguageModelUsage \| undefined` | Token usage for this turn |
 | `totalUsage` | `LanguageModelUsage` | Cumulative token usage across all turns |
 
+## BeforeTurnCompleteEvent
+
+Passed to the `onBeforeTurnComplete` callback. Same fields as `TurnCompleteEvent` plus a `writer`.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| _(all TurnCompleteEvent fields)_ | | See [TurnCompleteEvent](#turncompleteevent) |
+| `writer` | [`ChatWriter`](#chatwriter) | Stream writer — the stream is still open so chunks appear in the current turn |
+
+## ChatWriter
+
+A stream writer passed to lifecycle callbacks. Write custom `UIMessageChunk` parts (e.g. `data-*` parts) to the chat stream.
+
+The writer is lazy — no stream is opened unless you call `write()` or `merge()`, so there's zero overhead for callbacks that don't use it.
+
+| Method | Type | Description |
+|--------|------|-------------|
+| `write(part)` | `(part: UIMessageChunk) => void` | Write a single chunk to the chat stream |
+| `merge(stream)` | `(stream: ReadableStream<UIMessageChunk>) => void` | Merge another stream's chunks into the chat stream |
+
+```ts
+onTurnStart: async ({ writer }) => {
+  // Write a custom data part — render it on the frontend
+  writer.write({ type: "data-status", data: { loading: true } });
+},
+onBeforeTurnComplete: async ({ writer, usage }) => {
+  // Stream is still open — these chunks arrive before the turn ends
+  writer.write({ type: "data-usage", data: { tokens: usage?.totalTokens } });
+},
+```
+
 ## ChatTaskCompactionOptions
 
 Options for the `compaction` field on `chat.task()`. See [Compaction](/ai-chat/compaction) for usage guide.
@@ -153,6 +188,7 @@ Passed to the `onCompacted` callback.
 | `stepNumber` | `number` | Step number (-1 for outer loop) |
 | `chatId` | `string \| undefined` | Chat session ID |
 | `turn` | `number \| undefined` | Current turn |
+| `writer` | [`ChatWriter`](#chatwriter) | Stream writer for custom chunks during compaction |
 
 ## PendingMessagesOptions