@trigger.dev/sdk 4.5.15 → 4.6.0

package/docs/ai-chat/transcript-storage.mdx

@@ -0,0 +1,247 @@
+---
+title: "Transcript storage"
+sidebarTitle: "Transcript storage"
+description: "Where a chat.agent conversation is kept: the UIMessages the runtime saves, the platform default, reading history back, and bringing your own database through the TranscriptStorage adapter."
+---
+
+## Why a conversation needs a home
+
+A `chat.agent` conversation outlives a single run. One run answers many turns and survives the idle gaps between them, but a run does end eventually (a version upgrade, its turn limit, a crash), and the next message then boots a fresh run with nothing in memory (see [How it works](/ai-chat/how-it-works)). For that new run to answer in context, the conversation so far has to be read back from somewhere durable. The same store is what a page reload and the dashboard read to show history.
+
+That somewhere is a **transcript storage**. You get one by default with no setup: the platform keeps the conversation as a snapshot in object storage, the same blob the Sessions view in the dashboard renders. Bring your own when you want the conversation in your own database instead.
+
+## What gets saved
+
+The transcript is a list of **`UIMessage`s**, keyed by `chatId`. A `UIMessage` is the rich, renderable message the frontend works with: an `id`, a `role`, and an array of `parts` (text, reasoning, tool calls and their results, and any custom `data-*` parts). It is the same shape your React app holds and the same shape the dashboard renders, so what you store is exactly what a user sees.
+
+<Note>
+`UIMessage`s are not what the model reads. Each turn the runtime derives a `ModelMessage[]` from the transcript, the flattened `{ role, content }` form an LLM takes, and hands it to your `run()` as `messages`. The transcript storage never deals in `ModelMessage`s. It holds the UI messages; the model's view is derived from them.
+</Note>
+
+Keeping the UI shape is deliberate. It is lossless (a tool call and its result survive as parts), it is what renders, and the model's view can be rebuilt from it. Two things cannot be rebuilt from the messages alone, so the runtime hands them to the storage as well:
+
+- **`state`**: an opaque record for what the model saw that the transcript does not capture, a [compaction](/ai-chat/compaction) summary and [injected context](/ai-chat/background-injection). Store it as-is and give it back on load.
+- **cursors**: the stream positions the next run resumes from. Persist them opaquely; a storage never reads them.
+
+So a save is: the messages, a `state` blob, and two cursors. Nothing else.
+
+## The default storage
+
+Do nothing and you get the platform snapshot: the whole conversation written to object storage after each change, read back when a run continues. It is the blob the dashboard's Sessions view renders, and it needs no configuration.
+
+```ts
+import { chat } from "@trigger.dev/sdk/ai";
+import { anthropic } from "@ai-sdk/anthropic";
+
+export const myChat = chat.agent({
+  id: "my-chat",
+  run: async ({ messages, signal, streamText }) =>
+    streamText({ model: anthropic("claude-sonnet-4-5"), messages, abortSignal: signal }),
+});
+```
+
+The default rewrites the whole conversation on every turn. That is fine for most chats and costs one write. When it stops being fine, or when you want the conversation in a database you already run, you bring your own.
+
+## Bring your own storage
+
+Set `storage` on the agent to persist the conversation yourself:
+
+```ts
+import { chat } from "@trigger.dev/sdk/ai";
+import { anthropic } from "@ai-sdk/anthropic";
+import { myTranscriptStorage } from "./transcript-storage";
+
+export const myChat = chat.agent({
+  id: "my-chat",
+  storage: myTranscriptStorage,
+  run: async ({ messages, signal, streamText }) =>
+    streamText({ model: anthropic("claude-sonnet-4-5"), messages, abortSignal: signal }),
+});
+```
+
+Reasons to:
+
+- **Your database is the source of truth.** History lives next to the rest of your data, queryable, backed up, and deletable on your terms.
+- **Cheaper writes on long chats.** A row-per-message store writes only what changed on a turn instead of rewriting the whole conversation.
+- **Render history in one query** from your own tables, the same `load` the runtime uses.
+- **Own the model's context** for branching, trust boundaries, or rollback (see [Owning the model's context](#owning-the-models-context)).
+
+The runtime drives the storage. You never decide when to write, what a regenerate means for your rows, or how a crash mid-answer is recovered. Those decisions are the same for every backend, so they live in the runtime; your job is to store what it hands you and give it back.
+
+## The interface
+
+```ts
+type TranscriptStorage<TClientData = unknown> = {
+  load(
+    scope: { chatId: string; clientData: TClientData },
+    opts?: { limit?: number; before?: string }
+  ): Promise<{
+    messages: UIMessage[];
+    state: unknown | null;
+    cursors?: { lastOutEventId?: string; lastInEventId?: string };
+    nextCursor?: string;
+  }>;
+
+  save(
+    ctx: {
+      chatId: string;
+      clientData: TClientData;
+      turn: number;
+      trigger: "submit-message" | "regenerate-message" | "action";
+      runId: string;
+      ctx: TaskRunContext;
+    },
+    changeset: {
+      reason: "turn-start" | "turn-complete" | "turn-error" | "action" | "compaction" | "recovery";
+      changes: TranscriptChange[];
+      transcript: { entries: Array<{ id: string; final: boolean; message: UIMessage }>; state: unknown | null };
+      cursors?: { lastOutEventId?: string; lastInEventId?: string };
+    }
+  ): Promise<void>;
+
+  loadContext?(
+    scope: { chatId: string; clientData: TClientData },
+    event: LoadContextEvent
+  ): Promise<UIMessage[]>;
+};
+
+type TranscriptChange =
+  | { op: "put"; message: UIMessage; final?: boolean }
+  | { op: "remove"; id: string }
+  | { op: "truncateAfter"; afterId: string }
+  | { op: "state"; value: unknown | null };
+```
+
+`load` returns the conversation. `save` records a change to it. `loadContext` is optional and covered [below](#owning-the-models-context). All the types are exported from `@trigger.dev/sdk/ai`.
+
+`scope` is the tenant of a read: the `chatId` and the `clientData` your app passed. `ctx` on a save is the same plus the run it happened in. `clientData` is how the runtime hands you the tenant; use it to scope or authorize where your backend needs to.
+
+## What the runtime hands `save`
+
+A changeset carries the same save two ways, and a storage uses whichever suits its shape.
+
+`changes` is the ordered list of what changed since the last save. A row-per-message store applies them, as one transaction where the backend supports one:
+
+| Change | Meaning |
+| --- | --- |
+| `put` | Upsert by `message.id`. An unknown id appends at the end; a known id is replaced in place. `final` is `false` for a partial answer captured from a turn that failed or was stopped, and `true` otherwise. |
+| `remove` | Delete by id. A no-op for an unknown id. |
+| `truncateAfter` | Drop every message ordered after `afterId`. This is what an undo or a regenerate becomes. A no-op for an unknown id. |
+| `state` | Replace the runtime's opaque record; `null` clears it. |
+
+`transcript` is the whole conversation as it stands after those changes, `entries` plus `state`. A store that keeps the conversation as one document (object storage, a key-value store, a JSON column) writes it as-is and keeps no state of its own between saves. The default storage is exactly that: it serialises `transcript` and rewrites the blob.
+
+The changes are the intent, spelled out. A normal turn is two `put`s, the user's message and the assistant's answer, split across the turn's two saves. A steering message the user sent mid-turn is another `put` in the same changeset. An undo through `chat.history.slice(0, -2)` is one `truncateAfter`. A regenerate is a `truncateAfter` and a `put`. A tool approval that updates the assistant message in place is one `put` for that id. Messages are addressed by id; how you order rows is your concern.
+
+Every turn saves twice. The `turn-start` save carries the message being answered, before the model runs. The `turn-complete` save carries the answer. Both `put` the same user message id, and a `put` upserts, so a storage that applies changes in order needs no special handling for the repeat.
+
+The `turn-start` save is what makes a reload during an answer show the question that is being answered. It leaves `cursors` on the previous turn's position, because the answer's own cursor does not exist yet, so a reload mid-answer still resumes from the last completed turn rather than skipping chunks it never received.
+
+A few properties worth knowing:
+
+- The `turn-start` save runs alongside the model rather than before it, so it costs no time to first token. Nothing from the turn reaches the browser until it settles, which is what makes the question durable before the answer can render. A save that fails or runs long lets the answer through rather than stalling the conversation.
+- The `turn-complete` save happens after the turn's answer has reached the browser, so it never delays the response. The runtime awaits each `save` before the run suspends.
+- A `save` that throws is logged and the turn continues. The changes fold into the next changeset, and every change is idempotent, so a retried changeset converges on the same result.
+- A `load` that throws boots the run from the durable stream's recent tail rather than failing.
+
+## Reading the transcript
+
+`load` is the one read for every backend, the default included. Call it on your server, scoped to the signed-in user through `clientData`, and pass the result to the browser:
+
+```ts app/actions.ts
+"use server";
+import { chat, defaultStorage } from "@trigger.dev/sdk/ai";
+
+export const loadTranscript = chat.createLoadTranscriptAction(defaultStorage, { limit: 50 });
+```
+
+```tsx app/chat/[chatId]/ChatPage.tsx
+"use client";
+import { useLoadTranscript, useTriggerChatTransport } from "@trigger.dev/sdk/chat/react";
+import { loadTranscript } from "@/app/actions";
+
+export function ChatPage({ chatId }: { chatId: string }) {
+  const transport = useTriggerChatTransport({ task: "my-chat", accessToken, startSession });
+  const { messages, isLoading, nextCursor } = useLoadTranscript(chatId, loadTranscript, {
+    transport,
+  });
+  if (isLoading) return <Spinner />;
+  return <ChatView chatId={chatId} initialMessages={messages} transport={transport} />;
+}
+```
+
+<Warning>
+The action receives `chatId` from the browser, so authorize it before returning: check that the signed-in user owns this chat. `defaultStorage` loads purely by `chatId` and does no tenant check of its own, so an exported action with no authorization lets any authenticated user read any chat's transcript. A custom storage can enforce tenancy inside `load` using `clientData`, but the server action is still the place to reject a `chatId` the caller may not read.
+</Warning>
+
+`limit` returns the most recent messages and a `nextCursor`; pass it as `before` for the page before that one. With the default storage, a paged read is served by the platform, so a long conversation is not downloaded in full to render its last fifty messages. A paged read returns the transcript only: `state` is always `null`, because the model lane is not part of what a page renders, and the platform reads just the bytes holding that page rather than the whole conversation. The runtime reads the state separately when it restores context at boot. When you pass `transport` and it already knows the session, the hook seeds its resume cursor from the transcript, so the live subscription opens just past the persisted history instead of replaying it.
+
+Swap `defaultStorage` for your own storage and nothing else about the read changes.
+
+<Warning>
+The saved format changed in this release, and an older SDK cannot read it. Rolling a deployment back to a version from before this release means its runs will not find a readable transcript for conversations already saved by the newer one, and will continue from the live stream tail instead, so earlier history is lost for those conversations. Roll forward rather than back, or keep your own transcript storage.
+</Warning>
+
+The default storage is deliberately basic about long conversations. Once compaction has run, it keeps roughly the last hundred messages and drops the rest, so what it rewrites on each save stops growing. A conversation that never compacts is kept whole. If your app renders history further back than that, give the agent your own storage and keep the messages yourself.
+
+## Owning the model's context
+
+By default the model's context each turn is the transcript the runtime accumulated, converted to `ModelMessage`s. A storage that declares `loadContext` takes that over: the runtime calls it on every turn and action, with the messages the frontend sent and the transcript the runtime had, and uses the `UIMessage`s it returns as the conversation (converting them to `ModelMessage`s the same way). Reach for it when your database decides what the model sees, for branching conversations, a trust boundary where the browser's history is not to be believed, or a curated context window.
+
+```ts
+const storage: TranscriptStorage<{ userId: string }> = {
+  load: (scope, opts) => rows.load(scope, opts),
+  save: (ctx, changeset) => rows.save(ctx, changeset),
+  loadContext: async ({ chatId, clientData }, { incomingMessages }) => {
+    const branch = await rows.activeBranch(chatId, clientData.userId);
+    return [...branch, ...incomingMessages];
+  },
+};
+```
+
+`save` keeps receiving every change, and crash recovery keeps running. This is the replacement for the deprecated [`hydrateMessages`](/ai-chat/lifecycle-hooks#hydratemessages) hook; setting both `hydrateMessages` and `storage` on an agent is a startup error.
+
+## Writing your own storage
+
+The contract is small and the conformance suite checks it. Point the suite at a factory for your storage and run it under vitest or jest:
+
+```ts transcript-storage.test.ts
+import { runTranscriptStorageTests } from "@trigger.dev/sdk/ai/test";
+import { postgresTranscriptStorage } from "./transcript-storage";
+
+runTranscriptStorageTests(() => postgresTranscriptStorage(process.env.TEST_DATABASE_URL!));
+```
+
+The suite covers appends and in-place replacement, idempotent `remove` and `truncateAfter`, `state` round-trips, cursors, replaying the same changeset twice, paging, and chat isolation. `memoryTranscriptStorage()` is the reference implementation, and it is handy in your own tests to see exactly what the runtime hands a storage.
+
+A few things to get right:
+
+- Pick one view and stay with it. Apply `changes` if you store rows, write `transcript` if you store a document; don't mix them within one save.
+- `put` for a known id replaces the message in place; position and ordering don't change.
+- Order is the message's position in the transcript. A document store gets it from `transcript.entries`. A row store needs an order column set once, when a `put` first inserts an id, following the order the `put`s arrive in, and left unchanged when a later `put` replaces that id in place. Don't sort by a write timestamp: a replaced message has to keep its place, and a steering message sent mid-turn sorts before the answer it shaped even though its row is written later.
+- `truncateAfter` and `remove` are idempotent. Applying a changeset twice gives the same result as applying it once.
+- `load` with no options returns the whole conversation in order. With `limit`, return the most recent messages and a `nextCursor` (the id of the oldest returned message) when earlier messages exist.
+- Scope reads and writes by `clientData` where your backend enforces tenancy.
+
+## Guarantees and limits
+
+- Crash recovery of a half-written answer is runtime-owned in every configuration. It comes from the durable session stream, which no application database can reconstruct. A storage holds settled turns; the runtime overlays the recovered tail and hands it to `save` like any other change.
+- Bringing your own database does not remove platform custody. Session streams still hold message content for their retention window.
+- The default storage rewrites the whole conversation each turn. A row-per-message storage writes only what changed. That is the reason to plug in your own.
+
+## Migrating from hydrateMessages
+
+`hydrateMessages` keeps working with a one-time deprecation warning. Crash recovery runs for it, but the runtime does not write to your store on its behalf. The move, in short:
+
+1. Implement `TranscriptStorage` over your existing tables. The writes you did in hooks become `save`; the read your hook did becomes `load`. Add `loadContext` only if your database decides what the model sees each turn.
+2. Set `storage` on the agent and remove `hydrateMessages`. Setting both is an error.
+3. Delete the recovery, compaction and cursor code the runtime now owns, and run `runTranscriptStorageTests` against your implementation.
+
+The [migration guide](/ai-chat/migrating-from-hydrate-messages) walks through each step with code, and lists what to delete from each hook.
+
+## See also
+
+- [Persistence and replay](/ai-chat/patterns/persistence-and-replay): how the runtime rebuilds a conversation when a new run boots
+- [Database persistence](/ai-chat/patterns/database-persistence): the hook-based pattern and how it relates
+- [Actions](/ai-chat/actions#actions-and-persistence): what an undo or regenerate becomes in the changeset
+- [Compaction](/ai-chat/compaction): the summary the runtime keeps in `state`

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, and `onAction` returning a `StreamTextResult` produces a model
-  response.
+  turns. To answer after an action's edit, return `chat.turn()`; returning
+  a `StreamTextResult` is no longer supported.
 - `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,17 +10,35 @@ 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>
 
-## Find your API keys
+## Create an API key
 
-Open your project in the dashboard, select an environment, and open the [**API keys**](https://cloud.trigger.dev/_/apikeys) page.
+Create a separate named key for each service or integration that accesses Trigger.dev.
 
-API keys belong to one environment. A Development key cannot access Production, and a Production key cannot access Staging.
+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.
 
 <Note>
-  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.
+  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 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.
@@ -49,38 +67,12 @@ 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_…"
+TRIGGER_SECRET_KEY="tr_prod_sk_…"
 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).
@@ -124,28 +116,18 @@ 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()`.
 
-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:
+Use `@trigger.dev/sdk` version 4.5.8 or later to create public tokens with environment API keys. Public tokens have 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, unless the environment's root key is regenerated.
+Revoking or expiring an API key does not revoke tokens it already created. Those tokens remain valid until their own expiration.
 </Note>
 
 ## Target Preview and Development branches
@@ -163,7 +145,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; use the root key until the server is upgraded.
+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.
 
 ## Security recommendations
 

package/docs/config/extensions/custom.mdx

@@ -80,7 +80,7 @@ export default defineConfig({
     extensions: [
       {
         name: "my-extension",
-        externalsForTarget: async (target) => {
+        externalsForTarget: (target) => {
           return ["my-dependency"];
         },
       },
@@ -89,6 +89,19 @@ export default defineConfig({
 });
 ```
 
+### installedPackagesForTarget
+
+This tells build diagnostics which packages your extension installs into the deployed image for a given target, so warnings (like the one for packages loaded via `createRequire()`) don't fire for packages that will actually be available at runtime. The bundler ignores this hook, so declaring it never changes the build output. Only implement it if your extension installs packages; extensions without it are assumed to install none.
+
+```ts
+{
+  name: "my-extension",
+  installedPackagesForTarget: (target) => {
+    return target === "deploy" ? ["my-dependency"] : [];
+  },
+}
+```
+
 ### onBuildStart
 
 This hook runs before the build starts. It receives the `BuildContext` object as an argument.

package/docs/config/extensions/syncEnvVars.mdx

@@ -63,6 +63,12 @@ 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,14 +184,35 @@ For more information about the context object, see the [Context documentation](/
 
 ### Sync env vars from another service
 
-You could use the SDK functions above but it's much easier to use our `syncEnvVars` build extension in your `trigger.config` file.
+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.
 
 <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).
+In this example we're using env vars from [Infisical](https://infisical.com), but you can adapt it to any secrets manager.
 
 ```ts trigger.config.ts
 import { defineConfig } from "@trigger.dev/sdk";

package/docs/deployment/overview.mdx

@@ -69,14 +69,10 @@ Now if you visit your Trigger.dev dashboard you should see the new version deplo
 
 ## Triggering deployed tasks
 
-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:
+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:
 
 ```txt .env
-TRIGGER_SECRET_KEY="tr_prod_abc123"
+TRIGGER_SECRET_KEY="tr_prod_sk_abc123"
 ```
 
 Now you can trigger your tasks:
@@ -180,10 +176,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)
 
-Now you can trigger tasks against the staging environment by setting the `TRIGGER_SECRET_KEY` environment variable to the staging API key:
+To trigger tasks against Staging, create a named key in the Staging environment with **Trigger only** access and set it as `TRIGGER_SECRET_KEY`:
 
 ```txt .env
-TRIGGER_SECRET_KEY="tr_stg_abcd123"
+TRIGGER_SECRET_KEY="tr_stg_sk_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. Trigger runs using your Preview API key (`TRIGGER_SECRET_KEY`) and the branch name (`TRIGGER_PREVIEW_BRANCH`).
+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`).
 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
 
-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.
+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.
 
 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_1234567890"
+TRIGGER_SECRET_KEY="tr_preview_sk_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_1234567890", // WARNING: Never actually hardcode your secret key like this
+  secretKey: "tr_preview_sk_1234567890", // WARNING: Never actually hardcode your secret key like this
   previewBranch: "your-branch-name",
 });
 

package/docs/deployment/version-skew-protection.mdx

@@ -276,6 +276,68 @@ An empty or whitespace-only value counts as "not supplied" rather than an error,
 
 Batch triggers carry the id too. `batchTrigger` resolves it per item exactly as `trigger` does, and it survives the asynchronous materialisation of batch items — so a large batch triggered during a deploy waits and releases item by item, each pinned to the deployment its calling code came from.
 
+## Chat sessions
+
+[Chat agents](/ai-chat/overview) are covered by the same mechanism, with one difference: the id belongs to the **session**, not to a single trigger. It is resolved wherever you start the session — your server action, your route handler, `sessions.start()` — using the same order of precedence as a task trigger, and stored on the session. Every run that session goes on to schedule carries it: the first run, each continuation after an idle suspend, and each recovery after a crash.
+
+That is what you want for a conversation. A chat started by one release of your app keeps talking to the agent build that release shipped with, however many turns and however many runs that takes.
+
+Chats need the same two halves as tasks, and no more: a deployment carrying an id, and an app that sends the same one (explicitly, through `TRIGGER_EXTERNAL_DEPLOYMENT_ID`, or through [automatic discovery](#automatic-discovery)). There is nothing chat-specific to switch on, so an app already pinning its task runs gets pinned chats with no code change.
+
+```ts
+// app/actions.ts
+"use server";
+import { chat } from "@trigger.dev/sdk/ai";
+import type { myChat } from "@/trigger/chat";
+
+// No chat-specific setup: the id is discovered per call, exactly as it is for `trigger()`.
+export const startChatSession = chat.createStartSessionAction<typeof myChat>("my-chat");
+```
+
+Three things follow from the pin living on the session:
+
+- **Starting the session again refreshes it, and the conversation follows.** `sessions.start()` is idempotent on `chatId` and rewrites the stored config, so when your transport calls `startSession` after a redeploy, the session re-pins. A **running** agent then hands the conversation over at the next turn boundary, so the next message is answered by the deployment you just named — not several turns later when the old run happens to end. The turn already in flight finishes on the code it started on. Set [`versionSkew: "hold"`](/ai-chat/patterns/version-upgrades#staying-put) on an agent that should stay put instead.
+- **There is one pin per `chatId`.** If the same conversation is open in two tabs on two different releases of your app, whichever called `startSession` most recently sets the pin for both.
+- **A parked chat is waiting, not broken.** A run pinned to a deployment that hasn't landed parks, and every message sent meanwhile is stored durably and delivered once the deployment arrives. Nothing is lost — but nothing answers either, so tell the user. Re-pinning does not release a parked run: it keeps waiting for the deployment it was created for. If that deployment never lands, the run waits until its park deadline elapses, and the next message after that starts a fresh run on the session's current pin. Pass `pendingVersion` through your `startSession` callback and the transport emits a `run-pending-version` event:
+
+```tsx
+const transport = useTriggerChatTransport({
+  task: "my-chat",
+  accessToken: ({ chatId }) => mintChatAccessToken(chatId),
+  startSession: ({ chatId, clientData }) => startChatSession({ chatId, clientData }),
+  onEvent: (event) => {
+    if (event.type === "run-pending-version") setDeploying(true);
+    if (event.type === "first-chunk") setDeploying(false);
+  },
+});
+```
+
+The event repeats on every message sent while the chat is parked, so a notice driven off it stays accurate. Its `source` says where the park was learned: `start` from creating the session, `send` from an append, `head-start` from the route's response header, and `upgrade` when a session followed its pin onto a deployment that hasn't landed yet — that last one arrives as soon as the handoff happens, without waiting for another message.
+
+[Head Start](/ai-chat/fast-starts#head-start) softens this considerably: turn 1 runs in your own warm process, so a parked deployment costs nothing until step 2. The handover signal is durable, so the agent picks the turn up where it left off once the deployment lands. The transport emits `run-pending-version` with `source: "head-start"` for that case, and `chat.startHeadStart` returns `pendingVersion` for the detached flow.
+
+### Opting a chat out
+
+Pass `null` and that chat is never pinned, whatever the environment says:
+
+```ts
+export const startChatSession = chat.createStartSessionAction<typeof myChat>("my-chat", {
+  triggerConfig: { externalDeploymentId: null },
+});
+```
+
+Use this for a conversation that should always run on the current version — a long-lived support thread, say — while the rest of your chats stay pinned. To turn pinning off everywhere instead, set `TRIGGER_AUTOMATIC_SKEW_VERSION_PROTECTION` to `0` and don't set `TRIGGER_EXTERNAL_DEPLOYMENT_ID`.
+
+### Escaping the pin from inside the agent
+
+[`chat.requestUpgrade()`](/ai-chat/patterns/version-upgrades) clears the session's external deployment id as part of the handoff, so the new run is free to land on the current version. Pass a target to move to a specific deployment instead:
+
+```ts
+chat.requestUpgrade({ externalDeploymentId: clientData.commitSha });
+```
+
+Either way the change is persisted on the session, so the next continuation doesn't fall back to the id the agent just rejected. `lockToVersion` is a separate, explicit pin and is never cleared — `requestUpgrade()` cannot escape it, which is also why a session using it never follows its external deployment id automatically.
+
 ## Waiting and expiry
 
 When a run arrives with an id that isn't deployed yet, it doesn't fail — it **waits**. This is the ordinary case, not an edge case: your app frequently goes live a few seconds before your task build finishes.

package/docs/github-integration.mdx

@@ -34,7 +34,7 @@ This eliminates the need to manually run the `trigger.dev deploy` command or set
 <Step title="Customize build settings (optional)">
   Configure how your project is built:
 
-  - **Trigger config file**: Path to your `trigger.config.ts` file. By default, we look for it in the root of your repository. The path should be relative to the root of your repository and contain the config file name, e.g., `apps/tasks/trigger.config.ts`.
+  - **Trigger config file**: Auto-detected by default — we find your `trigger.config.ts` anywhere in your repository. Set a path relative to the root of your repository to override it, e.g., `apps/tasks/trigger.config.ts`. If your repository contains more than one config file, set the path of the one to use.
   - **Install command**: Auto-detected by default, but you can override it if necessary. The command will be run from the root of your repository.
   - **Pre-build command**: Run any commands before building and deploying your project, e.g., `pnpm run prisma:generate`. The command will be run from the root of your repository.
 </Step>