@trigger.dev/sdk 4.5.12 → 4.5.14

package/docs/realtime/react-hooks/session-stream.mdx

@@ -0,0 +1,109 @@
+---
+title: "Read a session channel in React"
+sidebarTitle: "Session streams"
+description: "Subscribe to a session's output or input channel from React with useSessionStream: accumulate records, resume from a cursor, and read only the latest."
+---
+
+**`useSessionStream` subscribes to one channel of a [session](/ai-chat/sessions) and updates a `records` array as new records arrive.** It reads the `out` channel by default (the agent's output) or `in` (the input channel). It is read-only; `useSession` is reserved for two-way (read and write) communication.
+
+<Note>
+  Requires a Public Access Token with the `read:sessions:{id}` scope. See [Realtime
+  auth](/realtime/auth) for generating one.
+</Note>
+
+## Basic usage
+
+Pass the session id (or external id) and an `accessToken`. The hook returns the `records` received so far, the last control record, the cursor of the last record seen, and any error:
+
+```tsx
+"use client";
+
+import { useSessionStream } from "@trigger.dev/react-hooks";
+
+export function SessionViewer({
+  sessionId,
+  accessToken,
+}: {
+  sessionId: string;
+  accessToken: string;
+}) {
+  const { records, error } = useSessionStream<string>(sessionId, { accessToken });
+
+  if (error) return <div>Error: {error.message}</div>;
+
+  return <div>{records.join("")}</div>;
+}
+```
+
+## Options
+
+```tsx
+const { records, lastEventId, lastControl, error, stop } = useSessionStream(sessionId, {
+  accessToken: "pk_...", // Required: public access token with read:sessions:{id}
+  io: "out", // Optional: "out" (default) or "in"
+  from: "beginning", // Optional: "beginning" (default) or "latest"
+  maxRecords: 100, // Optional: keep only the most recent N records (default: unbounded)
+  lastEventId: undefined, // Optional: resume cursor
+  timeoutInSeconds: 60, // Optional: close after this long with no new data (default: 60)
+  throttleInMs: 16, // Optional: throttle record updates (default: 16ms)
+  onRecords: (batch) => {}, // Optional: callback per throttled batch, each with its event id
+  onControl: (event) => {}, // Optional: callback for control records (e.g. turn-complete)
+});
+```
+
+The return value:
+
+- **`records`**: every data record received so far, in arrival order. Control records are delivered to `onControl` instead.
+- **`lastEventId`**: the cursor of the last record seen. Persist it and pass it back as the `lastEventId` option to resume.
+- **`lastControl`**: the last control record (for example `turn-complete`).
+- **`stop`**: abort the subscription, keeping the records received so far.
+
+## Start from the latest record
+
+By default the hook replays the channel history, then live-tails. Pass `from: "latest"` to start at the current tail (the latest record, then live updates) instead of replaying, and `maxRecords` to bound memory:
+
+```tsx
+const { records } = useSessionStream<{ url: string }>(sessionId, {
+  accessToken,
+  io: "out",
+  from: "latest", // start at the latest record, then live updates
+  maxRecords: 1, // keep just the most recent record
+});
+```
+
+<Note>
+  `from: "latest"` requires a server that supports it. Against an older server a client that passes
+  it degrades safely to a full replay.
+</Note>
+
+## Resume from a cursor
+
+The hook resumes automatically across a component remount. A full page reload clears in-memory state, so to resume there, persist the returned `lastEventId` and pass it back on the next load. The channel then continues after that record with no replay and no gap:
+
+```tsx
+const cursorKey = `session-cursor:${sessionId}:out`; // scope the key to this session and channel
+const saved = localStorage.getItem(cursorKey) ?? undefined;
+
+const { records, lastEventId } = useSessionStream<string>(sessionId, {
+  accessToken,
+  lastEventId: saved,
+  onRecords: (batch) => localStorage.setItem(cursorKey, batch.at(-1)!.id),
+});
+```
+
+## React to control records
+
+Control records (such as `turn-complete`) never enter `records`. Handle them with `onControl`, or read the latest from `lastControl`:
+
+```tsx
+const { records, lastControl } = useSessionStream<string>(sessionId, {
+  accessToken,
+  onControl: (event) => {
+    if (event.subtype === "turn-complete") {
+      console.log("The turn is complete");
+    }
+  },
+});
+```
+
+For an expiring token on a long-lived subscription, pass `refreshAccessToken` (see [Realtime auth](/realtime/auth)). To read a session channel outside React, use [`session.out.read()`](/ai-chat/sessions).

package/docs/realtime/react-hooks/streams.mdx

@@ -130,16 +130,84 @@ export function AIStreamViewer({
 The `useRealtimeStream` hook accepts the following options:
 
 ```tsx
-const { parts, error } = useRealtimeStream(streamOrRunId, streamKeyOrOptions, {
+const { parts, lastEventId, error } = useRealtimeStream(streamOrRunId, streamKeyOrOptions, {
   accessToken: "pk_...", // Required: Public access token
   baseURL: "https://api.trigger.dev", // Optional: Custom API URL
   timeoutInSeconds: 60, // Optional: Timeout (default: 60)
-  startIndex: 0, // Optional: Start from specific chunk
+  from: "beginning", // Optional: "beginning" (default) or "latest"
+  maxParts: 100, // Optional: keep only the most recent N parts (default: unbounded)
+  lastEventId: undefined, // Optional: resume cursor (takes precedence over startIndex)
+  startIndex: 0, // Optional: start from a specific chunk index
   throttleInMs: 16, // Optional: Throttle updates (default: 16ms)
-  onData: (chunk) => {}, // Optional: Callback for each chunk
+  onData: (chunk) => {}, // Optional: callback for each chunk
+  onParts: (batch) => {}, // Optional: callback per throttled batch, each with its event id
+  refreshAccessToken: async () => "pk_...", // Optional: mint a fresh token on expiry
 });
 ```
 
+The hook returns `lastEventId`, the cursor of the last part it received. Persist it and pass it back as the `lastEventId` option to resume later.
+
+### Live view: start from the latest record
+
+By default a subscriber replays the whole stream history, then live-tails. Pass `from: "latest"` to start at the current tail (the latest record, then live updates) instead of replaying, and `maxParts` to keep memory bounded. Together they give a last-value view:
+
+```tsx
+"use client";
+
+import { useRealtimeStream } from "@trigger.dev/react-hooks";
+
+export function LatestFrame({ runId, accessToken }: { runId: string; accessToken: string }) {
+  const { parts } = useRealtimeStream<{ url: string }>(runId, "frames", {
+    accessToken,
+    from: "latest", // start at the latest frame, then live updates
+    maxParts: 1, // keep just the most recent frame
+  });
+
+  const frame = parts.at(-1);
+  return frame ? <img src={frame.url} alt="latest frame" /> : null;
+}
+```
+
+<Note>
+  `from: "latest"` requires a server that supports it. Against an older server a client that passes
+  it degrades safely to a full replay.
+</Note>
+
+### Resume across a page reload
+
+The hook resumes automatically across a component remount. A full page reload clears in-memory
+state, so to resume there, persist the returned `lastEventId` and pass it back on the next load. The
+subscription then continues after that record with no replay and no gap:
+
+```tsx
+const cursorKey = `frames-cursor:${runId}`; // scope the key to this stream
+const saved = localStorage.getItem(cursorKey) ?? undefined;
+
+const { parts, lastEventId } = useRealtimeStream<{ url: string }>(runId, "frames", {
+  accessToken,
+  lastEventId: saved, // resume where the previous session left off
+  onParts: (batch) => localStorage.setItem(cursorKey, batch.at(-1)!.id),
+});
+```
+
+### Refresh an expired access token
+
+Public access tokens are short-lived. For a long-running subscription, pass `refreshAccessToken` to
+mint a fresh token when the server rejects the connection with a 401/403. The subscription re-mints
+once and reconnects; with no refresher, auth errors stay terminal:
+
+```tsx
+const { parts } = useRealtimeStream<{ url: string }>(runId, "frames", {
+  accessToken,
+  refreshAccessToken: async () => {
+    const res = await fetch("/api/realtime-token"); // your backend mints a fresh public token
+    return (await res.json()).token;
+  },
+});
+```
+
+`refreshAccessToken` is also available on [`useApiClient` and `TriggerAuthContext`](/realtime/auth), so every hook under a provider shares one refresher.
+
 ### Using Default Stream
 
 You can omit the stream key to use the default stream:

package/docs/self-hosting/env/webapp.mdx

@@ -184,6 +184,7 @@ mode: "wide"
 | `MACHINE_PRESETS_OVERRIDE_PATH`                  | No       | —                     | Path to machine presets override file. See [machine overrides](/self-hosting/overview#machine-overrides).          |
 | `APP_ENV`                                        | No       | `NODE_ENV`            | App environment. Used for things like the title tag.                                                               |
 | `ADMIN_EMAILS`                                   | No       | —                     | Regex of user emails to automatically promote to admin on signup. Does not apply to existing users.                |
+| `ADMIN_DASHBOARD_ENABLED`                        | No       | 1                     | Set to anything other than `1` or `true` to disable the admin dashboard and user impersonation on this instance.   |
 | `EVENT_LOOP_MONITOR_ENABLED`                     | No       | 1                     | Node.js event loop lag monitor.                                                                                    |
 
 ## Multi-Provider Object Storage

package/docs/self-hosting/security.mdx

@@ -15,7 +15,7 @@ We take the security of Trigger.dev seriously, for both Cloud and self-hosted de
 <Steps>
   <Step title="Choose a private channel">
     - **GitHub (preferred):** open a private report from the repository's **Security** tab using **"Report a vulnerability"** ([direct link](https://github.com/triggerdotdev/trigger.dev/security/advisories/new)).
-    - **Email:** `security-advisories@trigger.dev`
+    - **Email:** `security@trigger.dev`
   </Step>
   <Step title="Include the details">
     A description and impact, steps to reproduce (a proof of concept helps), affected versions/components, and any suggested fix.

package/docs/tasks/streams.mdx

@@ -144,9 +144,12 @@ With options:
 const stream = await aiStream.read(runId, {
   timeoutInSeconds: 60, // Stop if no data for 60 seconds
   startIndex: 10, // Start from the 10th chunk
+  from: "latest", // Or skip history and read only new records from now
 });
 ```
 
+Pass `from: "latest"` to start at the current tail and receive only records appended after the read connects, instead of replaying from the beginning.
+
 #### Appending to a Stream
 
 Use the defined stream's `append()` method to add a single chunk:

package/docs/vercel-integration.mdx

@@ -5,7 +5,7 @@ description: "Automatically deploy your tasks whenever you deploy to Vercel."
 
 ## How it works
 
-The Vercel integration connects your Vercel project to your Trigger.dev project so that every Vercel deployment automatically triggers a Trigger.dev deployment. It also syncs environment variables from Vercel into Trigger.dev and supports atomic deployments to keep your app and tasks in sync.
+The Vercel integration connects your Vercel project to your Trigger.dev project so that every Vercel deployment automatically triggers a Trigger.dev deployment. It also syncs environment variables from Vercel into Trigger.dev, and sets up [version skew protection](/deployment/version-skew-protection) so your app and tasks stay in sync.
 
 This eliminates the need to manually run the `trigger.dev deploy` command or maintain custom CI/CD workflows for Vercel-based projects.
 
@@ -42,8 +42,7 @@ You can connect Vercel from two entry points:
 </Step>
 
 <Step title="Configure build options">
-  Optionally adjust [build options](#build-options) for atomic deployments, env var pulling, and new
-  env var discovery.
+  Optionally adjust [build options](#build-options) for env var pulling and new env var discovery.
 </Step>
 
 <Step title="Connect GitHub">
@@ -99,7 +98,7 @@ The integration syncs environment variables in both directions:
 
 The following variables are excluded from the Vercel → Trigger.dev sync:
 
-- `TRIGGER_SECRET_KEY`, `TRIGGER_VERSION`, `TRIGGER_PREVIEW_BRANCH` (managed by Trigger.dev)
+- `TRIGGER_SECRET_KEY`, `TRIGGER_API_URL`, `TRIGGER_VERSION`, `TRIGGER_PREVIEW_BRANCH`, `TRIGGER_AUTOMATIC_SKEW_VERSION_PROTECTION` (managed by Trigger.dev)
 - Sensitive/secret-type variables (Vercel API limitation)
 
 You can control sync behavior per-variable from your project's Vercel settings. Deselecting a variable prevents its value from being updated during future syncs.
@@ -120,8 +119,41 @@ You can control sync behavior per-variable from your project's Vercel settings.
 
 If you use [Supabase Branching](https://supabase.com/docs/guides/deployment/branching) or [Neon Database Branching](https://neon.tech/docs/guides/branching-intro) for preview environments, disable syncing for database env vars on the Environment Variables page and use the [syncSupabaseEnvVars](/config/extensions/syncEnvVars#syncsupabaseenvvars) or [syncNeonEnvVars](/config/extensions/syncEnvVars#syncneonenvvars) build extensions instead. These extensions automatically resolve the correct branch-specific credentials at build time.
 
+## Version skew protection
+
+Your Vercel app and your tasks are deployed separately, so there is always a window where a new app can trigger tasks built from older code. [Version skew protection](/deployment/version-skew-protection) closes that window: each Trigger.dev deployment is tagged with your commit SHA, your app sends the same SHA when it triggers, and every run is pinned to the deployment built from the same commit. Runs triggered before the task build finishes wait for it rather than running on the previous version.
+
+The integration sets this up for you:
+
+- It sets `TRIGGER_AUTOMATIC_SKEW_VERSION_PROTECTION=1` on your Vercel project when you connect it, and re-asserts it on every build — so existing projects pick it up on their next deployment.
+- It passes your commit SHA as the deployment's external id.
+- `VERCEL_GIT_COMMIT_SHA` is available at runtime on Vercel, so the SDK finds the matching id with no work from you.
+
+There is nothing to enable, and it works in production, staging and preview alike. Nothing is gated: your Vercel deployment is never held back.
+
+<Note>
+  Version skew protection requires the `@trigger.dev/sdk` release that introduces external
+  deployment ids. Check the [release
+  notes](https://github.com/triggerdotdev/trigger.dev/releases) for the exact version, or just use
+  the latest. On an older SDK no id is sent and your runs execute on the current version, with no
+  warning.
+</Note>
+
+To opt out, set `TRIGGER_AUTOMATIC_SKEW_VERSION_PROTECTION` to `0` on your Vercel project. The integration only writes the variable when it is absent, so a value you set is never overwritten.
+
 ## Atomic deployments
 
+<Warning>
+  **Automatic atomic deployments are deprecated.** Use [version skew
+  protection](/deployment/version-skew-protection) instead — it needs no second Vercel deployment,
+  never gates your app's deploy, doesn't touch `Auto-assign Custom Production Domains`, and covers
+  staging and preview as well as production.
+
+  Nothing is being switched off. The setting stays in your project's Vercel settings, keeps working,
+  and remains the way to hold your Vercel deployment back until your tasks have built. New
+  connections have it off by default.
+</Warning>
+
 Atomic deployments ensure your Vercel app and Trigger.dev tasks are deployed in sync. When enabled, Trigger.dev gates your Vercel deployment until the task build completes, then triggers a Vercel redeployment with the correct `TRIGGER_VERSION` set. This guarantees your app always uses the matching version of your tasks.
 
 ```mermaid
@@ -152,15 +184,16 @@ sequenceDiagram
   TD->>TD: Promote build
 ```
 
-Atomic deployments are enabled for the production environment by default.
+Atomic deployments are off by default for new connections. Projects that already had them enabled keep them enabled until you turn them off. Enabling them asks you to confirm first.
 
 <Note>
   When atomic deployments are enabled, the integration automatically disables `Auto-assign Custom
   Production Domains` on your Vercel project. This is required so that Vercel doesn't promote a
-  deployment before the Trigger.dev build is ready.
+  deployment before the Trigger.dev build is ready. If you turn atomic deployments off, re-enable
+  that setting in Vercel or promote deployments yourself.
 </Note>
 
-Previously, setting up atomic deployments with Vercel required custom GitHub Actions workflows. The Vercel integration automates this entirely. For more details on how atomic deployments work, see [Atomic deploys](/deployment/atomic-deployment).
+Previously, setting up atomic deployments with Vercel required custom GitHub Actions workflows. The Vercel integration automates this entirely. For more details on how atomic deployments work, see [Atomic deploys](/deployment/atomic-deployment). For how to move off them, see [replacing automatic atomic deployments](/deployment/version-skew-protection#replacing-automatic-atomic-deployments).
 
 ## Environment mapping
 
@@ -184,7 +217,7 @@ If your Vercel project has a custom environment, you can select which one maps t
 
 You can configure the following settings per-environment from your project's Vercel settings:
 
-- **Atomic deployments**: Controls whether Trigger.dev and Vercel deployments are synchronized. Enabled for production by default.
+- **Atomic deployments** (deprecated): Controls whether Trigger.dev gates and redeploys your Vercel deployment to keep it in sync. Off by default for new connections — use [version skew protection](/deployment/version-skew-protection) instead.
 - **Pull env vars before build**: When enabled, Trigger.dev pulls the latest environment variables from Vercel before each build. Enabled for production, staging, and preview by default.
 - **Discover new env vars**: When enabled, new environment variables found in Vercel that don't yet exist in Trigger.dev are created automatically during builds. Only available for environments that also have env var pulling enabled. Enabled for production, staging, and preview by default.
 
@@ -201,7 +234,8 @@ Disconnecting stops automatic deployments, environment variable syncing, and dep
 
 ## Related
 
+- [Version skew protection](/deployment/version-skew-protection)
 - [GitHub integration](/github-integration)
-- [Atomic deploys](/deployment/atomic-deployment)
+- [Atomic deploys](/deployment/atomic-deployment) (deprecated for Vercel)
 - [Environment variables](/deploy-environment-variables)
 - [Preview branches](/deployment/preview-branches)

package/docs/versioning.mdx

@@ -47,6 +47,8 @@ So a task run will continue running on the version it was locked to. We do this
 
 Every deployment creates a new version of all tasks for that environment.
 
+Because your application and your tasks deploy separately, a release of your app can briefly trigger tasks that belong to a different version. [Version skew protection](/deployment/version-skew-protection) pins each run to the deployment built from the same commit, once your app sends the id it was deployed with.
+
 ## Retries and reattempts
 
 When a task has an uncaught error it will [retry](/errors-retrying), assuming you have not set `maxAttempts` to 0. Retries are locked to the original version of the run.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trigger.dev/sdk",
-  "version": "4.5.12",
+  "version": "4.5.14",
   "description": "trigger.dev Node.JS SDK",
   "license": "MIT",
   "publishConfig": {
@@ -66,7 +66,7 @@
   "dependencies": {
     "@opentelemetry/api": "1.9.1",
     "@opentelemetry/semantic-conventions": "1.41.1",
-    "@trigger.dev/core": "4.5.12",
+    "@trigger.dev/core": "4.5.14",
     "uncrypto": "^0.1.3"
   },
   "devDependencies": {