@trigger.dev/sdk 4.5.1 → 4.5.3

package/docs/ai-chat/reference.mdx

@@ -630,10 +630,30 @@ Options for the frontend transport constructor and `useTriggerChatTransport` hoo
 | `clientData`           | Typed by `clientDataSchema`                                          | —                           | Default client data merged into per-turn `metadata` and threaded through `startSession`'s params (so the first run's `payload.metadata` matches per-turn `metadata`). Live-updated when the option value changes. |
 | `sessions`             | `Record<string, ChatSession>`                                        | —                           | Restore sessions from storage. See [ChatSession](#chatsession).             |
 | `onSessionChange`      | `(chatId, session \| null) => void`                                  | —                           | Fires when session state changes. `session` is the full `ChatSession` or `null` when the run ends. |
+| `onEvent`              | `(event: ChatTransportEvent) => void`                                | —                           | Observability callback for transport lifecycle events (send outcomes, stream connects, first chunk, turn completion). See [Transport events](#transport-events). Exceptions thrown by the callback are swallowed. |
 | `multiTab`             | `boolean`                                                            | `false`                     | Enable multi-tab claim coordination via `BroadcastChannel`. See [Frontend → multi-tab](/ai-chat/frontend#multi-tab-coordination). |
 | `watch`                | `boolean`                                                            | `false`                     | Read-only watcher mode — keep the SSE subscription open across `trigger:turn-complete` so a viewer sees turns 2, 3, … through one long-lived stream. |
 | `headStart`            | `string`                                                             | —                           | URL of a [`chat.headStart`](/ai-chat/fast-starts#head-start) route handler. When set, the FIRST message of a brand-new chat POSTs to this URL so step 1's LLM call runs in your warm process while the agent run boots in parallel. Subsequent turns bypass it. |
 
+### Transport events
+
+The `onEvent` callback receives a `ChatTransportEvent` (exported from `@trigger.dev/sdk/chat` and `@trigger.dev/sdk/chat/react`) for each lifecycle moment the transport observes. All events carry `chatId` and `timestamp`.
+
+| Event | Extra fields | Fires when |
+| --- | --- | --- |
+| `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`. |
+| `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 agent's committed input-stream cursor. |
+| `stream-error` | `error`, `status?` | The output stream failed unrecoverably. |
+
+`source` identifies the send path: `"submit-message"`, `"regenerate-message"`, `"steer"` (`sendPendingMessage`), `"action"` (`sendAction`), `"stop"` (`stopGeneration`), or `"head-start"`.
+
+`messageId` on the response-side events is client-side attribution: the id from the most recent turn-producing send (`submit-message`, `regenerate-message`, or `head-start`) on that chat.
+
+See [Monitoring message delivery](/ai-chat/frontend#monitoring-message-delivery) for the metrics and watchdog patterns these enable.
+
 ### `accessToken` callback
 
 The transport invokes `accessToken` whenever it needs a *fresh* session-scoped PAT — initial use after no PAT is cached, or after a 401/403 from any session-PAT-authed request. The callback's job is to **return a token, not to start a run.**

package/docs/billing-limits.mdx

@@ -0,0 +1,73 @@
+---
+title: "Billing limits and alerts"
+sidebarTitle: "Billing limits & alerts"
+description: "Set a monthly compute spend cap for your organization and get email alerts before you reach it."
+---
+
+Billing limits let you cap your organization's monthly compute spend so a runaway task or unexpected traffic spike can't blow your budget. Billing alerts notify you by email as you approach thresholds you choose.
+
+<Note>Billing limits and alerts are available to all [Trigger.dev Cloud](https://trigger.dev) organizations. They don't apply to self-hosted instances.</Note>
+
+You can find the settings in the dashboard: open the **Organization** menu in the top left, then **Settings** → **Billing limits**.
+
+<picture>
+  <source srcSet="/images/billing-docs.webp" type="image/webp" />
+  <img src="/images/billing-docs.png" alt="Billing limit settings" />
+</picture>
+
+## Setting a billing limit
+
+Choose one of three options:
+
+- **Plan limit**: Use your plan's maximum as the spending cap.
+- **Custom limit**: Set your own monthly spend threshold.
+- **No limit**: No cap is enforced. This is the default.
+
+A billing limit applies to your whole organization and covers billable environments: `production`, `staging`, and `preview`. Your `dev` environment is not affected.
+
+Optionally, enable **Cancel in-progress runs when this limit is reached** to immediately cancel executing runs when the limit is hit, instead of letting them finish naturally.
+
+## Billing alerts
+
+Billing alerts are email notifications sent when your monthly spend crosses a threshold. You can add multiple thresholds:
+
+- **With a billing limit set**: thresholds are percentages of your limit (e.g. 50%, 80%).
+- **Without a billing limit**: thresholds are dollar amounts.
+
+<picture>
+  <source srcSet="/images/billing-alerts-docs.webp" type="image/webp" />
+  <img src="/images/billing-alerts-docs.png" alt="Billing alerts settings" />
+</picture>
+
+Alerts only notify you — they never pause environments or reject runs. Use them on their own for visibility, or alongside a limit to get advance warning before enforcement kicks in.
+
+## What happens when you reach your limit
+
+When your organization's spend reaches the billing limit, billable environments enter a **grace period**:
+
+1. Queues pause across `production`, `staging`, and `preview`. In-progress runs finish naturally (unless you enabled **Cancel in-progress runs**).
+2. New runs can still be triggered and are queued, but they won't start executing. Queued runs incur no compute cost until they start.
+3. You have **24 hours** to review and decide what to do.
+
+If you don't act before the grace period ends, queued runs are canceled and new triggers are rejected for the rest of the billing cycle.
+
+<Note>
+  Billing limits are **soft limits**, not instantaneous hard caps. Usage is evaluated on a short
+  delay, so spend can briefly exceed your limit before enforcement applies. See our
+  [terms](https://trigger.dev/terms) for refund policy details.
+</Note>
+
+## Resuming after hitting a limit
+
+To resume execution, increase or remove the billing limit from the **Billing limits** page. You'll be asked what to do with the runs that queued up during the pause:
+
+- **Resume queued runs**: everything that built up during the pause runs in order.
+- **Cancel queued runs**: the backlog is discarded and only new triggers run going forward.
+
+Execution resumes automatically once you've resolved the limit. Limits also reset at the start of each billing cycle.
+
+## Tracking spend against your limit
+
+On the **Usage** page (Organization menu → **Usage**), a **Billing limit** marker appears on the usage bar alongside your current spend and plan included usage, so you can see how close you are at a glance.
+
+For tips on lowering your spend in the first place, see [How to reduce your spend](/how-to-reduce-your-spend).

package/docs/github-repo.mdx

@@ -5,4 +5,4 @@ url: "https://github.com/triggerdotdev/trigger.dev"
 
 Trigger.dev is [Open Source on GitHub](https://github.com/triggerdotdev/trigger.dev). You can contribute to the project by submitting issues, pull requests, or simply by using it and providing feedback.
 
-You can also [self-host](/open-source-self-hosting) the project if you want to run it on your own infrastructure.
+You can also [self-host](/self-hosting/overview) the project if you want to run it on your own infrastructure.

package/docs/how-to-reduce-your-spend.mdx

@@ -24,20 +24,7 @@ Configure billing limits and alerts in your dashboard to protect against unexpec
 - Catch unexpected cost increases early
 - Identify runaway tasks before they become expensive
 
-The **Billing limits** settings page has two sections:
-
-- **Billing limit**: Choose your plan limit, a custom amount, or no limit. When a limit is reached, billable environments (`production`, `staging`, and `preview`) enter a **grace period** — queues pause and new runs queue without starting. After grace expires, new triggers are rejected until you increase or remove the limit.
-- **Billing alerts**: Add email alerts at specific spend thresholds (% of your limit when a limit is set, or dollar amounts when no limit is configured). Alerts notify you only; they do **not** pause environments or reject triggers.
-
-**Limits vs alerts:** A billing limit enforces spend (grace → reject). Billing alerts are optional notifications at thresholds you choose.
-
-**Soft limits:** Billing limits are not instantaneous hard caps. Usage is evaluated on a short delay, so spend can briefly exceed your limit before enforcement applies. Queued runs during grace incur no compute cost until they start. See our [terms](https://trigger.dev/terms) for refund policy details.
-
-On the **Usage** page, when you have a custom billing limit (or a plan limit that differs from included usage), a **Billing limit** marker appears on the usage bar alongside your current spend and plan included usage.
-
-![Billing limits and alerts settings](./images/billing-alerts-ui.png)
-
-You can open the page from the **Organization** menu in the top left of the dashboard, then **Settings** → **Billing limits**.
+You can open the settings from the **Organization** menu in the top left of the dashboard, then **Settings** → **Billing limits**. [Read the full billing limits and alerts docs](/billing-limits) for how limits are enforced, the grace period, and resuming after hitting a limit.
 
 ## Reduce your machine sizes
 

package/docs/limits.mdx

@@ -7,6 +7,11 @@ import RateLimitHitUseBatchTrigger from "/snippets/rate-limit-hit-use-batchtrigg
 
 You can view your current limits, quotas, and rate limit usage in real-time by visiting the **Limits** page in the dashboard (accessible from the left sidebar). This page shows current rate limit token availability, quota usage, and plan features for your organization.
 
+<Note>
+  Looking to cap your monthly spend? That's a setting you control, not a platform limit — see
+  [Billing limits and alerts](/billing-limits).
+</Note>
+
 ## Concurrency limits
 
 | Pricing tier | Limit                |

package/docs/quick-start.mdx

@@ -57,7 +57,7 @@ If I've already run init and want the MCP server, run: npx trigger.dev@latest in
 
 <Step title="Create a Trigger.dev account">
 
-Sign up at [Trigger.dev Cloud](https://cloud.trigger.dev) (or [self-host](/open-source-self-hosting)). The onboarding flow will guide you through creating your first organization and project.
+Sign up at [Trigger.dev Cloud](https://cloud.trigger.dev) (or [self-host](/self-hosting/overview)). The onboarding flow will guide you through creating your first organization and project.
 
 </Step>
 

package/docs/self-hosting/docker.mdx

@@ -339,9 +339,11 @@ There are several reasons to lock the version of your Docker images:
 By default, the images will point at the latest versioned release via the `latest` tag. You can override this by specifying a different tag in your `.env` file. For example:
 
 ```bash
-TRIGGER_IMAGE_TAG=v4.0.0
+TRIGGER_IMAGE_TAG=v4.5.0
 ```
 
+We patch the latest released version line only, so keep an eye on new releases to receive security fixes. See [Security & vulnerability reporting](/self-hosting/security).
+
 ## Task events
 
 By default, task events (timeline, logs, spans) are stored in PostgreSQL. For production deployments we recommend storing them in ClickHouse instead, it scales to much higher volumes and avoids unbounded growth of the `TaskEvent` table.
@@ -354,6 +356,27 @@ EVENT_REPOSITORY_DEFAULT_STORE=clickhouse_v2
 
 This only affects new runs; existing runs continue to read from wherever their events were originally stored.
 
+## Realtime streams
+
+Realtime streams power AI-agent token streaming and run streams. They default to **v2**, backed by the bundled `s2` service — [s2-lite](https://s2.dev), the open-source, self-hostable S2 server. It stores stream data in a persistent volume and is preconfigured in the webapp compose file, so no setup is required.
+
+To fall back to the Redis-backed **v1** streams, set on the webapp in your `.env`:
+
+```bash
+REALTIME_STREAMS_DEFAULT_VERSION=v1
+```
+
+To use a hosted S2 at [s2.dev](https://s2.dev) instead of the bundled s2-lite, point the endpoint at your basin and supply an access token:
+
+```bash
+REALTIME_STREAMS_S2_BASIN=your-basin
+REALTIME_STREAMS_S2_ENDPOINT=https://your-basin.b.aws.s2.dev/v1
+REALTIME_STREAMS_S2_SKIP_ACCESS_TOKENS=false
+REALTIME_STREAMS_S2_ACCESS_TOKEN=your-access-token
+```
+
+See the [webapp environment variables](/self-hosting/env/webapp) for the full list of realtime stream settings.
+
 ## Troubleshooting
 
 - **Deployment fails at the push step.** The machine running `deploy` needs registry access. See the [registry setup](#registry-setup) section for more details.

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

@@ -139,9 +139,14 @@ mode: "wide"
 | **Task events**                                  |          |                       |                                                                                                                    |
 | `EVENT_REPOSITORY_DEFAULT_STORE`                 | No       | postgres              | Where to store task events. Set to `clickhouse_v2` to store in ClickHouse (recommended for production).            |
 | **Realtime**                                     |          |                       |                                                                                                                    |
-| `REALTIME_STREAM_VERSION`                        | No       | v1                    | Realtime stream protocol version. One of `v1`, `v2`.                                                               |
+| `REALTIME_STREAM_VERSION`                        | No       | v1                    | Stream version exposed to tasks via the `TRIGGER_REALTIME_STREAM_VERSION` variable. Distinct from `REALTIME_STREAMS_DEFAULT_VERSION`. One of `v1`, `v2`. |
 | `REALTIME_STREAM_MAX_LENGTH`                     | No       | 1000                  | Realtime stream max length.                                                                                        |
 | `REALTIME_STREAM_TTL`                            | No       | 86400 (1d)            | Realtime stream TTL (s).                                                                                           |
+| `REALTIME_STREAMS_DEFAULT_VERSION`               | No       | v1                    | Server-side default the webapp uses when a stream request doesn't pin a version (modern SDKs request `v2`). The Docker and Helm self-hosting defaults set this to `v2`. One of `v1`, `v2`. |
+| `REALTIME_STREAMS_S2_BASIN`                       | No       | —                     | S2 basin that holds v2 realtime streams. Required for `v2`. Must be at least 8 characters.                          |
+| `REALTIME_STREAMS_S2_ENDPOINT`                    | No       | —                     | Custom S2 API endpoint, including the `/v1` suffix (e.g. `http://s2/v1` for the bundled s2-lite). Omit to use hosted S2 at s2.dev. |
+| `REALTIME_STREAMS_S2_SKIP_ACCESS_TOKENS`         | No       | false                 | Skip minting per-stream access tokens. Set to `true` for s2-lite, which needs no authentication.                    |
+| `REALTIME_STREAMS_S2_ACCESS_TOKEN`               | No       | —                     | S2 access token. Required for hosted S2 unless `REALTIME_STREAMS_S2_SKIP_ACCESS_TOKENS` is `true`.                  |
 | **Bootstrap**                                    |          |                       |                                                                                                                    |
 | `TRIGGER_BOOTSTRAP_ENABLED`                      | No       | 0                     | Trigger bootstrap enabled.                                                                                         |
 | `TRIGGER_BOOTSTRAP_WORKER_GROUP_NAME`            | No       | —                     | Trigger bootstrap worker group name.                                                                               |

package/docs/self-hosting/kubernetes.mdx

@@ -375,6 +375,32 @@ webapp:
 
 This only affects new runs; existing runs continue to read from wherever their events were originally stored.
 
+## Realtime streams
+
+Realtime streams power AI-agent token streaming and run streams. They default to **v2**, backed by the bundled `s2` deployment — [s2-lite](https://s2.dev), the open-source, self-hostable S2 server. The chart deploys it with a persistent volume, so no extra services are required.
+
+To fall back to the Redis-backed **v1** streams, set the default version to `v1`:
+
+```yaml
+s2:
+  defaultStreamVersion: "v1"
+```
+
+To use a hosted S2 at [s2.dev](https://s2.dev) instead of the bundled s2-lite, disable the bundled deployment and point at your basin. Supply the access token via an existing secret:
+
+```yaml
+s2:
+  deploy: false
+  skipAccessTokens: false
+  external:
+    endpoint: "https://your-basin.b.aws.s2.dev/v1"
+    existingSecret: "s2-credentials"
+    existingSecretAccessTokenKey: "access-token"
+  basin: "your-basin"
+```
+
+To disable realtime streams v2 entirely and use v1, set `s2.deploy: false` with no external endpoint. See `helm show values` for all `s2` options.
+
 ## Worker token
 
 When using the default bootstrap configuration, worker creation and authentication is handled automatically. The webapp generates a worker token and makes it available to the supervisor via a shared volume.

package/docs/self-hosting/overview.mdx

@@ -6,7 +6,7 @@ description: "You can self-host Trigger.dev on your own infrastructure."
 
 Self-hosting Trigger.dev means you run and manage the platform on your own infrastructure, giving you full control over your environment, deployment process, and the URLs you expose the service on.
 
-You are responsible for provisioning resources, handling updates, and managing any security, scaling or reliability challenges that arise.
+You are responsible for provisioning resources, handling updates, and managing any security, scaling or reliability challenges that arise. See [Security & vulnerability reporting](/self-hosting/security) for how to report issues and stay informed about security releases.
 
 We provide version-tagged releases for self-hosted deployments. It's highly advised to use these tags exclusively and keep them locked with your CLI version.
 
@@ -106,4 +106,7 @@ It's dangerous to go alone! Join the self-hosting channel on our [Discord server
   <Card title="Kubernetes" color="#326CE5" icon="dharmachakra" href="/self-hosting/kubernetes">
     Learn how to self-host Trigger.dev with Kubernetes.
   </Card>
+  <Card title="Security" icon="shield-halved" href="/self-hosting/security">
+    Report vulnerabilities and stay informed about security releases.
+  </Card>
 </CardGroup>

package/docs/self-hosting/security.mdx

@@ -0,0 +1,50 @@
+---
+title: "Security & vulnerability reporting"
+description: "How to report security issues in Trigger.dev, our response targets, and how self-hosters receive security notices."
+sidebarTitle: "Security"
+---
+
+We take the security of Trigger.dev seriously, for both Cloud and self-hosted deployments. This page covers how to report a vulnerability, what to expect, and how to stay informed about security releases.
+
+<Warning>
+  Do not report security vulnerabilities through public GitHub issues, pull requests, or Discord. Use one of the private channels below.
+</Warning>
+
+## Reporting a vulnerability
+
+<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`
+  </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.
+  </Step>
+  <Step title="We track it privately">
+    Every report is tracked in a private GitHub Security Advisory. If you email us, we open the advisory on your behalf.
+  </Step>
+</Steps>
+
+## What to expect
+
+| Stage | Target |
+| --- | --- |
+| Acknowledgement | within 3 business days |
+| Validation + CVSS 3.1 severity assessment | within 1 week |
+
+We score issues with CVSS 3.1 and prioritise remediation by severity:
+
+| Severity (CVSS 3.1) | Target time to resolve |
+| --- | --- |
+| Critical (9.0–10.0) | 7 days |
+| High (7.0–8.9) | 30 days |
+| Medium (4.0–6.9) | 90 days |
+| Low (0.1–3.9) | As needed |
+
+<Note>
+  These are best-effort targets measured from when we validate and accept a report, not guarantees. We follow coordinated disclosure with a default 90-day window, and publish a GitHub Security Advisory (requesting a CVE where applicable) once a fix ships.
+</Note>
+
+## Supported versions
+
+We patch the **latest released version line** only. Run the latest version-tagged release to receive security fixes — see [Self-hosting overview](/self-hosting/overview).

package/docs/troubleshooting.mdx

@@ -242,6 +242,10 @@ If runs are staying in the `QUEUED` state for extended periods, check your concu
 - **Review queue concurrency limits** - Check if individual queues have restrictive `concurrencyLimit` settings
 - **Check for stuck runs** - See if stalled runs are blocking new executions
 
+### Runs queued because a billing limit was reached
+
+If your organization reaches a billing limit, billable environments (`production`, `staging`, and `preview`) pause: new runs still queue, but they won't start executing until you raise or remove the limit and choose whether to resume or cancel the queued runs. See [Billing limits and alerts](/billing-limits) for the full flow.
+
 ### `Crypto is not defined`
 
 This can happen in different situations, for example when using plain strings as idempotency keys. Support for `Crypto` without a special flag was added in Node `v19.0.0`. You will have to upgrade Node - we recommend even-numbered major releases, e.g. `v20` or `v22`. Alternatively, you can switch from plain strings to the `idempotencyKeys.create` SDK function. [Read the guide](/idempotency).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trigger.dev/sdk",
-  "version": "4.5.1",
+  "version": "4.5.3",
   "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.1",
+    "@trigger.dev/core": "4.5.3",
     "chalk": "^5.2.0",
     "cronstrue": "^2.21.0",
     "debug": "^4.3.4",