@trigger.dev/sdk 0.0.0-prerelease-20260309160514 → 0.0.0-prerelease-20260310150337

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

@@ -1,5 +1,5 @@
 import { AnyTask, Task, type inferSchemaIn, type inferSchemaOut, type TaskIdentifier, type TaskOptions, type TaskSchema, type TaskWithSchema } from "@trigger.dev/core/v3";
-import type { ModelMessage, UIMessage, UIMessageChunk } from "ai";
+import type { ModelMessage, UIMessage, UIMessageChunk, UIMessageStreamOptions } from "ai";
 import { Tool } from "ai";
 import { locals } from "./locals.js";
 import { CHAT_MESSAGES_STREAM_ID, CHAT_STOP_STREAM_ID } from "./chat-constants.js";
@@ -110,6 +110,8 @@ export type ChatTaskWirePayload<TMessage extends UIMessage = UIMessage, TMetadat
     continuation?: boolean;
     /** The run ID of the previous run (only set when `continuation` is true). */
     previousRunId?: string;
+    /** Override warm timeout for this run (seconds). Set by transport.preload(). */
+    warmTimeoutInSeconds?: number;
 };
 /**
  * The payload shape passed to the `chatTask` run function.
@@ -179,6 +181,19 @@ export type PipeChatOptions = {
     /** Override the default span name for this operation. */
     spanName?: string;
 };
+/**
+ * Options for customizing the `toUIMessageStream()` call used when piping
+ * `streamText` results to the frontend.
+ *
+ * Set static defaults via `uiMessageStreamOptions` on `chat.task()`, or
+ * override per-turn via `chat.setUIMessageStreamOptions()`.
+ *
+ * `onFinish`, `originalMessages`, and `generateMessageId` are omitted because
+ * they are managed internally for response capture and message accumulation.
+ * Use `streamText`'s `onFinish` for custom finish handling, or drop down to
+ * raw task mode with `chat.pipe()` for full control.
+ */
+export type ChatUIMessageStreamOptions = Omit<UIMessageStreamOptions<UIMessage>, "onFinish" | "originalMessages" | "generateMessageId">;
 /**
  * An object with a `toUIMessageStream()` method (e.g. `StreamTextResult` from `streamText()`).
  */
@@ -489,6 +504,34 @@ export type ChatTaskOptions<TIdentifier extends string, TClientDataSchema extend
      * @default Same as `turnTimeout`
      */
     preloadTimeout?: string;
+    /**
+     * Default options for `toUIMessageStream()` when auto-piping or using
+     * `turn.complete()` / `chat.pipeAndCapture()`.
+     *
+     * Controls how the `StreamTextResult` is converted to a `UIMessageChunk`
+     * stream — error handling, reasoning/source visibility, metadata, etc.
+     *
+     * Can be overridden per-turn by calling `chat.setUIMessageStreamOptions()`
+     * inside `run()` or lifecycle hooks. Per-turn values are merged on top
+     * of these defaults (per-turn wins on conflicts).
+     *
+     * `onFinish`, `originalMessages`, and `generateMessageId` are managed
+     * internally and cannot be overridden here. Use `streamText`'s `onFinish`
+     * for custom finish handling, or drop to raw task mode for full control.
+     *
+     * @example
+     * ```ts
+     * chat.task({
+     *   id: "my-chat",
+     *   uiMessageStreamOptions: {
+     *     sendReasoning: true,
+     *     onError: (error) => error instanceof Error ? error.message : "An error occurred.",
+     *   },
+     *   run: async ({ messages, signal }) => { ... },
+     * });
+     * ```
+     */
+    uiMessageStreamOptions?: ChatUIMessageStreamOptions;
 };
 /**
  * Creates a Trigger.dev task pre-configured for AI SDK chat.
@@ -570,6 +613,28 @@ declare function setTurnTimeoutInSeconds(seconds: number): void;
  * ```
  */
 declare function setWarmTimeoutInSeconds(seconds: number): void;
+/**
+ * Override the `toUIMessageStream()` options for the current turn.
+ *
+ * These options control how the `StreamTextResult` is converted to a
+ * `UIMessageChunk` stream — error handling, reasoning/source visibility,
+ * message metadata, etc.
+ *
+ * Per-turn options are merged on top of the static `uiMessageStreamOptions`
+ * set on `chat.task()`. Per-turn values win on conflicts.
+ *
+ * @example
+ * ```ts
+ * run: async ({ messages, signal }) => {
+ *   chat.setUIMessageStreamOptions({
+ *     sendReasoning: true,
+ *     onError: (error) => error instanceof Error ? error.message : "An error occurred.",
+ *   });
+ *   return streamText({ model, messages, abortSignal: signal });
+ * }
+ * ```
+ */
+declare function setUIMessageStreamOptions(options: ChatUIMessageStreamOptions): void;
 /**
  * Check whether the user stopped generation during the current turn.
  *
@@ -635,6 +700,172 @@ declare function chatDefer(promise: Promise<unknown>): void;
  * ```
  */
 declare function cleanupAbortedParts(message: UIMessage): UIMessage;
+/**
+ * Create a managed stop signal wired to the chat stop input stream.
+ *
+ * Call once at the start of your run. Use `signal` as the abort signal for
+ * `streamText`. Call `reset()` at the start of each turn to get a fresh
+ * per-turn signal. Call `cleanup()` when the run ends.
+ *
+ * @example
+ * ```ts
+ * const stop = chat.createStopSignal();
+ * for (let turn = 0; turn < 100; turn++) {
+ *   stop.reset();
+ *   const result = streamText({ model, messages, abortSignal: stop.signal });
+ *   await chat.pipe(result);
+ *   // ...
+ * }
+ * stop.cleanup();
+ * ```
+ */
+declare function createStopSignal(): {
+    readonly signal: AbortSignal;
+    reset: () => void;
+    cleanup: () => void;
+};
+/**
+ * Signal the frontend that the current turn is complete.
+ *
+ * The `TriggerChatTransport` intercepts this to close the ReadableStream
+ * for the current turn. Call after piping the response stream.
+ *
+ * @example
+ * ```ts
+ * await chat.pipe(result);
+ * await chat.writeTurnComplete();
+ * ```
+ */
+declare function chatWriteTurnComplete(options?: {
+    publicAccessToken?: string;
+}): Promise<void>;
+/**
+ * Pipe a `StreamTextResult` (or similar) to the chat stream and capture
+ * the assistant's response message via `onFinish`.
+ *
+ * Combines `toUIMessageStream()` + `onFinish` callback + `chat.pipe()`.
+ * Returns the captured `UIMessage`, or `undefined` if capture failed.
+ *
+ * @example
+ * ```ts
+ * const result = streamText({ model, messages, abortSignal: signal });
+ * const response = await chat.pipeAndCapture(result, { signal });
+ * if (response) conversation.addResponse(response);
+ * ```
+ */
+declare function pipeChatAndCapture(source: UIMessageStreamable, options?: {
+    signal?: AbortSignal;
+    spanName?: string;
+}): Promise<UIMessage | undefined>;
+/**
+ * Accumulates conversation messages across turns.
+ *
+ * Handles the transport protocol: turn 0 sends full history (replace),
+ * subsequent turns send only new messages (append), regenerate sends
+ * full history minus last assistant message (replace).
+ *
+ * @example
+ * ```ts
+ * const conversation = new chat.MessageAccumulator();
+ * for (let turn = 0; turn < 100; turn++) {
+ *   const messages = await conversation.addIncoming(payload.messages, payload.trigger, turn);
+ *   const result = streamText({ model, messages });
+ *   const response = await chat.pipeAndCapture(result);
+ *   if (response) await conversation.addResponse(response);
+ * }
+ * ```
+ */
+declare class ChatMessageAccumulator {
+    modelMessages: ModelMessage[];
+    uiMessages: UIMessage[];
+    /**
+     * Add incoming messages from the transport payload.
+     * Returns the full accumulated model messages for `streamText`.
+     */
+    addIncoming(messages: UIMessage[], trigger: string, turn: number): Promise<ModelMessage[]>;
+    /**
+     * Add the assistant's response to the accumulator.
+     * Call after `pipeAndCapture` with the captured response.
+     */
+    addResponse(response: UIMessage): Promise<void>;
+}
+export type ChatSessionOptions = {
+    /** Run-level cancel signal (from task context). */
+    signal: AbortSignal;
+    /** Seconds to stay warm between turns before suspending. @default 30 */
+    warmTimeoutInSeconds?: number;
+    /** Duration string for suspend timeout. @default "1h" */
+    timeout?: string;
+    /** Max turns before ending. @default 100 */
+    maxTurns?: number;
+};
+export type ChatTurn = {
+    /** Turn number (0-indexed). */
+    number: number;
+    /** Chat session ID. */
+    chatId: string;
+    /** What triggered this turn. */
+    trigger: string;
+    /** Client data from the transport (`metadata` field on the wire payload). */
+    clientData: unknown;
+    /** Full accumulated model messages — pass directly to `streamText`. */
+    messages: ModelMessage[];
+    /** Full accumulated UI messages — use for persistence. */
+    uiMessages: UIMessage[];
+    /** Combined stop+cancel AbortSignal (fresh each turn). */
+    signal: AbortSignal;
+    /** Whether the user stopped generation this turn. */
+    readonly stopped: boolean;
+    /** Whether this is a continuation run. */
+    continuation: boolean;
+    /**
+     * Easy path: pipe stream, capture response, accumulate it,
+     * clean up aborted parts if stopped, and write turn-complete chunk.
+     */
+    complete(source: UIMessageStreamable): Promise<UIMessage | undefined>;
+    /**
+     * Manual path: just write turn-complete chunk.
+     * Use when you've already piped and accumulated manually.
+     */
+    done(): Promise<void>;
+    /**
+     * Add the response to the accumulator manually.
+     * Use with `chat.pipeAndCapture` when you need control between pipe and done.
+     */
+    addResponse(response: UIMessage): Promise<void>;
+};
+/**
+ * Create a chat session that yields turns as an async iterator.
+ *
+ * Handles: preload wait, stop signals, message accumulation, turn-complete
+ * signaling, and warm/suspend between turns. You control: initialization,
+ * model/tool selection, persistence, and any custom per-turn logic.
+ *
+ * @example
+ * ```ts
+ * import { task } from "@trigger.dev/sdk";
+ * import { chat, type ChatTaskWirePayload } from "@trigger.dev/sdk/ai";
+ * import { streamText } from "ai";
+ * import { openai } from "@ai-sdk/openai";
+ *
+ * export const myChat = task({
+ *   id: "my-chat",
+ *   run: async (payload: ChatTaskWirePayload, { signal }) => {
+ *     const session = chat.createSession(payload, { signal });
+ *
+ *     for await (const turn of session) {
+ *       const result = streamText({
+ *         model: openai("gpt-4o"),
+ *         messages: turn.messages,
+ *         abortSignal: turn.signal,
+ *       });
+ *       await turn.complete(result);
+ *     }
+ *   },
+ * });
+ * ```
+ */
+declare function createChatSession(payload: ChatTaskWirePayload, options: ChatSessionOptions): AsyncIterable<ChatTurn>;
 /**
  * A Proxy-backed, run-scoped data object that appears as `T` to users.
  * Includes helper methods for initialization, dirty tracking, and serialization.
@@ -724,6 +955,8 @@ export declare const chat: {
     setTurnTimeoutInSeconds: typeof setTurnTimeoutInSeconds;
     /** Override the warm timeout at runtime. See {@link setWarmTimeoutInSeconds}. */
     setWarmTimeoutInSeconds: typeof setWarmTimeoutInSeconds;
+    /** Override toUIMessageStream() options for the current turn. See {@link setUIMessageStreamOptions}. */
+    setUIMessageStreamOptions: typeof setUIMessageStreamOptions;
     /** Check if the current turn was stopped by the user. See {@link isStopped}. */
     isStopped: typeof isStopped;
     /** Clean up aborted parts from a UIMessage. See {@link cleanupAbortedParts}. */
@@ -732,4 +965,16 @@ export declare const chat: {
     defer: typeof chatDefer;
     /** Typed chat output stream for writing custom chunks or piping from subtasks. */
     stream: import("@trigger.dev/core/v3").RealtimeDefinedStream<UIMessageChunk>;
+    /** Pre-built input stream for receiving messages from the transport. */
+    messages: import("@trigger.dev/core/v3").RealtimeDefinedInputStream<ChatTaskWirePayload<UIMessage<unknown, import("ai").UIDataTypes, import("ai").UITools>, unknown>>;
+    /** Create a managed stop signal wired to the stop input stream. See {@link createStopSignal}. */
+    createStopSignal: typeof createStopSignal;
+    /** Signal the frontend that the current turn is complete. See {@link chatWriteTurnComplete}. */
+    writeTurnComplete: typeof chatWriteTurnComplete;
+    /** Pipe a stream and capture the response message. See {@link pipeChatAndCapture}. */
+    pipeAndCapture: typeof pipeChatAndCapture;
+    /** Message accumulator class for raw task chat. See {@link ChatMessageAccumulator}. */
+    MessageAccumulator: typeof ChatMessageAccumulator;
+    /** Create a chat session (async iterator). See {@link createChatSession}. */
+    createSession: typeof createChatSession;
 };