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

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/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",
 });
 

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

@@ -276,68 +276,6 @@ 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/manual-setup.mdx

@@ -55,15 +55,15 @@ bun add -D @trigger.dev/build@latest
 
 ## Environment variables
 
-For local development, create a named environment API key and set it as `TRIGGER_SECRET_KEY`:
+For local development, you need to set up the `TRIGGER_SECRET_KEY` environment variable. This key authenticates your application with Trigger.dev.
 
-1. Open your project's Development environment in the Trigger.dev dashboard.
-2. Open the **API Keys** page.
-3. Click **New API key**, give it a descriptive name, and select **Trigger only** access.
-4. Copy the key and add it to your local environment file. Trigger.dev shows the complete value only once.
+1. Go to your project dashboard in Trigger.dev
+2. Navigate to the "API Keys" page
+3. Copy the **DEV** secret key
+4. Add it to your local environment file:
 
-```bash .env
-TRIGGER_SECRET_KEY=tr_dev_sk_xxxxxxxxxx
+```bash
+TRIGGER_SECRET_KEY=tr_dev_xxxxxxxxxx
 ```
 
 ### Self-hosted instances

package/docs/mcp-tools.mdx

@@ -189,15 +189,6 @@ Execute a single widget query from a built-in dashboard. Use `list_dashboards` f
 - `"Run the total runs widget from the overview dashboard"`
 - `"Show me the LLM cost over time from the AI dashboard"`
 
-### get_report
-
-Render an interpreted [health report](/reports) — a deterministic verdict, not a raw panel — as text with sparklines. The `health` report answers whether work is flowing, whether the runs that start are healthy, and whether the telemetry is fresh, with a headline verdict and a suggested next action. Returns markdown by default, or ANSI when `color` is set. Read-only.
-
-**Example usage:**
-- `"Is my production project healthy?"`
-- `"Run the health report for the last 24 hours"`
-- `"Why are my runs backing up?"`
-
 ## Dev Server Tools
 
 ### start_dev_server

package/docs/quick-start.mdx

@@ -26,7 +26,7 @@ Help me add Trigger.dev to this project.
    - Install the "Hello World" example task when prompted.
 3. Run `npx trigger.dev@latest dev` to start the dev server.
 4. Once the dev server is running, test the example task from the Trigger.dev dashboard.
-5. Create a named API key in my Development environment with **Trigger only** access. Set it as TRIGGER_SECRET_KEY in my .env file (or .env.local for Next.js).
+5. Set TRIGGER_SECRET_KEY in my .env file (or .env.local for Next.js). I can find it on the API Keys page in the dashboard.
 6. Ask me what framework I'm using and show me how to trigger the task from my backend code.
 
 If I've already run init and want the MCP server, run: npx trigger.dev@latest install-mcp
@@ -70,10 +70,10 @@ Sign up at [Trigger.dev Cloud](https://cloud.trigger.dev) (or [self-host](/self-
 
 ## Triggering tasks from your app
 
-The test page in the dashboard verifies that your task works. To trigger tasks from your own code, open the API Keys page for your Development environment and create a named key with **Trigger only** access. Set the key as `TRIGGER_SECRET_KEY` in your `.env` file.
+The test page in the dashboard is great for verifying your task works. To trigger tasks from your own code, you'll need to set the `TRIGGER_SECRET_KEY` environment variable. Grab it from the API Keys page in the dashboard and add it to your `.env` file.
 
 ```bash .env
-TRIGGER_SECRET_KEY=tr_dev_sk_...
+TRIGGER_SECRET_KEY=tr_dev_...
 ```
 
 See [Triggering](/triggering) for the full guide, or jump straight to framework-specific setup for [Next.js](/guides/frameworks/nextjs), [Remix](/guides/frameworks/remix), or [Node.js](/guides/frameworks/nodejs).

package/docs/realtime/auth.mdx

@@ -131,7 +131,7 @@ const publicToken = await auth.createPublicToken({
 - If `expirationTime` is a number, it will be treated as a Unix timestamp in **seconds**
 - If `expirationTime` is a `Date`, it will be treated as a date
 
-Public Access Tokens cannot expire more than 30 days in the future.
+When using non-root API keys (recommended), the expiration cannot be more than 30 days in the future.
 
 The format used for a time span is the same as the [jose package](https://github.com/panva/jose), which is a number followed by a unit. Valid units are: "sec", "secs", "second", "seconds", "s", "minute", "minutes", "min", "mins", "m", "hour", "hours", "hr", "hrs", "h", "day", "days", "d", "week", "weeks", "w", "year", "years", "yr", "yrs", and "y". It is not possible to specify months. 365.25 days is used as an alias for a year. If the string is suffixed with "ago", or prefixed with a "-", the resulting time span gets subtracted from the current unix timestamp. A "from now" suffix can also be used for readability when adding to the current unix timestamp.
 

package/docs/self-hosting/security.mdx

@@ -6,11 +6,6 @@ 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.
 
-<Note>
-  Unlike Trigger.dev Cloud, the self-hosted setup is optimized for single-tenant use, with code and
-  users you trust. It is not designed to run untrusted code or untrusted payloads.
-</Note>
-
 <Warning>
   Do not report security vulnerabilities through public GitHub issues, pull requests, or Discord. Use one of the private channels below.
 </Warning>

package/docs/tasks/scheduled.mdx

@@ -184,30 +184,6 @@ const createdSchedule = await schedules.create({
   is the assigned time the run will actually start.
 </Note>
 
-### Free-plan minimum window
-
-Schedules created while an organization is on a free plan run no more than once per hour and use a minimum 60-minute window.
-
-- The minimum applies to the **cron cadence**: creating or deploying a schedule whose cron fires more often than once an hour is rejected with an actionable error. Change the cron expression or upgrade before saving.
-- Omitted, zero (`"0m"` / `"0%"`), or smaller windows are treated as the 60-minute minimum. A larger configured window still wins, subject to the usual cap at the next cron occurrence.
-- The policy applies to **all environment types**, including Development.
-- It is captured when the schedule is created. Existing schedules — and schedules created while paid, even after a later downgrade — are **grandfathered** and keep running unchanged.
-- Upgrading does not immediately rewrite existing schedules. A free-created restriction is cleared the next time the schedule is saved (imperative/dashboard) or redeployed (declarative) while the organization is paying.
-- No runs are ever skipped or coalesced: unsupported high-frequency schedules are rejected at create/update time rather than silently thinned out.
-- Self-hosted deployments, and any case where the billing plan can't be determined, are unrestricted.
-
-When a schedule is subject to this policy, the API returns an `appliedSchedulePolicy` object alongside the configured `window`:
-
-```json
-{
-  "window": "0m",
-  "appliedSchedulePolicy": {
-    "minimumWindowSeconds": 3600,
-    "reason": "free_schedule"
-  }
-}
-```
-
 ## Supported cron syntax
 
 ```

package/docs/triggering.mdx

@@ -27,7 +27,7 @@ Trigger tasks **from inside a another task**:
 
 ## Triggering from your backend
 
-When you trigger a task from your backend code, create a named API key with **Trigger only** access in the environment you want to target and set it as `TRIGGER_SECRET_KEY`. If you're [using a preview branch](/deployment/preview-branches), also set `TRIGGER_PREVIEW_BRANCH`. [More info on API keys](/apikeys).
+When you trigger a task from your backend code, you need to set the `TRIGGER_SECRET_KEY` environment variable. If you're [using a preview branch](/deployment/preview-branches), you also need to set the `TRIGGER_PREVIEW_BRANCH` environment variable. You can find the value on the API keys page in the Trigger.dev dashboard. [More info on API keys](/apikeys).
 
 If a single process needs to trigger across multiple projects, environments, or preview branches, use [`new TriggerClient({...})`](/management/multiple-clients) for each target instead of relying on the global env vars.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trigger.dev/sdk",
-  "version": "0.0.0-prerelease-20260908122921",
+  "version": "0.0.0-prerelease-streamfix-20260909094302",
   "description": "trigger.dev Node.JS SDK",
   "license": "MIT",
   "publishConfig": {
@@ -69,7 +69,7 @@
   "dependencies": {
     "@opentelemetry/api": "1.9.1",
     "@opentelemetry/semantic-conventions": "1.41.1",
-    "@trigger.dev/core": "0.0.0-prerelease-20260908122921",
+    "@trigger.dev/core": "0.0.0-prerelease-streamfix-20260909094302",
     "uncrypto": "^0.1.3"
   },
   "devDependencies": {
@@ -82,13 +82,13 @@
     "tshy": "^4.1.3",
     "tsx": "4.17.0",
     "typescript": "7.0.2",
-    "zod": "4.5.4"
+    "zod": "3.25.76"
   },
   "peerDependencies": {
     "@ai-sdk/otel": ">=1.0.0-0 <2",
     "ai": "^5.0.0 || ^6.0.0 || >=7.0.0-canary <8",
     "react": "^18.0 || ^19.0",
-    "zod": "^3.25.56 || ^4.0.0"
+    "zod": "^3.0.0 || ^4.0.0"
   },
   "peerDependenciesMeta": {
     "@ai-sdk/otel": {

package/skills/trigger-authoring-chat-agent/SKILL.md

@@ -2,8 +2,8 @@
 name: trigger-authoring-chat-agent
 description: >
   Author and run a durable AI chat agent with chat.agent from @trigger.dev/sdk/ai: the per-turn
-  run loop, why you MUST take streamText from the run argument rather than importing it from ai,
-  returning a StreamTextResult vs calling chat.pipe(), the two server actions (chat.createStartSessionAction +
+  run loop, why you MUST spread ...chat.toStreamTextOptions() first, returning a StreamTextResult
+  vs calling chat.pipe(), the two server actions (chat.createStartSessionAction +
   auth.createPublicToken), and wiring useChat to useTriggerChatTransport. Load this when building,
   modifying, or debugging a chat backend (the agent task or its lifecycle hooks) or its React
   transport, when declaring typed tools or custom data parts, or when migrating a plain AI SDK
@@ -47,9 +47,10 @@ import { anthropic } from "@ai-sdk/anthropic";
 
 export const myChat = chat.agent({
   id: "my-chat",
-  // `streamText` below is the SDK's, from the run argument. See "Common mistakes".
-  run: async ({ messages, signal, streamText }) =>
+  run: async ({ messages, signal }) =>
     streamText({
+      // Spread this FIRST. See "Common mistakes".
+      ...chat.toStreamTextOptions(),
       model: anthropic("claude-sonnet-4-5"),
       messages,
       abortSignal: signal,
@@ -120,22 +121,16 @@ inside nested helpers, call `await chat.pipe(result)` from anywhere in the task
 `run` resolve `void`.
 
 ```ts
-import { chat, type ChatStreamText } from "@trigger.dev/sdk/ai";
-import { anthropic } from "@ai-sdk/anthropic";
-import type { ModelMessage } from "ai";
-
 export const agentChat = chat.agent({
   id: "agent-chat",
-  run: async ({ messages, streamText }) => {
-    await runAgentLoop(messages, streamText); // don't return; pipe inside
+  run: async ({ messages }) => {
+    await runAgentLoop(messages); // don't return; pipe inside
   },
 });
 
-// A loop factored out of `run` takes `streamText` as an argument, so it keeps the
-// managed options. `ChatStreamText` (from `@trigger.dev/sdk/ai`) types the parameter.
-// `chat.toStreamTextOptions()` is the alternative when threading it down is impractical.
-async function runAgentLoop(messages: ModelMessage[], streamText: ChatStreamText) {
+async function runAgentLoop(messages: ModelMessage[]) {
   const result = streamText({
+    ...chat.toStreamTextOptions(),
     model: anthropic("claude-sonnet-4-5"),
     messages,
   });
@@ -143,10 +138,10 @@ async function runAgentLoop(messages: ModelMessage[], streamText: ChatStreamText
 }
 ```
 
-### 2. Typed tools (declare on config AND pass back)
+### 2. Typed tools (declare on config AND spread back)
 
 Declare tools on `chat.agent({ tools })`, read them back typed from the `run()` payload, and pass
-that set as `tools`. One declaration flows everywhere.
+that set to `chat.toStreamTextOptions({ tools })`. One declaration flows everywhere.
 
 ```ts
 import { tool, stepCountIs } from "ai";
@@ -163,11 +158,11 @@ const tools = {
 export const myChat = chat.agent({
   id: "my-chat",
   tools, // so toModelOutput survives across turns
-  run: async ({ messages, tools, signal, streamText }) =>
+  run: async ({ messages, tools, signal }) =>
     streamText({
+      ...chat.toStreamTextOptions({ tools }), // same set, handed back typed
       model: anthropic("claude-sonnet-4-5"),
       messages,
-      tools, // same set, handed back typed
       abortSignal: signal,
       stopWhen: stepCountIs(15),
     }),
@@ -208,8 +203,8 @@ export const myChat = chat
     onTurnStart: async ({ uiMessages, writer }) => {
       writer.write({ type: "data-turn-status", data: { status: "preparing" } });
     },
-    run: async ({ messages, tools, signal, streamText }) =>
-      streamText({ model, messages, tools, abortSignal: signal }),
+    run: async ({ messages, tools, signal }) =>
+      streamText({ ...chat.toStreamTextOptions({ tools }), model, messages, abortSignal: signal }),
   });
 ```
 
@@ -233,13 +228,13 @@ first message. Suspend/resume use `onChatSuspend` / `onChatResume`. Config optio
 `uiMessageStreamOptions`, and `exitAfterPreloadIdle`. There is no generic `retry`; `chat.agent`
 runs with `maxAttempts: 1` internally.
 
-Stop depends on it: the `signal` passed to `run` aborts on stop or cancel. Forward it as
+Stop is load-bearing: the `signal` passed to `run` aborts on stop or cancel. Forward it as
 `abortSignal` to `streamText`, or the Stop button updates the UI while the model keeps generating
 server-side.
 
 ```ts
-run: async ({ messages, signal, streamText }) =>
-  streamText({ model, messages, abortSignal: signal, stopWhen: stepCountIs(15) });
+run: async ({ messages, signal }) =>
+  streamText({ ...chat.toStreamTextOptions(), model, messages, abortSignal: signal, stopWhen: stepCountIs(15) });
 ```
 
 ### 6. Migrating from a plain AI SDK `streamText` route
@@ -248,30 +243,24 @@ There is no API route in this model. The transport replaces the route round-trip
 
 - Delete the route handler. Move per-request auth into the two server actions from Setup step 2.
 - Move the `streamText` call into `run`. It already receives pre-converted `ModelMessage[]`.
-- Return the `StreamTextResult` (it auto-pipes) and take `streamText` from `run`'s argument, not from `ai`.
+- Return the `StreamTextResult` (it auto-pipes) and add `...chat.toStreamTextOptions()` first.
 - On the client, swap the `api` URL for `useTriggerChatTransport`; `useChat` stays the same shape.
 
 ## Common mistakes
 
-- **CRITICAL: calling the `streamText` imported from `ai`.**
+- **CRITICAL: forgetting `...chat.toStreamTextOptions()`.**
   ```ts
   // Wrong - compaction / steering / background injection silently no-op
-  import { streamText } from "ai";
-  run: async ({ messages, signal }) => streamText({ model, messages, abortSignal: signal });
-  // Correct - the run argument's streamText carries the managed options
-  run: async ({ messages, signal, streamText }) => streamText({ model, messages, abortSignal: signal });
+  return streamText({ model, messages, abortSignal: signal });
+  // Correct - spread FIRST so explicit overrides win
+  return streamText({ ...chat.toStreamTextOptions(), model, messages, abortSignal: signal });
   ```
-  The SDK's one carries the `prepareStep` behind compaction, mid-turn steering and background
-  injection, the system prompt from `chat.prompt()` or `chat.agent({ system })`, the registry-resolved
-  model, and telemetry. The imported one carries none of it, with no error.
-  `...chat.toStreamTextOptions()` does the same job by hand, and is what a custom agent has to use,
-  since it has no `run` argument. A `chat.headStart` route gets a bound `streamText` too, and there it
-  also owns `messages`, `prompt`, `stopWhen` and `abortSignal`. Spreading it and then re-setting
-  `tools` or `prepareStep` replaces the managed ones; the run argument's `streamText` merges `tools`
-  and composes `prepareStep` instead.
+  It wires the `prepareStep` callback behind compaction, mid-turn steering, and background
+  injection, injects the system prompt from `chat.prompt()`, resolves the registry model, and adds
+  telemetry. Omitting it makes all of those silently no-op with no error.
 
 - **Declaring tools only on `streamText`.** Also declare them on `chat.agent({ tools })`, read them
-  back from `run`, and pass that set as `tools`. Otherwise each tool's
+  back from `run`, and pass `chat.toStreamTextOptions({ tools })`. Otherwise each tool's
   `toModelOutput` runs on turn 1 but is dropped when history is re-converted on later turns.
 
 - **Not forwarding `signal` for stop.** Without `abortSignal: signal`, Stop updates the UI but the