@trigger.dev/sdk 0.0.0-chat-prerelease-20260417152143 → 0.0.0-chat-prerelease-20260418174118

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

@@ -1,5 +1,5 @@
 import { AnyTask, Task, type inferSchemaIn, type inferSchemaOut, type TaskIdentifier, type TaskOptions, type TaskSchema, type TaskRunContext, type TaskWithSchema } from "@trigger.dev/core/v3";
-import type { ModelMessage, ToolSet, UIMessage, UIMessageChunk, UIMessageStreamOptions, LanguageModelUsage } from "ai";
+import type { FinishReason, ModelMessage, ToolSet, UIMessage, UIMessageChunk, UIMessageStreamOptions, LanguageModelUsage } from "ai";
 import { Tool, ToolCallOptions } from "ai";
 import { locals } from "./locals.js";
 import type { ResolvedPrompt } from "./prompt.js";
@@ -202,8 +202,12 @@ export type ChatTaskPayload<TClientData = unknown> = {
      * - `"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)
+     * - `"action"`: A typed action from the frontend (see `actionSchema` + `onAction`).
+     *   The action has already been applied before `run()` fires — check `trigger === "action"`
+     *   to short-circuit the LLM call when an action doesn't need a response.
+     * - `"close"`: The chat session is being closed (internal; `run()` is not called).
      */
-    trigger: "submit-message" | "regenerate-message" | "preload" | "close";
+    trigger: "submit-message" | "regenerate-message" | "preload" | "action" | "close";
     /** 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). */
@@ -979,6 +983,22 @@ export type TurnCompleteEvent<TClientData = unknown, TUIM extends UIMessage = UI
     usage?: LanguageModelUsage;
     /** Cumulative token usage across all turns in this run (including this turn). */
     totalUsage: LanguageModelUsage;
+    /**
+     * Why the LLM stopped generating this turn:
+     * - `"stop"` — model generated a stop sequence (normal completion)
+     * - `"tool-calls"` — model stopped on one or more tool calls. If any tool
+     *   has no `execute` function (e.g. an `ask_user` HITL tool), the turn is
+     *   paused awaiting user input; inspect `responseMessage.parts` for tool
+     *   parts in `input-available` state to distinguish.
+     * - `"length"` — max tokens reached
+     * - `"content-filter"` — content filter stopped the model
+     * - `"error"` — model errored
+     * - `"other"` — provider-specific reason
+     *
+     * Undefined if the underlying stream didn't provide a finish reason (e.g.
+     * manual `pipeChat()` or an aborted stream).
+     */
+    finishReason?: FinishReason;
 };
 /**
  * Event passed to the `onBeforeTurnComplete` callback.
@@ -1744,6 +1764,33 @@ declare function isStopped(): boolean;
  * ```
  */
 declare function requestUpgrade(): void;
+/**
+ * Exit the run after the current turn completes, without waiting for the
+ * next message. Unlike {@link requestUpgrade}, no upgrade-required signal
+ * is sent to the client — the turn finishes normally, `onTurnComplete`
+ * fires, and the loop exits instead of going idle.
+ *
+ * Call from `run()`, `chat.defer()`, `onBeforeTurnComplete`, or
+ * `onTurnComplete` to end the run on your own terms (budget exhausted,
+ * task complete, goal achieved, etc.).
+ *
+ * The next user message on the same `chatId` starts a fresh run via the
+ * normal continuation mechanism.
+ *
+ * @example
+ * ```ts
+ * chat.agent({
+ *   id: "one-shot-agent",
+ *   run: async ({ messages, signal }) => {
+ *     const result = streamText({ model: openai("gpt-4o"), messages, abortSignal: signal });
+ *     // Single-response agent — exit after this turn.
+ *     chat.endRun();
+ *     return result;
+ *   },
+ * });
+ * ```
+ */
+declare function endRun(): void;
 /**
  * Register a promise that runs in the background during the current turn.
  *
@@ -2208,6 +2255,8 @@ export declare const chat: {
     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;
+    /** Exit the run after the current turn completes, without any upgrade signal. See {@link endRun}. */
+    endRun: typeof endRun;
     /** 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

@@ -482,6 +482,12 @@ 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 Flag set by `chat.endRun()` to exit the loop after the current
+ * turn completes, without any upgrade semantics. Checked at the same
+ * post-turn / pre-wait sites as `chatUpgradeRequestedKey`.
+ */
+const chatEndRunRequestedKey = locals_js_1.locals.create("chat.endRunRequested");
 /** @internal */
 const chatAgentCompactionKey = locals_js_1.locals.create("chat.agentCompaction");
 /**
@@ -1666,6 +1672,7 @@ function chatAgent(options) {
                             }
                             // Captured by the onFinish callback below — works even on abort/stop.
                             let capturedResponseMessage;
+                            let capturedFinishReason;
                             // Promise that resolves when the AI SDK's onFinish fires.
                             // On abort, the stream's cancel() handler calls onFinish
                             // asynchronously AFTER pipeChat resolves, so we must await
@@ -1727,8 +1734,9 @@ function chatAgent(options) {
                                         // messageId. Without this, the frontend and backend generate IDs
                                         // independently and they won't match for ID-based dedup.
                                         generateMessageId: resolvedOptions.generateMessageId ?? ai_1.generateId,
-                                        onFinish: ({ responseMessage }) => {
+                                        onFinish: ({ responseMessage, finishReason, }) => {
                                             capturedResponseMessage = responseMessage;
+                                            capturedFinishReason = finishReason;
                                             resolveOnFinish();
                                         },
                                     });
@@ -2056,6 +2064,7 @@ function chatAgent(options) {
                                 preloaded,
                                 usage: turnUsage,
                                 totalUsage: cumulativeUsage,
+                                finishReason: capturedFinishReason,
                             };
                             // Fire onBeforeTurnComplete — stream is still open so the hook
                             // can write custom chunks to the frontend (e.g. compaction progress).
@@ -2158,7 +2167,9 @@ function chatAgent(options) {
                             }
                             // 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)) {
+                            // chat.endRun() — same exit, no upgrade semantics.
+                            if (locals_js_1.locals.get(chatUpgradeRequestedKey) ||
+                                locals_js_1.locals.get(chatEndRunRequestedKey)) {
                                 return "exit";
                             }
                             // Wait for the next message — stay idle briefly, then suspend
@@ -2253,8 +2264,9 @@ 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)) {
+                        // chat.requestUpgrade() / chat.endRun() — exit after error turn too
+                        if (locals_js_1.locals.get(chatUpgradeRequestedKey) ||
+                            locals_js_1.locals.get(chatEndRunRequestedKey)) {
                             return;
                         }
                         // Wait for the next message — same as after a successful turn
@@ -2624,6 +2636,35 @@ function isStopped() {
 function requestUpgrade() {
     locals_js_1.locals.set(chatUpgradeRequestedKey, true);
 }
+/**
+ * Exit the run after the current turn completes, without waiting for the
+ * next message. Unlike {@link requestUpgrade}, no upgrade-required signal
+ * is sent to the client — the turn finishes normally, `onTurnComplete`
+ * fires, and the loop exits instead of going idle.
+ *
+ * Call from `run()`, `chat.defer()`, `onBeforeTurnComplete`, or
+ * `onTurnComplete` to end the run on your own terms (budget exhausted,
+ * task complete, goal achieved, etc.).
+ *
+ * The next user message on the same `chatId` starts a fresh run via the
+ * normal continuation mechanism.
+ *
+ * @example
+ * ```ts
+ * chat.agent({
+ *   id: "one-shot-agent",
+ *   run: async ({ messages, signal }) => {
+ *     const result = streamText({ model: openai("gpt-4o"), messages, abortSignal: signal });
+ *     // Single-response agent — exit after this turn.
+ *     chat.endRun();
+ *     return result;
+ *   },
+ * });
+ * ```
+ */
+function endRun() {
+    locals_js_1.locals.set(chatEndRunRequestedKey, true);
+}
 // ---------------------------------------------------------------------------
 // Per-turn deferred work
 // ---------------------------------------------------------------------------
@@ -3085,8 +3126,9 @@ 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)) {
+                        // chat.requestUpgrade() / chat.endRun() — exit before waiting
+                        if (locals_js_1.locals.get(chatUpgradeRequestedKey) ||
+                            locals_js_1.locals.get(chatEndRunRequestedKey)) {
                             stop.cleanup();
                             return { done: true, value: undefined };
                         }
@@ -3592,6 +3634,8 @@ exports.chat = {
     isStopped,
     /** Request that the run exits after the current turn so the next message starts on the latest version. See {@link requestUpgrade}. */
     requestUpgrade,
+    /** Exit the run after the current turn completes, without any upgrade signal. See {@link endRun}. */
+    endRun,
     /** Clean up aborted parts from a UIMessage. See {@link cleanupAbortedParts}. */
     cleanupAbortedParts,
     /** Register background work that runs in parallel with streaming. See {@link chatDefer}. */