@trigger.dev/sdk 4.5.16 → 4.6.0

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.0",
   "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.0",
     "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

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

@@ -143,6 +143,12 @@ 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",
@@ -154,8 +160,9 @@ export const myChat = chat.agent({
       })()
     );
   },
-  run: async ({ messages, signal }) =>
-    streamText({ ...chat.toStreamTextOptions({ registry }), messages, abortSignal: signal, stopWhen: stepCountIs(15) }),
+  registry,
+  run: async ({ messages, signal, streamText }) =>
+    streamText({ messages, abortSignal: signal, stopWhen: stepCountIs(15) }),
 });
 ```
 
@@ -163,8 +170,9 @@ 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 is auto-injected by `chat.toStreamTextOptions()`; a `prepareStep`
-you pass after the spread wins.
+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.
 
 ```ts
 compaction: {
@@ -177,29 +185,53 @@ compaction: {
 },
 ```
 
-### 5. Actions: mutate state without a turn
-
-`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.
+### 5. Actions: edit state, and optionally answer
+
+`actionSchema` validates; `onAction` edits via `chat.history` (`slice`, `replace`, `rollbackTo`,
+`remove`, `getPendingToolCalls`, `extractNewToolResults`). An action fires `hydrateMessages` and
+`onAction` only. Return nothing for an edit-only action: no model call, and the turn counter does not
+advance. Return `chat.turn()` to answer after the edit: a turn runs on the edited history with
+everything a turn has (the agent's system prompt and tools, steering, compaction, injected
+instructions, `onTurnStart` and `onTurnComplete`, persistence), and `run()` receives it with
+`trigger: "action-turn"`. `onAction` has no `streamText` argument, and returning a
+`StreamTextResult`, string or `UIMessage` from it throws.
+
+Persistence splits by model. With transcript storage (`storage` on `chat.agent`; the platform
+snapshot by default), the runtime hands storage a changeset with `reason: "action"` after an action
+that changed the conversation: an undo is one `truncateAfter`, a regenerate is a `truncateAfter`
+followed by the new answer's `put` when the turn completes, and an edit is a `put` for the edited
+id. 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, and the
+answer that follows `chat.turn()` arrives through `onTurnComplete` like any turn's answer.
 
 ```ts
 export const myChat = chat.agent({
   id: "my-chat",
   actionSchema: z.discriminatedUnion("type", [
     z.object({ type: z.literal("undo") }),
+    z.object({ type: z.literal("regenerate") }),
     z.object({ type: z.literal("rollback"), targetMessageId: z.string() }),
   ]),
   onAction: async ({ action }) => {
-    if (action.type === "undo") chat.history.slice(0, -2);
+    if (action.type === "undo") chat.history.slice(0, -2); // edit only
     if (action.type === "rollback") chat.history.rollbackTo(action.targetMessageId);
+    if (action.type === "regenerate") {
+      chat.history.slice(0, -1);
+      return chat.turn(); // answer the edited history
+    }
   },
-  run: async ({ messages, signal }) => streamText({ model: anthropic("claude-sonnet-4-5"), messages, abortSignal: signal }),
+  run: async ({ messages, signal, streamText }) =>
+    streamText({ model: anthropic("claude-sonnet-4-5"), messages, abortSignal: signal }),
 });
 ```
 
-Send from the browser with `transport.sendAction(chatId, { type: "undo" })`, or server-side with
+Send from the browser through `useChat`, so the answer a turn produces renders like any turn:
+`sendMessage(undefined, { body: { action: { type: "regenerate" } } })`, `regenerate({ body: { action } })`,
+or `useChatActions({ sendMessage })` from `@trigger.dev/sdk/chat/react`. For regeneration, use
+`regenerate()` from `useChat` (Vercel AI SDK) which removes the last assistant message before
+streaming the new one; calling `sendMessage` with a regenerate action appends without removal,
+leaving both answers visible. `transport.sendAction(chatId, action)` returns a raw stream the
+caller must read and apply itself. Server-side, use
 `agentChat.sendAction({ type: "rollback", targetMessageId: "msg-3" })`.
 
 ### 6. Fast starts: Head Start
@@ -210,18 +242,19 @@ 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",
-  run: async ({ chat: helper }) =>
+  // `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 }) =>
     streamText({
-      ...helper.toStreamTextOptions({ tools: headStartTools }),
       model: anthropic("claude-sonnet-4-6"),
       system: "You are helpful.",
-      stopWhen: stepCountIs(15),
+      tools: headStartTools,
     }),
 });
 // Next.js: export const POST = chatHandler;  Transport: headStart: "/api/chat"
@@ -248,8 +281,10 @@ 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 SDK's
-auto-injected `prepareStep` folds them in at the next boundary. On the frontend, `usePendingMessages`
+`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`
 returns `pending`, `steer(text)`, `queue(text)`, and `promoteToSteering(id)`; send via
 `transport.sendPendingMessage(chatId, uiMessage, metadata?)`.