@trigger.dev/sdk 0.0.0-chat-prerelease-20260402124815 → 0.0.0-chat-prerelease-20260413101648

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

@@ -832,6 +832,19 @@ export type ChatStartEvent<TClientData = unknown> = {
     /** Stream writer — write custom `UIMessageChunk` parts to the chat stream. Lazy: no overhead if unused. */
     writer: ChatWriter;
 };
+/**
+ * Event passed to the `onValidateMessages` callback.
+ */
+export type ValidateMessagesEvent<TUIM extends UIMessage = UIMessage> = {
+    /** The incoming UI messages for this turn (after cleanup of aborted tool parts). */
+    messages: TUIM[];
+    /** The unique identifier for the chat session. */
+    chatId: string;
+    /** The turn number (0-indexed). */
+    turn: number;
+    /** The trigger type for this turn. */
+    trigger: "submit-message" | "regenerate-message" | "preload" | "close";
+};
 /**
  * Event passed to the `onTurnStart` callback.
  */
@@ -1055,6 +1068,32 @@ export type ChatAgentOptions<TIdentifier extends string, TClientDataSchema exten
      * ```
      */
     onChatStart?: (event: ChatStartEvent<inferSchemaOut<TClientDataSchema>>) => Promise<void> | void;
+    /**
+     * Validate or transform incoming UI messages before they are converted to model
+     * messages and accumulated. Fires once per turn with the raw `UIMessage[]` from
+     * the wire payload (after cleanup of aborted tool parts).
+     *
+     * Return the validated messages array. Throw to abort the turn with an error.
+     *
+     * This is the right place to call the AI SDK's `validateUIMessages` to catch
+     * malformed messages from storage or untrusted input before they reach the model.
+     *
+     * @example
+     * ```ts
+     * import { validateUIMessages } from "ai";
+     *
+     * chat.agent({
+     *   id: "my-chat",
+     *   onValidateMessages: async ({ messages }) => {
+     *     return validateUIMessages({ messages, tools: chatTools });
+     *   },
+     *   run: async ({ messages }) => {
+     *     return streamText({ model, messages, tools: chatTools });
+     *   },
+     * });
+     * ```
+     */
+    onValidateMessages?: (event: ValidateMessagesEvent<TUIMessage>) => TUIMessage[] | Promise<TUIMessage[]>;
     /**
      * Called at the start of every turn, after message accumulation and `onChatStart` (turn 0),
      * but before the `run` function executes.
@@ -1199,6 +1238,8 @@ export type ChatAgentOptions<TIdentifier extends string, TClientDataSchema exten
      * waiting for the first message before suspending.
      *
      * Only applies to preloaded runs (triggered via `transport.preload()`).
+     * Takes precedence over `transport.preload(..., { idleTimeoutInSeconds })`
+     * and over {@link ChatAgentOptions.idleTimeoutInSeconds}.
      *
      * @default Same as `idleTimeoutInSeconds`
      */
@@ -1554,6 +1595,36 @@ declare function setUIMessageStreamOptions(options: ChatUIMessageStreamOptions<U
  * ```
  */
 declare function isStopped(): boolean;
+/**
+ * Request that the current run exits so the next message starts on the latest
+ * deployed version (via the standard continuation mechanism).
+ *
+ * When called from `onTurnStart` or `onValidateMessages`, `run()` is skipped
+ * entirely — the run exits immediately and the transport re-triggers the
+ * same message on the new version.
+ *
+ * When called from `run()` or `chat.defer()`, the current turn completes
+ * normally and the run exits afterward instead of waiting for the next message.
+ *
+ * Call from `onTurnStart`, `onValidateMessages`, `onChatResume`, `run()`,
+ * or inside `chat.defer()`.
+ *
+ * @example
+ * ```ts
+ * const SUPPORTED_VERSIONS = new Set(["v2", "v3"]);
+ *
+ * chat.agent({
+ *   id: "my-chat",
+ *   onTurnStart: async ({ clientData }) => {
+ *     if (clientData?.protocolVersion && !SUPPORTED_VERSIONS.has(clientData.protocolVersion)) {
+ *       chat.requestUpgrade();
+ *     }
+ *   },
+ *   run: async ({ messages }) => { ... },
+ * });
+ * ```
+ */
+declare function requestUpgrade(): void;
 /**
  * Register a promise that runs in the background during the current turn.
  *
@@ -1564,12 +1635,18 @@ declare function isStopped(): boolean;
  * @example
  * ```ts
  * onTurnStart: async ({ chatId, uiMessages }) => {
- *   // Persist messages without blocking the LLM call
+ *   // Pass a promise directly
  *   chat.defer(db.chat.update({ where: { id: chatId }, data: { messages: uiMessages } }));
+ *
+ *   // Or pass an async function — cleaner for multi-step work
+ *   chat.defer(async () => {
+ *     const flags = await getFeatureFlags();
+ *     if (flags.forceUpgrade) chat.requestUpgrade();
+ *   });
  * },
  * ```
  */
-declare function chatDefer(promise: Promise<unknown>): void;
+declare function chatDefer(promiseOrFn: Promise<unknown> | (() => Promise<unknown>)): void;
 /**
  * Queue model messages for injection at the next `prepareStep` boundary.
  *
@@ -2010,6 +2087,8 @@ export declare const chat: {
     setUIMessageStreamOptions: typeof setUIMessageStreamOptions;
     /** Check if the current turn was stopped by the user. See {@link isStopped}. */
     isStopped: typeof isStopped;
+    /** Request that the run exits after the current turn so the next message starts on the latest version. See {@link requestUpgrade}. */
+    requestUpgrade: typeof requestUpgrade;
     /** 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}. */

package/dist/commonjs/v3/ai.js

@@ -384,6 +384,8 @@ const chatOnCompactedKey = locals_js_1.locals.create("chat.onCompacted");
 /** @internal Full task `ctx` for the active `chat.agent` run (for hooks invoked from nested compaction). */
 const chatAgentRunContextKey = locals_js_1.locals.create("chat.agentRunContext");
 const chatPrepareMessagesKey = locals_js_1.locals.create("chat.prepareMessages");
+/** @internal Flag set by `chat.requestUpgrade()` to exit the loop after the current turn. */
+const chatUpgradeRequestedKey = locals_js_1.locals.create("chat.upgradeRequested");
 /** @internal */
 const chatAgentCompactionKey = locals_js_1.locals.create("chat.agentCompaction");
 /**
@@ -975,7 +977,7 @@ function chatCustomAgent(options) {
     return task;
 }
 function chatAgent(options) {
-    const { run: userRun, clientDataSchema, onPreload, onChatStart, onTurnStart, onBeforeTurnComplete, onCompacted, compaction, pendingMessages: pendingMessagesConfig, prepareMessages, onTurnComplete, maxTurns = 100, turnTimeout = "1h", idleTimeoutInSeconds = 30, chatAccessTokenTTL = "1h", preloadIdleTimeoutInSeconds, preloadTimeout, uiMessageStreamOptions, onChatSuspend, onChatResume, exitAfterPreloadIdle = false, ...restOptions } = options;
+    const { run: userRun, clientDataSchema, onPreload, onChatStart, onValidateMessages, onTurnStart, onBeforeTurnComplete, onCompacted, compaction, pendingMessages: pendingMessagesConfig, prepareMessages, onTurnComplete, maxTurns = 100, turnTimeout = "1h", idleTimeoutInSeconds = 30, chatAccessTokenTTL = "1h", preloadIdleTimeoutInSeconds, preloadTimeout, uiMessageStreamOptions, onChatSuspend, onChatResume, exitAfterPreloadIdle = false, ...restOptions } = options;
     const parseClientData = clientDataSchema ? (0, v3_1.getSchemaParseFn)(clientDataSchema) : undefined;
     const task = (0, shared_js_1.createTask)({
         retry: { maxAttempts: 1 },
@@ -1073,8 +1075,12 @@ function chatAgent(options) {
                             },
                         });
                     }
-                    // Wait for the first real message — use preload-specific timeouts if configured
-                    const effectivePreloadIdleTimeout = payload.idleTimeoutInSeconds ?? preloadIdleTimeoutInSeconds ?? idleTimeoutInSeconds;
+                    // Wait for the first real message — task-level idle settings win over
+                    // `transport.preload(..., { idleTimeoutInSeconds })` / wire payload so
+                    // `chat.agent({ idleTimeoutInSeconds, preloadIdleTimeoutInSeconds })` is authoritative.
+                    const effectivePreloadIdleTimeout = preloadIdleTimeoutInSeconds ??
+                        idleTimeoutInSeconds ??
+                        payload.idleTimeoutInSeconds;
                     const effectivePreloadTimeout = metadata_js_1.metadata.get(TURN_TIMEOUT_METADATA_KEY) ??
                         preloadTimeout ??
                         turnTimeout;
@@ -1236,7 +1242,27 @@ function chatAgent(options) {
                             // useChat state may still contain assistant messages with tool parts
                             // in partial/input-available state. These cause API errors (e.g.
                             // Anthropic requires every tool_use to have a matching tool_result).
-                            const cleanedUIMessages = uiMessages.map((msg) => msg.role === "assistant" ? cleanupAbortedParts(msg) : msg);
+                            let cleanedUIMessages = uiMessages.map((msg) => msg.role === "assistant" ? cleanupAbortedParts(msg) : msg);
+                            // Validate/transform UIMessages before conversion — catches malformed
+                            // messages from storage or untrusted input before they reach the model.
+                            if (onValidateMessages) {
+                                cleanedUIMessages = await tracer_js_1.tracer.startActiveSpan("onValidateMessages()", async () => {
+                                    return onValidateMessages({
+                                        messages: cleanedUIMessages,
+                                        chatId: currentWirePayload.chatId,
+                                        turn,
+                                        trigger: currentWirePayload.trigger,
+                                    });
+                                }, {
+                                    attributes: {
+                                        [v3_1.SemanticInternalAttributes.STYLE_ICON]: "task-hook-onStart",
+                                        [v3_1.SemanticInternalAttributes.COLLAPSED]: true,
+                                        "chat.id": currentWirePayload.chatId,
+                                        "chat.turn": turn + 1,
+                                        "chat.messages.count": cleanedUIMessages.length,
+                                    },
+                                });
+                            }
                             // Convert the incoming UIMessages to model messages and update the accumulator.
                             // Turn 1: full history from the frontend → replaces the accumulator.
                             // Turn 2+: only the new message(s) → appended to the accumulator.
@@ -1360,6 +1386,13 @@ function chatAgent(options) {
                                     },
                                 });
                             }
+                            // chat.requestUpgrade() called in onTurnStart (or onValidateMessages) —
+                            // skip run() and signal the transport to re-trigger the same message
+                            // on the new version.
+                            if (locals_js_1.locals.get(chatUpgradeRequestedKey)) {
+                                await writeUpgradeRequiredChunk();
+                                return "exit";
+                            }
                             // Captured by the onFinish callback below — works even on abort/stop.
                             let capturedResponseMessage;
                             // Promise that resolves when the AI SDK's onFinish fires.
@@ -1425,8 +1458,13 @@ function chatAgent(options) {
                             }
                             // Wait for onFinish to fire — on abort this may resolve slightly
                             // after pipeChat, since the stream's cancel() handler is async.
+                            // Race with a timeout so a stop-abort that prevents onFinish from
+                            // firing doesn't hang the turn loop indefinitely.
                             if (onFinishAttached) {
-                                await onFinishPromise;
+                                await Promise.race([
+                                    onFinishPromise,
+                                    new Promise((r) => setTimeout(r, 2_000)),
+                                ]);
                             }
                             // Capture token usage from the streamText result (if available).
                             // totalUsage is a PromiseLike that resolves after the stream is consumed.
@@ -1714,7 +1752,7 @@ function chatAgent(options) {
                                 await tracer_js_1.tracer.startActiveSpan("onTurnComplete()", async () => {
                                     await onTurnComplete({
                                         ...turnCompleteEvent,
-                                        lastEventId: turnCompleteResult.lastEventId,
+                                        lastEventId: turnCompleteResult?.lastEventId,
                                     });
                                     // Check if onTurnComplete replaced messages (compaction)
                                     const turnCompleteOverride = locals_js_1.locals.get(chatOverrideMessagesKey);
@@ -1762,6 +1800,11 @@ function chatAgent(options) {
                                 currentWirePayload = pendingMessages[0];
                                 return "continue";
                             }
+                            // chat.requestUpgrade() was called — exit the loop so the
+                            // transport triggers a new run on the latest version.
+                            if (locals_js_1.locals.get(chatUpgradeRequestedKey)) {
+                                return "exit";
+                            }
                             // Wait for the next message — stay idle briefly, then suspend
                             const effectiveIdleTimeout = metadata_js_1.metadata.get(IDLE_TIMEOUT_METADATA_KEY) ??
                                 idleTimeoutInSeconds;
@@ -1854,6 +1897,10 @@ function chatAgent(options) {
                         catch {
                             // Best-effort — if stream write fails, let the run continue anyway
                         }
+                        // chat.requestUpgrade() — exit after error turn too
+                        if (locals_js_1.locals.get(chatUpgradeRequestedKey)) {
+                            return;
+                        }
                         // Wait for the next message — same as after a successful turn
                         const effectiveIdleTimeout = metadata_js_1.metadata.get(IDLE_TIMEOUT_METADATA_KEY) ??
                             idleTimeoutInSeconds;
@@ -2187,6 +2234,41 @@ function isStopped() {
     return controller?.signal.aborted ?? false;
 }
 // ---------------------------------------------------------------------------
+// Version upgrade
+// ---------------------------------------------------------------------------
+/**
+ * Request that the current run exits so the next message starts on the latest
+ * deployed version (via the standard continuation mechanism).
+ *
+ * When called from `onTurnStart` or `onValidateMessages`, `run()` is skipped
+ * entirely — the run exits immediately and the transport re-triggers the
+ * same message on the new version.
+ *
+ * When called from `run()` or `chat.defer()`, the current turn completes
+ * normally and the run exits afterward instead of waiting for the next message.
+ *
+ * Call from `onTurnStart`, `onValidateMessages`, `onChatResume`, `run()`,
+ * or inside `chat.defer()`.
+ *
+ * @example
+ * ```ts
+ * const SUPPORTED_VERSIONS = new Set(["v2", "v3"]);
+ *
+ * chat.agent({
+ *   id: "my-chat",
+ *   onTurnStart: async ({ clientData }) => {
+ *     if (clientData?.protocolVersion && !SUPPORTED_VERSIONS.has(clientData.protocolVersion)) {
+ *       chat.requestUpgrade();
+ *     }
+ *   },
+ *   run: async ({ messages }) => { ... },
+ * });
+ * ```
+ */
+function requestUpgrade() {
+    locals_js_1.locals.set(chatUpgradeRequestedKey, true);
+}
+// ---------------------------------------------------------------------------
 // Per-turn deferred work
 // ---------------------------------------------------------------------------
 /**
@@ -2199,15 +2281,21 @@ function isStopped() {
  * @example
  * ```ts
  * onTurnStart: async ({ chatId, uiMessages }) => {
- *   // Persist messages without blocking the LLM call
+ *   // Pass a promise directly
  *   chat.defer(db.chat.update({ where: { id: chatId }, data: { messages: uiMessages } }));
+ *
+ *   // Or pass an async function — cleaner for multi-step work
+ *   chat.defer(async () => {
+ *     const flags = await getFeatureFlags();
+ *     if (flags.forceUpgrade) chat.requestUpgrade();
+ *   });
  * },
  * ```
  */
-function chatDefer(promise) {
+function chatDefer(promiseOrFn) {
     const promises = locals_js_1.locals.get(chatDeferKey);
     if (promises) {
-        promises.add(promise);
+        promises.add(typeof promiseOrFn === "function" ? promiseOrFn() : promiseOrFn);
     }
 }
 // ---------------------------------------------------------------------------
@@ -2613,7 +2701,8 @@ class ChatMessageAccumulator {
  * ```
  */
 function createChatSession(payload, options) {
-    const { signal: runSignal, idleTimeoutInSeconds = 30, timeout = "1h", maxTurns = 100, compaction: sessionCompaction, pendingMessages: sessionPendingMessages, } = options;
+    const { signal: runSignal, idleTimeoutInSeconds: sessionIdleTimeoutOpt, timeout = "1h", maxTurns = 100, compaction: sessionCompaction, pendingMessages: sessionPendingMessages, } = options;
+    const idleTimeoutInSeconds = sessionIdleTimeoutOpt ?? 30;
     return {
         [Symbol.asyncIterator]() {
             let currentPayload = payload;
@@ -2628,7 +2717,7 @@ function createChatSession(payload, options) {
                     // First turn: handle preload — wait for the first real message
                     if (turn === 0 && currentPayload.trigger === "preload") {
                         const result = await messagesInput.waitWithIdleTimeout({
-                            idleTimeoutInSeconds: currentPayload.idleTimeoutInSeconds ?? idleTimeoutInSeconds,
+                            idleTimeoutInSeconds: sessionIdleTimeoutOpt ?? currentPayload.idleTimeoutInSeconds ?? 30,
                             timeout,
                             spanName: "waiting for first message",
                         });
@@ -2640,6 +2729,11 @@ function createChatSession(payload, options) {
                     }
                     // Subsequent turns: wait for the next message
                     if (turn > 0) {
+                        // chat.requestUpgrade() — exit before waiting
+                        if (locals_js_1.locals.get(chatUpgradeRequestedKey)) {
+                            stop.cleanup();
+                            return { done: true, value: undefined };
+                        }
                         const next = await messagesInput.waitWithIdleTimeout({
                             idleTimeoutInSeconds,
                             timeout,
@@ -2702,6 +2796,13 @@ function createChatSession(payload, options) {
                     });
                     // Accumulate messages
                     const messages = await accumulator.addIncoming(currentPayload.messages, currentPayload.trigger, turn);
+                    // chat.requestUpgrade() called before this turn — signal transport and exit
+                    if (locals_js_1.locals.get(chatUpgradeRequestedKey)) {
+                        await writeUpgradeRequiredChunk();
+                        sessionMsgSub.off();
+                        stop.cleanup();
+                        return { done: true, value: undefined };
+                    }
                     const combinedSignal = AbortSignal.any([runSignal, stop.signal]);
                     const turnObj = {
                         number: turn,
@@ -3107,6 +3208,8 @@ exports.chat = {
     setUIMessageStreamOptions,
     /** Check if the current turn was stopped by the user. See {@link isStopped}. */
     isStopped,
+    /** Request that the run exits after the current turn so the next message starts on the latest version. See {@link requestUpgrade}. */
+    requestUpgrade,
     /** Clean up aborted parts from a UIMessage. See {@link cleanupAbortedParts}. */
     cleanupAbortedParts,
     /** Register background work that runs in parallel with streaming. See {@link chatDefer}. */
@@ -3166,13 +3269,30 @@ async function writeTurnCompleteChunk(chatId, publicAccessToken) {
         collapsed: true,
         execute: ({ write }) => {
             write({
-                type: "__trigger_turn_complete",
+                type: "trigger:turn-complete",
                 ...(publicAccessToken ? { publicAccessToken } : {}),
             });
         },
     });
     return await waitUntilComplete();
 }
+/**
+ * Writes an upgrade-required control chunk to the chat output stream.
+ * The transport intercepts this to re-trigger the same message on the latest version.
+ * @internal
+ */
+async function writeUpgradeRequiredChunk() {
+    const { waitUntilComplete } = streams_js_1.streams.writer(exports.CHAT_STREAM_KEY, {
+        spanName: "upgrade required",
+        collapsed: true,
+        execute: ({ write }) => {
+            write({
+                type: "trigger:upgrade-required",
+            });
+        },
+    });
+    return await waitUntilComplete();
+}
 /**
  * Extracts the text content of the last user message from a UIMessage array.
  * Returns undefined if no user message is found.