@trigger.dev/sdk 0.0.0-prerelease-20260325143642 → 0.0.0-prerelease-20260327224514

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

@@ -1,8 +1,10 @@
-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, UIMessageStreamOptions, LanguageModelUsage } from "ai";
-import { Tool } from "ai";
+import { AnyTask, Task, type inferSchemaIn, type inferSchemaOut, type TaskIdentifier, type TaskOptions, type TaskSchema, type TaskRunContext, type TaskWithSchema } from "@trigger.dev/core/v3";
+import type { ModelMessage, ToolSet, UIMessage, UIMessageChunk, UIMessageStreamOptions, LanguageModelUsage } from "ai";
+import { Tool, ToolCallOptions } from "ai";
 import { locals } from "./locals.js";
 import type { ResolvedPrompt } from "./prompt.js";
+/** Re-export for typing `ctx` in `chat.task` hooks without importing `@trigger.dev/core`. */
+export type { TaskRunContext } from "@trigger.dev/core/v3";
 import { CHAT_MESSAGES_STREAM_ID, CHAT_STOP_STREAM_ID } from "./chat-constants.js";
 export type ToolCallExecutionOptions = {
     toolCallId: string;
@@ -31,16 +33,46 @@ type ToolResultContent = Array<{
 export type ToolOptions<TResult> = {
     experimental_toToolResultContent?: (result: TResult) => ToolResultContent;
 };
-declare function toolFromTask<TIdentifier extends string, TInput = void, TOutput = unknown>(task: Task<TIdentifier, TInput, TOutput>, options?: ToolOptions<TOutput>): Tool<TInput, TOutput>;
-declare function toolFromTask<TIdentifier extends string, TTaskSchema extends TaskSchema | undefined = undefined, TOutput = unknown>(task: TaskWithSchema<TIdentifier, TTaskSchema, TOutput>, options?: ToolOptions<TOutput>): Tool<inferSchemaIn<TTaskSchema>, TOutput>;
+/** Satisfies AI SDK `ToolSet` index signature alongside concrete `Tool` input/output types. */
+type ToolSetCompatible<T extends Tool<any, any>> = T & NonNullable<ToolSet[string]>;
+/**
+ * Returns an `execute` function for the AI SDK `tool()` helper (or any compatible tool definition).
+ * Preferred API for task-backed tools: the same Trigger wiring as the deprecated `ai.tool()`
+ * (`triggerAndSubscribe`, tool-call metadata, chat context, `chat.local` serialization) without
+ * building the tool object. You supply `description`, `inputSchema`, and any AI-SDK-only options
+ * (e.g. `experimental_toToolResultContent`) on `tool()` yourself.
+ *
+ * @example
+ * ```ts
+ * import { tool } from "ai";
+ * import { z } from "zod";
+ * import { ai } from "@trigger.dev/sdk/ai";
+ * import { myTask } from "./trigger/myTask";
+ *
+ * export const myTool = tool({
+ *   description: myTask.description ?? "",
+ *   inputSchema: z.object({ id: z.string() }),
+ *   execute: ai.toolExecute(myTask),
+ * });
+ * ```
+ */
+declare function toolExecute<TIdentifier extends string, TInput = void, TOutput = unknown>(task: Task<TIdentifier, TInput, TOutput>): (input: TInput, toolOpts: ToolCallOptions) => Promise<TOutput>;
+declare function toolExecute<TIdentifier extends string, TTaskSchema extends TaskSchema | undefined = undefined, TOutput = unknown>(task: TaskWithSchema<TIdentifier, TTaskSchema, TOutput>): (input: inferSchemaIn<TTaskSchema>, toolOpts: ToolCallOptions) => Promise<TOutput>;
+/**
+ * @deprecated Use `tool()` from the `ai` package with `execute: ai.toolExecute(task)` instead.
+ * This helper may be removed in a future major release.
+ */
+declare function toolFromTask<TIdentifier extends string, TInput = void, TOutput = unknown>(task: Task<TIdentifier, TInput, TOutput>, options?: ToolOptions<TOutput>): ToolSetCompatible<Tool<TInput, TOutput>>;
+/** @deprecated Use `tool()` from `ai` with `execute: ai.toolExecute(task)`. */
+declare function toolFromTask<TIdentifier extends string, TTaskSchema extends TaskSchema | undefined = undefined, TOutput = unknown>(task: TaskWithSchema<TIdentifier, TTaskSchema, TOutput>, options?: ToolOptions<TOutput>): ToolSetCompatible<Tool<inferSchemaIn<TTaskSchema>, TOutput>>;
 declare function getToolOptionsFromMetadata(): ToolCallExecutionOptions | undefined;
 /**
- * Get the current tool call ID from inside a subtask invoked via `ai.tool()`.
+ * Get the current tool call ID from inside a subtask invoked via `ai.toolExecute()` (or legacy `ai.tool()`).
  * Returns `undefined` if not running as a tool subtask.
  */
 declare function getToolCallId(): string | undefined;
 /**
- * Get the chat context from inside a subtask invoked via `ai.tool()` within a `chat.task`.
+ * Get the chat context from inside a subtask invoked via `ai.toolExecute()` (or legacy `ai.tool()`) within a `chat.task`.
  * Pass `typeof yourChatTask` as the type parameter to get typed `clientData`.
  * Returns `undefined` if the parent is not a chat task.
  *
@@ -63,9 +95,17 @@ declare function getToolChatContext<TChatTask extends AnyTask = AnyTask>(): Chat
  */
 declare function getToolChatContextOrThrow<TChatTask extends AnyTask = AnyTask>(): ChatTurnContext<InferChatClientData<TChatTask>>;
 export declare const ai: {
+    /**
+     * @deprecated Use `tool()` from the `ai` package with `execute: ai.toolExecute(task)` instead.
+     */
     tool: typeof toolFromTask;
+    /**
+     * Preferred: return value for the `execute` field of AI SDK `tool()`. Keeps Trigger subtask and
+     * metadata behavior without coupling to a specific `ai` version’s `Tool` / `ToolSet` types.
+     */
+    toolExecute: typeof toolExecute;
     currentToolOptions: typeof getToolOptionsFromMetadata;
-    /** Get the tool call ID from inside a subtask invoked via `ai.tool()`. */
+    /** Get the tool call ID from inside a subtask invoked via `ai.toolExecute()` (or legacy `ai.tool()`). */
     toolCallId: typeof getToolCallId;
     /** Get chat context (chatId, turn, clientData, etc.) from inside a subtask of a `chat.task`. Returns undefined if not in a chat context. */
     chatContext: typeof getToolChatContext;
@@ -97,6 +137,31 @@ declare function createChatAccessToken<TTask extends AnyTask>(taskId: TaskIdenti
  */
 export declare const CHAT_STREAM_KEY = "chat";
 export { CHAT_MESSAGES_STREAM_ID, CHAT_STOP_STREAM_ID };
+/**
+ * A stream writer passed to chat lifecycle callbacks (`onPreload`, `onChatStart`,
+ * `onTurnStart`, `onTurnComplete`, `onCompacted`).
+ *
+ * Write custom `UIMessageChunk` parts (e.g. `data-*` parts) directly to the chat
+ * stream without the ceremony of `chat.stream.writer({ execute })`.
+ *
+ * The writer is lazy — no stream overhead if you don't call `write()` or `merge()`.
+ *
+ * @example
+ * ```ts
+ * onTurnStart: async ({ writer }) => {
+ *   writer.write({ type: "data-status", data: { loading: true } });
+ * },
+ * onTurnComplete: async ({ writer, uiMessages }) => {
+ *   writer.write({ type: "data-analytics", data: { messageCount: uiMessages.length } });
+ * },
+ * ```
+ */
+export type ChatWriter = {
+    /** Write a single UIMessageChunk to the chat stream. */
+    write(part: UIMessageChunk): void;
+    /** Merge another stream's chunks into the chat stream. */
+    merge(stream: ReadableStream<UIMessageChunk>): void;
+};
 /**
  * The wire payload shape sent by `TriggerChatTransport`.
  * Uses `metadata` to match the AI SDK's `ChatRequestOptions` field name.
@@ -163,6 +228,11 @@ export type ChatTaskSignals = {
  * Extends `ChatTaskPayload` (the wire payload) with abort signals.
  */
 export type ChatTaskRunPayload<TClientData = unknown> = ChatTaskPayload<TClientData> & ChatTaskSignals & {
+    /**
+     * Task run context — same object as the `ctx` passed to a standard `task({ run })` handler’s second argument.
+     * Use for tags, metadata, parent run links, or any API that needs the full run record.
+     */
+    ctx: TaskRunContext;
     /** Token usage from the previous turn. Undefined on turn 0. */
     previousTurnUsage?: LanguageModelUsage;
     /** Cumulative token usage across all completed turns so far. */
@@ -177,7 +247,7 @@ export type ChatTurnUsage = LanguageModelUsage;
  * `onTurnComplete` to compact before the next turn. Takes `UIMessage[]`
  * and converts to `ModelMessage[]` internally.
  */
-declare function setChatMessages(uiMessages: UIMessage[]): void;
+declare function setChatMessages<TUIM extends UIMessage = UIMessage>(uiMessages: TUIM[]): void;
 /** State stored in locals during prepareStep compaction. */
 interface CompactionState {
     summary: string;
@@ -211,11 +281,11 @@ export type SummarizeEvent = {
 /**
  * Event passed to `compactUIMessages` and `compactModelMessages` callbacks.
  */
-export type CompactMessagesEvent = {
+export type CompactMessagesEvent<TUIM extends UIMessage = UIMessage> = {
     /** The generated summary text. */
     summary: string;
     /** The current UI messages (full conversation). */
-    uiMessages: UIMessage[];
+    uiMessages: TUIM[];
     /** The current model messages (full conversation). */
     modelMessages: ModelMessage[];
     /** The chat session ID. */
@@ -238,7 +308,7 @@ export type CompactMessagesEvent = {
  * tool-call steps) and the outer loop (between turns, for single-step responses
  * where prepareStep never fires).
  */
-export type ChatTaskCompactionOptions = {
+export type ChatTaskCompactionOptions<TUIM extends UIMessage = UIMessage> = {
     /** 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. */
@@ -263,7 +333,7 @@ export type ChatTaskCompactionOptions = {
      * ],
      * ```
      */
-    compactUIMessages?: (event: CompactMessagesEvent) => UIMessage[] | Promise<UIMessage[]>;
+    compactUIMessages?: (event: CompactMessagesEvent<TUIM>) => TUIM[] | Promise<TUIM[]>;
     /**
      * Transform model messages after compaction (what gets sent to the LLM).
      * Default: replace all with a single summary message.
@@ -277,14 +347,14 @@ export type ChatTaskCompactionOptions = {
      * ],
      * ```
      */
-    compactModelMessages?: (event: CompactMessagesEvent) => ModelMessage[] | Promise<ModelMessage[]>;
+    compactModelMessages?: (event: CompactMessagesEvent<TUIM>) => ModelMessage[] | Promise<ModelMessage[]>;
 };
 /**
  * Event passed to `shouldInject` and `prepareMessages` callbacks.
  */
-export type PendingMessagesBatchEvent = {
+export type PendingMessagesBatchEvent<TUIM extends UIMessage = UIMessage> = {
     /** All pending UI messages that arrived during streaming (batch). */
-    messages: UIMessage[];
+    messages: TUIM[];
     /** Current model messages in the conversation. */
     modelMessages: ModelMessage[];
     /** Completed steps so far. */
@@ -301,9 +371,9 @@ export type PendingMessagesBatchEvent = {
 /**
  * Event passed to `onReceived` callback (per-message, as they arrive).
  */
-export type PendingMessageReceivedEvent = {
+export type PendingMessageReceivedEvent<TUIM extends UIMessage = UIMessage> = {
     /** The UI message that arrived during streaming. */
-    message: UIMessage;
+    message: TUIM;
     /** Chat session ID. */
     chatId: string;
     /** Current turn number (0-indexed). */
@@ -312,9 +382,9 @@ export type PendingMessageReceivedEvent = {
 /**
  * Event passed to `onInjected` callback (batch, after injection).
  */
-export type PendingMessagesInjectedEvent = {
+export type PendingMessagesInjectedEvent<TUIM extends UIMessage = UIMessage> = {
     /** All UI messages that were injected. */
-    messages: UIMessage[];
+    messages: TUIM[];
     /** The model messages that were injected. */
     injectedModelMessages: ModelMessage[];
     /** Chat session ID. */
@@ -333,23 +403,23 @@ export type PendingMessagesInjectedEvent = {
  * messages is injected between tool-call steps via `prepareStep`.
  * Otherwise, messages queue for the next turn.
  */
-export type PendingMessagesOptions = {
+export type PendingMessagesOptions<TUIM extends UIMessage = UIMessage> = {
     /**
      * Decide whether to inject pending messages between tool-call steps.
      * Called once per step boundary with the full batch of pending messages.
      * If absent, no injection happens — messages only queue for the next turn.
      */
-    shouldInject?: (event: PendingMessagesBatchEvent) => boolean | Promise<boolean>;
+    shouldInject?: (event: PendingMessagesBatchEvent<TUIM>) => boolean | Promise<boolean>;
     /**
      * Transform the batch of pending messages before injection.
      * Return the model messages to inject.
      * Default: convert each UI message via `convertToModelMessages`.
      */
-    prepare?: (event: PendingMessagesBatchEvent) => ModelMessage[] | Promise<ModelMessage[]>;
+    prepare?: (event: PendingMessagesBatchEvent<TUIM>) => ModelMessage[] | Promise<ModelMessage[]>;
     /** Called when a message arrives during streaming (per-message). */
-    onReceived?: (event: PendingMessageReceivedEvent) => void | Promise<void>;
+    onReceived?: (event: PendingMessageReceivedEvent<TUIM>) => void | Promise<void>;
     /** Called after a batch of messages is injected via `prepareStep`. */
-    onInjected?: (event: PendingMessagesInjectedEvent) => void | Promise<void>;
+    onInjected?: (event: PendingMessagesInjectedEvent<TUIM>) => void | Promise<void>;
 };
 /**
  * The data part type used to signal that pending messages were injected
@@ -384,6 +454,8 @@ export type CompactionChunkData = {
  * Event passed to the `onCompacted` callback.
  */
 export type CompactedEvent = {
+    /** Task run context — same as `task` lifecycle hooks and `chat.task` `run({ ctx })`. */
+    ctx: TaskRunContext;
     /** The generated summary text. */
     summary: string;
     /** The messages that were compacted (pre-compaction). */
@@ -404,6 +476,8 @@ export type CompactedEvent = {
     chatId?: string;
     /** The current turn number (if running inside a chat.task). */
     turn?: number;
+    /** Stream writer — write custom `UIMessageChunk` parts to the chat stream. Lazy: no overhead if unused. */
+    writer: ChatWriter;
 };
 /**
  * Event passed to `shouldCompact` callbacks.
@@ -654,7 +728,7 @@ export type PipeChatOptions = {
  * 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">;
+export type ChatUIMessageStreamOptions<TUIM extends UIMessage = UIMessage> = Omit<UIMessageStreamOptions<TUIM>, "onFinish" | "originalMessages" | "generateMessageId">;
 /**
  * An object with a `toUIMessageStream()` method (e.g. `StreamTextResult` from `streamText()`).
  */
@@ -719,6 +793,8 @@ declare function pipeChat(source: UIMessageStreamable | AsyncIterable<unknown> |
  * Event passed to the `onPreload` callback.
  */
 export type PreloadEvent<TClientData = unknown> = {
+    /** Task run context — same as `task({ run })` second-argument `ctx`. */
+    ctx: TaskRunContext;
     /** The unique identifier for the chat session. */
     chatId: string;
     /** The Trigger.dev run ID for this conversation. */
@@ -727,11 +803,15 @@ export type PreloadEvent<TClientData = unknown> = {
     chatAccessToken: string;
     /** Custom data from the frontend. */
     clientData?: TClientData;
+    /** Stream writer — write custom `UIMessageChunk` parts to the chat stream. Lazy: no overhead if unused. */
+    writer: ChatWriter;
 };
 /**
  * Event passed to the `onChatStart` callback.
  */
 export type ChatStartEvent<TClientData = unknown> = {
+    /** Task run context — same as `task({ run })` second-argument `ctx`. */
+    ctx: TaskRunContext;
     /** The unique identifier for the chat session. */
     chatId: string;
     /** The initial model-ready messages for this conversation. */
@@ -748,17 +828,21 @@ export type ChatStartEvent<TClientData = unknown> = {
     previousRunId?: string;
     /** Whether this run was preloaded before the first message. */
     preloaded: boolean;
+    /** Stream writer — write custom `UIMessageChunk` parts to the chat stream. Lazy: no overhead if unused. */
+    writer: ChatWriter;
 };
 /**
  * Event passed to the `onTurnStart` callback.
  */
-export type TurnStartEvent<TClientData = unknown> = {
+export type TurnStartEvent<TClientData = unknown, TUIM extends UIMessage = UIMessage> = {
+    /** Task run context — same as `task({ run })` second-argument `ctx`. */
+    ctx: TaskRunContext;
     /** The unique identifier for the chat session. */
     chatId: string;
     /** The accumulated model-ready messages (all turns so far, including new user message). */
     messages: ModelMessage[];
     /** The accumulated UI messages (all turns so far, including new user message). */
-    uiMessages: UIMessage[];
+    uiMessages: TUIM[];
     /** The turn number (0-indexed). */
     turn: number;
     /** The Trigger.dev run ID for this conversation. */
@@ -777,11 +861,15 @@ export type TurnStartEvent<TClientData = unknown> = {
     previousTurnUsage?: LanguageModelUsage;
     /** Cumulative token usage across all completed turns so far. */
     totalUsage: LanguageModelUsage;
+    /** Stream writer — write custom `UIMessageChunk` parts to the chat stream. Lazy: no overhead if unused. */
+    writer: ChatWriter;
 };
 /**
  * Event passed to the `onTurnComplete` callback.
  */
-export type TurnCompleteEvent<TClientData = unknown> = {
+export type TurnCompleteEvent<TClientData = unknown, TUIM extends UIMessage = UIMessage> = {
+    /** Task run context — same as `task({ run })` second-argument `ctx`. */
+    ctx: TaskRunContext;
     /** The unique identifier for the chat session. */
     chatId: string;
     /** The full accumulated conversation in model format (all turns so far). */
@@ -790,7 +878,7 @@ export type TurnCompleteEvent<TClientData = unknown> = {
      * The full accumulated conversation in UI format (all turns so far).
      * This is the format expected by `useChat` — store this for persistence.
      */
-    uiMessages: UIMessage[];
+    uiMessages: TUIM[];
     /**
      * Only the new model messages from this turn (user message(s) + assistant response).
      * Useful for appending to an existing conversation record.
@@ -800,15 +888,15 @@ export type TurnCompleteEvent<TClientData = unknown> = {
      * 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[];
+    newUIMessages: TUIM[];
     /** The assistant's response for this turn, with aborted parts cleaned up when `stopped` is true. Undefined if `pipeChat` was used manually. */
-    responseMessage: UIMessage | undefined;
+    responseMessage: TUIM | undefined;
     /**
      * The raw assistant response before abort cleanup. Includes incomplete tool parts
      * (`input-available`, `partial-call`) and streaming reasoning/text parts.
      * Use this if you need custom cleanup logic. Same as `responseMessage` when not stopped.
      */
-    rawResponseMessage: UIMessage | undefined;
+    rawResponseMessage: TUIM | undefined;
     /** The turn number (0-indexed). */
     turn: number;
     /** The Trigger.dev run ID for this conversation. */
@@ -832,7 +920,15 @@ export type TurnCompleteEvent<TClientData = unknown> = {
     /** 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"> & {
+/**
+ * Event passed to the `onBeforeTurnComplete` callback.
+ * Same as `TurnCompleteEvent` but includes a `writer` since the stream is still open.
+ */
+export type BeforeTurnCompleteEvent<TClientData = unknown, TUIM extends UIMessage = UIMessage> = TurnCompleteEvent<TClientData, TUIM> & {
+    /** Stream writer — write custom `UIMessageChunk` parts to the chat stream. Lazy: no overhead if unused. */
+    writer: ChatWriter;
+};
+export type ChatTaskOptions<TIdentifier extends string, TClientDataSchema extends TaskSchema | undefined = undefined, TUIMessage extends UIMessage = UIMessage> = Omit<TaskOptions<TIdentifier, ChatTaskWirePayload<TUIMessage, inferSchemaIn<TClientDataSchema>>, unknown>, "run"> & {
     /**
      * Schema for validating `clientData` from the frontend.
      * Accepts Zod, ArkType, Valibot, or any supported schema library.
@@ -845,8 +941,9 @@ export type ChatTaskOptions<TIdentifier extends string, TClientDataSchema extend
      * chat.task({
      *   id: "my-chat",
      *   clientDataSchema: z.object({ model: z.string().optional(), userId: z.string() }),
-     *   run: async ({ messages, clientData, signal }) => {
+     *   run: async ({ messages, clientData, ctx, signal }) => {
      *     // clientData is typed as { model?: string; userId: string }
+     *     // ctx is the same TaskRunContext as in task({ run: (payload, { ctx }) => ... })
      *   },
      * });
      * ```
@@ -856,7 +953,8 @@ export type ChatTaskOptions<TIdentifier extends string, TClientDataSchema extend
      * 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`).
+     * trigger type, task `ctx` (same as `task({ run })`’s second argument), and abort signals
+     * (`signal`, `cancelSignal`, `stopSignal`).
      *
      * **Auto-piping:** If this function returns a value with `.toUIMessageStream()`,
      * the stream is automatically piped to the frontend.
@@ -870,7 +968,7 @@ export type ChatTaskOptions<TIdentifier extends string, TClientDataSchema extend
      *
      * @example
      * ```ts
-     * onPreload: async ({ chatId, clientData }) => {
+     * onPreload: async ({ ctx, chatId, clientData }) => {
      *   await db.chat.create({ data: { id: chatId } });
      *   userContext.init(await loadUser(clientData.userId));
      * }
@@ -884,7 +982,7 @@ export type ChatTaskOptions<TIdentifier extends string, TClientDataSchema extend
      *
      * @example
      * ```ts
-     * onChatStart: async ({ chatId, messages, clientData }) => {
+     * onChatStart: async ({ ctx, chatId, messages, clientData }) => {
      *   await db.chat.create({ data: { id: chatId, userId: clientData.userId } });
      * }
      * ```
@@ -899,12 +997,12 @@ export type ChatTaskOptions<TIdentifier extends string, TClientDataSchema extend
      *
      * @example
      * ```ts
-     * onTurnStart: async ({ chatId, uiMessages }) => {
+     * onTurnStart: async ({ ctx, chatId, uiMessages }) => {
      *   await db.chat.update({ where: { id: chatId }, data: { messages: uiMessages } });
      * }
      * ```
      */
-    onTurnStart?: (event: TurnStartEvent<inferSchemaOut<TClientDataSchema>>) => Promise<void> | void;
+    onTurnStart?: (event: TurnStartEvent<inferSchemaOut<TClientDataSchema>, TUIMessage>) => Promise<void> | void;
     /**
      * 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
@@ -913,24 +1011,24 @@ export type ChatTaskOptions<TIdentifier extends string, TClientDataSchema extend
      *
      * @example
      * ```ts
-     * onBeforeTurnComplete: async ({ messages, uiMessages, usage }) => {
+     * onBeforeTurnComplete: async ({ ctx, writer, usage }) => {
      *   if (usage?.inputTokens && usage.inputTokens > 5000) {
-     *     await chat.stream.append({ type: "data-compaction", id: generateId(), data: { status: "compacting" } });
+     *     writer.write({ 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" } });
+     *     writer.write({ type: "data-compaction", id: generateId(), data: { status: "complete" } });
      *   }
      * }
      * ```
      */
-    onBeforeTurnComplete?: (event: TurnCompleteEvent<inferSchemaOut<TClientDataSchema>>) => Promise<void> | void;
+    onBeforeTurnComplete?: (event: BeforeTurnCompleteEvent<inferSchemaOut<TClientDataSchema>, TUIMessage>) => 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 }) => {
+     * onCompacted: async ({ ctx, summary, totalTokens, chatId }) => {
      *   logger.info("Compacted", { totalTokens, chatId });
      *   await db.compactionLog.create({ data: { chatId, summary } });
      * }
@@ -964,7 +1062,7 @@ export type ChatTaskOptions<TIdentifier extends string, TClientDataSchema extend
      * });
      * ```
      */
-    compaction?: ChatTaskCompactionOptions;
+    compaction?: ChatTaskCompactionOptions<TUIMessage>;
     /**
      * Configure how messages that arrive during streaming are handled.
      *
@@ -980,18 +1078,19 @@ export type ChatTaskOptions<TIdentifier extends string, TClientDataSchema extend
      * },
      * ```
      */
-    pendingMessages?: PendingMessagesOptions;
+    pendingMessages?: PendingMessagesOptions<TUIMessage>;
     /**
+     * Called after each assistant response completes. Use to persist the
      * conversation to your database after each assistant response.
      *
      * @example
      * ```ts
-     * onTurnComplete: async ({ chatId, messages }) => {
+     * onTurnComplete: async ({ ctx, chatId, messages }) => {
      *   await db.chat.update({ where: { id: chatId }, data: { messages } });
      * }
      * ```
      */
-    onTurnComplete?: (event: TurnCompleteEvent<inferSchemaOut<TClientDataSchema>>) => Promise<void> | void;
+    onTurnComplete?: (event: TurnCompleteEvent<inferSchemaOut<TClientDataSchema>, TUIMessage>) => 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
@@ -1094,7 +1193,7 @@ export type ChatTaskOptions<TIdentifier extends string, TClientDataSchema extend
      * });
      * ```
      */
-    uiMessageStreamOptions?: ChatUIMessageStreamOptions;
+    uiMessageStreamOptions?: ChatUIMessageStreamOptions<TUIMessage>;
 };
 /**
  * Creates a Trigger.dev task pre-configured for AI SDK chat.
@@ -1123,7 +1222,34 @@ export type ChatTaskOptions<TIdentifier extends string, TClientDataSchema extend
  * });
  * ```
  */
-declare function chatTask<TIdentifier extends string, TClientDataSchema extends TaskSchema | undefined = undefined>(options: ChatTaskOptions<TIdentifier, TClientDataSchema>): Task<TIdentifier, ChatTaskWirePayload<UIMessage, inferSchemaIn<TClientDataSchema>>, unknown>;
+declare function chatTask<TIdentifier extends string, TClientDataSchema extends TaskSchema | undefined = undefined, TUIMessage extends UIMessage = UIMessage>(options: ChatTaskOptions<TIdentifier, TClientDataSchema, TUIMessage>): Task<TIdentifier, ChatTaskWirePayload<TUIMessage, inferSchemaIn<TClientDataSchema>>, unknown>;
+/**
+ * Optional config for {@link chat.withUIMessage}. `streamOptions` become default
+ * static `toUIMessageStream()` settings; inner `chat.task({ uiMessageStreamOptions })`
+ * shallow-merges on top (task wins on conflicts).
+ */
+export type ChatWithUIMessageConfig<TUIM extends UIMessage = UIMessage> = {
+    streamOptions?: ChatUIMessageStreamOptions<TUIM>;
+};
+/**
+ * Fix the UI message type for a chat task (AI SDK `UIMessage` generics) while
+ * keeping `id` and `clientDataSchema` inference on the inner {@link chat.task} call.
+ *
+ * @example
+ * ```ts
+ * type AgentUiMessage = UIMessage<unknown, UIDataTypes, UITools>;
+ *
+ * export const myChat = chat.withUIMessage<AgentUiMessage>({
+ *   streamOptions: { sendReasoning: true },
+ * }).task({
+ *   id: "my-chat",
+ *   run: async ({ messages, signal }) => { ... },
+ * });
+ * ```
+ */
+declare function withUIMessage<TUIM extends UIMessage = UIMessage>(config?: ChatWithUIMessageConfig<TUIM>): {
+    task: <TIdentifier extends string, TClientDataSchema extends TaskSchema | undefined = undefined>(options: ChatTaskOptions<TIdentifier, TClientDataSchema, TUIM>) => Task<TIdentifier, ChatTaskWirePayload<TUIM, inferSchemaIn<TClientDataSchema>>, unknown>;
+};
 /**
  * Override the turn timeout for subsequent turns in the current run.
  *
@@ -1197,7 +1323,7 @@ declare function setIdleTimeoutInSeconds(seconds: number): void;
  * }
  * ```
  */
-declare function setUIMessageStreamOptions(options: ChatUIMessageStreamOptions): void;
+declare function setUIMessageStreamOptions(options: ChatUIMessageStreamOptions<UIMessage>): void;
 /**
  * Check whether the user stopped generation during the current turn.
  *
@@ -1235,6 +1361,34 @@ declare function isStopped(): boolean;
  * ```
  */
 declare function chatDefer(promise: Promise<unknown>): void;
+/**
+ * Queue model messages for injection at the next `prepareStep` boundary.
+ *
+ * Use this to inject context from background work into the agent's conversation.
+ * Messages are appended to the model messages before the next LLM inference call.
+ *
+ * Combine with `chat.defer()` to run background analysis and inject results:
+ *
+ * @example
+ * ```ts
+ * onTurnComplete: async ({ messages }) => {
+ *   chat.defer((async () => {
+ *     const review = await generateObject({
+ *       model: openai("gpt-4o-mini"),
+ *       messages: [...messages, { role: "user", content: "Review the last response." }],
+ *       schema: z.object({ suggestions: z.array(z.string()) }),
+ *     });
+ *     if (review.object.suggestions.length > 0) {
+ *       chat.inject([{
+ *         role: "system",
+ *         content: `Improvements for next response:\n${review.object.suggestions.join("\n")}`,
+ *       }]);
+ *     }
+ *   })());
+ * },
+ * ```
+ */
+declare function injectBackgroundContext(messages: ModelMessage[]): void;
 /**
  * Clean up a UIMessage that was captured during an aborted/stopped turn.
  *
@@ -1262,7 +1416,7 @@ declare function chatDefer(promise: Promise<unknown>): void;
  * }
  * ```
  */
-declare function cleanupAbortedParts(message: UIMessage): UIMessage;
+declare function cleanupAbortedParts<TUIM extends UIMessage>(message: TUIM): TUIM;
 /**
  * Create a managed stop signal wired to the chat stop input stream.
  *
@@ -1528,7 +1682,7 @@ export type ChatLocal<T extends Record<string, unknown>> = T & {
  *
  * The `id` is required and must be unique across all `chat.local()` calls in
  * your project. It's used to serialize values into subtask metadata so that
- * `ai.tool()` subtasks can auto-hydrate parent locals (read-only).
+ * `ai.toolExecute()` (or legacy `ai.tool()`) subtasks can auto-hydrate parent locals (read-only).
  *
  * @example
  * ```ts
@@ -1576,9 +1730,23 @@ declare function chatLocal<T extends Record<string, unknown>>(options: {
  * ```
  */
 export type InferChatClientData<TTask extends AnyTask> = TTask extends Task<string, ChatTaskWirePayload<any, infer TMetadata>, any> ? TMetadata : unknown;
+/**
+ * Extracts the UI message type from a chat task (wire payload `messages` items).
+ *
+ * @example
+ * ```ts
+ * import type { InferChatUIMessage } from "@trigger.dev/sdk/ai";
+ * import type { myChat } from "@/trigger/chat";
+ *
+ * type Msg = InferChatUIMessage<typeof myChat>;
+ * ```
+ */
+export type InferChatUIMessage<TTask extends AnyTask> = TTask extends Task<string, ChatTaskWirePayload<infer TUIM extends UIMessage, any>, any> ? TUIM : UIMessage;
 export declare const chat: {
     /** Create a chat task. See {@link chatTask}. */
     task: typeof chatTask;
+    /** Create a chat task with a fixed {@link UIMessage} subtype and optional default stream options. See {@link withUIMessage}. */
+    withUIMessage: typeof withUIMessage;
     /** Pipe a stream to the chat transport. See {@link pipeChat}. */
     pipe: typeof pipeChat;
     /** Create a per-run typed local. See {@link chatLocal}. */
@@ -1599,6 +1767,8 @@ export declare const chat: {
     cleanupAbortedParts: typeof cleanupAbortedParts;
     /** Register background work that runs in parallel with streaming. See {@link chatDefer}. */
     defer: typeof chatDefer;
+    /** Queue model messages for injection at the next `prepareStep` boundary. See {@link injectBackgroundContext}. */
+    inject: typeof injectBackgroundContext;
     /** 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. */