@trigger.dev/sdk 4.5.16 → 4.6.0

package/docs/ai-chat/pending-messages.mdx

@@ -30,18 +30,18 @@ Add `pendingMessages` to your `chat.agent` configuration:
 
 ```ts
 import { chat } from "@trigger.dev/sdk/ai";
-import { streamText, stepCountIs } from "ai";
+import { stepCountIs } from "ai";
 import { anthropic } from "@ai-sdk/anthropic";
 
 export const myChat = chat.agent({
   id: "my-chat",
+  registry,
   pendingMessages: {
     // Only inject when there are completed steps (tool calls happened)
     shouldInject: ({ steps }) => steps.length > 0,
   },
-  run: async ({ messages, signal }) => {
+  run: async ({ messages, signal, streamText }) => {
     return streamText({
-      ...chat.toStreamTextOptions({ registry }),
       messages,
       tools: { /* ... */ },
       abortSignal: signal,

package/docs/ai-chat/prompt-caching.mdx

@@ -16,7 +16,7 @@ A request renders as `tools` → `system` → `messages`. There are three prefix
 
 | Region | How to cache it | Stability |
 | --- | --- | --- |
-| System prompt (+ tools) | `cacheControl` / `systemProviderOptions` on `chat.toStreamTextOptions()`, or `providerOptions` on `chat.prompt.set()` | Set once, never changes — the highest-value target |
+| System prompt (+ tools) | `cacheControl` / `systemProviderOptions` on `chat.agent()`, or `providerOptions` on `chat.prompt.set()` | Set once, never changes — the highest-value target |
 | Conversation history | `prepareMessages` adds a breakpoint to the last message | Grows append-only across turns |
 | Tool definitions | Stable as long as your tool set doesn't change between turns | Render at position 0 — changing them invalidates everything |
 
@@ -32,23 +32,22 @@ The system prompt (your `chat.prompt` text plus any skills preamble) is usually
 
 Three ways to opt in, depending on where you'd rather express it.
 
-**`cacheControl` at the `streamText` call site** — the Anthropic-flavored one-liner:
+**`cacheControl` on the agent** — the Anthropic-flavored one-liner:
 
 ```ts /trigger/chat.ts
 import { chat } from "@trigger.dev/sdk/ai";
-import { streamText } from "ai";
 import { anthropic } from "@ai-sdk/anthropic";
 
 export const myChat = chat.agent({
   id: "my-chat",
+  cacheControl: { type: "ephemeral" },
   onChatStart: async () => {
     chat.prompt.set(SYSTEM_PROMPT); // a large, stable instruction block
   },
-  run: async ({ messages, signal }) => {
+  run: async ({ messages, signal, streamText }) => {
     return streamText({
       model: anthropic("claude-sonnet-4-6"),
       // Caches the system block with a 5-minute breakpoint.
-      ...chat.toStreamTextOptions({ cacheControl: { type: "ephemeral" } }),
       messages,
       abortSignal: signal,
     });
@@ -59,17 +58,19 @@ export const myChat = chat.agent({
 **`systemProviderOptions`** is the provider-agnostic form — pass the raw `providerOptions` so it composes with any provider:
 
 ```ts /trigger/chat.ts
-return streamText({
-  model: anthropic("claude-sonnet-4-6"),
-  ...chat.toStreamTextOptions({
-    systemProviderOptions: { anthropic: { cacheControl: { type: "ephemeral" } } },
-  }),
-  messages,
-  abortSignal: signal,
+export const myChat = chat.agent({
+  id: "my-chat",
+  systemProviderOptions: { anthropic: { cacheControl: { type: "ephemeral" } } },
+  run: async ({ messages, signal, streamText }) =>
+    streamText({
+      model: anthropic("claude-sonnet-4-6"),
+      messages,
+      abortSignal: signal,
+    }),
 });
 ```
 
-**`providerOptions` on `chat.prompt.set()`** co-locates the intent with where the prompt is defined. It carries through to `toStreamTextOptions()` with no call-site change:
+**`providerOptions` on `chat.prompt.set()`** co-locates the intent with where the prompt is defined. It carries through to the managed `streamText` with no call-site change:
 
 ```ts /trigger/chat.ts
 onChatStart: async () => {
@@ -77,17 +78,16 @@ onChatStart: async () => {
     providerOptions: { anthropic: { cacheControl: { type: "ephemeral" } } },
   });
 },
-run: async ({ messages, signal }) => {
+run: async ({ messages, signal, streamText }) => {
   return streamText({
     model: anthropic("claude-sonnet-4-6"),
-    ...chat.toStreamTextOptions(), // already cached
     messages,
     abortSignal: signal,
   });
 },
 ```
 
-If more than one is set, the call-site option wins: `systemProviderOptions` overrides `cacheControl`, and both override `chat.prompt.set`'s `providerOptions`. There's no deep merge — the most specific option replaces the rest.
+If more than one is set, the most specific wins: `systemProviderOptions` overrides `cacheControl`, and both override `chat.prompt.set`'s `providerOptions`. There's no deep merge — the most specific option replaces the rest.
 
 <Note>
   Use the 1-hour cache for prefixes that sit idle longer than 5 minutes between turns: `cacheControl: { type: "ephemeral", ttl: "1h" }`. Writes cost more (2× vs 1.25×), so it pays off only when reads span the longer window.
@@ -100,6 +100,7 @@ Place a breakpoint on the last message and the entire conversation prefix up to
 ```ts /trigger/chat.ts
 export const myChat = chat.agent({
   id: "my-chat",
+  cacheControl: { type: "ephemeral" },
   prepareMessages: async ({ messages }) => {
     if (messages.length === 0) return messages;
     const last = messages[messages.length - 1];
@@ -114,10 +115,9 @@ export const myChat = chat.agent({
       },
     ];
   },
-  run: async ({ messages, signal }) => {
+  run: async ({ messages, signal, streamText }) => {
     return streamText({
       model: anthropic("claude-sonnet-4-6"),
-      ...chat.toStreamTextOptions({ cacheControl: { type: "ephemeral" } }),
       messages,
       abortSignal: signal,
     });
@@ -149,11 +149,10 @@ Caching is provider-specific, and most providers don't use per-block breakpoints
 
 ```ts /trigger/chat.ts
 // Amazon Bedrock
-return streamText({
-  ...chat.toStreamTextOptions({
-    systemProviderOptions: { bedrock: { cachePoint: { type: "default" } } },
-  }),
-  messages,
+export const myChat = chat.agent({
+  id: "my-chat",
+  systemProviderOptions: { bedrock: { cachePoint: { type: "default" } } },
+  run: async ({ messages, streamText }) => streamText({ messages }),
 });
 ```
 
@@ -166,14 +165,13 @@ Usage reporting is normalized. Each provider reports cache tokens under its own
 The turn's usage carries cache token counts. `chat.agent` accumulates them across turns and hands them to `run` as `previousTurnUsage` (last turn) and `totalUsage` (whole chat), both `LanguageModelUsage`:
 
 ```ts /trigger/chat.ts
-run: async ({ messages, signal, previousTurnUsage }) => {
+run: async ({ messages, signal, previousTurnUsage, streamText }) => {
   // After turn 1, cacheReadTokens should be > 0 on a stable prefix.
   console.log("cache read", previousTurnUsage?.inputTokenDetails?.cacheReadTokens);
   console.log("cache write", previousTurnUsage?.inputTokenDetails?.cacheWriteTokens);
 
   return streamText({
     model: anthropic("claude-sonnet-4-6"),
-    ...chat.toStreamTextOptions({ cacheControl: { type: "ephemeral" } }),
     messages,
     abortSignal: signal,
   });

package/docs/ai-chat/quick-start.mdx

@@ -16,19 +16,16 @@ The chat surface works with Vercel AI SDK **v5, v6, or v7**; install whichever m
 
     ```ts trigger/chat.ts
     import { chat } from "@trigger.dev/sdk/ai";
-    import { streamText, stepCountIs } from "ai";
+    import { stepCountIs } from "ai";
     import { anthropic } from "@ai-sdk/anthropic";
 
     export const myChat = chat.agent({
       id: "my-chat",
-      run: async ({ messages, signal }) => {
+      // `streamText` here is the SDK's, not the one from `ai`: it carries
+      // compaction, steering, background injection, the system prompt and
+      // telemetry, so none of them have to be wired up by hand.
+      run: async ({ messages, signal, streamText }) => {
         return streamText({
-          // Spread chat.toStreamTextOptions() FIRST — it wires up
-          // prepareStep (compaction, steering, background injection),
-          // the system prompt set via chat.prompt(), and telemetry.
-          // Skipping this is the single most common cause of subtle
-          // bugs (silent broken compaction, missing steering, etc.).
-          ...chat.toStreamTextOptions(),
           model: anthropic("claude-sonnet-4-5"),
           messages,
           abortSignal: signal,
@@ -38,9 +35,12 @@ The chat surface works with Vercel AI SDK **v5, v6, or v7**; install whichever m
     });
     ```
 
-    <Warning>
-      **Always spread `chat.toStreamTextOptions()` into your `streamText` call.** It wires up the `prepareStep` callback that drives compaction, mid-turn steering, and background injection — features that silently no-op if the spread is missing. Spread it **first** so any explicit overrides (e.g. a custom `prepareStep`) win.
-    </Warning>
+    <Note>
+      Take `streamText` from `run`'s argument rather than importing it from `ai`. The
+      imported one drives no `prepareStep`, so compaction, mid-turn steering and
+      background injection never run, and nothing reports it. Spreading
+      `chat.toStreamTextOptions()` into the imported one does the same job by hand.
+    </Note>
 
     <Tip>
       For a **custom** [`UIMessage`](https://sdk.vercel.ai/docs/reference/ai-sdk-core/ui-message) subtype (typed `data-*` parts, tool map, etc.), define the agent with [`chat.withUIMessage<...>().agent({...})`](/ai-chat/types) instead of `chat.agent`.

package/docs/ai-chat/reference.mdx

@@ -44,14 +44,19 @@ Options for `chat.agent()`.
 | `onPreload`                   | `(event: PreloadEvent) => Promise<void> \| void`            | —                              | Fires on preloaded runs before the first message                                                    |
 | `onChatStart`                 | `(event: ChatStartEvent) => Promise<void> \| void`          | —                              | Fires once per chat, on the very first user message. Does NOT fire on continuation runs or OOM-retries — see [onChatStart](/ai-chat/lifecycle-hooks#onchatstart). |
 | `onValidateMessages`          | `(event: ValidateMessagesEvent) => UIMessage[] \| Promise<UIMessage[]>` | —                | Validate/transform UIMessages before model conversion. See [onValidateMessages](/ai-chat/lifecycle-hooks#onvalidatemessages) |
-| `hydrateMessages`             | `(event: HydrateMessagesEvent) => UIMessage[] \| Promise<UIMessage[]>` | —                 | Load message history from backend, replacing the linear accumulator. See [hydrateMessages](/ai-chat/lifecycle-hooks#hydratemessages) |
+| `storage`                     | `TranscriptStorage`                                         | `defaultStorage`               | Where the conversation is persisted and read back. The platform snapshot by default; bring your own to write each change to your database. See [Transcript storage](/ai-chat/transcript-storage) |
+| `hydrateMessages`             | `(event: HydrateMessagesEvent) => UIMessage[] \| Promise<UIMessage[]>` | —                 | **Deprecated.** Load message history from backend, replacing the linear accumulator. Use `loadContext` on a `storage` instead; cannot be combined with `storage`. See [hydrateMessages](/ai-chat/lifecycle-hooks#hydratemessages) |
 | `actionSchema`                | `TaskSchema`                                                | —                              | Schema for validating custom actions sent via `transport.sendAction()`. See [Actions](/ai-chat/actions) |
-| `onAction`                    | `(event: ActionEvent) => Promise<unknown> \| unknown`       | —                              | Handle custom actions. Actions are not turns — only `hydrateMessages` + `onAction` fire. Return a `StreamTextResult` (or `string` / `UIMessage`) for a model response; return `void` for side-effect-only. See [Actions](/ai-chat/actions) |
+| `onAction`                    | `(event: ActionEvent) => Promise<void \| ActionTurn> \| void \| ActionTurn` | —                              | Handle custom actions. Actions are state edits: only `hydrateMessages` (or a storage's `loadContext`) + `onAction` fire. Return `chat.turn()` to run a turn on the edited history, or nothing for an edit only. See [Actions](/ai-chat/actions) |
 | `onTurnStart`                 | `(event: TurnStartEvent) => Promise<void> \| void`          | —                              | Fires every turn before `run()`                                                                     |
 | `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`                  | `ChatAgentCompactionOptions`                                | —                              | Automatic context compaction. See [Compaction](/ai-chat/compaction)                                 |
+| `registry`                    | `{ languageModel(id: string): unknown }`                    | —                              | A provider registry, so the managed `streamText` can resolve a model set through `chat.prompt.set()` |
+| `system`                      | `string \| SystemModelMessage`                              | —                              | The agent's system prompt. Injected instructions append to it. Set it here, at the `streamText` call site, or through `chat.prompt.set()`, but only in one of them |
+| `cacheControl`                | `SystemCacheControl`                                        | —                              | Mark the system prompt for provider-side caching. See [Prompt caching](/ai-chat/prompt-caching) |
+| `systemProviderOptions`       | `ProviderMetadata`                                          | —                              | Raw provider options for the system block. Takes precedence over `cacheControl` |
 | `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.)                         |
 | `tools`                       | `ToolSet \| ((event: ResolveToolsEvent) => ToolSet \| Promise<ToolSet>)` | —                 | Tools for this agent. Threads each tool's `toModelOutput` through cross-turn history re-conversion, and hands the resolved set back on the run payload. Static set or per-turn function. See [Tools](/ai-chat/tools). |
@@ -98,9 +103,10 @@ The payload passed to the `run` function.
 | `ctx`          | `TaskRunContext`                           | Full task run context — same as `task` `run`’s `{ ctx }`             |
 | `messages`     | `ModelMessage[]`                           | Model-ready messages — pass directly to `streamText`                 |
 | `tools`        | `ToolSet`                                  | Resolved tools declared on the agent config (empty object when none). Pass straight to `streamText`. See [Tools](/ai-chat/tools). |
+| `streamText`   | `typeof streamText`                        | The AI SDK's `streamText` with this agent's managed options already applied: the prompt, skill tools, telemetry, and the `prepareStep` that delivers steering, compaction and injected context. Prefer it over importing `streamText` from `ai`. See [The managed streamText](/ai-chat/backend#the-managed-streamtext). |
 | `chatId`       | `string`                                   | Your conversation ID (the session's `externalId`)                    |
 | `sessionId`    | `string`                                   | Friendly ID of the backing Session (`session_*`). Use with `sessions.open()` for advanced cases. Always set — every chat.agent run is bound to a Session. |
-| `trigger`      | `"submit-message" \| "regenerate-message"` | What triggered the request                                           |
+| `trigger`      | `"submit-message" \| "regenerate-message" \| "action-turn"` | What triggered the request; `"action-turn"` is a turn requested by `chat.turn()` |
 | `messageId`    | `string \| undefined`                      | Message ID (for regenerate)                                          |
 | `clientData`   | Typed by `clientDataSchema`                | Custom data from the frontend (typed when schema is provided)        |
 | `continuation` | `boolean`                                  | Whether this run is continuing an existing chat (previous run ended) |
@@ -213,9 +219,38 @@ Passed to the `tools` function form on `chat.agent`, once per turn, to resolve t
 | `continuation` | `boolean`                   | Whether this run is continuing an existing chat   |
 | `clientData`   | Typed by `clientDataSchema` | Custom data from the frontend                     |
 
+## TranscriptStorage
+
+The persistence adapter set through `chat.agent({ storage })`. See [Transcript storage](/ai-chat/transcript-storage). All types below are exported from `@trigger.dev/sdk/ai`.
+
+| Member | Signature | Description |
+| --- | --- | --- |
+| `load` | `(scope: TranscriptScope, opts?: TranscriptLoadOptions) => Promise<TranscriptLoadResult>` | The conversation, in order. Called once at a continuation boot and by `chat.createLoadTranscriptAction` for rendering. |
+| `save` | `(ctx: TranscriptStorageContext, changeset: TranscriptChangeset) => Promise<void>` | Apply the changes since the last save. Called after every turn, failed turn and history-changing action. |
+| `loadContext?` | `(scope: TranscriptScope, event: LoadContextEvent) => Promise<UIMessage[]>` | Optional. When present, the storage owns the model's context: called on every turn and action in place of the runtime's transcript. Same event shape as `HydrateMessagesEvent`. |
+
+| Type | Shape |
+| --- | --- |
+| `TranscriptScope<TClientData>` | `{ chatId: string; clientData: TClientData }` |
+| `TranscriptStorageContext<TClientData>` | `TranscriptScope` plus `{ turn: number; trigger: "submit-message" \| "regenerate-message" \| "action"; runId: string; ctx: TaskRunContext }` |
+| `TranscriptChange` | `{ op: "put"; message: UIMessage; final?: boolean }` \| `{ op: "remove"; id: string }` \| `{ op: "truncateAfter"; afterId: string }` \| `{ op: "state"; value: unknown \| null }` |
+| `TranscriptChangeset` | `{ reason: "turn-complete" \| "turn-error" \| "action" \| "compaction" \| "recovery"; changes: TranscriptChange[]; transcript: TranscriptState; cursors?: TranscriptCursors }` |
+| `TranscriptState` | `{ entries: Array<{ id: string; final: boolean; message: UIMessage }>; state: unknown \| null }`: the whole conversation after the changeset's changes, for stores that write one document |
+| `TranscriptCursors` | `{ lastOutEventId?: string; lastInEventId?: string }` |
+| `TranscriptLoadOptions` | `{ limit?: number; before?: string }` |
+| `TranscriptLoadResult` | `{ messages: UIMessage[]; state: unknown \| null; cursors?: TranscriptCursors; nextCursor?: string }` |
+
+| Export | Description |
+| --- | --- |
+| `defaultStorage` | The platform snapshot storage the agent uses when `storage` is not set. Equal to `snapshotTranscriptStorage()`. |
+| `snapshotTranscriptStorage()` | Factory for the platform snapshot storage. |
+| `memoryTranscriptStorage()` | An in-process storage that also records every changeset it receives. The reference implementation. |
+| `reduceTranscriptChanges(state, changes)` | Pure reducer that applies changes to `{ entries, state }`. Useful for building a storage over a document store. |
+| `runTranscriptStorageTests(makeStorage, options?)` | From `@trigger.dev/sdk/ai/test`. The conformance suite for a storage implementation. Pass `{ api: { describe, it, expect } }` when test globals are off, and `clientData` when your storage scopes by it. |
+
 ## HydrateMessagesEvent
 
-Passed to the `hydrateMessages` callback. See [hydrateMessages](/ai-chat/lifecycle-hooks#hydratemessages).
+Passed to the `hydrateMessages` callback. See [hydrateMessages](/ai-chat/lifecycle-hooks#hydratemessages). `hydrateMessages` is deprecated; `LoadContextEvent`, passed to a storage's `loadContext`, has the same shape.
 
 | Field              | Type                                                  | Description                                               |
 | ------------------ | ----------------------------------------------------- | --------------------------------------------------------- |
@@ -364,8 +399,8 @@ Passed to `compactUIMessages` and `compactModelMessages` callbacks.
 | Field           | Type                 | Description                                          |
 | --------------- | -------------------- | ---------------------------------------------------- |
 | `summary`       | `string`             | The generated summary text                           |
-| `uiMessages`    | `UIMessage[]`        | Current UI messages (full conversation)              |
-| `modelMessages` | `ModelMessage[]`     | Current model messages (full conversation)           |
+| `uiMessages`    | `UIMessage[]`        | Current UI messages (the transcript)                 |
+| `modelMessages` | `ModelMessage[]`     | Current model messages (the lane the model is sent; after a compaction this is the summary plus what followed it, not the whole transcript) |
 | `chatId`        | `string`             | Chat session ID                                      |
 | `turn`          | `number`             | Current turn (0-indexed)                             |
 | `clientData`    | `unknown`            | Custom data from the frontend                        |
@@ -490,9 +525,9 @@ Options for [`chat.headStart()`](/ai-chat/fast-starts#head-start), the warm-serv
 | `agentId`              | `string`                                                | required    | The `chat.agent` / `chat.customAgent` id to hand off to                                              |
 | `run`                  | `(args: HeadStartRunArgs) => Promise<StreamTextResult>` | required    | First-turn callback. Call `streamText` and spread `chat.toStreamTextOptions({ tools })`              |
 | `idleTimeoutInSeconds` | `number`                                                | `60`        | How long the agent waits for the handover signal                                                     |
-| `triggerConfig`        | `Partial<SessionTriggerConfig>`                         | `undefined` | Run options (tags, queue, machine, maxAttempts, maxDuration, region, lockToVersion) for the auto-triggered handover-prepare run. The `chat:{chatId}` tag is prepended automatically and counts toward the 10-tag limit |
+| `triggerConfig`        | `Partial<SessionTriggerConfig>`                         | `undefined` | Run options (tags, queue, machine, maxAttempts, maxDuration, region, lockToVersion, externalDeploymentId) for the auto-triggered handover-prepare run. The `chat:{chatId}` tag is prepended automatically and counts toward the 10-tag limit |
 
-`chat.headStart(options)` returns the handler `(req: Request) => Promise<Response>`. The `run` callback receives `HeadStartRunArgs`: `{ messages: UIMessage[], signal: AbortSignal, chat: HeadStartChatHelper }`, where the helper exposes `chat.toStreamTextOptions({ tools })` and a `chat.session` escape hatch. See [Head Start](/ai-chat/fast-starts#head-start) for the full guide.
+`chat.headStart(options)` returns the handler `(req: Request) => Promise<Response>`. The `run` callback receives `HeadStartRunArgs`: `{ messages: UIMessage[], signal: AbortSignal, chat: HeadStartChatHelper }`, where the helper exposes `chat.toStreamTextOptions({ tools })` and a `chat.session` escape hatch (whose `pendingVersion` says whether the agent run is parked waiting for its deployment). See [Head Start](/ai-chat/fast-starts#head-start) for the full guide.
 
 ## chat namespace
 
@@ -509,8 +544,10 @@ All methods available on the `chat` object from `@trigger.dev/sdk/ai`.
 | `chat.messages`                             | Incoming message mailbox; supports non-consuming `.peek()` / `.hasPending()`, single-record `.next()`, `.on()`, and suspend-aware `.waitWithIdleTimeout()` |
 | `chat.local<T>({ id })`                     | Create a per-run typed local (see [`chat.local`](/ai-chat/chat-local))                             |
 | `chat.createStartSessionAction(taskId, options?)` | Returns a server action that creates a chat Session + triggers the first run + returns a session-scoped PAT. Idempotent on `(env, externalId)`.   |
+| `chat.createLoadTranscriptAction(storage, options?)` | Returns a server action that reads a conversation from a transcript storage (`{ chatId, clientData?, limit?, before? }` → `TranscriptLoadResult`). Pair with `useLoadTranscript`. Performs no application authorization: authorize `chatId` for the signed-in user in your own code. See [Transcript storage](/ai-chat/transcript-storage#reading-the-transcript) |
 | `chat.waitForHandover(options)`             | Wait for a [`chat.headStart`](/ai-chat/fast-starts#handover-with-custom-agents) handover signal in a custom loop. Returns the signal or `null`. `chat.MessageAccumulator` wraps this as `consumeHandover()` / `applyHandover()` |
 | `chat.requestUpgrade()`                     | End the current run after this turn so the next message starts on the latest agent version. Server-orchestrated handoff.    |
+| `chat.close({ reason })`                    | End the conversation permanently: close the session row, write a terminal `session-closed` record, and exit without a continuation. Decide it before the turn ends (`onBeforeTurnComplete`, not `onTurnComplete`) so the client sees the closed state on that turn. |
 | `chat.endAndContinue()`                     | In a hand-rolled custom agent, hand off the Session to a fresh continuation run. Call between turns after detaching input listeners, then return immediately. The promise rejects if the handoff fails. |
 | `chat.setTurnTimeout(duration)`             | Override turn timeout at runtime (e.g. `"2h"`)                                                                               |
 | `chat.setTurnTimeoutInSeconds(seconds)`     | Override turn timeout at runtime (in seconds)                                                                                |
@@ -659,6 +696,7 @@ The `onEvent` callback receives a `ChatTransportEvent` (exported from `@trigger.
 | --- | --- | --- |
 | `message-sent` | `messageId?`, `source`, `durationMs`, `partId?`, `bodyBytes?` | A send was durably acknowledged — a 2xx from the session input stream append (or the `headStart` POST), after any internal token-refresh retries. This means the message is durably written to the stream the agent consumes from, not merely "request accepted". `partId` is the append's idempotency key, also stored on the server-side record. |
 | `message-send-failed` | `messageId?`, `source`, `error`, `status?`, `durationMs`, `partId?`, `bodyBytes?` | A send definitively failed after internal retries. Fires in addition to `useChat`'s `onError`. |
+| `run-pending-version` | `source` | The chat's run is parked waiting for the deployment carrying its external deployment id ([version skew protection](/deployment/version-skew-protection#chat-sessions)). Everything already sent is durable and answered once the deployment lands. `source` is `"start"` (learned while starting the session), `"send"` (from a message append, re-emitted on every send while parked) `"head-start"` (from the `headStart` POST, where step 1 still streams from your server and only step 2 waits) or `"upgrade"` (an automatic version handover whose successor is parked on a deployment that has not landed). |
 | `stream-connected` | `resumed`, `lastEventId?`, `messageId?` | The SSE subscription to the session's output stream started delivering. `resumed: true` when reconnecting from a stored cursor (page reload) rather than following a fresh send. `lastEventId` is the cursor it connected from. |
 | `first-chunk` | `chunkType?`, `lastEventId?`, `messageId?`, `sinceSendMs?` | The first response chunk of a turn arrived. `sinceSendMs` is the delta from the last turn-producing send — time to first token without any bookkeeping. |
 | `turn-completed` | `lastEventId?`, `sessionInEventId?`, `messageId?`, `sinceSendMs?` | The agent's turn-complete control record arrived — the "finished answering" signal. `sinceSendMs` is the full turn latency; `sessionInEventId` is the cursor the agent can safely resume its input stream from. Treat it as a lower bound: it is held back behind any message still waiting to be handled, so it can be below the sequence of the record this turn answered. Do not use it to decide whether a turn boundary belongs to your own send. |
@@ -794,7 +832,7 @@ See [Stop generation](/ai-chat/frontend#stop-generation) for full details.
 
 ### transport.sendAction()
 
-Send a custom action to the agent. Actions wake the agent from suspension and fire `onAction`. They are not turns — `run()` and turn lifecycle hooks do not fire. If `onAction` returns a `StreamTextResult`, the response is auto-piped to the frontend.
+Send a custom action to the agent, outside `useChat`. Actions wake the agent from suspension and fire `onAction`. An action that returns `chat.turn()` is followed by a turn; its answer arrives on the returned stream, which the caller must read. From a `useChat` app, send actions as requests instead (`sendMessage(undefined, { body: { action } })` or the `useChatActions` hook) so `useChat` renders the answer.
 
 ```ts
 transport.sendAction(chatId: string, action: unknown): Promise<ReadableStream<UIMessageChunk>>
@@ -869,6 +907,26 @@ Second argument to `chat.createStartSessionAction(taskId, options?)`. Controls h
 | `baseURL`        | `string \| (ctx: { endpoint: "sessions" \| "auth"; chatId: string }) => string`      | `apiClientManager.baseURL`    | API base URL. `endpoint` is `"sessions"` for `POST /api/v1/sessions` or `"auth"` for `POST /api/v1/auth/jwt/claims` (only fires when `tokenTTL` is set). |
 | `fetch`          | `(url: string, init: RequestInit, ctx: { endpoint: "sessions" \| "auth"; chatId: string }) => Promise<Response>` | —                             | Per-request fetch override. Use to route session-create through a trusted edge proxy so `basePayload.metadata` is rewritten before reaching `api.trigger.dev`. |
 
+## createLoadTranscriptAction options
+
+Second argument to `chat.createLoadTranscriptAction(storage, options?)`.
+
+| Option      | Type                     | Default                    | Description                                                                 |
+| ----------- | ------------------------ | -------------------------- | --------------------------------------------------------------------------- |
+| `limit`     | `number`                 | —                          | Page size when the caller passes none. Returns the most recent messages and a `nextCursor`. |
+| `apiClient` | `ApiClientConfiguration` | `apiClientManager` config  | Scope the read to a specific API client (secret key, base URL). The default storage reads through it. |
+
+## useLoadTranscript
+
+`useLoadTranscript(chatId, load, options?)` from `@trigger.dev/sdk/chat/react`. Loads a conversation through a `chat.createLoadTranscriptAction` action, for rendering before the chat connects. Re-runs when `chatId` changes.
+
+| Option      | Type                   | Description                                                                                  |
+| ----------- | ---------------------- | -------------------------------------------------------------------------------------------- |
+| `transport` | `TriggerChatTransport` | Seed the transport's resume cursor for this chat from the transcript, once it knows the session. |
+| `limit`     | `number`               | Page size passed to the action.                                                              |
+
+Returns `{ messages, isLoading, error, nextCursor }`. `nextCursor` is the id to pass as `before` to the action for the page before this one.
+
 ## useMultiTabChat
 
 React hook for multi-tab message coordination. Import from `@trigger.dev/sdk/chat/react`.
@@ -929,9 +987,10 @@ Tokens minted for `TriggerChatTransport` and `AgentChat` are session-scoped —
 | Scope | Grants |
 | --- | --- |
 | `read:sessions:<chatId>` | Subscribe to `.out`, HEAD probe the stream, retrieve the session row |
+| `read:sessions:<chatId>:out` | Subscribe to `.out` and HEAD probe the stream only. Use this when the browser needs nothing but the response stream. |
 | `write:sessions:<chatId>` | Append to `.in`, close the session, end-and-continue, update metadata |
 
-Tokens are produced by `auth.createPublicToken({ scopes: { read: { sessions: chatId }, write: { sessions: chatId } } })` (used by the customer's `accessToken` server action) or returned automatically from `chat.createStartSessionAction` / `POST /api/v1/sessions`. Either form authorizes both URL forms (`/sessions/{chatId}/...` and `/sessions/session_*/...`) on every read and write route.
+Reading `.in` requires a secret key, so no browser token can replay what clients sent. Tokens are produced by `auth.createPublicToken({ scopes: { read: { sessions: chatId }, write: { sessions: chatId } } })` (used by the customer's `accessToken` server action) or returned automatically from `chat.createStartSessionAction` / `POST /api/v1/sessions`. Either form authorizes both URL forms (`/sessions/{chatId}/...` and `/sessions/session_*/...`) on every read and write route.
 
 ## Related
 

package/docs/ai-chat/sessions.mdx

@@ -111,7 +111,7 @@ const { id, runId, publicAccessToken, isCached } = await sessions.start({
 | `type` | `string` | Free-form discriminator. `chat.agent` uses `"chat.agent"`. |
 | `externalId` | `string?` | Your stable identity. Cannot start with `session_` (reserved). |
 | `taskIdentifier` | `string` | Task this session triggers runs against. |
-| `triggerConfig` | `SessionTriggerConfig` | Trigger options applied to every run: `tags` (up to 10, same as [run tags](/tags); the chat helpers such as `chat.createStartSessionAction` and `AgentChat` add a `chat:{chatId}` tag themselves, which uses one slot. Direct `sessions.start` callers get all 10 and must add any chat tag themselves), `queue`, `machine`, `maxAttempts`, `idleTimeoutInSeconds`, `basePayload`. |
+| `triggerConfig` | `SessionTriggerConfig` | Trigger options applied to every run: `tags` (up to 10, same as [run tags](/tags); the chat helpers such as `chat.createStartSessionAction` and `AgentChat` add a `chat:{chatId}` tag themselves, which uses one slot. Direct `sessions.start` callers get all 10 and must add any chat tag themselves), `queue`, `machine`, `maxAttempts`, `maxDuration`, `region`, `idleTimeoutInSeconds`, `basePayload`, and the version pins `lockToVersion` / [`externalDeploymentId`](/deployment/version-skew-protection#chat-sessions). |
 | `tags` | `string[]?` | Up to 10 tags on the Session row (separate from `triggerConfig.tags`). |
 | `metadata` | `Record<string, unknown>?` | Arbitrary JSON. |
 | `expiresAt` | `Date?` | Hard retention deadline. |
@@ -146,6 +146,11 @@ Mark a Session as closed. Terminal and idempotent. The optional `reason` is stor
 await sessions.close(chatId, { reason: "user signed out" });
 ```
 
+Closing tells a live run too: the close lands on the session's input channel, so an idle or suspended agent exits its loop on the next wake rather than waiting out its idle timeout. After it lands, appends to `.in` are refused with HTTP 409 and `code: "session_closed"`.
+
+To close from inside the agent instead, call [`chat.close()`](/ai-chat/backend#ending-the-conversation). It writes a terminal record to the response stream so the browser learns the reason, then closes the row.
+
+
 ### `sessions.list(options?, requestOptions?)`
 
 Cursor-paginated list of Sessions in the current environment. Returns a `CursorPagePromise` you can iterate with `for await`.

package/docs/ai-chat/side-channels.mdx

@@ -138,7 +138,7 @@ A side channel's streams are bounded by the same retention as the rest of your r
 
 ## Auth
 
-A side channel is covered by the session's public access token: a token scoped to `read:sessions:{id}` / `write:sessions:{id}` grants every channel of that session. Mint a narrower token scoped to a single channel with `read:sessions:{id}:channels:{name}`. Writing a channel's `.out` requires secret-key auth (only the agent run), so a browser cannot forge frames; `.in` is writable with the session token. See [Realtime auth](/realtime/auth).
+A side channel is covered by the session's public access token: a token scoped to `read:sessions:{id}` / `write:sessions:{id}` grants every channel of that session. Mint a narrower token scoped to a single channel with `read:sessions:{id}:channels:{name}`, or to one direction of it with `read:sessions:{id}:channels:{name}:out`. Writing a channel's `.out` requires secret-key auth (only the agent run), so a browser cannot forge frames; `.in` is writable with the session token. See [Realtime auth](/realtime/auth).
 
 ### Scope tokens to the channel, not the whole session
 

package/docs/ai-chat/testing.mdx

@@ -203,7 +203,7 @@ Equivalent to the frontend's `useChat().regenerate()` — replays a turn with th
 
 ### sendAction
 
-Routes a payload through `actionSchema` + `onAction`. Actions are not turns: only `hydrateMessages` and `onAction` fire on the agent side — no turn lifecycle hooks, no `run()`. The returned `turn.rawChunks` contains whatever `onAction` produced (a streamed model response if it returned a `StreamTextResult`, otherwise just `trigger:turn-complete`):
+Routes a payload through `actionSchema` + `onAction`. An action is a state edit: only `hydrateMessages` and `onAction` fire, unless `onAction` returns `chat.turn()`, in which case a turn runs on the edited history and the returned `turn.rawChunks` carries that turn's answer.
 
 ```ts
 const turn = await harness.sendAction({ type: "undo" });
@@ -634,6 +634,7 @@ The harness's initial wire payload depends on `mode`:
 | `sendHandover({ partialAssistantMessage, isFinal?, messageId? })` | Dispatch a `handover` signal — only meaningful when started with `mode: "handover-prepare"`. The agent picks up partial assistant messages and continues the turn. |
 | `sendHandoverSkip()`                  | Dispatch a `handover-skip` signal — only meaningful when started with `mode: "handover-prepare"`. The agent exits cleanly without firing turn hooks. |
 | `sendAction(action)`                  | Route a custom action through `actionSchema` + `onAction`.                                             |
+| `sendPendingMessage(message)`         | Append a user message mid-turn without waiting for a turn to complete, so it reaches the running turn as a steering message. Resolves once the record has landed on `session.in`. |
 | `sendStop(message?)`                  | Fire a stop signal. Does not wait for the turn — the run's `signal.aborted` becomes `true`.            |
 | `seedSnapshot(snapshot)`              | Pre-seed the snapshot read for the next boot. Effective on the next run boot only.                     |
 | `seedSessionOutTail(chunks?)`         | Pre-seed `session.out` chunks for the next boot's replay. Reduces to settled assistant turns.          |

package/docs/ai-chat/tools.mdx

@@ -8,7 +8,7 @@ description: "Declare tools on chat.agent so toModelOutput survives across turns
 
 ```ts
 import { chat } from "@trigger.dev/sdk/ai";
-import { streamText, stepCountIs, tool } from "ai";
+import { stepCountIs, tool } from "ai";
 import { anthropic } from "@ai-sdk/anthropic";
 import { z } from "zod";
 
@@ -23,9 +23,9 @@ const tools = {
 export const myChat = chat.agent({
   id: "my-chat",
   tools, // ← declare here
-  run: async ({ messages, tools, signal }) =>
+  run: async ({ messages, tools, signal, streamText }) =>
     streamText({
-      ...chat.toStreamTextOptions({ tools }), // ← the same set, handed back on the payload
+      tools,
       model: anthropic("claude-sonnet-4-5"),
       messages,
       abortSignal: signal,
@@ -46,10 +46,15 @@ There are three places a tool set shows up. Declare once, reuse:
 | Surface | What it's for |
 | --- | --- |
 | `chat.agent({ tools })` | Re-applies `toModelOutput` on prior-turn history; hands the set back typed on the `run()` payload. |
-| `chat.toStreamTextOptions({ tools })` | Detects which tool calls need [HITL approval](/ai-chat/patterns/human-in-the-loop) (`needsApproval`) and merges any auto-injected [skill](/ai-chat/patterns/skills) tools. |
-| `streamText({ tools })` | What the model actually calls. `chat.toStreamTextOptions({ tools })` already sets this, so spread it instead of passing `tools` twice. |
+| `streamText({ tools })` on the `run` argument's `streamText` | What the model actually calls. Detects which calls need [HITL approval](/ai-chat/patterns/human-in-the-loop) (`needsApproval`) and merges the auto-injected [skill](/ai-chat/patterns/skills) tools on top. Naming `tools` replaces the config set for that call, so you can narrow it; omitting `tools` falls back to the config set. |
+| `chat.toStreamTextOptions({ tools })` | The same job by hand, for a [custom agent](#manual-turn-loops-chatcustomagent), which has no `run` argument. |
 
-The canonical pattern: declare `tools` on the config, read them back from the `run()` payload, and pass that to `chat.toStreamTextOptions({ tools })`. One declaration flows everywhere.
+The canonical pattern: declare `tools` on the config, read them back from the `run()` payload, and pass that set to the `streamText` the payload also carries.
+
+```ts
+run: async ({ messages, tools, signal, streamText }) =>
+  streamText({ model, messages, tools, abortSignal: signal }),
+```
 
 <Tip>
   Conversion only reads each tool's `inputSchema` and `toModelOutput`, never `execute`. If you keep heavy `execute` dependencies out of a module (for bundle reasons), you can declare a lightweight schema-only tool map on the config and add the executes where you call `streamText`.
@@ -80,9 +85,9 @@ const tools = {
 export const chartChat = chat.agent({
   id: "chart-chat",
   tools, // ← without this, the image is "remembered" on turn 1 and gone from turn 2
-  run: async ({ messages, tools, signal }) =>
+  run: async ({ messages, tools, signal, streamText }) =>
     streamText({
-      ...chat.toStreamTextOptions({ tools }),
+      tools,
       model: anthropic("claude-sonnet-4-5"),
       messages,
       abortSignal: signal,
@@ -104,9 +109,9 @@ export const myChat = chat
       searchDocs,
       ...(clientData?.plan === "pro" ? { deepResearch } : {}),
     }),
-    run: async ({ messages, tools, signal }) =>
+    run: async ({ messages, tools, signal, streamText }) =>
       streamText({
-        ...chat.toStreamTextOptions({ tools }),
+        tools,
         model: anthropic("claude-sonnet-4-5"),
         messages,
         abortSignal: signal,
@@ -131,10 +136,10 @@ The resolved set is what lands on the `run()` payload's `tools`.
 The `run()` payload's `tools` is typed to whatever you declared, so you can pass it straight through without re-importing the map:
 
 ```ts
-run: async ({ messages, tools, signal }) => {
+run: async ({ messages, tools, signal, streamText }) => {
   // `tools` is typed as your tool set, not a broad `ToolSet`
   return streamText({
-    ...chat.toStreamTextOptions({ tools }),
+    tools,
     model: anthropic("claude-sonnet-4-5"),
     messages,
     abortSignal: signal,
@@ -160,7 +165,7 @@ This is shorthand for `UIMessage<unknown, UIDataTypes, InferUITools<typeof tools
 
 ## Skills
 
-[Agent skills](/ai-chat/patterns/skills) are auto-injected as tools (`loadSkill`, `readFile`, `bash`) by `chat.toStreamTextOptions()`. They're separate from your config `tools`: declare your own tools on the config (so their `toModelOutput` survives across turns), and let `toStreamTextOptions` merge the skill tools on top at call time. Skill tools don't define `toModelOutput`, so they don't need to be on the config.
+[Agent skills](/ai-chat/patterns/skills) are auto-injected as tools (`loadSkill`, `readFile`, `bash`) by the managed `streamText`, or by `chat.toStreamTextOptions()` if you build the options yourself. They're separate from your config `tools`: declare your own tools on the config (so their `toModelOutput` survives across turns), and the merge happens at call time. Skill tools don't define `toModelOutput`, so they don't need to be on the config.
 
 ## Manual turn loops (`chat.customAgent`)