@trigger.dev/sdk 4.5.0-rc.5 → 4.5.0-rc.7

package/docs/wait-until.mdx

@@ -0,0 +1,53 @@
+---
+title: "Wait until"
+description: "Wait until a date, then continue execution."
+---
+
+import PausedExecutionFree from "/snippets/paused-execution-free.mdx"
+
+This example sends a reminder email to a user at the specified datetime.
+
+```ts /trigger/reminder-email.ts
+export const sendReminderEmail = task({
+  id: "send-reminder-email",
+  run: async (payload: { to: string; name: string; date: string }) => {
+    //wait until the date
+    await wait.until({ date: new Date(payload.date) });
+
+    //todo send email
+    const { data, error } = await resend.emails.send({
+      from: "hello@trigger.dev",
+      to: payload.to,
+      subject: "Don't forget…",
+      html: `<p>Hello ${payload.name},</p><p>...</p>`,
+    });
+  },
+});
+```
+
+This allows you to write linear code without having to worry about the complexity of scheduling or managing cron jobs.
+
+<PausedExecutionFree />
+
+## `throwIfInThePast`
+
+You can optionally throw an error if the date is already in the past when the function is called:
+
+```ts
+await wait.until({ date: new Date(date), throwIfInThePast: true });
+```
+
+You can of course use try/catch if you want to do something special in this case.
+
+## Wait idempotency
+
+You can pass an idempotency key to any wait function, allowing you to skip waits if the same idempotency key is used again. This can be useful if you want to skip waits when retrying a task, for example:
+
+```ts
+// Specify the idempotency key and TTL when waiting until a date:
+await wait.until({
+  date: futureDate,
+  idempotencyKey: "my-idempotency-key",
+  idempotencyKeyTTL: "1h",
+});
+```

package/docs/wait.mdx

@@ -0,0 +1,18 @@
+---
+title: "Wait: Overview"
+sidebarTitle: "Overview"
+description: "During your run you can wait for a period of time or for something to happen."
+---
+
+import PausedExecutionFree from "/snippets/paused-execution-free.mdx";
+
+Waiting allows you to write complex tasks as a set of async code, without having to schedule another task or poll for changes.
+
+<PausedExecutionFree />
+
+| Function                                          | What it does                                                     |
+| :------------------------------------------------ | :--------------------------------------------------------------- |
+| [wait.for()](/wait-for)                           | Waits for a specific period of time, e.g. 1 day.                |
+| [wait.until()](/wait-until)                       | Waits until the provided `Date`.                                 |
+| [wait.forToken()](/wait-for-token)                | Pauses runs until a token is completed.                          |
+| [inputStream.wait()](/tasks/streams#wait--suspend-until-data-arrives) | Pauses runs until data arrives on an input stream. |

package/docs/writing-tasks-introduction.mdx

@@ -0,0 +1,33 @@
+---
+title: "Writing tasks: Overview"
+sidebarTitle: "Overview"
+description: "Tasks are the core of Trigger.dev. They are long-running processes that are triggered by events."
+---
+
+import ExamplesCards from "/snippets/examples-cards.mdx";
+
+Before digging deeper into the details of writing tasks, you should read the [fundamentals of tasks](/tasks/overview) to understand what tasks are and how they work.
+
+## Writing tasks
+
+| Topic                                        | Description                                                                                         |
+| :------------------------------------------- | :-------------------------------------------------------------------------------------------------- |
+| [Logging](/logging)                          | View and send logs and traces from your tasks.                                                      |
+| [Errors & retrying](/errors-retrying)        | How to deal with errors and write reliable tasks.                                                   |
+| [Wait](/wait)                                | Wait for periods of time or for external events to occur before continuing.                         |
+| [Concurrency & Queues](/queue-concurrency)   | Configure what you want to happen when there is more than one run at a time.                        |
+| [Realtime notifications](/realtime/overview) | Send realtime notifications from your task that you can subscribe to from your backend or frontend. |
+| [Versioning](/versioning)                    | How versioning works.                                                                               |
+| [Machines](/machines)                        | Configure the CPU and RAM of the machine your task runs on                                          |
+| [Idempotency](/idempotency)                  | Protect against mutations happening twice.                                                          |
+| [Replaying](/replaying)                      | You can replay a single task or many at once with a new version of your code.                       |
+| [Max duration](/runs/max-duration)           | Set a maximum duration for your task to run.                                                        |
+| [Tags](/tags)                                | Tags allow you to easily filter runs in the dashboard and when using the SDK.                       |
+| [Metadata](/runs/metadata)                   | Attach a small amount of data to a run and update it as the run progresses.                         |
+| [Usage](/run-usage)                          | Get compute duration and cost from inside a run, or for a specific block of code.                   |
+| [Context](/context)                          | Access the context of the task run.                                                                 |
+| [Bulk actions](/bulk-actions)                | Run actions on many task runs at once.                                                              |
+| [Priority](/runs/priority)                   | Specify a priority when triggering a task.                                                          |
+| [Hidden tasks](/hidden-tasks)                | Create tasks that are not exported from your trigger files but can still be executed.               |
+
+<ExamplesCards />

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trigger.dev/sdk",
-  "version": "4.5.0-rc.5",
+  "version": "4.5.0-rc.7",
   "description": "trigger.dev Node.JS SDK",
   "license": "MIT",
   "publishConfig": {
@@ -14,7 +14,9 @@
   "type": "module",
   "sideEffects": false,
   "files": [
-    "dist"
+    "dist",
+    "docs",
+    "skills"
   ],
   "tshy": {
     "selfLink": false,
@@ -64,7 +66,7 @@
   "dependencies": {
     "@opentelemetry/api": "1.9.1",
     "@opentelemetry/semantic-conventions": "1.41.1",
-    "@trigger.dev/core": "4.5.0-rc.5",
+    "@trigger.dev/core": "4.5.0-rc.7",
     "chalk": "^5.2.0",
     "cronstrue": "^2.21.0",
     "debug": "^4.3.4",
@@ -205,10 +207,12 @@
   "types": "./dist/commonjs/v3/index.d.ts",
   "module": "./dist/esm/v3/index.js",
   "scripts": {
-    "clean": "rimraf dist .tshy .tshy-build .turbo",
-    "build": "tshy && pnpm run update-version",
+    "clean": "rimraf dist docs .tshy .tshy-build .turbo",
+    "build": "tshy && pnpm run update-version && pnpm run bundle-docs",
+    "bundle-docs": "tsx ../../scripts/bundleSdkDocs.ts",
     "dev": "tshy --watch",
-    "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.ai-v7.json",
+    "typecheck": "tsc --noEmit",
+    "typecheck:ai-v7": "tsc --noEmit -p tsconfig.ai-v7.json",
     "test": "vitest",
     "update-version": "tsx ../../scripts/updateVersion.ts",
     "check-exports": "attw --pack ."

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

@@ -0,0 +1,296 @@
+---
+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 +
+  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
+  streamText route to chat.agent.
+type: core
+library: trigger.dev
+sources:
+  - docs/ai-chat/overview.mdx
+  - docs/ai-chat/quick-start.mdx
+  - docs/ai-chat/how-it-works.mdx
+  - docs/ai-chat/backend.mdx
+  - docs/ai-chat/frontend.mdx
+  - docs/ai-chat/reference.mdx
+  - docs/ai-chat/types.mdx
+  - docs/ai-chat/tools.mdx
+  - docs/ai-chat/lifecycle-hooks.mdx
+  - docs/ai-chat/error-handling.mdx
+---
+
+# Authoring a chat agent
+
+A `chat.agent` runs an entire conversation as one long-lived Trigger.dev task. It wakes when a
+message arrives, freezes when none do, and in-memory state survives page refreshes, deploys, idle
+gaps, and crashes. Your code is the loop you would write anyway: messages in, `streamText` out.
+There are no API routes. The frontend talks to the agent through a `TriggerChatTransport`, so
+history accumulates server-side and the client ships only the new message each turn.
+
+Works with Vercel AI SDK v5, v6, or v7. On v7 also install `@ai-sdk/otel` so model calls are traced
+(the SDK registers it for you).
+
+## Setup
+
+Three pieces: the agent task, two server actions, and the frontend transport.
+
+### 1. Define the agent
+
+```ts trigger/chat.ts
+import { chat } from "@trigger.dev/sdk/ai";
+import { streamText, stepCountIs } from "ai";
+import { anthropic } from "@ai-sdk/anthropic";
+
+export const myChat = chat.agent({
+  id: "my-chat",
+  run: async ({ messages, signal }) =>
+    streamText({
+      // Spread this FIRST. See "Common mistakes".
+      ...chat.toStreamTextOptions(),
+      model: anthropic("claude-sonnet-4-5"),
+      messages,
+      abortSignal: signal,
+      stopWhen: stepCountIs(15),
+    }),
+});
+```
+
+`run` receives `messages` already converted to `ModelMessage[]` (the SDK converts the frontend's
+`UIMessage[]` for you) plus a `signal` that aborts on stop or cancel. Returning the
+`StreamTextResult` auto-pipes it to the frontend.
+
+### 2. Add two server actions
+
+Both run on your server, so the browser never holds your environment secret key. This is also
+where per-user / per-plan authorization and any paired DB writes live.
+
+```ts app/actions.ts
+"use server";
+import { auth } from "@trigger.dev/sdk";
+import { chat } from "@trigger.dev/sdk/ai";
+
+// Creates the Session + first run, returns a session PAT. Idempotent on (env, chatId).
+export const startChatSession = chat.createStartSessionAction("my-chat");
+
+// Pure mint. The transport calls this on 401/403 to refresh an expired token.
+export async function mintChatAccessToken(chatId: string) {
+  return auth.createPublicToken({
+    scopes: { read: { sessions: chatId }, write: { sessions: chatId } },
+    expirationTime: "1h",
+  });
+}
+```
+
+### 3. Wire the frontend
+
+```tsx app/components/chat.tsx
+"use client";
+import { useState } from "react";
+import { useChat } from "@ai-sdk/react";
+import { useTriggerChatTransport } from "@trigger.dev/sdk/chat/react";
+import type { myChat } from "@/trigger/chat";
+import { mintChatAccessToken, startChatSession } from "@/app/actions";
+
+export function Chat() {
+  const transport = useTriggerChatTransport<typeof myChat>({
+    task: "my-chat", // typeof myChat gives compile-time task-id validation
+    accessToken: ({ chatId }) => mintChatAccessToken(chatId),
+    startSession: ({ chatId, clientData }) => startChatSession({ chatId, clientData }),
+  });
+
+  const { messages, sendMessage, stop, status } = useChat({ transport });
+  const [input, setInput] = useState("");
+  // render messages, a form that calls sendMessage({ text: input }),
+  // and a Stop button (onClick={stop}) while status === "streaming".
+}
+```
+
+The transport is memoized (created once, reused across renders). Passing `typeof myChat` flows the
+agent's message type through `useChat`.
+
+## Core patterns
+
+### 1. Return vs pipe
+
+Return the `streamText` result from `run` for the simple case. When `streamText` is called deep
+inside nested helpers, call `await chat.pipe(result)` from anywhere in the task instead, and let
+`run` resolve `void`.
+
+```ts
+export const agentChat = chat.agent({
+  id: "agent-chat",
+  run: async ({ messages }) => {
+    await runAgentLoop(messages); // don't return; pipe inside
+  },
+});
+
+async function runAgentLoop(messages: ModelMessage[]) {
+  const result = streamText({
+    ...chat.toStreamTextOptions(),
+    model: anthropic("claude-sonnet-4-5"),
+    messages,
+  });
+  await chat.pipe(result); // works from anywhere in the task
+}
+```
+
+### 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 to `chat.toStreamTextOptions({ tools })`. One declaration flows everywhere.
+
+```ts
+import { tool, stepCountIs } from "ai";
+import { z } from "zod";
+
+const tools = {
+  searchDocs: tool({
+    description: "Search the docs.",
+    inputSchema: z.object({ query: z.string() }),
+    execute: async ({ query }) => searchIndex(query),
+  }),
+};
+
+export const myChat = chat.agent({
+  id: "my-chat",
+  tools, // so toModelOutput survives across turns
+  run: async ({ messages, tools, signal }) =>
+    streamText({
+      ...chat.toStreamTextOptions({ tools }), // same set, handed back typed
+      model: anthropic("claude-sonnet-4-5"),
+      messages,
+      abortSignal: signal,
+      stopWhen: stepCountIs(15),
+    }),
+});
+```
+
+`tools` also accepts a function `(event) => ToolSet` resolved per turn, where `event` carries
+`chatId`, `turn`, `continuation`, and `clientData`.
+
+### 3. Custom data parts (persisted vs transient)
+
+`data-*` parts written via `chat.response.write()` in `run()` (or `writer.write()` in hooks)
+persist into `responseMessage.parts` and surface in `onTurnComplete`. Add `transient: true` to
+stream them without persisting. Writes via `chat.stream` are always ephemeral.
+
+```ts
+// In run() - persists, surfaces in onTurnComplete's responseMessage
+chat.response.write({ type: "data-context", data: { searchResults } });
+
+// In a hook via writer - streams but does NOT persist
+writer.write({ type: "data-progress", id: "search", data: { percent: 50 }, transient: true });
+```
+
+### 4. Custom UIMessage type, client data, and builder hooks
+
+For typed `data-*` parts or a tool map, build the agent through `chat.withUIMessage<T>()` and
+`chat.withClientData({ schema })`. Builder methods chain in any order; builder hooks run before the
+matching task hook. `streamOptions` becomes the default `uiMessageStreamOptions` (shallow-merged,
+agent wins).
+
+```ts
+export const myChat = chat
+  .withUIMessage<MyChatUIMessage>({ streamOptions: { sendReasoning: true } })
+  .withClientData({ schema: z.object({ userId: z.string() }) })
+  .agent({
+    id: "my-chat",
+    tools: myTools,
+    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 }),
+  });
+```
+
+Build `MyChatUIMessage` as `UIMessage<unknown, MyDataTypes, InferUITools<typeof tools>>` (or, for
+tools only, `InferChatUIMessageFromTools<typeof tools>` from `@trigger.dev/sdk/ai`). On the
+frontend, narrow `useChat` with `InferChatUIMessage<typeof myChat>` from `@trigger.dev/sdk/chat/react`.
+
+### 5. Lifecycle hooks and stop
+
+`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
+```
+
+`onBoot` fires once per worker process (every fresh boot, including continuation runs) and is where
+`chat.local`, DB connections, and per-process state belong. `onChatStart` fires only on the chat's
+first message. Suspend/resume use `onChatSuspend` / `onChatResume`. Config options include
+`tools`, `clientDataSchema`, `maxTurns` (100), `turnTimeout` ("1h"), `idleTimeoutInSeconds` (30),
+`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
+`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) });
+```
+
+### 6. Migrating from a plain AI SDK `streamText` route
+
+There is no API route in this model. The transport replaces the route round-trip, so:
+
+- 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.
+- On the client, swap the `api` URL for `useTriggerChatTransport`; `useChat` stays the same shape.
+
+## Common mistakes
+
+- **CRITICAL: forgetting `...chat.toStreamTextOptions()`.**
+  ```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 });
+  ```
+  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 `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
+  model keeps generating server-side.
+
+- **Initializing `chat.local` in `onChatStart`.** Initialize it in `onBoot`. `onChatStart` fires
+  once per chat, so continuation runs skip it and crash with
+  `chat.local can only be modified after initialization`. `onBoot` fires on every fresh worker.
+
+- **Minting tokens in the browser.** Never expose the environment secret key client-side. Mint via
+  the two server actions; the transport calls them.
+
+- **Clearing `lastEventId` on `chat.endRun()`.** Keep the cursor for the Session lifetime; clear it
+  only when the Session itself closes. It is sessionId-keyed, so clearing forces a resubscribe from
+  `seq_num=0` that can hit the prior turn's stale `turn-complete` and close the stream empty.
+
+- **Returning the raw error from `uiMessageStreamOptions.onError`.** It leaks internals (keys,
+  stack traces). Return a sanitized string instead.
+
+## References
+
+- `trigger-chat-agent-advanced` skill - lifecycle hooks in depth, sessions, raw-task primitives
+  (`chat.createSession`, `chat.customAgent`, `chat.stream`), compaction, HITL approvals, recovery.
+- `trigger-realtime-and-frontend` skill - Realtime hooks and frontend streaming beyond the chat transport.
+- `trigger-authoring-tasks` skill - base `task()` semantics, `ctx`, and standard lifecycle hooks.
+
+Reference docs ship beside this skill in the same package, read them locally (no network), pinned to your installed version. The `sources:` frontmatter above lists every doc this skill draws from, all under `@trigger.dev/sdk/docs/ai-chat/`. Start with `quick-start.mdx`, `backend.mdx`, `tools.mdx`, `types.mdx`, `frontend.mdx`.
+
+A `chat.agent` is a Trigger.dev task, so it builds and deploys like any other. For `trigger.config.ts` and build extensions (Prisma, Playwright, Python, FFmpeg, etc. — e.g. when a tool needs them), read the bundled config docs under `@trigger.dev/sdk/docs/config/` (extensions are in `config/extensions/`, starting with `overview.mdx`).
+
+## Version
+
+This skill is bundled inside `@trigger.dev/sdk` and read directly from `node_modules`, so it always matches your installed SDK version (see the adjacent `package.json`). The full documentation for these APIs ships alongside it under `@trigger.dev/sdk/docs/`.