Trigger AI SDK chat

.changeset/chilled-cougars-relate.md

@@ -0,0 +1,5 @@
+---
+"@trigger.dev/sdk": patch
+---
+
+Document and guide AI users toward `@trigger.dev/ai` as the recommended package for AI SDK integrations, while keeping `@trigger.dev/sdk/ai` for backwards compatibility.

.changeset/curly-radios-visit.md

@@ -0,0 +1,24 @@
+---
+"@trigger.dev/ai": minor
+---
+
+Add a new `@trigger.dev/ai` package with:
+
+- `ai.tool(...)` and `ai.currentToolOptions()` helpers for AI SDK tool calling ergonomics
+- a typed `TriggerChatTransport` that plugs into AI SDK UI `useChat()` and runs chat backends as Trigger.dev tasks
+- rich default task payloads (`chatId`, trigger metadata, messages, request context) with optional payload mapping
+- reconnect-aware stream handling on top of Trigger.dev Realtime Streams v2
+- strict `baseURL` normalization/validation (trimming, path-safe slash handling, absolute `http(s)` URLs only, no query/hash/credentials)
+- rejection of internal whitespace characters in normalized `baseURL` values
+- rejection of internal invisible separator characters (e.g. zero-width/BOM characters) in normalized `baseURL` values
+- rejection of invisible separator wrappers around otherwise valid `baseURL` values (for example `\u200B...` and `\u2060...`)
+- support for trimming additional unicode wrapper whitespace (`\u1680`, `\u3000`) while still rejecting
+  values that normalize to empty after trimming
+- expanded unicode whitespace handling coverage to include figure space (`\u2007`) and medium
+  mathematical space (`\u205F`) for both wrapper trimming and internal-whitespace rejection
+- expanded invisible-separator rejection coverage to include mongolian vowel separator (`\u180E`)
+  in both wrapper and internal `baseURL` positions
+- expanded unicode spacing coverage to include hair space (`\u200A`), thin space (`\u2009`),
+  punctuation space (`\u2008`), six-per-em space (`\u2006`), and em space (`\u2003`)
+- deterministic baseURL validation error ordering for multi-issue inputs (internal whitespace → protocol → query/hash → credentials)
+- explicit default `baseURL` behavior (`https://api.trigger.dev`) and case-insensitive `HTTP(S)` protocol acceptance

docs/tasks/schemaTask.mdx

@@ -80,8 +80,11 @@ await myTask.trigger({ name: "Alice", age: 30, dob: "2020-01-01" }); // this is
 
 The `ai.tool` function allows you to create an AI tool from an existing `schemaTask` to use with the Vercel [AI SDK](https://vercel.com/docs/ai-sdk):
 
+> `@trigger.dev/ai` is the recommended import path. For backwards compatibility,
+> `@trigger.dev/sdk/ai` continues to work.
+
 ```ts
-import { ai } from "@trigger.dev/sdk/ai";
+import { ai } from "@trigger.dev/ai";
 import { schemaTask } from "@trigger.dev/sdk";
 import { z } from "zod";
 import { generateText } from "ai";
@@ -118,7 +121,7 @@ You can also pass the `experimental_toToolResultContent` option to the `ai.tool`
 ```ts
 import { openai } from "@ai-sdk/openai";
 import { Sandbox } from "@e2b/code-interpreter";
-import { ai } from "@trigger.dev/sdk/ai";
+import { ai } from "@trigger.dev/ai";
 import { schemaTask } from "@trigger.dev/sdk";
 import { generateObject } from "ai";
 import { z } from "zod";
@@ -183,7 +186,7 @@ export const chartTool = ai.tool(chartTask, {
 You can access the current tool execution options inside the task run function using the `ai.currentToolOptions()` function:
 
 ```ts
-import { ai } from "@trigger.dev/sdk/ai";
+import { ai } from "@trigger.dev/ai";
 import { schemaTask } from "@trigger.dev/sdk";
 import { z } from "zod";
 

docs/tasks/streams.mdx

@@ -517,6 +517,242 @@ const { parts, error } = useRealtimeStream(streamDef, runId, {
 });
 ```
 
+## AI SDK `useChat` transport with Trigger.dev tasks
+
+If you want to use AI SDK UI's `useChat()` on the frontend and run the backend as a Trigger.dev task,
+use the `@trigger.dev/ai` transport.
+
+### Install
+
+```bash
+npm add @trigger.dev/ai @ai-sdk/react ai
+```
+
+### Define a typed stream
+
+```ts
+// app/streams.ts
+import { streams } from "@trigger.dev/sdk";
+import { UIMessageChunk } from "ai";
+
+export const aiStream = streams.define<UIMessageChunk>({
+  id: "ai",
+});
+```
+
+### Create a task that accepts rich chat transport payload
+
+```ts
+// trigger/chat-task.ts
+import { openai } from "@ai-sdk/openai";
+import type { TriggerChatTransportPayload } from "@trigger.dev/ai";
+import { task } from "@trigger.dev/sdk";
+import { convertToModelMessages, streamText, UIMessage } from "ai";
+import { aiStream } from "@/app/streams";
+
+type ChatPayload = TriggerChatTransportPayload<UIMessage>;
+
+export const aiChatTask = task({
+  id: "ai-chat",
+  run: async (payload: ChatPayload) => {
+    const result = streamText({
+      model: openai("gpt-4o"),
+      messages: convertToModelMessages(payload.messages),
+    });
+
+    const { waitUntilComplete } = aiStream.pipe(result.toUIMessageStream());
+    await waitUntilComplete();
+  },
+});
+```
+
+### Use `useChat()` with Trigger chat transport
+
+```tsx
+"use client";
+
+import { useChat } from "@ai-sdk/react";
+import { TriggerChatTransport } from "@trigger.dev/ai";
+import { aiStream } from "@/app/streams";
+
+export function Chat({ triggerToken }: { triggerToken: string }) {
+  const chat = useChat({
+    transport: new TriggerChatTransport({
+      task: "ai-chat",
+      stream: aiStream,
+      accessToken: triggerToken,
+      timeoutInSeconds: 120,
+    }),
+  });
+
+  return (
+    <form
+      onSubmit={(event) => {
+        event.preventDefault();
+        chat.sendMessage({ text: "Hello!" });
+      }}
+    >
+      <button type="submit">Send</button>
+    </form>
+  );
+}
+```
+
+The default payload sent to your task is a rich, typed object that includes:
+
+- `chatId`
+- `trigger` (`"submit-message"` or `"regenerate-message"`)
+- `messageId`
+- `messages`
+- `request` (`headers`, `body`, and `metadata`)
+
+### Advanced transport options
+
+`TriggerChatTransport` also supports:
+
+- `payloadMapper` (sync or async) for custom task payload shapes
+- `triggerOptions` as an object or resolver function (sync or async)
+- `runStore` for custom reconnect-state persistence (including async stores)
+- `onTriggeredRun` callback (sync or async) to persist or observe run IDs
+- `onError` callback to observe non-fatal transport issues
+- headers passed through transport can be object, `Headers`, or tuple arrays
+
+`onError` receives phase-aware details (`payloadMapper`, `triggerOptions`, `triggerTask`,
+`streamSubscribe`, `onTriggeredRun`, `consumeTrackingStream`, `reconnect`) plus `chatId`,
+optional `runId`, and the underlying `error` (non-Error throws are normalized to `Error`
+instances).
+
+Run-store cleanup is handled as best effort, and cleanup failures won't mask the original
+transport failure that triggered `onError`. Cleanup still attempts both persistence steps
+(`set` inactive state and `delete`) even when one step fails.
+
+```ts
+import type { TriggerChatRunState, TriggerChatRunStore } from "@trigger.dev/ai";
+
+class MemoryRunStore implements TriggerChatRunStore {
+  private runs = new Map<string, TriggerChatRunState>();
+
+  async get(chatId: string) {
+    return this.runs.get(chatId);
+  }
+
+  async set(state: TriggerChatRunState) {
+    this.runs.set(state.chatId, state);
+  }
+
+  async delete(chatId: string) {
+    this.runs.delete(chatId);
+  }
+}
+```
+
+`reconnectToStream()` only resumes active streams. When a stream completes or errors,
+the transport clears stored run state and future reconnect attempts return `null`.
+If stale inactive reconnect state cannot be cleaned up, reconnect still returns `null` and
+the failure is surfaced through `onError` with phase `reconnect`.
+Subsequent reconnect calls will retry stale inactive-state cleanup until it succeeds.
+If `onError` is omitted, reconnect still returns `null` and continues without callback reporting.
+
+`baseURL` defaults to `https://api.trigger.dev` when omitted.
+It supports optional path prefixes and trailing slashes; both trigger and stream URLs
+are normalized consistently, surrounding whitespace is trimmed before normalization, and
+the resulting value must not be empty. The value must also be a valid absolute URL using
+the `http` or `https` protocol, without query parameters, hash fragments, or embedded
+username/password credentials.
+Protocol matching is case-insensitive (`HTTP://...` and `HTTPS://...` are accepted).
+
+Examples:
+
+- ✅ `https://api.trigger.dev`
+- ✅ `https://api.trigger.dev/custom-prefix`
+- ✅ `  https://api.trigger.dev/custom-prefix///   ` (trimmed + normalized)
+- ✅ `\n\thttps://api.trigger.dev/custom-prefix/\t\n` (newline/tab wrappers trimmed)
+- ✅ `https://api.trigger.dev/custom%20prefix` (percent-encoded whitespace)
+- ✅ `https://api.trigger.dev/custom%3Fprefix%23segment` (percent-encoded `?` / `#`)
+- ✅ `\u00A0https://api.trigger.dev/custom-prefix/\u00A0` (non-breaking-space wrapper trimmed)
+- ✅ `\u1680https://api.trigger.dev/custom-prefix/\u1680` (ogham-space-mark wrapper trimmed)
+- ✅ `\u2007https://api.trigger.dev/custom-prefix/\u2007` (figure-space wrapper trimmed)
+- ✅ `\u200Ahttps://api.trigger.dev/custom-prefix/\u200A` (hair-space wrapper trimmed)
+- ✅ `\u2009https://api.trigger.dev/custom-prefix/\u2009` (thin-space wrapper trimmed)
+- ✅ `\u2008https://api.trigger.dev/custom-prefix/\u2008` (punctuation-space wrapper trimmed)
+- ✅ `\u2006https://api.trigger.dev/custom-prefix/\u2006` (six-per-em-space wrapper trimmed)
+- ✅ `\u2003https://api.trigger.dev/custom-prefix/\u2003` (em-space wrapper trimmed)
+- ✅ `\u205Fhttps://api.trigger.dev/custom-prefix/\u205F` (medium-mathematical-space wrapper trimmed)
+- ✅ `\u3000https://api.trigger.dev/custom-prefix/\u3000` (ideographic-space wrapper trimmed)
+- ✅ `\uFEFFhttps://api.trigger.dev/custom-prefix/\uFEFF` (BOM wrapper trimmed)
+- ❌ `\u2060https://api.trigger.dev/custom-prefix/\u2060` (word-joiner wrappers are rejected)
+- ❌ `\u200Bhttps://api.trigger.dev/custom-prefix/\u200B` (zero-width-space wrappers are rejected)
+- ❌ `\u200Chttps://api.trigger.dev/custom-prefix/\u200C` (zero-width-non-joiner wrappers are rejected)
+- ❌ `\u200Dhttps://api.trigger.dev/custom-prefix/\u200D` (zero-width-joiner wrappers are rejected)
+- ❌ `\u180Ehttps://api.trigger.dev/custom-prefix/\u180E` (mongolian-vowel-separator wrappers are rejected)
+- ❌ `https://api.trigger.dev?foo=bar`
+- ❌ `https://api.trigger.dev#fragment`
+- ❌ `https://user:pass@api.trigger.dev`
+- ❌ `ftp://api.trigger.dev`
+- ❌ `ws://api.trigger.dev` / `wss://api.trigger.dev`
+- ❌ `\u1680///\u1680` (empty after trimming wrapper whitespace)
+- ❌ `\u2007///\u2007` (empty after trimming wrapper whitespace)
+- ❌ `\u205F///\u205F` (empty after trimming wrapper whitespace)
+- ❌ `\u180E///\u180E` (rejected as internal invisible-separator whitespace)
+- ❌ `\u3000///\u3000` (empty after trimming wrapper whitespace)
+- ❌ `\n\thttps://api.trigger.dev/base/?query=1\t\n` (query is still rejected after trimming wrappers)
+- ❌ `\n\thttps://api.trigger.dev/base/#fragment\t\n` (hash is still rejected after trimming wrappers)
+- ❌ `\n\thttps://user:pass@api.trigger.dev/base/\t\n` (credentials are still rejected after trimming wrappers)
+- ❌ `\n\tws://api.trigger.dev\t\n` / `\n\twss://api.trigger.dev\t\n` (trimmed wrappers still reject websocket protocols)
+- ❌ `https://api.trigger.dev/\ninternal`
+- ❌ `https://api.trigger.dev/in valid`
+- ❌ `https://api.trigger.dev/\tinternal`
+- ❌ `https://api.trigger.dev/\vinternal`
+- ❌ `https://api.trigger.dev/\finternal`
+- ❌ `https://api.trigger.dev/\rinternal`
+- ❌ `https://api.trigger.dev/\u200Binternal`
+- ❌ `https://api.trigger.dev/\u200Cinternal`
+- ❌ `https://api.trigger.dev/\u200Dinternal`
+- ❌ `https://api.trigger.dev/\u1680internal`
+- ❌ `https://api.trigger.dev/\u2007internal`
+- ❌ `https://api.trigger.dev/\u200Ainternal`
+- ❌ `https://api.trigger.dev/\u2009internal`
+- ❌ `https://api.trigger.dev/\u2008internal`
+- ❌ `https://api.trigger.dev/\u2006internal`
+- ❌ `https://api.trigger.dev/\u2003internal`
+- ❌ `https://api.trigger.dev/\u202Finternal`
+- ❌ `https://api.trigger.dev/\u205Finternal`
+- ❌ `https://api.trigger.dev/\u180Einternal`
+- ❌ `https://api.trigger.dev/\u3000internal`
+- ❌ `https://api.trigger.dev/\u2028internal`
+- ❌ `https://api.trigger.dev/\u2029internal`
+- ❌ `https://api.trigger.dev/\u2060internal`
+- ❌ `https://api.trigger.dev/\uFEFFinternal`
+
+Validation errors use these exact messages:
+
+- `baseURL must not be empty`
+- `baseURL must be a valid absolute URL`
+- `baseURL must not contain internal whitespace characters`
+- `baseURL must use http or https protocol`
+- `baseURL must not include query parameters or hash fragments`
+- `baseURL must not include username or password credentials`
+
+The internal-whitespace error also applies to invisible separator characters
+like `\u200B`, `\u200C`, `\u200D`, `\u2060`, and `\uFEFF`.
+
+When multiple issues are present, validation order is deterministic:
+internal whitespace → protocol → query/hash → credentials.
+
+Examples of ordering:
+
+- `ftp://example.com?x=1` → `baseURL must use http or https protocol`
+- `https://user:pass@example.com?x=1` → `baseURL must not include query parameters or hash fragments`
+- `ftp://user:pass@example.com/in valid?x=1` → `baseURL must not contain internal whitespace characters`
+- `ftp://user:pass@example.com/\u2060invalid?x=1#fragment` → `baseURL must not contain internal whitespace characters`
+- `ftp://user:pass@example.com/\u180Einvalid?x=1#fragment` → `baseURL must not contain internal whitespace characters`
+
+For richer TypeScript ergonomics in app code, `@trigger.dev/ai` also exports:
+
+- `TriggerChatHeadersInput`
+- `TriggerChatSendMessagesOptions`
+- `TriggerChatReconnectOptions`
+
 ## Complete Example: AI Streaming
 
 ### Define the stream

packages/ai/CHANGELOG.md

@@ -0,0 +1,43 @@
+# @trigger.dev/ai
+
+## 4.3.3
+
+### Added
+
+- Introduced a new `@trigger.dev/ai` package.
+- Added `ai.tool(...)` and `ai.currentToolOptions()` helpers for AI SDK tool ergonomics.
+- Added `TriggerChatTransport` / `createTriggerChatTransport(...)` for AI SDK `useChat()` integrations powered by Trigger.dev tasks and Realtime Streams v2.
+- Added rich default chat payload typing (`chatId`, `trigger`, `messageId`, `messages`, request context) and mapper hooks for custom payloads.
+- Added support for async payload mappers, async trigger option resolvers, and async `onTriggeredRun` callbacks.
+- Added support for tuple-style header input normalization and typing.
+- Added reconnect lifecycle handling that cleans run state after completion/error and gracefully returns `null` when reconnect cannot be resumed.
+- Added explicit helper option types for chat send/reconnect request inputs.
+- Added optional `onError` callback support for observing non-fatal transport issues.
+- Added phase-aware `onError` reporting across send, stream-subscribe, reconnect, and stream-consumption paths.
+- Added normalization of non-Error throw values into Error instances before `onError` reporting.
+- Added best-effort run-store cleanup so cleanup failures do not mask root transport errors.
+- Improved best-effort run-store cleanup to attempt both inactive-state writes and deletes even if one step fails.
+- Added reconnect cleanup error reporting for stale inactive state while still returning `null`.
+- Added retry semantics for stale inactive reconnect cleanup on subsequent reconnect attempts.
+- Added consistent baseURL normalization for trigger and stream endpoints (including path prefixes and trailing slashes).
+- Added surrounding-whitespace trimming for `baseURL` before endpoint normalization.
+- Added explicit validation that `baseURL` is non-empty after normalization.
+- Added explicit validation that `baseURL` is a valid absolute URL.
+- Added explicit validation that `baseURL` uses `http` or `https`.
+- Added explicit validation that `baseURL` excludes query parameters and hash fragments.
+- Added explicit validation that `baseURL` excludes username/password credentials.
+- Added explicit validation that `baseURL` excludes internal whitespace/invisible separator characters (including zero-width/BOM characters).
+- Clarified that invisible separator characters are rejected even when wrapped around an otherwise valid `baseURL`.
+- Added explicit test/docs coverage for additional unicode-trimmable wrappers (`\u1680`, `\u3000`) and
+  confirmed empty-after-trim values still throw `baseURL must not be empty`.
+- Expanded unicode whitespace coverage with `\u2007` (figure space) and `\u205F` (medium mathematical space)
+  across internal-whitespace rejection, wrapper trimming acceptance, and empty-after-trim validation.
+- Expanded invisible-separator coverage to reject `\u180E` (mongolian vowel separator) in both
+  internal and wrapper `baseURL` positions.
+- Expanded unicode space coverage to include `\u200A` (hair space), `\u2009` (thin space),
+  `\u2008` (punctuation space), `\u2006` (six-per-em space), and `\u2003` (em space)
+  across wrapper-trimming acceptance and internal-whitespace rejection scenarios.
+- Documented that `HTTP://` and `HTTPS://` are accepted (case-insensitive protocol matching).
+- Added deterministic validation ordering for multi-issue baseURL values
+  (internal whitespace → protocol → query/hash → credentials).
+- Documented explicit default `baseURL` value (`https://api.trigger.dev`) when omitted.