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

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

@@ -1,8 +1,24 @@
 import { AnyTask, Task, type inferSchemaIn, type inferSchemaOut, 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 type { ModelMessage, UIMessage, UIMessageChunk } from "ai";
+import { Tool } from "ai";
+import { locals } from "./locals.js";
 import { CHAT_MESSAGES_STREAM_ID, CHAT_STOP_STREAM_ID } from "./chat-constants.js";
-export type ToolCallExecutionOptions = Omit<ToolCallOptions, "abortSignal">;
+export type ToolCallExecutionOptions = {
+    toolCallId: string;
+    experimental_context?: unknown;
+    /** Chat context — only present when the tool runs inside a chat.task turn. */
+    chatId?: string;
+    turn?: number;
+    continuation?: boolean;
+    clientData?: unknown;
+};
+/** Chat context stored in locals during each chat.task turn for auto-detection. */
+type ChatTurnContext<TClientData = unknown> = {
+    chatId: string;
+    turn: number;
+    continuation: boolean;
+    clientData?: TClientData;
+};
 type ToolResultContent = Array<{
     type: "text";
     text: string;
@@ -17,9 +33,43 @@ export type ToolOptions<TResult> = {
 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>;
 declare function getToolOptionsFromMetadata(): ToolCallExecutionOptions | undefined;
+/**
+ * Get the current tool call ID from inside a subtask invoked via `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`.
+ * Pass `typeof yourChatTask` as the type parameter to get typed `clientData`.
+ * Returns `undefined` if the parent is not a chat task.
+ *
+ * @example
+ * ```ts
+ * const ctx = ai.chatContext<typeof myChat>();
+ * // ctx?.clientData is typed based on myChat's clientDataSchema
+ * ```
+ */
+declare function getToolChatContext<TChatTask extends AnyTask = AnyTask>(): ChatTurnContext<InferChatClientData<TChatTask>> | undefined;
+/**
+ * Get the chat context from inside a subtask, throwing if not in a chat context.
+ * Pass `typeof yourChatTask` as the type parameter to get typed `clientData`.
+ *
+ * @example
+ * ```ts
+ * const ctx = ai.chatContextOrThrow<typeof myChat>();
+ * // ctx.chatId, ctx.clientData are guaranteed non-null
+ * ```
+ */
+declare function getToolChatContextOrThrow<TChatTask extends AnyTask = AnyTask>(): ChatTurnContext<InferChatClientData<TChatTask>>;
 export declare const ai: {
     tool: typeof toolFromTask;
     currentToolOptions: typeof getToolOptionsFromMetadata;
+    /** Get the tool call ID from inside a subtask invoked via `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;
+    /** Get chat context or throw if not in a chat context. Pass `typeof yourChatTask` for typed clientData. */
+    chatContextOrThrow: typeof getToolChatContextOrThrow;
 };
 /**
  * Creates a public access token for a chat task.
@@ -46,6 +96,21 @@ declare function createChatAccessToken<TTask extends AnyTask>(taskId: TaskIdenti
  */
 export declare const CHAT_STREAM_KEY = "chat";
 export { CHAT_MESSAGES_STREAM_ID, CHAT_STOP_STREAM_ID };
+/**
+ * The wire payload shape sent by `TriggerChatTransport`.
+ * Uses `metadata` to match the AI SDK's `ChatRequestOptions` field name.
+ */
+export type ChatTaskWirePayload<TMessage extends UIMessage = UIMessage, TMetadata = unknown> = {
+    messages: TMessage[];
+    chatId: string;
+    trigger: "submit-message" | "regenerate-message" | "preload";
+    messageId?: string;
+    metadata?: TMetadata;
+    /** Whether this run is continuing an existing chat whose previous run ended. */
+    continuation?: boolean;
+    /** The run ID of the previous run (only set when `continuation` is true). */
+    previousRunId?: string;
+};
 /**
  * The payload shape passed to the `chatTask` run function.
  *
@@ -65,12 +130,19 @@ export type ChatTaskPayload<TClientData = unknown> = {
      * The trigger type:
      * - `"submit-message"`: A new user message
      * - `"regenerate-message"`: Regenerate the last assistant response
+     * - `"preload"`: Run was preloaded before the first message (only on turn 0)
      */
-    trigger: "submit-message" | "regenerate-message";
+    trigger: "submit-message" | "regenerate-message" | "preload";
     /** 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?: TClientData;
+    /** Whether this run is continuing an existing chat (previous run timed out or was cancelled). False for brand new chats. */
+    continuation: boolean;
+    /** The run ID of the previous run (only set when `continuation` is true). */
+    previousRunId?: string;
+    /** Whether this run was preloaded before the first message. */
+    preloaded: boolean;
 };
 /**
  * Abort signals provided to the `chatTask` run function.
@@ -167,6 +239,19 @@ declare function pipeChat(source: UIMessageStreamable | AsyncIterable<unknown> |
  * 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 `onPreload` callback.
+ */
+export type PreloadEvent<TClientData = unknown> = {
+    /** The unique identifier for the chat session. */
+    chatId: string;
+    /** The Trigger.dev run ID for this conversation. */
+    runId: string;
+    /** A scoped access token for this chat run. */
+    chatAccessToken: string;
+    /** Custom data from the frontend. */
+    clientData?: TClientData;
+};
 /**
  * Event passed to the `onChatStart` callback.
  */
@@ -181,6 +266,12 @@ export type ChatStartEvent<TClientData = unknown> = {
     runId: string;
     /** A scoped access token for this chat run. Persist this for frontend reconnection. */
     chatAccessToken: string;
+    /** Whether this run is continuing an existing chat (previous run timed out or was cancelled). False for brand new chats. */
+    continuation: boolean;
+    /** The run ID of the previous run (only set when `continuation` is true). */
+    previousRunId?: string;
+    /** Whether this run was preloaded before the first message. */
+    preloaded: boolean;
 };
 /**
  * Event passed to the `onTurnStart` callback.
@@ -200,6 +291,12 @@ export type TurnStartEvent<TClientData = unknown> = {
     chatAccessToken: string;
     /** Custom data from the frontend. */
     clientData?: TClientData;
+    /** Whether this run is continuing an existing chat (previous run timed out or was cancelled). False for brand new chats. */
+    continuation: boolean;
+    /** The run ID of the previous run (only set when `continuation` is true). */
+    previousRunId?: string;
+    /** Whether this run was preloaded before the first message. */
+    preloaded: boolean;
 };
 /**
  * Event passed to the `onTurnComplete` callback.
@@ -224,8 +321,14 @@ export type TurnCompleteEvent<TClientData = unknown> = {
      * 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). */
+    /** 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;
+    /**
+     * 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;
     /** The turn number (0-indexed). */
     turn: number;
     /** The Trigger.dev run ID for this conversation. */
@@ -236,6 +339,14 @@ export type TurnCompleteEvent<TClientData = unknown> = {
     lastEventId?: string;
     /** Custom data from the frontend. */
     clientData?: TClientData;
+    /** Whether the user stopped generation during this turn. */
+    stopped: boolean;
+    /** Whether this run is continuing an existing chat (previous run timed out or was cancelled). False for brand new chats. */
+    continuation: boolean;
+    /** The run ID of the previous run (only set when `continuation` is true). */
+    previousRunId?: string;
+    /** Whether this run was preloaded before the first message. */
+    preloaded: boolean;
 };
 export type ChatTaskOptions<TIdentifier extends string, TClientDataSchema extends TaskSchema | undefined = undefined> = Omit<TaskOptions<TIdentifier, ChatTaskWirePayload, unknown>, "run"> & {
     /**
@@ -267,6 +378,21 @@ export type ChatTaskOptions<TIdentifier extends string, TClientDataSchema extend
      * the stream is automatically piped to the frontend.
      */
     run: (payload: ChatTaskRunPayload<inferSchemaOut<TClientDataSchema>>) => Promise<unknown>;
+    /**
+     * Called when a preloaded run starts, before the first message arrives.
+     *
+     * Use this to initialize state, create DB records, and load context early —
+     * so everything is ready when the user's first message comes through.
+     *
+     * @example
+     * ```ts
+     * onPreload: async ({ chatId, clientData }) => {
+     *   await db.chat.create({ data: { id: chatId } });
+     *   userContext.init(await loadUser(clientData.userId));
+     * }
+     * ```
+     */
+    onPreload?: (event: PreloadEvent<inferSchemaOut<TClientDataSchema>>) => Promise<void> | void;
     /**
      * Called on the first turn (turn 0) of a new run, before the `run` function executes.
      *
@@ -345,6 +471,24 @@ export type ChatTaskOptions<TIdentifier extends string, TClientDataSchema extend
      * @default "1h"
      */
     chatAccessTokenTTL?: string;
+    /**
+     * How long (in seconds) to keep the run warm after `onPreload` fires,
+     * waiting for the first message before suspending.
+     *
+     * Only applies to preloaded runs (triggered via `transport.preload()`).
+     *
+     * @default Same as `warmTimeoutInSeconds`
+     */
+    preloadWarmTimeoutInSeconds?: 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.
+     *
+     * Only applies to preloaded runs.
+     *
+     * @default Same as `turnTimeout`
+     */
+    preloadTimeout?: string;
 };
 /**
  * Creates a Trigger.dev task pre-configured for AI SDK chat.
@@ -426,6 +570,131 @@ declare function setTurnTimeoutInSeconds(seconds: number): void;
  * ```
  */
 declare function setWarmTimeoutInSeconds(seconds: number): void;
+/**
+ * Check whether the user stopped generation during the current turn.
+ *
+ * Works from **anywhere** inside a `chat.task` run — including inside
+ * `streamText`'s `onFinish` callback — without needing to thread the
+ * `stopSignal` through closures.
+ *
+ * This is especially useful when the AI SDK's `isAborted` flag is unreliable
+ * (e.g. when using `createUIMessageStream` + `writer.merge()`).
+ *
+ * @example
+ * ```ts
+ * onFinish: ({ isAborted }) => {
+ *   const wasStopped = isAborted || chat.isStopped();
+ *   if (wasStopped) {
+ *     // handle stop
+ *   }
+ * }
+ * ```
+ */
+declare function isStopped(): boolean;
+/**
+ * Register a promise that runs in the background during the current turn.
+ *
+ * Use this to move non-blocking work (DB writes, analytics, etc.) out of
+ * the critical path. The promise runs in parallel with streaming and is
+ * awaited (with a 5 s timeout) before `onTurnComplete` fires.
+ *
+ * @example
+ * ```ts
+ * onTurnStart: async ({ chatId, uiMessages }) => {
+ *   // Persist messages without blocking the LLM call
+ *   chat.defer(db.chat.update({ where: { id: chatId }, data: { messages: uiMessages } }));
+ * },
+ * ```
+ */
+declare function chatDefer(promise: Promise<unknown>): void;
+/**
+ * Clean up a UIMessage that was captured during an aborted/stopped turn.
+ *
+ * When generation is stopped mid-stream, the captured message may contain:
+ * - Tool parts stuck in incomplete states (`partial-call`, `input-available`,
+ *   `input-streaming`) that cause permanent UI spinners
+ * - Reasoning parts with `state: "streaming"` instead of `"done"`
+ * - Text parts with `state: "streaming"` instead of `"done"`
+ *
+ * This function returns a cleaned copy with:
+ * - Incomplete tool parts removed entirely
+ * - Reasoning and text parts marked as `"done"`
+ *
+ * `chat.task` calls this automatically when stop is detected before passing
+ * the response to `onTurnComplete`. Use this manually when calling `pipeChat`
+ * directly and capturing response messages yourself.
+ *
+ * @example
+ * ```ts
+ * onTurnComplete: async ({ responseMessage, stopped }) => {
+ *   // Already cleaned automatically by chat.task — but if you captured
+ *   // your own message via pipeChat, clean it manually:
+ *   const cleaned = chat.cleanupAbortedParts(myMessage);
+ *   await db.messages.save(cleaned);
+ * }
+ * ```
+ */
+declare function cleanupAbortedParts(message: UIMessage): UIMessage;
+/**
+ * A Proxy-backed, run-scoped data object that appears as `T` to users.
+ * Includes helper methods for initialization, dirty tracking, and serialization.
+ * Internal metadata is stored behind Symbols and invisible to
+ * `Object.keys()`, `JSON.stringify()`, and spread.
+ */
+export type ChatLocal<T extends Record<string, unknown>> = T & {
+    /** Initialize the local with a value. Call in `onChatStart` or `run()`. */
+    init(value: T): void;
+    /** Returns `true` if any property was set since the last check. Resets the dirty flag. */
+    hasChanged(): boolean;
+    /** Returns a plain object copy of the current value. Useful for persistence. */
+    get(): T;
+    readonly [CHAT_LOCAL_KEY]: ReturnType<typeof locals.create<T>>;
+    readonly [CHAT_LOCAL_DIRTY_KEY]: ReturnType<typeof locals.create<boolean>>;
+};
+/**
+ * Creates a per-run typed data object accessible from anywhere during task execution.
+ *
+ * Declare at module level, then initialize inside a lifecycle hook (e.g. `onChatStart`)
+ * using `chat.initLocal()`. Properties are accessible directly via the Proxy.
+ *
+ * Multiple locals can coexist — each gets its own isolated run-scoped storage.
+ *
+ * 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).
+ *
+ * @example
+ * ```ts
+ * import { chat } from "@trigger.dev/sdk/ai";
+ *
+ * const userPrefs = chat.local<{ theme: string; language: string }>({ id: "userPrefs" });
+ * const gameState = chat.local<{ score: number; streak: number }>({ id: "gameState" });
+ *
+ * export const myChat = chat.task({
+ *   id: "my-chat",
+ *   onChatStart: async ({ clientData }) => {
+ *     const prefs = await db.prefs.findUnique({ where: { userId: clientData.userId } });
+ *     userPrefs.init(prefs ?? { theme: "dark", language: "en" });
+ *     gameState.init({ score: 0, streak: 0 });
+ *   },
+ *   onTurnComplete: async ({ chatId }) => {
+ *     if (gameState.hasChanged()) {
+ *       await db.save({ where: { chatId }, data: gameState.get() });
+ *     }
+ *   },
+ *   run: async ({ messages }) => {
+ *     gameState.score++;
+ *     return streamText({
+ *       system: `User prefers ${userPrefs.theme} theme. Score: ${gameState.score}`,
+ *       messages,
+ *     });
+ *   },
+ * });
+ * ```
+ */
+declare function chatLocal<T extends Record<string, unknown>>(options: {
+    id: string;
+}): ChatLocal<T>;
 /**
  * Extracts the client data (metadata) type from a chat task.
  * Use this to type the `metadata` option on the transport.
@@ -445,6 +714,8 @@ export declare const chat: {
     task: typeof chatTask;
     /** Pipe a stream to the chat transport. See {@link pipeChat}. */
     pipe: typeof pipeChat;
+    /** Create a per-run typed local. See {@link chatLocal}. */
+    local: typeof chatLocal;
     /** 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}. */
@@ -453,4 +724,12 @@ export declare const chat: {
     setTurnTimeoutInSeconds: typeof setTurnTimeoutInSeconds;
     /** Override the warm timeout at runtime. See {@link setWarmTimeoutInSeconds}. */
     setWarmTimeoutInSeconds: typeof setWarmTimeoutInSeconds;
+    /** 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}. */
+    cleanupAbortedParts: typeof cleanupAbortedParts;
+    /** Register background work that runs in parallel with streaming. See {@link chatDefer}. */
+    defer: typeof chatDefer;
+    /** Typed chat output stream for writing custom chunks or piping from subtasks. */
+    stream: import("@trigger.dev/core/v3").RealtimeDefinedStream<UIMessageChunk>;
 };