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

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-20260909071038",
+  "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-20260909071038",
+    "@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 }),
   });
 ```
 
@@ -222,9 +217,8 @@ frontend, narrow `useChat` with `InferChatUIMessage<typeof myChat>` from `@trigg
 `chat.agent` accepts hooks that fire in a fixed per-turn order:
 
 ```text
-onValidateMessages -> storage.loadContext (or the deprecated hydrateMessages)
-  -> onChatStart (chat's first message only)
-  -> onTurnStart -> run() -> onBeforeTurnComplete -> onTurnComplete -> storage.save
+onValidateMessages -> hydrateMessages -> onChatStart (chat's first message only)
+  -> onTurnStart -> run() -> onBeforeTurnComplete -> onTurnComplete
 ```
 
 `onBoot` fires once per worker process (every fresh boot, including continuation runs) and is where
@@ -234,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
@@ -249,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

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

@@ -143,12 +143,6 @@ await waitUntilComplete();
 5s timeout, before `onTurnComplete`). `chat.inject(messages)` queues `ModelMessage[]` that drain at
 the next turn start or `prepareStep` boundary.
 
-Two lanes, decided by role. A `role: "system"` message goes to the model's instructions, where it is
-trusted like the system prompt, and applies to the next turn only. Any other role joins the
-conversation and is untrusted by construction, so put checkable facts there and directives in the
-system lane. The instructions lane reaches the model only through the managed `streamText` (or a
-`chat.toStreamTextOptions()` spread), since that is where the SDK can set instructions.
-
 ```ts
 export const myChat = chat.agent({
   id: "my-chat",
@@ -160,9 +154,8 @@ export const myChat = chat.agent({
       })()
     );
   },
-  registry,
-  run: async ({ messages, signal, streamText }) =>
-    streamText({ messages, abortSignal: signal, stopWhen: stepCountIs(15) }),
+  run: async ({ messages, signal }) =>
+    streamText({ ...chat.toStreamTextOptions({ registry }), messages, abortSignal: signal, stopWhen: stepCountIs(15) }),
 });
 ```
 
@@ -170,9 +163,8 @@ export const myChat = chat.agent({
 
 `compaction.shouldCompact` decides when, `summarize` produces the summary that replaces the model
 messages. UI messages are preserved by default (customize via `compactUIMessages`). The `prepareStep`
-that performs inner-loop compaction rides the managed `streamText`, which composes a `prepareStep`
-you pass after it. Spreading `chat.toStreamTextOptions()` and then passing your own replaces it,
-switching compaction off.
+that performs inner-loop compaction is auto-injected by `chat.toStreamTextOptions()`; a `prepareStep`
+you pass after the spread wins.
 
 ```ts
 compaction: {
@@ -190,14 +182,7 @@ compaction: {
 `actionSchema` validates; `onAction` mutates via `chat.history` (`slice`, `replace`, `rollbackTo`,
 `remove`, `getPendingToolCalls`, `extractNewToolResults`). Actions fire `hydrateMessages` and
 `onAction` only, never `run()` or the turn hooks. Return a `StreamTextResult`, string, or `UIMessage`
-to also emit a model response, built with the `streamText` from `onAction`'s own argument so it
-carries the agent's prompt and tools like any other turn.
-
-Persistence goes through the agent's transcript storage (`storage` on `chat.agent`; the platform
-snapshot by default). After an action that changed the conversation the runtime hands the storage a
-changeset: an undo is one `truncateAfter`, a regenerate is a `truncateAfter` plus the new answer's
-`put`. With the deprecated `hydrateMessages` your store is the source of truth and the runtime does
-not write, so mirror every mutation yourself: a regenerate is a delete and an insert.
+to also emit a model response.
 
 ```ts
 export const myChat = chat.agent({
@@ -210,8 +195,7 @@ export const myChat = chat.agent({
     if (action.type === "undo") chat.history.slice(0, -2);
     if (action.type === "rollback") chat.history.rollbackTo(action.targetMessageId);
   },
-  run: async ({ messages, signal, streamText }) =>
-    streamText({ model: anthropic("claude-sonnet-4-5"), messages, abortSignal: signal }),
+  run: async ({ messages, signal }) => streamText({ model: anthropic("claude-sonnet-4-5"), messages, abortSignal: signal }),
 });
 ```
 
@@ -226,19 +210,18 @@ must be **schema-only** (a module importing `ai` + `zod` only); heavy executes s
 
 ```ts
 import { chat } from "@trigger.dev/sdk/chat-server";
+import { streamText, stepCountIs } from "ai";
 import { anthropic } from "@ai-sdk/anthropic";
 import { headStartTools } from "@/lib/chat-tools/schemas";
 
 export const chatHandler = chat.headStart({
   agentId: "my-chat",
-  // `streamText` from the run argument owns `messages`, `prompt`, `stopWhen`
-  // and `abortSignal`: the handover needs `stopWhen: stepCountIs(1)` so the agent,
-  // not this handler, runs step 2 onward. Passing any of them is a type error.
-  run: async ({ streamText }) =>
+  run: async ({ chat: helper }) =>
     streamText({
+      ...helper.toStreamTextOptions({ tools: headStartTools }),
       model: anthropic("claude-sonnet-4-6"),
       system: "You are helpful.",
-      tools: headStartTools,
+      stopWhen: stepCountIs(15),
     }),
 });
 // Next.js: export const POST = chatHandler;  Transport: headStart: "/api/chat"
@@ -265,10 +248,8 @@ export const myChat = chat.agent({
 ### 8. Pending messages (mid-stream user input)
 
 A message sent while a turn is streaming should NOT cancel the stream. Configure
-`pendingMessages` (`shouldInject`, `prepare`, `onReceived`, `onInjected`) on the agent so the managed
-`streamText`'s `prepareStep` folds them in at the next boundary. An injected steering message is part
-of the conversation your hooks see, so it arrives in `uiMessages` and `newUIMessages` at
-`onTurnComplete` and an app persisting from there stores it without extra work. On the frontend, `usePendingMessages`
+`pendingMessages` (`shouldInject`, `prepare`, `onReceived`, `onInjected`) on the agent so the SDK's
+auto-injected `prepareStep` folds them in at the next boundary. On the frontend, `usePendingMessages`
 returns `pending`, `steer(text)`, `queue(text)`, and `promoteToSteering(id)`; send via
 `transport.sendPendingMessage(chatId, uiMessage, metadata?)`.
 

package/dist/commonjs/v3/chatSnapshotIo.d.ts

@@ -1,2 +0,0 @@
-export declare function __setReadChatSnapshotImplForTests(impl: ReadChatSnapshotImpl | undefined): void;
-export declare function __setWriteChatSnapshotImplForTests(impl: WriteChatSnapshotImpl | undefined): void;