@trigger.dev/sdk 4.5.16 → 4.6.1

package/docs/reports.mdx

@@ -0,0 +1,157 @@
+---
+title: "Project health report"
+sidebarTitle: "Health report"
+description: "Get a deterministic verdict on your project's health — split into Flow, Execution, and Liveness — from the CLI, an MCP tool or prompt, or the HTTP API."
+---
+
+**The health report answers one question — "is my project healthy, and if not, is the problem my code or the platform?" — with a deterministic verdict, not a dashboard.** The server computes the verdict from your telemetry; no LLM interprets it, so the same numbers always produce the same answer.
+
+Every report reads a live window of your project's data and returns a headline verdict, the evidence behind it, and a single suggested next action. The only report today is `health`.
+
+## What the report measures
+
+The report splits a project into three dimensions, each with its own verdict:
+
+| Dimension | Question | What a bad verdict means |
+| --- | --- | --- |
+| **Flow** | Is work starting? | Runs are queuing but not being picked up — a concurrency limit, a throttle, or a trigger spike. |
+| **Execution** | Are the runs that start succeeding? | Runs are failing or slowing more than your baseline — usually your code. |
+| **Liveness** | Is the telemetry fresh? | The data behind the report is stale, so the verdict can't be trusted. |
+
+Splitting Flow from Execution is the point: a project can be failing to _start_ work (Flow) while every run that does start _completes_ fine (Execution), or the reverse. The report names which one, so you know whether to look at your concurrency settings or your task code.
+
+Each dimension carries a severity — healthy, degraded, or failing — and the report leads with the worst one as its headline. The headline finding is expanded with its supporting metrics; the others collapse to a one-line verdict.
+
+## Reading the report
+
+Here is `trigger report health` for a project whose runs are backing up against the environment concurrency limit:
+
+```text
+/report health        prod · last 1h · vs 7d normal
+
+✕ Flow stalled — at your env concurrency limit for the last 40 min
+
+  concurrency     100/100           ▄▅▆▇████   40 min at limit
+  pending         1,240      ↑ 6×   ▁▂▄▅▆▇██   (normal ~120)
+  start latency   p95 8.2s   ↑ 4×   ▁▂▃▄▆▇██   (normal ~2s)
+
+  why:  runs are finishing at ~90/min
+        nothing dead-lettered
+
+✓ EXECUTION   runs are executing normally
+
+✓ LIVENESS    fresh — telemetry current, updated 12s ago
+
+  read: limit saturated → incoming work exceeds capacity → backlog grows
+
+→ Raise the env concurrency limit
+  Read concurrency docs
+  or do nothing — backlog drains in ~26.7 min once triggers ease
+```
+
+The verdict reads top to bottom:
+
+- **Headline** — the worst finding, stated as a verdict with the breach window. Here Flow is stalled because concurrency has been pinned at its limit for 40 minutes.
+- **Evidence** — the metrics behind the headline, each with a sparkline over the window, its movement against your baseline (`↑ 6×` means six times normal), and an annotation (`40 min at limit`) or baseline (`normal ~120`).
+- **`why:`** — the facts that support the verdict, including what the problem _isn't_ (runs are still finishing, nothing is dead-lettered — so it's not your code).
+- **Sibling findings** — Execution and Liveness, each a one-line verdict.
+- **`read:`** — the causal chain in one line.
+- **Next steps** — the primary action first (`→`), then any alternatives.
+
+### The verdict vocabulary
+
+Every surface carries meaning in glyphs, never color alone, so the report is legible in a monochrome terminal or a plain-text MCP host:
+
+| Glyph | Meaning |
+| --- | --- |
+| `✓` | Healthy |
+| `⚠` | Degraded |
+| `✕` | Failing |
+| `○` | Genuinely unknown — neither good nor bad |
+| `⚑` | The data behind the report can't be trusted |
+| `↑` `↓` `→` | Above, below, or flat against the baseline |
+
+<Note>
+  The markdown surface swaps the status glyphs for traffic-light emoji (`🟢` `🟡` `🔴` `⚪` `🚩`) — the one color cue a chat host that renders neither ANSI nor HTML can show. The glyph and the emoji mean the same thing.
+</Note>
+
+## Surfaces
+
+The same report renders four ways.
+
+### CLI: `trigger report`
+
+Print an interpreted report for an environment. The command defaults to the `health` report and the `prod` environment — a manual production check.
+
+```bash
+npx trigger.dev@latest report health --env prod --period 24h
+```
+
+| Flag | Default | Description |
+| --- | --- | --- |
+| `[key]` | `health` | The report to render (positional argument). |
+| `-e, --env` | `prod` | The environment: `dev`, `staging`, `prod`, or `preview`. |
+| `-b, --branch` | — | The preview branch. Required when `--env preview`. |
+| `--period` | `1h` | The live window: `30m`, `1h`, `24h`, `7d`. Minutes to weeks, max 90 days. |
+| `-p, --project-ref` | from config | The project ref (`proj_…`). Required if there is no `trigger.config.ts`. |
+| `-c, --config` | — | Path to the config file. |
+
+The command prints only the report — no banner — so it pipes cleanly. Output is ANSI-colored in a real terminal and plain markdown when piped:
+
+```bash
+trigger report health > health.md   # markdown, no escape codes
+```
+
+Color follows the [supports-color](https://github.com/chalk/supports-color) convention: `NO_COLOR` (any value) or `FORCE_COLOR=0` disables color outright; `FORCE_COLOR` set to anything else force-enables it. Both win over TTY detection — which matters for agents spawned on a PTY, where `isTTY` is `true` but escape codes would be garbled.
+
+### MCP tool: `get_report`
+
+Fetch the report from an AI coding tool through the [Trigger.dev MCP server](/mcp-introduction). The tool returns plain markdown by default, or ANSI when `color` is set (for hosts that display escapes in tool output). It is read-only.
+
+| Parameter | Default | Description |
+| --- | --- | --- |
+| `key` | — | The report to render. Currently only `health`. |
+| `environment` | `dev` | The environment. The MCP server is dev-centric, so an unspecified environment reports on `dev` — pass `environment` explicitly to report on production. |
+| `period` | `1h` | Time window shorthand, e.g. `1h`, `24h`, `7d`. |
+| `color` | `false` | Return ANSI-colored text instead of markdown. |
+| `projectRef` | auto-detected | The project ref. Detected from `trigger.config.ts` if present. |
+| `branch` | — | The preview branch, for preview or branchable dev environments. |
+
+### MCP prompt: `/report`
+
+The MCP server also registers a `report` prompt, which hosts that support MCP prompts surface as a slash command (Claude Code renders it as `/mcp__trigger__report`). Running `/report health` calls `get_report` for you and shows the result verbatim in a fenced code block, preserving the monospace alignment and sparklines.
+
+### HTTP API: `GET /api/v1/reports/:key`
+
+The endpoint behind every surface. It accepts a `period` and a `format`, and authenticates with a token scoped to read the report's query tables (`read:query`).
+
+| Query param | Default | Description |
+| --- | --- | --- |
+| `period` | `1h` | The live window, same grammar as the CLI. |
+| `format` | `markdown` | `markdown`, `ansi`, or `json`. |
+
+`format=markdown` and `format=ansi` return the rendered text. `format=json` returns the `ReportViewModel` — the semantic payload behind the render, where verdicts are codes rather than prose, for building your own surface on top of the report.
+
+```bash
+curl "https://api.trigger.dev/api/v1/reports/health?period=24h&format=json" \
+  -H "Authorization: Bearer $TRIGGER_ACCESS_TOKEN"
+```
+
+An unknown report key returns `404` with the list of available keys.
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="MCP server" icon="plug" href="/mcp-introduction">
+    Connect your AI coding tool to Trigger.dev.
+  </Card>
+  <Card title="MCP tools" icon="wrench" href="/mcp-tools">
+    Every tool the MCP server exposes, including `get_report`.
+  </Card>
+  <Card title="Concurrency & queues" icon="layer-group" href="/queue-concurrency">
+    Configure the concurrency limits the Flow verdict checks against.
+  </Card>
+  <Card title="Query your data" icon="magnifying-glass" href="/observability/query">
+    Run TRQL queries against the same telemetry the report reads.
+  </Card>
+</CardGroup>

package/docs/self-hosting/security.mdx

@@ -6,10 +6,27 @@ 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>
 
+## What is in scope
+
+A self-hosted deployment is a single trust domain: as above, it is built for code and users you trust. Role separation inside an organization is therefore not a security boundary there. Role-based access control comes from a plugin that is not part of the open-source distribution, and without it the permission layer falls back to a permissive ability for session users and personal access tokens. That is deliberate.
+
+**Out of scope for self-hosted:** a member of an organization performing a privileged action inside that same organization, such as renaming or deleting the organization or managing other members. Control who you invite, or use Cloud, if you need that separation.
+
+**In scope from any deployment:** reaching data or actions belonging to an organization the caller is not a member of, or bypassing authentication. Organization is a hard boundary on Trigger.dev Cloud, and Cloud runs this same code, so report these even though your own install is single-tenant.
+
+Tell us which deployment you tested against. The same report can be out of scope for self-hosting and in scope for Cloud.
+
+The [security policy](https://github.com/triggerdotdev/trigger.dev/blob/main/SECURITY.md) is canonical.
+
 ## Reporting a vulnerability
 
 <Steps>

package/docs/tasks/scheduled.mdx

@@ -184,6 +184,30 @@ 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, 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).
+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).
 
 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/docs/troubleshooting-zod.mdx

@@ -0,0 +1,158 @@
+---
+title: "Zod"
+description: "Resolve Zod typechecking, test, and deployment errors when upgrading to Trigger.dev v4.6."
+---
+
+**Trigger.dev v4.6 uses Zod 4 by default. Zod 3.25.56 and later 3.x releases remain supported.**
+
+Use this guide if typechecking, tests, or deployment fail after upgrading. The supported project dependency range is `^3.25.56 || ^4.0.0`.
+
+| Your project's Zod dependency | What to do |
+| --- | --- |
+| No direct Zod dependency | No Zod-specific change is needed. Trigger.dev installs a compatible runtime dependency automatically. |
+| Zod below 3.25.56 | Upgrade before using Trigger.dev v4.6. These versions are unsupported. |
+| Zod 3.25.56 or later in the 3.x release line | Keep using your Zod 3 schemas with supported SDK APIs. Review the cross-major caveats below. |
+| Zod 4.x | Supported and the recommended default. |
+
+Passing your own supported Zod 3 schema to [`schemaTask`](/tasks/schemaTask) or `toolTask` remains supported. This does not make Zod 3 and Zod 4 schemas interchangeable when you compose or inspect them yourself.
+
+## Typechecking, tests, or deployment fail after upgrading
+
+An older Zod installation can be missing the entry points, types, or schema behavior that Trigger.dev v4.6 requires.
+
+Expect TypeScript errors when an unsupported version is resolved, particularly with `skipLibCheck: false`. Tests may also fail when they import or execute schemas. Deployment loads your task code, so an incompatible runtime installation causes deployment errors even if your local tooling skips typechecking. A passing local test suite does not establish that an unsupported version is safe to deploy.
+
+Symptoms include missing `zod/v4` or `zod/v4/core` exports, missing Zod types, incompatible generic parameters, and errors while loading tasks. The exact failure depends on the version and dependency tree; not every unsupported version fails at the same stage.
+
+### Check the installed version
+
+Inspect the resolved dependencies in the package that contains your tasks, not only the version range in `package.json`:
+
+<CodeGroup>
+```bash npm
+npm ls zod
+```
+
+```bash pnpm
+pnpm why zod
+```
+
+```bash bun
+bun pm ls --all
+```
+</CodeGroup>
+
+Check the lockfile and any dependency overrides or resolutions as well. An override can keep an old Zod version installed even after you update a direct dependency.
+
+### Update Zod
+
+Choose whether to move your application to Zod 4 or keep its existing Zod 3 schemas:
+
+<Tabs>
+  <Tab title="Move to Zod 4">
+    Install the latest Zod 4 release:
+
+    <CodeGroup>
+    ```bash npm
+    npm install zod@4
+    ```
+
+    ```bash pnpm
+    pnpm add zod@4
+    ```
+
+    ```bash bun
+    bun add zod@4
+    ```
+    </CodeGroup>
+
+    Review [Zod's migration guide](https://zod.dev/v4/changelog) for changes to your own schemas and error handling.
+  </Tab>
+  <Tab title="Stay on Zod 3">
+    Install the latest Zod 3 patch rather than pinning the minimum supported version:
+
+    <CodeGroup>
+    ```bash npm
+    npm install zod@3
+    ```
+
+    ```bash pnpm
+    pnpm add zod@3
+    ```
+
+    ```bash bun
+    bun add zod@3
+    ```
+    </CodeGroup>
+
+    Your existing `import { z } from "zod"` continues to use Zod 3. Trigger.dev's own schemas use the Zod 4 implementation included in the supported Zod 3 package.
+  </Tab>
+</Tabs>
+
+Other dependencies can require a higher minimum than Trigger.dev. For example, an AI SDK dependency may require Zod 3.25.76 or Zod 4. Meet those peer requirements too; do not force a lower version across every dependency.
+
+### Verify the update
+
+- Commit the updated manifest and lockfile, and make sure CI uses them.
+- Recheck the installed Zod versions in your local and deployment environments.
+- Run your project's TypeScript checks and tests, including code that constructs or inspects schemas.
+- Keep the CLI and SDK versions aligned using the [package upgrade guide](/upgrading-packages), then retry deployment.
+
+Do not use `skipLibCheck` or ignored peer-dependency warnings as a compatibility fix. They do not change the runtime package that deployment loads. You do not need to add Zod as a direct dependency if your application does not import it.
+
+## Parsing still fails with a supported Zod 3 version
+
+Supporting a Zod 3 schema as an SDK input is different from nesting a Trigger.dev-exported Zod 4 schema inside a Zod 3 object. Cross-major composition can fail during typechecking or parsing.
+
+For example, this mixes a Zod 3 object with a Zod 4 `RetryOptions` schema:
+
+```ts incompatible-schemas.ts
+import { z } from "zod"; // Project dependency is Zod 3.
+import { RetryOptions } from "@trigger.dev/core/v3";
+
+const schema = z.object({ retry: RetryOptions });
+schema.parse({ retry: {} });
+```
+
+Use Zod 4 for every schema in the composed object. The `zod/v4` entry point is available in both supported Zod 3 packages and Zod 4 packages:
+
+```ts compatible-schemas.ts
+import { z } from "zod/v4";
+import { RetryOptions } from "@trigger.dev/core/v3";
+
+const schema = z.object({ retry: RetryOptions });
+schema.parse({ retry: {} });
+```
+
+Alternatively, keep the Zod 3 and Trigger.dev schemas separate and call each schema's parser independently. You do not need to migrate unrelated application schemas to use this approach.
+
+## An `instanceof` check stops matching
+
+A Zod 4 error is not an instance of the Zod 3 `ZodError` constructor. A constructor check against your project's Zod 3 import can stop matching errors produced by Trigger.dev's schemas:
+
+```ts mismatched-error-check.ts
+import { z } from "zod"; // Project dependency is Zod 3.
+import { RetryOptions } from "@trigger.dev/core/v3";
+
+const result = RetryOptions.safeParse({ maxAttempts: "invalid" });
+
+if (!result.success) {
+  console.log(result.error instanceof z.ZodError); // false
+}
+```
+
+Use the result returned by the schema you called instead of a constructor from another Zod installation:
+
+```ts schema-error-handling.ts
+import { RetryOptions } from "@trigger.dev/core/v3";
+
+const result = RetryOptions.safeParse({ maxAttempts: "invalid" });
+
+if (!result.success) {
+  console.error(result.error.issues);
+}
+```
+
+The same caveat applies to checks such as `schema instanceof z.ZodObject`. Multiple installed copies can also have different constructors, even within the same major version. Prefer parsing and the returned validation result over inspecting classes or private fields such as `_def`.
+
+These examples are not an exhaustive list of cross-major differences. If errors remain after updating, check which Zod implementation creates each schema and which code composes, parses, or inspects it.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trigger.dev/sdk",
-  "version": "4.5.16",
+  "version": "4.6.1",
   "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": "4.5.16",
+    "@trigger.dev/core": "4.6.1",
     "uncrypto": "^0.1.3"
   },
   "devDependencies": {
@@ -82,13 +82,13 @@
     "tshy": "^4.1.3",
     "tsx": "4.17.0",
     "typescript": "7.0.2",
-    "zod": "3.25.76"
+    "zod": "4.5.4"
   },
   "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.0.0 || ^4.0.0"
+    "zod": "^3.25.56 || ^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 spread ...chat.toStreamTextOptions() first, returning a StreamTextResult
-  vs calling chat.pipe(), the two server actions (chat.createStartSessionAction +
+  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 +
   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,10 +47,9 @@ import { anthropic } from "@ai-sdk/anthropic";
 
 export const myChat = chat.agent({
   id: "my-chat",
-  run: async ({ messages, signal }) =>
+  // `streamText` below is the SDK's, from the run argument. See "Common mistakes".
+  run: async ({ messages, signal, streamText }) =>
     streamText({
-      // Spread this FIRST. See "Common mistakes".
-      ...chat.toStreamTextOptions(),
       model: anthropic("claude-sonnet-4-5"),
       messages,
       abortSignal: signal,
@@ -121,16 +120,22 @@ 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 }) => {
-    await runAgentLoop(messages); // don't return; pipe inside
+  run: async ({ messages, streamText }) => {
+    await runAgentLoop(messages, streamText); // don't return; pipe inside
   },
 });
 
-async function runAgentLoop(messages: ModelMessage[]) {
+// 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) {
   const result = streamText({
-    ...chat.toStreamTextOptions(),
     model: anthropic("claude-sonnet-4-5"),
     messages,
   });
@@ -138,10 +143,10 @@ async function runAgentLoop(messages: ModelMessage[]) {
 }
 ```
 
-### 2. Typed tools (declare on config AND spread back)
+### 2. Typed tools (declare on config AND pass back)
 
 Declare tools on `chat.agent({ tools })`, read them back typed from the `run()` payload, and pass
-that set to `chat.toStreamTextOptions({ tools })`. One declaration flows everywhere.
+that set as `tools`. One declaration flows everywhere.
 
 ```ts
 import { tool, stepCountIs } from "ai";
@@ -158,11 +163,11 @@ const tools = {
 export const myChat = chat.agent({
   id: "my-chat",
   tools, // so toModelOutput survives across turns
-  run: async ({ messages, tools, signal }) =>
+  run: async ({ messages, tools, signal, streamText }) =>
     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),
     }),
@@ -203,8 +208,8 @@ export const myChat = chat
     onTurnStart: async ({ uiMessages, writer }) => {
       writer.write({ type: "data-turn-status", data: { status: "preparing" } });
     },
-    run: async ({ messages, tools, signal }) =>
-      streamText({ ...chat.toStreamTextOptions({ tools }), model, messages, abortSignal: signal }),
+    run: async ({ messages, tools, signal, streamText }) =>
+      streamText({ model, messages, tools, abortSignal: signal }),
   });
 ```
 
@@ -217,8 +222,9 @@ frontend, narrow `useChat` with `InferChatUIMessage<typeof myChat>` from `@trigg
 `chat.agent` accepts hooks that fire in a fixed per-turn order:
 
 ```text
-onValidateMessages -> hydrateMessages -> onChatStart (chat's first message only)
-  -> onTurnStart -> run() -> onBeforeTurnComplete -> onTurnComplete
+onValidateMessages -> storage.loadContext (or the deprecated hydrateMessages)
+  -> onChatStart (chat's first message only)
+  -> onTurnStart -> run() -> onBeforeTurnComplete -> onTurnComplete -> storage.save
 ```
 
 `onBoot` fires once per worker process (every fresh boot, including continuation runs) and is where
@@ -228,13 +234,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 is load-bearing: the `signal` passed to `run` aborts on stop or cancel. Forward it as
+Stop depends on it: 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({ ...chat.toStreamTextOptions(), model, messages, abortSignal: signal, stopWhen: stepCountIs(15) });
+run: async ({ messages, signal, streamText }) =>
+  streamText({ model, messages, abortSignal: signal, stopWhen: stepCountIs(15) });
 ```
 
 ### 6. Migrating from a plain AI SDK `streamText` route
@@ -243,24 +249,30 @@ 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 add `...chat.toStreamTextOptions()` first.
+- Return the `StreamTextResult` (it auto-pipes) and take `streamText` from `run`'s argument, not from `ai`.
 - On the client, swap the `api` URL for `useTriggerChatTransport`; `useChat` stays the same shape.
 
 ## Common mistakes
 
-- **CRITICAL: forgetting `...chat.toStreamTextOptions()`.**
+- **CRITICAL: calling the `streamText` imported from `ai`.**
   ```ts
   // Wrong - compaction / steering / background injection silently no-op
-  return streamText({ model, messages, abortSignal: signal });
-  // Correct - spread FIRST so explicit overrides win
-  return streamText({ ...chat.toStreamTextOptions(), model, messages, abortSignal: signal });
+  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 });
   ```
-  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.
+  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.
 
 - **Declaring tools only on `streamText`.** Also declare them on `chat.agent({ tools })`, read them
-  back from `run`, and pass `chat.toStreamTextOptions({ tools })`. Otherwise each tool's
+  back from `run`, and pass that set as `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