@trigger.dev/sdk 0.0.0-prerelease-20260302145933 → 0.0.0-prerelease-20260305142821

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

@@ -1,5 +1,7 @@
-import { Task, type inferSchemaIn, type TaskSchema, type TaskWithSchema } from "@trigger.dev/core/v3";
+import { AnyTask, Task, type inferSchemaIn, type TaskIdentifier, type TaskOptions, type TaskSchema, type TaskWithSchema } from "@trigger.dev/core/v3";
+import type { ModelMessage, UIMessage } from "ai";
 import { Tool, ToolCallOptions } from "ai";
+import { CHAT_MESSAGES_STREAM_ID, CHAT_STOP_STREAM_ID } from "./chat-constants.js";
 export type ToolCallExecutionOptions = Omit<ToolCallOptions, "abortSignal">;
 type ToolResultContent = Array<{
     type: "text";
@@ -19,4 +21,347 @@ export declare const ai: {
     tool: typeof toolFromTask;
     currentToolOptions: typeof getToolOptionsFromMetadata;
 };
-export {};
+/**
+ * Creates a public access token for a chat task.
+ *
+ * This is a convenience helper that creates a multi-use trigger public token
+ * scoped to the given task. Use it in a server action to provide the frontend
+ * `TriggerChatTransport` with an `accessToken`.
+ *
+ * @example
+ * ```ts
+ * // actions.ts
+ * "use server";
+ * import { chat } from "@trigger.dev/sdk/ai";
+ * import type { myChat } from "@/trigger/chat";
+ *
+ * export const getChatToken = () => chat.createAccessToken<typeof myChat>("my-chat");
+ * ```
+ */
+declare function createChatAccessToken<TTask extends AnyTask>(taskId: TaskIdentifier<TTask>): Promise<string>;
+/**
+ * The default stream key used for chat transport communication.
+ * Both `TriggerChatTransport` (frontend) and `pipeChat`/`chatTask` (backend)
+ * use this key by default.
+ */
+export declare const CHAT_STREAM_KEY = "chat";
+export { CHAT_MESSAGES_STREAM_ID, CHAT_STOP_STREAM_ID };
+/**
+ * The payload shape passed to the `chatTask` run function.
+ *
+ * - `messages` contains model-ready messages (converted via `convertToModelMessages`) —
+ *   pass these directly to `streamText`.
+ * - `clientData` contains custom data from the frontend (the `metadata` field from `sendMessage()`).
+ *
+ * The backend accumulates the full conversation history across turns, so the frontend
+ * only needs to send new messages after the first turn.
+ */
+export type ChatTaskPayload = {
+    /** Model-ready messages — pass directly to `streamText({ messages })`. */
+    messages: ModelMessage[];
+    /** The unique identifier for the chat session */
+    chatId: string;
+    /**
+     * The trigger type:
+     * - `"submit-message"`: A new user message
+     * - `"regenerate-message"`: Regenerate the last assistant response
+     */
+    trigger: "submit-message" | "regenerate-message";
+    /** The ID of the message to regenerate (only for `"regenerate-message"`) */
+    messageId?: string;
+    /** Custom data from the frontend (passed via `metadata` on `sendMessage()` or the transport). */
+    clientData?: unknown;
+};
+/**
+ * Abort signals provided to the `chatTask` run function.
+ */
+export type ChatTaskSignals = {
+    /** Combined signal — fires on run cancel OR stop generation. Pass to `streamText`. */
+    signal: AbortSignal;
+    /** Fires only when the run is cancelled, expired, or exceeds maxDuration. */
+    cancelSignal: AbortSignal;
+    /** Fires only when the frontend stops generation for this turn (per-turn, reset each turn). */
+    stopSignal: AbortSignal;
+};
+/**
+ * The full payload passed to a `chatTask` run function.
+ * Extends `ChatTaskPayload` (the wire payload) with abort signals.
+ */
+export type ChatTaskRunPayload = ChatTaskPayload & ChatTaskSignals;
+/**
+ * Options for `pipeChat`.
+ */
+export type PipeChatOptions = {
+    /**
+     * Override the stream key. Must match the `streamKey` on `TriggerChatTransport`.
+     * @default "chat"
+     */
+    streamKey?: string;
+    /** An AbortSignal to cancel the stream. */
+    signal?: AbortSignal;
+    /**
+     * The target run ID to pipe to.
+     * @default "self" (current run)
+     */
+    target?: string;
+    /** Override the default span name for this operation. */
+    spanName?: string;
+};
+/**
+ * An object with a `toUIMessageStream()` method (e.g. `StreamTextResult` from `streamText()`).
+ */
+type UIMessageStreamable = {
+    toUIMessageStream: (...args: any[]) => AsyncIterable<unknown> | ReadableStream<unknown>;
+};
+/**
+ * Pipes a chat stream to the realtime stream, making it available to the
+ * `TriggerChatTransport` on the frontend.
+ *
+ * Accepts:
+ * - A `StreamTextResult` from `streamText()` (has `.toUIMessageStream()`)
+ * - An `AsyncIterable` of `UIMessageChunk`s
+ * - A `ReadableStream` of `UIMessageChunk`s
+ *
+ * Must be called from inside a Trigger.dev task's `run` function.
+ *
+ * @example
+ * ```ts
+ * import { task } from "@trigger.dev/sdk";
+ * import { chat, type ChatTaskPayload } from "@trigger.dev/sdk/ai";
+ * import { streamText, convertToModelMessages } from "ai";
+ *
+ * export const myChatTask = task({
+ *   id: "my-chat-task",
+ *   run: async (payload: ChatTaskPayload) => {
+ *     const result = streamText({
+ *       model: openai("gpt-4o"),
+ *       messages: payload.messages,
+ *     });
+ *
+ *     await chat.pipe(result);
+ *   },
+ * });
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Works from anywhere inside a task — even deep in your agent code
+ * async function runAgentLoop(messages: CoreMessage[]) {
+ *   const result = streamText({ model, messages });
+ *   await chat.pipe(result);
+ * }
+ * ```
+ */
+declare function pipeChat(source: UIMessageStreamable | AsyncIterable<unknown> | ReadableStream<unknown>, options?: PipeChatOptions): Promise<void>;
+/**
+ * Options for defining a chat task.
+ *
+ * Extends the standard `TaskOptions` but pre-types the payload as `ChatTaskPayload`
+ * and overrides `run` to accept `ChatTaskRunPayload` (with abort signals).
+ *
+ * **Auto-piping:** If the `run` function returns a value with `.toUIMessageStream()`
+ * (like a `StreamTextResult`), the stream is automatically piped to the frontend.
+ *
+ * **Single-run mode:** By default, the task uses input streams so that the
+ * entire conversation lives inside one run. After each AI response, the task
+ * emits a control chunk and suspends via `messagesInput.wait()`. The frontend
+ * transport resumes the same run by sending the next message via input streams.
+ */
+/**
+ * Event passed to the `onChatStart` callback.
+ */
+export type ChatStartEvent = {
+    /** The unique identifier for the chat session. */
+    chatId: string;
+    /** The initial model-ready messages for this conversation. */
+    messages: ModelMessage[];
+    /** Custom data from the frontend (passed via `metadata` on `sendMessage()` or the transport). */
+    clientData: unknown;
+};
+/**
+ * Event passed to the `onTurnComplete` callback.
+ */
+export type TurnCompleteEvent = {
+    /** The unique identifier for the chat session. */
+    chatId: string;
+    /** The full accumulated conversation in model format (all turns so far). */
+    messages: ModelMessage[];
+    /**
+     * The full accumulated conversation in UI format (all turns so far).
+     * This is the format expected by `useChat` — store this for persistence.
+     */
+    uiMessages: UIMessage[];
+    /**
+     * Only the new model messages from this turn (user message(s) + assistant response).
+     * Useful for appending to an existing conversation record.
+     */
+    newMessages: ModelMessage[];
+    /**
+     * Only the new UI messages from this turn (user message(s) + assistant response).
+     * Useful for inserting individual message records instead of overwriting the full history.
+     */
+    newUIMessages: UIMessage[];
+    /** The assistant's response for this turn (undefined if `pipeChat` was used manually). */
+    responseMessage: UIMessage | undefined;
+    /** The turn number (0-indexed). */
+    turn: number;
+};
+export type ChatTaskOptions<TIdentifier extends string> = Omit<TaskOptions<TIdentifier, ChatTaskWirePayload, unknown>, "run"> & {
+    /**
+     * The run function for the chat task.
+     *
+     * Receives a `ChatTaskRunPayload` with the conversation messages, chat session ID,
+     * trigger type, and abort signals (`signal`, `cancelSignal`, `stopSignal`).
+     *
+     * **Auto-piping:** If this function returns a value with `.toUIMessageStream()`,
+     * the stream is automatically piped to the frontend.
+     */
+    run: (payload: ChatTaskRunPayload) => Promise<unknown>;
+    /**
+     * Called on the first turn (turn 0) of a new run, before the `run` function executes.
+     *
+     * Use this to create the chat record in your database when a new conversation starts.
+     *
+     * @example
+     * ```ts
+     * onChatStart: async ({ chatId, messages, clientData }) => {
+     *   await db.chat.create({ data: { id: chatId, userId: clientData.userId } });
+     * }
+     * ```
+     */
+    onChatStart?: (event: ChatStartEvent) => Promise<void> | void;
+    /**
+     * Called after each turn completes (after the response is captured, before waiting
+     * for the next message). Also fires on the final turn.
+     *
+     * Use this to persist the conversation to your database after each assistant response.
+     *
+     * @example
+     * ```ts
+     * onTurnComplete: async ({ chatId, messages }) => {
+     *   await db.chat.update({ where: { id: chatId }, data: { messages } });
+     * }
+     * ```
+     */
+    onTurnComplete?: (event: TurnCompleteEvent) => Promise<void> | void;
+    /**
+     * Maximum number of conversational turns (message round-trips) a single run
+     * will handle before ending. After this many turns the run completes
+     * normally and the next message will start a fresh run.
+     *
+     * @default 100
+     */
+    maxTurns?: number;
+    /**
+     * How long to wait for the next message before timing out and ending the run.
+     * Accepts any duration string (e.g. `"1h"`, `"30m"`).
+     *
+     * @default "1h"
+     */
+    turnTimeout?: string;
+    /**
+     * How long (in seconds) to keep the run warm after each turn before suspending.
+     * During this window the run stays active and can respond instantly to the
+     * next message. After this timeout, the run suspends (frees compute) and waits
+     * via `inputStream.wait()`.
+     *
+     * Set to `0` to suspend immediately after each turn.
+     *
+     * @default 30
+     */
+    warmTimeoutInSeconds?: number;
+};
+/**
+ * Creates a Trigger.dev task pre-configured for AI SDK chat.
+ *
+ * - **Pre-types the payload** as `ChatTaskRunPayload` — includes abort signals
+ * - **Auto-pipes the stream** if `run` returns a `StreamTextResult`
+ * - **Multi-turn**: keeps the conversation in a single run using input streams
+ * - **Stop support**: frontend can stop generation mid-stream via the stop input stream
+ * - For complex flows, use `pipeChat()` from anywhere inside your task code
+ *
+ * @example
+ * ```ts
+ * import { chat } from "@trigger.dev/sdk/ai";
+ * import { streamText, convertToModelMessages } from "ai";
+ * import { openai } from "@ai-sdk/openai";
+ *
+ * export const myChat = chat.task({
+ *   id: "my-chat",
+ *   run: async ({ messages, signal }) => {
+ *     return streamText({
+ *       model: openai("gpt-4o"),
+ *       messages, // already converted via convertToModelMessages
+ *       abortSignal: signal,
+ *     });
+ *   },
+ * });
+ * ```
+ */
+declare function chatTask<TIdentifier extends string>(options: ChatTaskOptions<TIdentifier>): Task<TIdentifier, ChatTaskWirePayload, unknown>;
+/**
+ * Override the turn timeout for subsequent turns in the current run.
+ *
+ * The turn timeout controls how long the run stays suspended (freeing compute)
+ * waiting for the next user message. When it expires, the run completes
+ * gracefully and the next message starts a fresh run.
+ *
+ * Call from inside a `chatTask` run function to adjust based on context.
+ *
+ * @param duration - A duration string (e.g. `"5m"`, `"1h"`, `"30s"`)
+ *
+ * @example
+ * ```ts
+ * run: async ({ messages, signal }) => {
+ *   chat.setTurnTimeout("2h");
+ *   return streamText({ model, messages, abortSignal: signal });
+ * }
+ * ```
+ */
+declare function setTurnTimeout(duration: string): void;
+/**
+ * Override the turn timeout in seconds for subsequent turns in the current run.
+ *
+ * @param seconds - Number of seconds to wait for the next message before ending the run
+ *
+ * @example
+ * ```ts
+ * run: async ({ messages, signal }) => {
+ *   chat.setTurnTimeoutInSeconds(3600); // 1 hour
+ *   return streamText({ model, messages, abortSignal: signal });
+ * }
+ * ```
+ */
+declare function setTurnTimeoutInSeconds(seconds: number): void;
+/**
+ * Override the warm timeout for subsequent turns in the current run.
+ *
+ * The warm timeout controls how long the run stays active (using compute)
+ * after each turn, waiting for the next message. During this window,
+ * responses are instant. After it expires, the run suspends.
+ *
+ * @param seconds - Number of seconds to stay warm (0 to suspend immediately)
+ *
+ * @example
+ * ```ts
+ * run: async ({ messages, signal }) => {
+ *   chat.setWarmTimeoutInSeconds(60);
+ *   return streamText({ model, messages, abortSignal: signal });
+ * }
+ * ```
+ */
+declare function setWarmTimeoutInSeconds(seconds: number): void;
+export declare const chat: {
+    /** Create a chat task. See {@link chatTask}. */
+    task: typeof chatTask;
+    /** Pipe a stream to the chat transport. See {@link pipeChat}. */
+    pipe: typeof pipeChat;
+    /** Create a public access token for a chat task. See {@link createChatAccessToken}. */
+    createAccessToken: typeof createChatAccessToken;
+    /** Override the turn timeout at runtime (duration string). See {@link setTurnTimeout}. */
+    setTurnTimeout: typeof setTurnTimeout;
+    /** Override the turn timeout at runtime (seconds). See {@link setTurnTimeoutInSeconds}. */
+    setTurnTimeoutInSeconds: typeof setTurnTimeoutInSeconds;
+    /** Override the warm timeout at runtime. See {@link setWarmTimeoutInSeconds}. */
+    setWarmTimeoutInSeconds: typeof setWarmTimeoutInSeconds;
+};