@trigger.dev/sdk 0.0.0-prerelease-20260909071038 → 0.0.0-prerelease-streamfix-20260909094302

package/docs/ai-chat/reference.mdx

@@ -44,19 +44,14 @@ 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) |
-| `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) |
+| `hydrateMessages`             | `(event: HydrateMessagesEvent) => UIMessage[] \| Promise<UIMessage[]>` | —                 | Load message history from backend, replacing the linear accumulator. 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<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) |
+| `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) |
 | `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). |
@@ -103,10 +98,9 @@ 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" \| "action-turn"` | What triggered the request; `"action-turn"` is a turn requested by `chat.turn()` |
+| `trigger`      | `"submit-message" \| "regenerate-message"` | What triggered the request                                           |
 | `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) |
@@ -219,38 +213,9 @@ 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). `hydrateMessages` is deprecated; `LoadContextEvent`, passed to a storage's `loadContext`, has the same shape.
+Passed to the `hydrateMessages` callback. See [hydrateMessages](/ai-chat/lifecycle-hooks#hydratemessages).
 
 | Field              | Type                                                  | Description                                               |
 | ------------------ | ----------------------------------------------------- | --------------------------------------------------------- |
@@ -399,8 +364,8 @@ Passed to `compactUIMessages` and `compactModelMessages` callbacks.
 | Field           | Type                 | Description                                          |
 | --------------- | -------------------- | ---------------------------------------------------- |
 | `summary`       | `string`             | The generated summary text                           |
-| `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) |
+| `uiMessages`    | `UIMessage[]`        | Current UI messages (full conversation)              |
+| `modelMessages` | `ModelMessage[]`     | Current model messages (full conversation)           |
 | `chatId`        | `string`             | Chat session ID                                      |
 | `turn`          | `number`             | Current turn (0-indexed)                             |
 | `clientData`    | `unknown`            | Custom data from the frontend                        |
@@ -525,9 +490,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, externalDeploymentId) 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) 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 (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.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 namespace
 
@@ -544,10 +509,8 @@ 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)                                                                                |
@@ -696,7 +659,6 @@ 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. |
@@ -832,7 +794,7 @@ See [Stop generation](/ai-chat/frontend#stop-generation) for full details.
 
 ### transport.sendAction()
 
-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.
+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.
 
 ```ts
 transport.sendAction(chatId: string, action: unknown): Promise<ReadableStream<UIMessageChunk>>
@@ -907,26 +869,6 @@ 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`.

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`, `idleTimeoutInSeconds`, `basePayload`. |
 | `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,11 +146,6 @@ 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/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`. 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.
+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`):
 
 ```ts
 const turn = await harness.sendAction({ type: "undo" });
@@ -634,7 +634,6 @@ 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 { stepCountIs, tool } from "ai";
+import { streamText, 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, streamText }) =>
+  run: async ({ messages, tools, signal }) =>
     streamText({
-      tools,
+      ...chat.toStreamTextOptions({ tools }), // ← the same set, handed back on the payload
       model: anthropic("claude-sonnet-4-5"),
       messages,
       abortSignal: signal,
@@ -46,15 +46,10 @@ 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. |
-| `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. |
+| `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. |
 
-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 }),
-```
+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.
 
 <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`.
@@ -85,9 +80,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, streamText }) =>
+  run: async ({ messages, tools, signal }) =>
     streamText({
-      tools,
+      ...chat.toStreamTextOptions({ tools }),
       model: anthropic("claude-sonnet-4-5"),
       messages,
       abortSignal: signal,
@@ -109,9 +104,9 @@ export const myChat = chat
       searchDocs,
       ...(clientData?.plan === "pro" ? { deepResearch } : {}),
     }),
-    run: async ({ messages, tools, signal, streamText }) =>
+    run: async ({ messages, tools, signal }) =>
       streamText({
-        tools,
+        ...chat.toStreamTextOptions({ tools }),
         model: anthropic("claude-sonnet-4-5"),
         messages,
         abortSignal: signal,
@@ -136,10 +131,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, streamText }) => {
+run: async ({ messages, tools, signal }) => {
   // `tools` is typed as your tool set, not a broad `ToolSet`
   return streamText({
-    tools,
+    ...chat.toStreamTextOptions({ tools }),
     model: anthropic("claude-sonnet-4-5"),
     messages,
     abortSignal: signal,
@@ -165,7 +160,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 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.
+[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.
 
 ## Manual turn loops (`chat.customAgent`)
 

package/docs/ai-chat/upgrade-guide.mdx

@@ -298,8 +298,8 @@ and direct API consumers.
   fire at the same lifecycle points.
 - `onAction` is still defined the same way, but its semantics changed
   in the [May 6 prerelease](/ai-chat/changelog) — actions are no longer
-  turns. To answer after an action's edit, return `chat.turn()`; returning
-  a `StreamTextResult` is no longer supported.
+  turns, and `onAction` returning a `StreamTextResult` produces a model
+  response.
 - `chat.customAgent({...})` and the `chat.createSession(payload, ...)`
   helper for building a session loop manually inside a custom agent.
 - `chat.defer` (deferred work) and `chat.history` (imperative history

package/docs/apikeys.mdx

@@ -10,35 +10,17 @@ description: "Authenticate backend requests with environment-specific API keys."
   environment variable, never commit them to source control, and never expose them in frontend code.
 </Warning>
 
-## Create an API key
+## Find your API keys
 
-Create a separate named key for each service or integration that accesses Trigger.dev.
+Open your project in the dashboard, select an environment, and open the [**API keys**](https://cloud.trigger.dev/_/apikeys) page.
 
-API keys belong to one environment. A Development key cannot access Production, and a Production key cannot access Staging. Every team member has their own Development environment, so create local-development keys in your own environment.
+API keys belong to one environment. A Development key cannot access Production, and a Production key cannot access Staging.
 
 <Note>
-  Creating and revoking keys requires permission to manage API keys for the selected environment.
-  The dashboard disables these actions when your role does not have permission.
+  Every team member has their own Development environment and keys. Copy the Development key from
+  your own API keys page so local requests run against your machine.
 </Note>
 
-<Steps titleSize="h3">
-  <Step title="Open the API keys page">
-    Select the project and environment the integration needs to access, then open [**API keys**](https://cloud.trigger.dev/_/apikeys).
-  </Step>
-  <Step title="Create the key">
-    Click **New API key**, enter a descriptive name, and optionally set an expiration date. Names can
-    contain up to 64 characters.
-  </Step>
-  <Step title="Choose its access">
-    Select the narrowest access preset that supports the integration. For task-aware presets, choose
-    all tasks or up to 10 task identifiers.
-  </Step>
-  <Step title="Copy and store the secret">
-    Copy the key into your secret manager or backend environment. Trigger.dev shows the complete
-    value only once.
-  </Step>
-</Steps>
-
 ## Configure the SDK
 
 Set `TRIGGER_SECRET_KEY` in your backend environment. The SDK reads it automatically for operations such as triggering tasks and retrieving runs.
@@ -67,12 +49,38 @@ await tasks.trigger<typeof sendEmail>("send-email", {
 If you self-host Trigger.dev, set `TRIGGER_API_URL` or pass `baseURL` to `configure`:
 
 ```bash .env
-TRIGGER_SECRET_KEY="tr_prod_sk_…"
+TRIGGER_SECRET_KEY="tr_prod_…"
 TRIGGER_API_URL="https://trigger.example.com"
 ```
 
 The default API URL is `https://api.trigger.dev`.
 
+## Create a key
+
+Create a separate key for each service or integration that accesses Trigger.dev.
+
+<Note>
+  Creating and revoking keys requires permission to manage API keys for the selected environment.
+  The dashboard disables these actions when your role does not have permission.
+</Note>
+
+<Steps titleSize="h3">
+  <Step title="Open the API keys page">
+    Select the project and environment the integration needs to access, then open [**API keys**](https://cloud.trigger.dev/_/apikeys).
+  </Step>
+  <Step title="Create the key">
+    Click **New API key**, enter a descriptive name, and optionally set an expiration date. Names can
+    contain up to 64 characters.
+  </Step>
+  <Step title="Choose its access">
+    Select an access preset. For task-aware presets, choose all tasks or up to 10 task identifiers.
+  </Step>
+  <Step title="Copy and store the secret">
+    Copy the key into your secret manager or backend environment. Trigger.dev shows the complete
+    value only once.
+  </Step>
+</Steps>
+
 ## Access presets
 
 Access presets define what a key can do. Some presets require a paid plan. The dashboard shows which presets your organization can use — see [pricing](https://trigger.dev/pricing).
@@ -116,18 +124,28 @@ Revoking a key takes effect immediately and cannot be reversed. Requests using t
 
 Removing a team member does not revoke keys they created. Review and revoke their keys separately when their access changes.
 
+## Root keys
+
+<Warning>
+  Root keys are legacy, and are likely to be deprecated in the future. We recommend against using them.
+</Warning>
+
+Each environment has a single legacy root key. It can be regenerated, which creates a new value immediately. The previous root key remains valid for 24 hours so you can update services without downtime, then stops authenticating.
+
+Public access tokens signed with the previous root key remain valid until the earlier of their own expiration and the end of the 24-hour grace period.
+
 ## Create public access tokens
 
 API keys can be used to create scoped [Public Access Tokens](/realtime/auth) using `auth.createPublicToken()`.
 
-Use `@trigger.dev/sdk` version 4.5.8 or later to create public tokens with environment API keys. Public tokens have the following restrictions:
+To do so with the newer non-root keys, you must use `@trigger.dev/sdk` version 4.5.8 or later. Creating public tokens with non-root keys has the following restrictions:
 
 - The token must request at least one scope.
 - Its scopes cannot exceed the key's access.
 - Its expiration cannot exceed 30 days.
 
 <Note>
-Revoking or expiring an API key does not revoke tokens it already created. Those tokens remain valid until their own expiration.
+Revoking or expiring an API key does not revoke tokens it already created. Those tokens remain valid until their own expiration, unless the environment's root key is regenerated.
 </Note>
 
 ## Target Preview and Development branches
@@ -145,7 +163,7 @@ The SDK sends the branch automatically. When calling the API directly, send the
 
 Self-hosted installations support multiple keys with **No restrictions**. The restricted access presets are available in Trigger.dev Cloud.
 
-Keep your instance and SDK current before creating keys. Calling a public-token API with a key on a server that does not support server-minted tokens returns an upgrade error. Upgrade the instance before creating public tokens with an environment API key.
+Keep your instance and SDK current before creating keys. Calling a public-token API with a key on a server that does not support server-minted tokens returns an upgrade error; use the root key until the server is upgraded.
 
 ## Security recommendations
 

package/docs/config/extensions/syncEnvVars.mdx

@@ -63,12 +63,6 @@ export default defineConfig({
 
 In this example we're using env vars from [Infisical](https://infisical.com).
 
-<Tip>
-  Infisical also offers a native [Secret Sync](/deploy-environment-variables#infisical-secret-sync)
-  that pushes secrets to Trigger.dev without a build extension or a redeploy. Use `syncEnvVars` when
-  you want to resolve secrets at deploy time in code, or for a service without a native sync.
-</Tip>
-
 ```ts trigger.config.ts
 import { defineConfig } from "@trigger.dev/sdk";
 import { syncEnvVars } from "@trigger.dev/build/extensions/core";

package/docs/deploy-environment-variables.mdx

@@ -184,35 +184,14 @@ For more information about the context object, see the [Context documentation](/
 
 ### Sync env vars from another service
 
-There are two ways to pull secrets from another service into Trigger.dev: a native **Secret Sync** (currently [Infisical](https://infisical.com)), or the `syncEnvVars` build extension for any other service.
-
-#### Infisical Secret Sync
-
-If your secrets live in [Infisical](https://infisical.com), sync them natively, without a build extension or a redeploy. You configure the sync in the Infisical dashboard, and it pushes secrets straight to your [Environment Variables page](#in-the-dashboard) in Trigger.dev. When a secret changes in Infisical the sync updates the matching variable, and your tasks pick up the new value on their next run.
-
-Set it up in Infisical in two steps:
-
-1. Add a **Trigger.dev App Connection** using a Trigger.dev Personal Access Token from your account settings. Self-hosted instances are supported.
-2. Create a **Secret Sync**: choose the connection, pick the target organization, project and environment (Production, Staging, Development, or Preview), and set the secret path to sync.
-
-Follow the [Trigger.dev Secret Sync guide](https://infisical.com/docs/integrations/secret-syncs/trigger-dev) in the Infisical docs for the full walkthrough.
-
-<Note>
-  A Secret Sync only overwrites the keys it manages, leaving variables you set manually untouched.
-  Synced variables are marked as [secret](#secret-environment-variables) by default, so they appear
-  redacted on the Environment Variables page.
-</Note>
-
-#### Using the `syncEnvVars` build extension
-
-For any other service, use our `syncEnvVars` build extension in your `trigger.config` file to resolve secrets at deploy time.
+You could use the SDK functions above but it's much easier to use our `syncEnvVars` build extension in your `trigger.config` file.
 
 <Note>
   To use the `syncEnvVars` build extension, you should first install the `@trigger.dev/build`
   package into your devDependencies.
 </Note>
 
-In this example we're using env vars from [Infisical](https://infisical.com), but you can adapt it to any secrets manager.
+In this example we're using env vars from [Infisical](https://infisical.com).
 
 ```ts trigger.config.ts
 import { defineConfig } from "@trigger.dev/sdk";

package/docs/deployment/overview.mdx

@@ -69,10 +69,14 @@ Now if you visit your Trigger.dev dashboard you should see the new version deplo
 
 ## Triggering deployed tasks
 
-Once you have deployed your tasks, open the API Keys page for the Production environment and create a named key with **Trigger only** access. Set the key as `TRIGGER_SECRET_KEY` in your backend environment. Tasks triggered with this key run against the deployed Production version:
+Once you have deployed your tasks, you can trigger tasks exactly the same way you did locally, but with the "PROD" API key:
+
+![Trigger.dev dashboard showing the API key](/deployment/api-key.png)
+
+Copy the API key from the dashboard and set the `TRIGGER_SECRET_KEY` environment variable, and then any tasks you trigger will run against the deployed version:
 
 ```txt .env
-TRIGGER_SECRET_KEY="tr_prod_sk_abc123"
+TRIGGER_SECRET_KEY="tr_prod_abc123"
 ```
 
 Now you can trigger your tasks:
@@ -176,10 +180,10 @@ This will create an entirely new version of your tasks for the `staging` environ
 
 ![Trigger.dev dashboard showing the staging environment](/deployment/staging-deploy.png)
 
-To trigger tasks against Staging, create a named key in the Staging environment with **Trigger only** access and set it as `TRIGGER_SECRET_KEY`:
+Now you can trigger tasks against the staging environment by setting the `TRIGGER_SECRET_KEY` environment variable to the staging API key:
 
 ```txt .env
-TRIGGER_SECRET_KEY="tr_stg_sk_abcd123"
+TRIGGER_SECRET_KEY="tr_stg_abcd123"
 ```
 
 For additional environments beyond `prod` and `staging`, you can use [preview branches](/deployment/preview-branches), which allow you to create isolated environments for each branch of your code.

package/docs/deployment/preview-branches.mdx

@@ -15,7 +15,7 @@ The process to use preview branches looks like this:
 
 1. Create a preview branch
 2. Deploy to the preview branch (1+ times)
-3. Create a named **Trigger only** API key in the Preview environment, then trigger runs using the key (`TRIGGER_SECRET_KEY`) and branch name (`TRIGGER_PREVIEW_BRANCH`).
+3. Trigger runs using your Preview API key (`TRIGGER_SECRET_KEY`) and the branch name (`TRIGGER_PREVIEW_BRANCH`).
 4. Archive the preview branch when the branch is done.
 
 There are two main ways to do this:
@@ -41,12 +41,12 @@ For full details see our [pricing page](https://trigger.dev/pricing).
 
 ## Triggering runs and using the SDK
 
-Create a named API key in the Preview environment and set it as `TRIGGER_SECRET_KEY`. Set `TRIGGER_PREVIEW_BRANCH` to select the branch that receives the runs.
+Before we talk about how to deploy to preview branches, one important thing to understand is that you must set the `TRIGGER_PREVIEW_BRANCH` environment variable as well as the `TRIGGER_SECRET_KEY` environment variable.
 
 When deploying to somewhere that supports `process.env` (like Node.js runtimes) you can just set the environment variables:
 
 ```bash
-TRIGGER_SECRET_KEY="tr_preview_sk_1234567890"
+TRIGGER_SECRET_KEY="tr_preview_1234567890"
 TRIGGER_PREVIEW_BRANCH="your-branch-name"
 ```
 
@@ -57,7 +57,7 @@ import { configure } from "@trigger.dev/sdk";
 import { myTask } from "./trigger/myTasks";
 
 configure({
-  secretKey: "tr_preview_sk_1234567890", // WARNING: Never actually hardcode your secret key like this
+  secretKey: "tr_preview_1234567890", // WARNING: Never actually hardcode your secret key like this
   previewBranch: "your-branch-name",
 });