@trigger.dev/sdk 4.6.3 → 4.7.0

package/docs/ai-chat/patterns/version-upgrades.mdx

@@ -10,7 +10,7 @@ Chat agent runs are pinned to the worker version they started on. When you deplo
 
 <Note>
   If your sessions are pinned by [version skew
-  protection](/deployment/version-skew-protection#chat-sessions), you do not need this page to move a
+  protection](/deployment/atomic-deployment#chat-sessions), you do not need this page to move a
   conversation onto a new deployment. A pinned session follows its pin on its own: when the stored
   `externalDeploymentId` stops naming the deployment a run is on, the agent hands over at the next
   turn boundary. Set [`versionSkew: "hold"`](#staying-put) to turn that off for one agent.
@@ -32,7 +32,7 @@ The new run lives on the **same Session** as the old one. `chatId` is the durabl
 
 ### What "the latest deployment" means
 
-The handoff clears the session's [external deployment id](/deployment/version-skew-protection#chat-sessions) so the new run can land on the current version — re-applying the pin the agent just rejected would make the upgrade impossible. The cleared pin is persisted on the session, so the next continuation doesn't fall back to it either.
+The handoff clears the session's [external deployment id](/deployment/atomic-deployment#chat-sessions) so the new run can land on the current version — re-applying the pin the agent just rejected would make the upgrade impossible. The cleared pin is persisted on the session, so the next continuation doesn't fall back to it either.
 
 To move to a specific deployment rather than to whatever is current, name it:
 
@@ -220,7 +220,7 @@ Two cases never hand over automatically, whatever `versionSkew` says:
   turn boundary — never mid-turn. If the pin names a deployment that hasn't landed yet, the successor
   parks: your messages stay durable, and the transport emits `run-pending-version` with
   `source: "upgrade"` so you can say so in the UI. See [parked
-  chats](/deployment/version-skew-protection#chat-sessions).
+  chats](/deployment/atomic-deployment#chat-sessions).
 </Note>
 
 ## Custom agents
@@ -254,7 +254,7 @@ Both are graceful exits. [`onRecoveryBoot`](/ai-chat/patterns/recovery-boot) doe
 
 ## See also
 
-- [Version skew protection](/deployment/version-skew-protection#chat-sessions) — pin a session to the deployment matching the app build that started it
+- [Version skew protection](/deployment/atomic-deployment#chat-sessions) — pin a session to the deployment matching the app build that started it
 - [Lifecycle hooks](/ai-chat/lifecycle-hooks) — where `onTurnStart` and `onChatResume` fit in the turn cycle
 - [Recovery boot](/ai-chat/patterns/recovery-boot) — the sibling hook for mid-stream interruptions (does NOT fire on `requestUpgrade`)
 - [Database persistence](/ai-chat/patterns/database-persistence) — how continuations interact with session state

package/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.
 
-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.
+Use the `streamText` passed to your agent's `run` callback. It wires up pending-message injection automatically. If you import `streamText` directly from `ai`, spread `chat.toStreamTextOptions()` into its options to connect injection.
 
 ## How it works
 
@@ -30,20 +30,32 @@ Add `pendingMessages` to your `chat.agent` configuration:
 
 ```ts
 import { chat } from "@trigger.dev/sdk/ai";
-import { stepCountIs } from "ai";
+import { stepCountIs, tool } from "ai";
 import { anthropic } from "@ai-sdk/anthropic";
+import { z } from "zod";
+import { setTimeout } from "node:timers/promises";
 
 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, streamText }) => {
     return streamText({
+      model: anthropic("claude-sonnet-4-5"),
       messages,
-      tools: { /* ... */ },
+      tools: {
+        inspectDocument: tool({
+          description: "Inspect a document before summarizing it.",
+          inputSchema: z.object({ topic: z.string() }),
+          execute: async ({ topic }, { abortSignal }) => {
+            // Leave time to send a steering message in this example.
+            await setTimeout(10_000, undefined, { signal: abortSignal });
+            return { topic, findings: "The document describes a chat application." };
+          },
+        }),
+      },
       abortSignal: signal,
       stopWhen: stepCountIs(15),
     });
@@ -51,7 +63,9 @@ export const myChat = chat.agent({
 });
 ```
 
-The `prepareStep` for injection is automatically included when you spread `chat.toStreamTextOptions()`. If you provide your own `prepareStep` after the spread, it overrides the auto-injected one.
+The managed `streamText` composes your `prepareStep` callback after its own. You can add step-specific settings without disconnecting steering. With the manual `chat.toStreamTextOptions()` spread, a later `prepareStep` property replaces the spread's callback.
+
+To try it, ask the agent to inspect a document and summarize it in English. While the tool runs, send a steering message asking for French. The next model step receives that instruction, and the stream includes `data-pending-message-injected`.
 
 ### Options
 

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

@@ -1,7 +1,7 @@
 ---
 title: "Quick Start"
 sidebarTitle: "Quick Start"
-description: "Get a working AI agent in 3 steps — define an agent, generate a token, and wire up the frontend."
+description: "Define an agent, authorize chat sessions on your server, and stream responses into a React frontend."
 ---
 
 These steps assume you already have a Trigger.dev project with the SDK installed and the CLI authenticated — if you don't, follow [Manual setup](/manual-setup) (or `npx trigger.dev@latest init` in an existing project) first. You should be able to run `pnpm exec trigger dev` from your project root before continuing.
@@ -21,9 +21,6 @@ The chat surface works with Vercel AI SDK **v5, v6, or v7**; install whichever m
 
     export const myChat = chat.agent({
       id: "my-chat",
-      // `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({
           model: anthropic("claude-sonnet-4-5"),
@@ -36,10 +33,9 @@ The chat surface works with Vercel AI SDK **v5, v6, or v7**; install whichever m
     ```
 
     <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.
+      The `streamText` passed to `run` connects compaction, steering, background
+      injection, and telemetry. If you use an imported `streamText` from `ai`,
+      spread `chat.toStreamTextOptions()` into its options to connect those features.
     </Note>
 
     <Tip>
@@ -56,15 +52,18 @@ The chat surface works with Vercel AI SDK **v5, v6, or v7**; install whichever m
 
     import { auth } from "@trigger.dev/sdk";
     import { chat } from "@trigger.dev/sdk/ai";
+    import { requireChatOwner } from "@/lib/chat-access";
 
-    // Creates the Session row + triggers the first run, returns the
-    // session PAT. Idempotent on (env, chatId) so concurrent calls
-    // converge to the same session.
-    export const startChatSession = chat.createStartSessionAction("my-chat");
+    const startSession = chat.createStartSessionAction("my-chat");
 
-    // Pure mint — fresh session-scoped PAT for an existing session.
-    // The transport calls this on 401/403 to refresh.
+    export async function startChatSession({ chatId }: { chatId: string }) {
+      await requireChatOwner(chatId);
+      return startSession({ chatId });
+    }
+
+    // The transport calls this on 401/403 to refresh the session token.
     export async function mintChatAccessToken(chatId: string) {
+      await requireChatOwner(chatId);
       return auth.createPublicToken({
         scopes: {
           read: { sessions: chatId },
@@ -75,7 +74,9 @@ The chat surface works with Vercel AI SDK **v5, v6, or v7**; install whichever m
     }
     ```
 
-    The browser never holds your environment's secret key — both helpers run on your server, where customer-side authorization (per-user, per-plan, etc.) lives alongside any DB writes you want to pair with session creation.
+    `requireChatOwner` is your application helper: authenticate the request, load the chat by ID and owner, and throw if it doesn't belong to that user. Create the chat record on your server before rendering the frontend, and pass its ID into `Chat`. Check ownership in both actions, including token refresh.
+
+    Set `TRIGGER_SECRET_KEY` and your model provider key in the server and worker environments. Keep both keys out of the browser.
 
   </Step>
 
@@ -93,15 +94,14 @@ The chat surface works with Vercel AI SDK **v5, v6, or v7**; install whichever m
     import type { myChat } from "@/trigger/chat";
     import { mintChatAccessToken, startChatSession } from "@/app/actions";
 
-    export function Chat() {
+    export function Chat({ chatId }: { chatId: string }) {
       const transport = useTriggerChatTransport<typeof myChat>({
         task: "my-chat",
         accessToken: ({ chatId }) => mintChatAccessToken(chatId),
-        startSession: ({ chatId, clientData }) =>
-      startChatSession({ chatId, clientData }),
+        startSession: ({ chatId }) => startChatSession({ chatId }),
       });
 
-      const { messages, sendMessage, stop, status } = useChat({ transport });
+      const { messages, sendMessage, stop, status, error } = useChat({ id: chatId, transport });
       const [input, setInput] = useState("");
 
       return (
@@ -115,6 +115,8 @@ The chat surface works with Vercel AI SDK **v5, v6, or v7**; install whichever m
             </div>
           ))}
 
+          {error && <p role="alert">{error.message}</p>}
+
           <form
             onSubmit={(e) => {
               e.preventDefault();
@@ -129,7 +131,7 @@ The chat surface works with Vercel AI SDK **v5, v6, or v7**; install whichever m
               onChange={(e) => setInput(e.target.value)}
               placeholder="Type a message..."
             />
-            <button type="submit" disabled={status === "streaming"}>
+            <button type="submit" disabled={status === "streaming" || status === "submitted"}>
               Send
             </button>
             {status === "streaming" && (
@@ -146,6 +148,10 @@ The chat surface works with Vercel AI SDK **v5, v6, or v7**; install whichever m
   </Step>
 </Steps>
 
+## Try it
+
+Run your frontend and `pnpm exec trigger dev`, then send a message. You should see an assistant response stream into the page and a run in your project's dashboard. If session creation fails, check ownership and the server's `TRIGGER_SECRET_KEY`. If the run starts but the model fails, check the worker's provider key and run logs.
+
 ## Next steps
 
 - [Backend](/ai-chat/backend) — Lifecycle hooks, persistence, session iterator, raw task primitives

package/docs/ai-chat/reference.mdx

@@ -698,7 +698,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). |
+| `run-pending-version` | `source` | The chat's run is parked waiting for the deployment carrying its external deployment id ([version skew protection](/deployment/atomic-deployment#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. |
@@ -836,10 +836,28 @@ See [Stop generation](/ai-chat/frontend#stop-generation) for full details.
 
 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>>
+```typescript
+transport.sendAction(
+  chatId: string,
+  action: unknown,
+  options?: ChatActionOptions
+): Promise<ReadableStream<UIMessageChunk>>
 ```
 
+`ChatActionOptions` and `ChatActionSettlement` are exported from `@trigger.dev/sdk/chat`.
+
+| Option | Type | Description |
+| --- | --- | --- |
+| `abortSignal` | `AbortSignal` | Cancel the action's response subscription and send a stop signal for an outstanding turn. |
+| `metadata` | `Record<string, unknown>` | Per-action metadata merged over the transport's `clientData`. |
+| `onSettled` | `(settlement: ChatActionSettlement) => void` | Called at most once when this subscription accepts a turn-complete record confirming the action's input was processed. |
+
+`onSettled` receives `{ inputSeq, sessionInEventId, lastEventId? }`: the action's input append sequence, the committed input cursor, and the output cursor of the completion record. It runs before the returned stream closes, or continues in watch mode. Settlement confirms input processing, not application-level success; read the response chunks for the action's result. Synchronous callback exceptions do not interrupt the stream.
+
+<Note>
+The callback does not run after cancellation, stream closure without a matching completion, missing or invalid cursors, or an error because a previous stop caused the action's output to be discarded. In that last case, the action's own completion can arrive while its response stream still throws an output-lost error. A missing callback does not prove the action was unprocessed: reconcile persisted state or make the action idempotent before retrying.
+</Note>
+
 For managed `chat.agent()` tasks, the action payload is validated against the agent's `actionSchema` on the backend. Raw `chat.customAgent()` tasks receive it as `unknown` and must validate it themselves.
 
 ```tsx

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`, `maxDuration`, `region`, `idleTimeoutInSeconds`, `basePayload`, and the version pins `lockToVersion` / [`externalDeploymentId`](/deployment/version-skew-protection#chat-sessions). |
+| `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/atomic-deployment#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. |

package/docs/ai-chat/testing.mdx

@@ -73,11 +73,11 @@ describe("myChatAgent", () => {
 });
 ```
 
-The agent reads the mock model from `clientData`:
+This test-only agent reads the mock model from `clientData`. Keep this injection point in your test fixture; select production models on the server.
 
 ```ts trigger/my-chat.ts
 import { chat } from "@trigger.dev/sdk/ai";
-import { streamText, type LanguageModel } from "ai";
+import { stepCountIs, type LanguageModel } from "ai";
 import { z } from "zod";
 
 type ClientData = { model: LanguageModel };
@@ -90,7 +90,7 @@ export const myChatAgent = chat
   })
   .agent({
     id: "my-chat",
-    run: async ({ messages, clientData, signal }) => {
+    run: async ({ messages, clientData, signal, streamText }) => {
       return streamText({
         model: clientData?.model ?? "openai/gpt-4o-mini",
         messages,
@@ -159,7 +159,7 @@ export const agent = chat
   .withClientData({ schema: z.custom<ClientData>() })
   .agent({
     id: "agent",
-    run: async ({ messages, clientData, signal }) => {
+    run: async ({ messages, clientData, signal, streamText }) => {
       return streamText({
         model: clientData?.model ?? anthropic("claude-haiku-4-5"),
         messages,
@@ -677,3 +677,15 @@ await runInMockTaskContext(
 - **Single agent per process.** The resource catalog is process-global; tests within a file are sequential by default. If you parallelize across files, vitest runs each file in its own worker, which avoids registry collisions.
 - **Time-sensitive hooks.** `onTurnComplete` runs *after* the `turn-complete` chunk is written, so `sendMessage()` resolves before that hook finishes. Add a brief `await new Promise((r) => setTimeout(r, 20))` if you need to assert on hook side-effects.
 - **No real LLM.** The harness does not call providers — you must inject `MockLanguageModelV3` (or another mock) yourself.
+
+## Check the deployed behavior
+
+The harness checks your agent logic without a running platform. Also exercise the transport against a development or staging environment with a real model:
+
+- Send a message, reload during a tool call, and check that the conversation resumes without duplicate message IDs.
+- Send a pending message during a slow tool. Test both injection and deferral to the next turn.
+- Interrupt the model stream after some text arrives. Check the error, partial transcript, and a successful next turn.
+- Stop a resumed response and check `stopped` in `onTurnComplete`.
+- Try reading a chat and minting its token as another user. Both requests should fail before calling the SDK.
+
+For custom storage, test against your actual adapter. Include pagination boundaries, repeated saves, partial responses, and branch isolation. Development workers don't exercise deployed-worker checkpoint and restore; verify that separately if your application relies on it.