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

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

@@ -1,7 +1,8 @@
 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, LanguageModelUsage } from "ai";
 import { Tool } from "ai";
 import { locals } from "./locals.js";
+import type { ResolvedPrompt } from "./prompt.js";
 import { CHAT_MESSAGES_STREAM_ID, CHAT_STOP_STREAM_ID } from "./chat-constants.js";
 export type ToolCallExecutionOptions = {
     toolCallId: string;
@@ -110,6 +111,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 idle timeout for this run (seconds). Set by transport.preload(). */
+    idleTimeoutInSeconds?: number;
 };
 /**
  * The payload shape passed to the `chatTask` run function.
@@ -159,7 +162,389 @@ export type ChatTaskSignals = {
  * The full payload passed to a `chatTask` run function.
  * Extends `ChatTaskPayload` (the wire payload) with abort signals.
  */
-export type ChatTaskRunPayload<TClientData = unknown> = ChatTaskPayload<TClientData> & ChatTaskSignals;
+export type ChatTaskRunPayload<TClientData = unknown> = ChatTaskPayload<TClientData> & ChatTaskSignals & {
+    /** Token usage from the previous turn. Undefined on turn 0. */
+    previousTurnUsage?: LanguageModelUsage;
+    /** Cumulative token usage across all completed turns so far. */
+    totalUsage: LanguageModelUsage;
+};
+/** Convenience re-export of the AI SDK's `LanguageModelUsage` type. */
+export type ChatTurnUsage = LanguageModelUsage;
+/**
+ * Replace the accumulated conversation messages for the current run.
+ *
+ * Call from `onTurnStart` to compact before `run()` executes, or from
+ * `onTurnComplete` to compact before the next turn. Takes `UIMessage[]`
+ * and converts to `ModelMessage[]` internally.
+ */
+declare function setChatMessages(uiMessages: UIMessage[]): void;
+/** State stored in locals during prepareStep compaction. */
+interface CompactionState {
+    summary: string;
+    baseResponseMessageCount: number;
+}
+/**
+ * Event passed to `summarize` callbacks.
+ */
+export type SummarizeEvent = {
+    /** The current model messages to summarize. */
+    messages: ModelMessage[];
+    /** Full usage object from the triggering step/turn. */
+    usage?: LanguageModelUsage;
+    /** Cumulative token usage across all completed turns. Present in chat.task contexts. */
+    totalUsage?: LanguageModelUsage;
+    /** The chat session ID (if running inside a chat.task). */
+    chatId?: string;
+    /** The current turn number (0-indexed, if inside a chat.task). */
+    turn?: number;
+    /** Custom data from the frontend (if inside a chat.task). */
+    clientData?: unknown;
+    /**
+     * Where compaction is running:
+     * - `"inner"` — between tool-call steps (prepareStep)
+     * - `"outer"` — between turns
+     */
+    source?: "inner" | "outer";
+    /** The step number (0-indexed). Only present when `source` is `"inner"`. */
+    stepNumber?: number;
+};
+/**
+ * Event passed to `compactUIMessages` and `compactModelMessages` callbacks.
+ */
+export type CompactMessagesEvent = {
+    /** The generated summary text. */
+    summary: string;
+    /** The current UI messages (full conversation). */
+    uiMessages: UIMessage[];
+    /** The current model messages (full conversation). */
+    modelMessages: ModelMessage[];
+    /** The chat session ID. */
+    chatId: string;
+    /** The current turn number (0-indexed). */
+    turn: number;
+    /** Custom data from the frontend. */
+    clientData?: unknown;
+    /**
+     * Where compaction is running:
+     * - `"inner"` — between tool-call steps (prepareStep)
+     * - `"outer"` — between turns
+     */
+    source: "inner" | "outer";
+};
+/**
+ * Options for the `compaction` field on `chat.task()`.
+ *
+ * Handles compaction automatically in both the inner loop (prepareStep, between
+ * tool-call steps) and the outer loop (between turns, for single-step responses
+ * where prepareStep never fires).
+ */
+export type ChatTaskCompactionOptions = {
+    /** Decide whether to compact. Return true to trigger compaction. */
+    shouldCompact: (event: ShouldCompactEvent) => boolean | Promise<boolean>;
+    /** Generate a summary from the current messages. Return the summary text. */
+    summarize: (event: SummarizeEvent) => Promise<string>;
+    /**
+     * Transform UI messages after compaction (what gets persisted and displayed).
+     * Default: preserve all UI messages unchanged.
+     *
+     * @example
+     * ```ts
+     * // Flatten to summary
+     * compactUIMessages: ({ summary }) => [{
+     *   id: generateId(), role: "assistant",
+     *   parts: [{ type: "text", text: `[Summary]\n\n${summary}` }],
+     * }],
+     *
+     * // Summary + keep last 4 messages
+     * compactUIMessages: ({ uiMessages, summary }) => [
+     *   { id: generateId(), role: "assistant",
+     *     parts: [{ type: "text", text: `[Summary]\n\n${summary}` }] },
+     *   ...uiMessages.slice(-4),
+     * ],
+     * ```
+     */
+    compactUIMessages?: (event: CompactMessagesEvent) => UIMessage[] | Promise<UIMessage[]>;
+    /**
+     * Transform model messages after compaction (what gets sent to the LLM).
+     * Default: replace all with a single summary message.
+     *
+     * @example
+     * ```ts
+     * // Summary + keep last 2 model messages
+     * compactModelMessages: ({ modelMessages, summary }) => [
+     *   { role: "user", content: summary },
+     *   ...modelMessages.slice(-2),
+     * ],
+     * ```
+     */
+    compactModelMessages?: (event: CompactMessagesEvent) => ModelMessage[] | Promise<ModelMessage[]>;
+};
+/**
+ * Event passed to the `prepareMessages` hook.
+ */
+export type PrepareMessagesEvent<TClientData = unknown> = {
+    /** The messages to transform. Return the transformed array. */
+    messages: ModelMessage[];
+    /** Why messages are being prepared. */
+    reason: "run" | "compaction-rebuild" | "compaction-result";
+    /** The chat session ID. */
+    chatId: string;
+    /** The current turn number (0-indexed). */
+    turn: number;
+    /** Custom data from the frontend. */
+    clientData?: TClientData;
+};
+/**
+ * Data shape for `data-compaction` stream chunks emitted during compaction.
+ * Use to type the `data` field when rendering compaction parts in the frontend.
+ */
+export type CompactionChunkData = {
+    status: "compacting" | "complete";
+    totalTokens: number | undefined;
+};
+/**
+ * Event passed to the `onCompacted` callback.
+ */
+export type CompactedEvent = {
+    /** The generated summary text. */
+    summary: string;
+    /** The messages that were compacted (pre-compaction). */
+    messages: ModelMessage[];
+    /** Number of messages before compaction. */
+    messageCount: number;
+    /** Token usage from the step that triggered compaction. */
+    usage: LanguageModelUsage;
+    /** Total token count that triggered compaction. */
+    totalTokens: number | undefined;
+    /** Input token count from the triggering step. */
+    inputTokens: number | undefined;
+    /** Output token count from the triggering step. */
+    outputTokens: number | undefined;
+    /** The step number where compaction occurred (0-indexed). */
+    stepNumber: number;
+    /** The chat session ID (if running inside a chat.task). */
+    chatId?: string;
+    /** The current turn number (if running inside a chat.task). */
+    turn?: number;
+};
+/**
+ * Event passed to `shouldCompact` callbacks.
+ */
+export type ShouldCompactEvent = {
+    /** The current model messages (full conversation). */
+    messages: ModelMessage[];
+    /** Total token count from the triggering step/turn. */
+    totalTokens: number | undefined;
+    /** Input token count from the triggering step/turn. */
+    inputTokens: number | undefined;
+    /** Output token count from the triggering step/turn. */
+    outputTokens: number | undefined;
+    /** Full usage object from the triggering step/turn. */
+    usage?: LanguageModelUsage;
+    /** Cumulative token usage across all completed turns. Present in chat.task contexts. */
+    totalUsage?: LanguageModelUsage;
+    /** The chat session ID (if running inside a chat.task). */
+    chatId?: string;
+    /** The current turn number (0-indexed, if inside a chat.task). */
+    turn?: number;
+    /** Custom data from the frontend (if inside a chat.task). */
+    clientData?: unknown;
+    /**
+     * Where this check is running:
+     * - `"inner"` — between tool-call steps (prepareStep)
+     * - `"outer"` — between turns (after response, before onBeforeTurnComplete)
+     */
+    source?: "inner" | "outer";
+    /** The step number (0-indexed). Only present when `source` is `"inner"`. */
+    stepNumber?: number;
+    /** The steps array from prepareStep. Only present when `source` is `"inner"`. */
+    steps?: CompactionStep[];
+};
+/**
+ * Options for `chat.compaction()` — the high-level prepareStep factory.
+ */
+export type CompactionOptions = {
+    /** Generate a summary from the current messages. Return the summary text. */
+    summarize: (messages: ModelMessage[]) => Promise<string>;
+    /** Token threshold — compact when totalTokens exceeds this. Ignored if `shouldCompact` is provided. */
+    threshold?: number;
+    /** Custom compaction trigger. When provided, used instead of `threshold`. */
+    shouldCompact?: (event: ShouldCompactEvent) => boolean | Promise<boolean>;
+};
+/** A step object as received in prepareStep's `steps` array. */
+export type CompactionStep = {
+    usage: LanguageModelUsage;
+    finishReason: string;
+    content: Array<{
+        type: string;
+        toolCallId?: string;
+    }>;
+    response: {
+        messages: Array<any>;
+    };
+};
+/**
+ * Result of `chat.compact()`. Discriminated union so you can inspect
+ * what happened, but also directly compatible with prepareStep's return type.
+ *
+ * - `"skipped"` — no compaction needed (first step, boundary unsafe, or under threshold). Return `undefined` to prepareStep.
+ * - `"rebuilt"` — previous compaction exists, messages rebuilt from summary + new response messages.
+ * - `"compacted"` — compaction just happened, includes the generated summary.
+ */
+export type CompactResult = {
+    type: "skipped";
+} | {
+    type: "rebuilt";
+    messages: ModelMessage[];
+} | {
+    type: "compacted";
+    messages: ModelMessage[];
+    summary: string;
+};
+/**
+ * Options for `chat.compact()` — the low-level compaction function.
+ */
+export type CompactOptions = {
+    /** Generate a summary from the current messages. Return the summary text. */
+    summarize: (messages: ModelMessage[]) => Promise<string>;
+    /** Token threshold — compact when totalTokens exceeds this. Ignored if `shouldCompact` is provided. */
+    threshold?: number;
+    /** Custom compaction trigger. When provided, used instead of `threshold`. */
+    shouldCompact?: (event: ShouldCompactEvent) => boolean | Promise<boolean>;
+};
+/**
+ * Read the current compaction state. Returns the summary and base message count
+ * if compaction has occurred in this turn, or `undefined` if not.
+ *
+ * Use in a custom `prepareStep` to rebuild from a previous compaction:
+ * ```ts
+ * const state = chat.getCompactionState();
+ * if (state) {
+ *   return { messages: [{ role: "user", content: state.summary }, ...newMsgs] };
+ * }
+ * ```
+ */
+declare function getCompactionState(): CompactionState | undefined;
+/**
+ * Low-level compaction for use inside a custom `prepareStep`.
+ *
+ * Handles the full decision tree: first step, already-compacted rebuild,
+ * boundary safety, threshold check, summarization, stream chunks, state
+ * storage, and accumulator update.
+ *
+ * Returns a `CompactResult` — inspect `result.type` to see what happened,
+ * or convert to a prepareStep return with `result.type === "skipped" ? undefined : result`.
+ *
+ * @example
+ * ```ts
+ * prepareStep: async ({ messages, steps }) => {
+ *   // your custom logic here...
+ *   const result = await chat.compact(messages, steps, {
+ *     threshold: 80_000,
+ *     summarize: async (msgs) => generateText({ model, messages: msgs }).then(r => r.text),
+ *   });
+ *   if (result.type === "compacted") {
+ *     logger.info("Compacted!", { summary: result.summary });
+ *   }
+ *   return result.type === "skipped" ? undefined : result;
+ * },
+ * ```
+ */
+declare function chatCompact(messages: ModelMessage[], steps: CompactionStep[], options: CompactOptions): Promise<CompactResult>;
+/**
+ * Returns a `prepareStep` function that handles context compaction automatically.
+ *
+ * Monitors token usage between tool-call steps. When `totalTokens` exceeds
+ * the threshold, generates a summary via `summarize()`, replaces the message
+ * history, and emits `data-compaction` stream chunks for the frontend.
+ *
+ * @example
+ * ```ts
+ * return streamText({
+ *   ...chat.toStreamTextOptions({ registry }),
+ *   messages: chat.addCacheBreaks(messages),
+ *   prepareStep: chat.compactionStep({
+ *     threshold: 80_000,
+ *     summarize: async (messages) => {
+ *       return generateText({ model, messages: [...messages, { role: "user", content: "Summarize." }] })
+ *         .then((r) => r.text);
+ *     },
+ *   }),
+ *   tools: { ... },
+ * });
+ * ```
+ */
+declare function chatCompactionStep(options: CompactionOptions): (args: {
+    messages: ModelMessage[];
+    steps: CompactionStep[];
+}) => Promise<{
+    messages: ModelMessage[];
+} | undefined>;
+/**
+ * Checks whether it's safe to compact the message history. Returns `false`
+ * if any tool calls are in-flight (incomplete tool invocations without results).
+ *
+ * Call before `chat.setMessages()` to avoid corrupting tool-call state.
+ */
+declare function isCompactionSafe(messages: UIMessage[]): boolean;
+/**
+ * A resolved prompt stored via `chat.prompt.set()`. Either a full `ResolvedPrompt`
+ * from `prompts.define().resolve()`, or a lightweight wrapper around a plain string.
+ */
+export type ChatPromptValue = ResolvedPrompt | {
+    text: string;
+    model: undefined;
+    config: undefined;
+    promptId: string;
+    version: number;
+    labels: string[];
+    toAISDKTelemetry: (additionalMetadata?: Record<string, string>) => {
+        experimental_telemetry: {
+            isEnabled: true;
+            metadata: Record<string, string>;
+        };
+    };
+};
+/**
+ * Store a resolved prompt (or plain string) for the current run.
+ * Call from any hook (`onPreload`, `onChatStart`, `onTurnStart`) or `run()`.
+ */
+declare function setChatPrompt(resolved: ResolvedPrompt | string): void;
+/**
+ * Read the stored prompt. Throws if `chat.prompt.set()` has not been called.
+ */
+declare function getChatPrompt(): ChatPromptValue;
+/**
+ * Options for {@link toStreamTextOptions}.
+ */
+export type ToStreamTextOptionsOptions = {
+    /** Additional telemetry metadata merged into `experimental_telemetry.metadata`. */
+    telemetry?: Record<string, string>;
+    /**
+     * An AI SDK provider registry (from `createProviderRegistry`) or any object
+     * with a `languageModel(id)` method. When provided and the stored prompt has
+     * a `model` string, the resolved `LanguageModel` is included in the returned
+     * options so `streamText` uses it directly.
+     *
+     * The model string should use the `"provider:model-id"` format
+     * (e.g. `"openai:gpt-4o"`, `"anthropic:claude-sonnet-4-6"`).
+     */
+    registry?: {
+        languageModel(modelId: string): unknown;
+    };
+};
+/**
+ * Returns an options object ready to spread into `streamText()`.
+ *
+ * Includes `system`, `experimental_telemetry`, and any config fields
+ * (temperature, maxTokens, etc.) from the stored prompt.
+ *
+ * When a `registry` is provided and the prompt has a `model` string,
+ * the resolved `LanguageModel` is included as `model`.
+ *
+ * If no prompt has been set, returns `{}` (no-op spread).
+ */
+declare function toStreamTextOptions(options?: ToStreamTextOptionsOptions): Record<string, unknown>;
 /**
  * Options for `pipeChat`.
  */
@@ -179,6 +564,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()`).
  */
@@ -297,6 +695,10 @@ export type TurnStartEvent<TClientData = unknown> = {
     previousRunId?: string;
     /** Whether this run was preloaded before the first message. */
     preloaded: boolean;
+    /** Token usage from the previous turn. Undefined on turn 0. */
+    previousTurnUsage?: LanguageModelUsage;
+    /** Cumulative token usage across all completed turns so far. */
+    totalUsage: LanguageModelUsage;
 };
 /**
  * Event passed to the `onTurnComplete` callback.
@@ -347,6 +749,10 @@ export type TurnCompleteEvent<TClientData = unknown> = {
     previousRunId?: string;
     /** Whether this run was preloaded before the first message. */
     preloaded: boolean;
+    /** Token usage for this turn. Undefined if usage couldn't be captured (e.g. manual pipeChat). */
+    usage?: LanguageModelUsage;
+    /** Cumulative token usage across all turns in this run (including this turn). */
+    totalUsage: LanguageModelUsage;
 };
 export type ChatTaskOptions<TIdentifier extends string, TClientDataSchema extends TaskSchema | undefined = undefined> = Omit<TaskOptions<TIdentifier, ChatTaskWirePayload, unknown>, "run"> & {
     /**
@@ -422,10 +828,68 @@ export type ChatTaskOptions<TIdentifier extends string, TClientDataSchema extend
      */
     onTurnStart?: (event: TurnStartEvent<inferSchemaOut<TClientDataSchema>>) => 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.
+     * Called after the response is captured but before the stream closes.
+     * The stream is still open, so you can write custom chunks to the frontend
+     * (e.g. compaction progress). Use this for compaction, post-processing,
+     * or any work where the user should see real-time status updates.
+     *
+     * @example
+     * ```ts
+     * onBeforeTurnComplete: async ({ messages, uiMessages, usage }) => {
+     *   if (usage?.inputTokens && usage.inputTokens > 5000) {
+     *     await chat.stream.append({ type: "data-compaction", id: generateId(), data: { status: "compacting" } });
+     *     // ... compact messages ...
+     *     chat.setMessages(compactedMessages);
+     *     await chat.stream.append({ type: "data-compaction", id: generateId(), data: { status: "complete" } });
+     *   }
+     * }
+     * ```
+     */
+    onBeforeTurnComplete?: (event: TurnCompleteEvent<inferSchemaOut<TClientDataSchema>>) => Promise<void> | void;
+    /**
+     * Called when conversation compaction occurs (via `chat.compact()` or
+     * `chat.compactionStep()`). Use for logging, billing, or persisting the summary.
+     *
+     * @example
+     * ```ts
+     * onCompacted: async ({ summary, totalTokens, chatId }) => {
+     *   logger.info("Compacted", { totalTokens, chatId });
+     *   await db.compactionLog.create({ data: { chatId, summary } });
+     * }
+     * ```
+     */
+    onCompacted?: (event: CompactedEvent) => Promise<void> | void;
+    /**
+     * Automatic context compaction. When provided, compaction runs automatically
+     * in both the inner loop (prepareStep, between tool-call steps) and the
+     * outer loop (between turns, for single-step responses where prepareStep
+     * never fires).
      *
-     * Use this to persist the conversation to your database after each assistant response.
+     * The `shouldCompact` callback decides when to compact, and `summarize`
+     * generates the summary. The prepareStep is auto-injected into
+     * `chat.toStreamTextOptions()` — if you provide your own `prepareStep`
+     * after spreading, it overrides the auto-injected one.
+     *
+     * @example
+     * ```ts
+     * chat.task({
+     *   id: "my-chat",
+     *   compaction: {
+     *     shouldCompact: ({ totalTokens }) => (totalTokens ?? 0) > 80_000,
+     *     summarize: async (messages) =>
+     *       generateText({ model, messages: [...messages, { role: "user", content: "Summarize." }] })
+     *         .then((r) => r.text),
+     *   },
+     *   run: async ({ messages, signal }) => {
+     *     return streamText({ ...chat.toStreamTextOptions({ registry }), messages });
+     *   },
+     * });
+     * ```
+     */
+    compaction?: ChatTaskCompactionOptions;
+    /**
+     * Called after the stream closes for this turn. Use this to persist the
+     * conversation to your database after each assistant response.
      *
      * @example
      * ```ts
@@ -451,16 +915,16 @@ export type ChatTaskOptions<TIdentifier extends string, TClientDataSchema extend
      */
     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()`.
+     * How long (in seconds) the run stays idle (active, using compute) after each
+     * turn, waiting for the next message. During this window responses are instant.
+     * 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;
+    idleTimeoutInSeconds?: number;
     /**
      * How long the `chatAccessToken` (scoped to this run) remains valid.
      * A fresh token is minted after each turn, so this only needs to cover
@@ -472,14 +936,14 @@ export type ChatTaskOptions<TIdentifier extends string, TClientDataSchema extend
      */
     chatAccessTokenTTL?: string;
     /**
-     * How long (in seconds) to keep the run warm after `onPreload` fires,
+     * How long (in seconds) the run stays idle after `onPreload` fires,
      * waiting for the first message before suspending.
      *
      * Only applies to preloaded runs (triggered via `transport.preload()`).
      *
-     * @default Same as `warmTimeoutInSeconds`
+     * @default Same as `idleTimeoutInSeconds`
      */
-    preloadWarmTimeoutInSeconds?: number;
+    preloadIdleTimeoutInSeconds?: number;
     /**
      * How long to wait (suspended) for the first message after a preloaded run starts.
      * If no message arrives within this time, the run ends.
@@ -489,6 +953,55 @@ export type ChatTaskOptions<TIdentifier extends string, TClientDataSchema extend
      * @default Same as `turnTimeout`
      */
     preloadTimeout?: string;
+    /**
+     * Transform model messages before they're used anywhere — in `run()`,
+     * in compaction rebuilds, and in compaction results.
+     *
+     * Define once, applied everywhere. Use for Anthropic cache breaks,
+     * injecting system context, stripping PII, etc.
+     *
+     * @example
+     * ```ts
+     * prepareMessages: async ({ messages, reason }) => {
+     *   // Add Anthropic cache breaks to the last message
+     *   if (messages.length === 0) return messages;
+     *   const last = messages[messages.length - 1];
+     *   return [...messages.slice(0, -1), {
+     *     ...last,
+     *     providerOptions: { ...last.providerOptions, anthropic: { cacheControl: { type: "ephemeral" } } },
+     *   }];
+     * }
+     * ```
+     */
+    prepareMessages?: (event: PrepareMessagesEvent<inferSchemaOut<TClientDataSchema>>) => ModelMessage[] | Promise<ModelMessage[]>;
+    /**
+     * 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.
@@ -553,23 +1066,45 @@ declare function setTurnTimeout(duration: string): void;
  */
 declare function setTurnTimeoutInSeconds(seconds: number): void;
 /**
- * Override the warm timeout for subsequent turns in the current run.
+ * Override the idle timeout for subsequent turns in the current run.
  *
- * The warm timeout controls how long the run stays active (using compute)
+ * The idle 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)
+ * @param seconds - Number of seconds to stay idle (0 to suspend immediately)
+ *
+ * @example
+ * ```ts
+ * run: async ({ messages, signal }) => {
+ *   chat.setIdleTimeoutInSeconds(60);
+ *   return streamText({ model, messages, abortSignal: signal });
+ * }
+ * ```
+ */
+declare function setIdleTimeoutInSeconds(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.setWarmTimeoutInSeconds(60);
+ *   chat.setUIMessageStreamOptions({
+ *     sendReasoning: true,
+ *     onError: (error) => error instanceof Error ? error.message : "An error occurred.",
+ *   });
  *   return streamText({ model, messages, abortSignal: signal });
  * }
  * ```
  */
-declare function setWarmTimeoutInSeconds(seconds: number): void;
+declare function setUIMessageStreamOptions(options: ChatUIMessageStreamOptions): void;
 /**
  * Check whether the user stopped generation during the current turn.
  *
@@ -635,6 +1170,217 @@ 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[];
+    private _compaction?;
+    constructor(options?: {
+        compaction?: ChatTaskCompactionOptions;
+    });
+    /**
+     * 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.
+     */
+    /**
+     * Replace all accumulated messages (for compaction).
+     * Converts UIMessages to ModelMessages internally.
+     */
+    setMessages(uiMessages: UIMessage[]): Promise<void>;
+    addResponse(response: UIMessage): Promise<void>;
+    /**
+     * Returns a `prepareStep` function for inner-loop compaction.
+     * Only available when `compaction` was provided to the constructor.
+     * Pass the result to `streamText({ prepareStep: conversation.prepareStep() })`.
+     */
+    prepareStep(): ((args: {
+        messages: ModelMessage[];
+        steps: CompactionStep[];
+    }) => Promise<{
+        messages: ModelMessage[];
+    } | undefined>) | undefined;
+    /**
+     * Run outer-loop compaction if needed. Call after adding the response
+     * and capturing usage. Applies `compactModelMessages` and `compactUIMessages`
+     * callbacks if configured.
+     *
+     * @returns `true` if compaction was performed, `false` otherwise.
+     */
+    compactIfNeeded(usage: LanguageModelUsage | undefined, context?: {
+        chatId?: string;
+        turn?: number;
+        clientData?: unknown;
+        totalUsage?: LanguageModelUsage;
+    }): Promise<boolean>;
+}
+export type ChatSessionOptions = {
+    /** Run-level cancel signal (from task context). */
+    signal: AbortSignal;
+    /** Seconds to stay idle between turns before suspending. @default 30 */
+    idleTimeoutInSeconds?: number;
+    /** Duration string for suspend timeout. @default "1h" */
+    timeout?: string;
+    /** Max turns before ending. @default 100 */
+    maxTurns?: number;
+    /** Automatic context compaction — same options as `chat.task({ compaction })`. */
+    compaction?: ChatTaskCompactionOptions;
+};
+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`. */
+    readonly messages: ModelMessage[];
+    /** Full accumulated UI messages — use for persistence. */
+    readonly 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;
+    /** Token usage from the previous turn. Undefined on turn 0. */
+    previousTurnUsage?: LanguageModelUsage;
+    /** Cumulative token usage across all completed turns so far. */
+    totalUsage: LanguageModelUsage;
+    /**
+     * Replace accumulated messages (for compaction). Takes UIMessages and
+     * converts to ModelMessages internally. After calling this, `turn.messages`
+     * reflects the compacted history.
+     */
+    setMessages(uiMessages: UIMessage[]): Promise<void>;
+    /**
+     * 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 idle/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.
@@ -722,8 +1468,10 @@ export declare const chat: {
     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;
+    /** Override the idle timeout at runtime. See {@link setIdleTimeoutInSeconds}. */
+    setIdleTimeoutInSeconds: typeof setIdleTimeoutInSeconds;
+    /** 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 +1480,45 @@ 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;
+    /**
+     * Store and retrieve a resolved prompt for the current run.
+     *
+     * - `chat.prompt.set(resolved)` — store a `ResolvedPrompt` or plain string
+     * - `chat.prompt()` — read the stored prompt (throws if not set)
+     */
+    prompt: typeof getChatPrompt & {
+        set: typeof setChatPrompt;
+    };
+    /**
+     * Returns an options object ready to spread into `streamText()`.
+     * Reads the stored prompt and returns `{ system, experimental_telemetry, ...config }`.
+     * Returns `{}` if no prompt has been set.
+     */
+    toStreamTextOptions: typeof toStreamTextOptions;
+    /**
+     * Replace the accumulated conversation messages for compaction.
+     * Call from `onTurnStart` or `onTurnComplete`. Takes `UIMessage[]` and
+     * converts to `ModelMessage[]` internally.
+     */
+    setMessages: typeof setChatMessages;
+    /** Check if it's safe to compact messages (no in-flight tool calls). */
+    isCompactionSafe: typeof isCompactionSafe;
+    /** Returns a `prepareStep` function that handles context compaction automatically. */
+    compactionStep: typeof chatCompactionStep;
+    /** Low-level compaction for use inside a custom `prepareStep`. */
+    compact: typeof chatCompact;
+    /** Read the current compaction state (summary + base message count). */
+    getCompactionState: typeof getCompactionState;
 };