@trigger.dev/sdk 0.0.0-chat-prerelease-20260502065709 → 0.0.0-chat-prerelease-20260505140031

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

@@ -15,7 +15,7 @@
  * import from `ai.ts`.
  */
 import type { Task, AnyTask } from "@trigger.dev/core/v3";
-import type { UIMessage } from "ai";
+import type { ModelMessage, UIMessage } from "ai";
 /**
  * Message-part `type` value for the pending-message data part the agent
  * injects when a follow-up message arrives mid-turn.
@@ -28,7 +28,16 @@ export declare const PENDING_MESSAGE_INJECTED_TYPE: "data-pending-message-inject
 export type ChatTaskWirePayload<TMessage extends UIMessage = UIMessage, TMetadata = unknown> = {
     messages: TMessage[];
     chatId: string;
-    trigger: "submit-message" | "regenerate-message" | "preload" | "close" | "action";
+    trigger: "submit-message" | "regenerate-message" | "preload" | "close" | "action"
+    /**
+     * The customer's `chat.handover` route handler kicked us off in
+     * parallel with the first-turn `streamText` running in the warm
+     * Next.js process. The run sits idle on `session.in` waiting for
+     * a `kind: "handover"` (continue from tool execution) or
+     * `kind: "handover-skip"` (handler finished pure-text, exit
+     * cleanly). See `chat.handover` in `@trigger.dev/sdk/chat-server`.
+     */
+     | "handover-prepare";
     messageId?: string;
     metadata?: TMetadata;
     /** Custom action payload when `trigger` is `"action"`. Validated against `actionSchema` on the backend. */
@@ -77,6 +86,54 @@ export type ChatInputChunk<TMessage extends UIMessage = UIMessage, TMetadata = u
     kind: "stop";
     /** Optional human-readable reason. Maps to the legacy `chat-stop` record. */
     message?: string;
+} | {
+    /**
+     * Sent by `chat.headStart` when the customer's first-turn
+     * `streamText` finishes. The agent run (currently parked in
+     * `handover-prepare`) wakes, seeds its accumulators with
+     * `partialAssistantMessage`, and runs the normal turn loop
+     * (`onChatStart` → `onTurnStart` → … → `onTurnComplete`).
+     *
+     * What happens after that depends on `isFinal`:
+     *
+     * - `isFinal: false` — step 1 ended with `finishReason:
+     *   "tool-calls"`. The partial carries the assistant's
+     *   tool-call(s) wrapped in AI SDK's tool-approval round. The
+     *   agent's `streamText` runs the approved tools and continues
+     *   from step 2.
+     * - `isFinal: true` — step 1 ended pure-text (no tool calls).
+     *   The partial carries the final assistant text. The agent
+     *   skips the LLM call entirely (the response is already
+     *   complete on the customer side) and runs `onTurnComplete`
+     *   with the partial as `responseMessage` so persistence and
+     *   any post-turn work fire normally.
+     */
+    kind: "handover";
+    /** Customer's step-1 response messages (ModelMessage form). */
+    partialAssistantMessage: ModelMessage[];
+    /**
+     * The UI messageId the customer's handler used for its step-1
+     * assistant message. The agent reuses this so any post-handover
+     * chunks (tool-output-available, step-2 text, data-* parts
+     * written by hooks) merge into the SAME assistant message on
+     * the browser side instead of starting a new one.
+     */
+    messageId?: string;
+    /**
+     * Whether the customer's step 1 is the final response. See
+     * `kind` description above for the two branches.
+     */
+    isFinal: boolean;
+} | {
+    /**
+     * Sent by `chat.headStart` only when the customer's handler
+     * ABORTS before producing a finishReason (e.g., dispatch error,
+     * stream cancelled before any tokens). The agent run exits
+     * cleanly without firing turn hooks. Normal pure-text and
+     * tool-call finishes go through `kind: "handover"` with the
+     * appropriate `isFinal` flag.
+     */
+    kind: "handover-skip";
 };
 /**
  * Extracts the client-data (`metadata`) type from a chat task.

package/dist/commonjs/v3/ai.js

@@ -672,12 +672,113 @@ const stopInput = {
         await getChatSession().in.send({ kind: "stop", message: data?.message }, options?.requestOptions);
     },
 };
+/**
+ * Internal facade for waiting on the handover signal. Mirrors
+ * `messagesInput` / `stopInput` so the wait paths and tracing
+ * attributes stay consistent across all input-stream branches.
+ * @internal
+ */
+const handoverInput = {
+    async waitWithIdleTimeout(options) {
+        while (true) {
+            const result = await getChatSession().in.waitWithIdleTimeout(options);
+            if (!result.ok)
+                return result;
+            if (result.output.kind === "handover" ||
+                result.output.kind === "handover-skip") {
+                return { ok: true, output: result.output };
+            }
+            // Other kinds (message, stop) are not expected during handover-prepare.
+            // Loop back; the message and stop facades have their own listeners
+            // running so signals on those kinds aren't lost.
+        }
+    },
+};
 /**
  * Per-turn deferred promises. Registered via `chat.defer()`, awaited
  * before `onTurnComplete` fires. Reset each turn.
  * @internal
  */
 const chatDeferKey = locals_js_1.locals.create("chat.defer");
+/**
+ * Run-scoped slot holding the partial assistant message handed over by
+ * `chat.handover` from a customer's first-turn `streamText`. Appended
+ * to `accumulatedMessages` during turn 0 setup so `streamText` resumes
+ * at tool execution. Cleared (read once) after consumption.
+ * @internal
+ */
+const chatHandoverPartialKey = locals_js_1.locals.create("chat.handoverPartial");
+/**
+ * Run-scoped slot holding the assistant `messageId` the customer's
+ * `chat.handover` handler used for its step-1 stream. The agent reuses
+ * it on the agent-side `toUIMessageStream` (and the synthesized
+ * partial UIMessage in `originalMessages`) so all chunks merge into a
+ * single assistant message on the browser side.
+ * @internal
+ */
+const chatHandoverMessageIdKey = locals_js_1.locals.create("chat.handoverMessageId");
+/**
+ * Run-scoped slot indicating that the customer's step-1 head-start
+ * response is the FINAL turn response. When true, turn 0 runs through
+ * the full turn-loop hooks but SKIPS the `userRun` / `streamText`
+ * call — the customer's partial already IS the response. The agent's
+ * `onTurnComplete` fires with that partial so persistence + any
+ * post-turn work happens normally. Cleared after consumption.
+ * @internal
+ */
+const chatHandoverIsFinalKey = locals_js_1.locals.create("chat.handoverIsFinal");
+/**
+ * Build a UIMessage representation of a `chat.handover` partial so AI
+ * SDK's `processUIMessageStream` can transition `tool-output-available`
+ * chunks (emitted by the initial-tool-execution branch when the
+ * approval round runs) onto the existing tool-call. Without this,
+ * `state.message.parts` is empty when the agent's `streamText`
+ * finishes, and AI SDK throws
+ * `UIMessageStreamError: No tool invocation found`.
+ *
+ * Only the assistant message matters — the synthesized
+ * `tool-approval-response` rows are AI-SDK-internal and don't need a
+ * UIMessage representation. We map:
+ *   - `text` parts → `{ type: "text", text }`
+ *   - `tool-call` parts → `{ type: "tool-${name}", toolCallId,
+ *      state: "input-available", input }`
+ *   - `tool-approval-request` parts → skipped (AI SDK derives the
+ *      approval state from chunks during processing)
+ *
+ * @internal
+ */
+function synthesizeHandoverUIMessage(partial, messageId) {
+    const assistant = partial.find((m) => m.role === "assistant");
+    if (!assistant || typeof assistant.content === "string")
+        return undefined;
+    const parts = [];
+    for (const part of assistant.content) {
+        if (part.type === "text" && typeof part.text === "string") {
+            parts.push({ type: "text", text: part.text });
+        }
+        else if (part.type === "tool-call" && part.toolCallId && part.toolName) {
+            parts.push({
+                type: `tool-${part.toolName}`,
+                toolCallId: part.toolCallId,
+                state: "input-available",
+                input: part.input,
+            });
+        }
+        // tool-approval-request parts intentionally skipped — they're an
+        // AI-SDK protocol detail, not a UI surface.
+    }
+    if (parts.length === 0)
+        return undefined;
+    // Use the customer's step-1 messageId if provided (so the agent's
+    // post-handover chunks merge into the same assistant message on the
+    // browser). Fall back to a fresh id only if the handover signal
+    // didn't carry one.
+    return {
+        id: messageId ?? (0, ai_1.generateId)(),
+        role: "assistant",
+        parts,
+    };
+}
 /**
  * Per-turn background context queue. Messages added via `chat.backgroundWork.inject()`
  * are drained at the next `prepareStep` boundary and appended to the model messages.
@@ -1798,6 +1899,59 @@ function chatAgent(options) {
                         return;
                     }
                 }
+                // Handle handover-prepare runs — wait on session.in for the
+                // customer's `chat.handover` route handler to either hand off
+                // mid-turn (tool calls) or signal pure-text completion.
+                if (payload.trigger === "handover-prepare") {
+                    if (activeSpan) {
+                        activeSpan.setAttribute("chat.handoverPreparing", true);
+                    }
+                    const handoverResult = await handoverInput.waitWithIdleTimeout({
+                        idleTimeoutInSeconds: idleTimeoutInSeconds ?? payload.idleTimeoutInSeconds ?? 60,
+                        spanName: "waiting for handover signal",
+                    });
+                    if (!handoverResult.ok) {
+                        // Handler crashed before signaling — exit cleanly.
+                        return;
+                    }
+                    if (handoverResult.output.kind === "handover-skip") {
+                        // Sent only when the customer's handler aborts before
+                        // producing a finishReason. Normal pure-text and
+                        // tool-call finishes go through `kind: "handover"` with
+                        // `isFinal: true | false`. Exit without firing any turn
+                        // hooks.
+                        return;
+                    }
+                    // kind === "handover": stash the partial assistant message
+                    // so turn-0 setup can append it after loading user
+                    // messages. Two branches downstream, switched by `isFinal`:
+                    //   - `false`: customer's step 1 ended with `tool-calls`.
+                    //     The agent's `streamText` sees pending tool-calls (via
+                    //     the approval round in the partial) and executes them,
+                    //     then runs step 2's LLM call.
+                    //   - `true`: customer's step 1 ended pure-text. The agent
+                    //     runs the turn-loop hooks but SKIPS the `streamText`
+                    //     call entirely (the response is already complete).
+                    //     `onTurnComplete` fires with the partial as
+                    //     `responseMessage` so persistence works normally.
+                    locals_js_1.locals.set(chatHandoverPartialKey, handoverResult.output.partialAssistantMessage);
+                    // Stash the customer-side step-1 messageId. Turn-0 setup
+                    // uses it to seed the synthesized partial UIMessage with the
+                    // SAME id, so the agent's post-handover chunks merge into
+                    // the same assistant message on the browser side.
+                    if (handoverResult.output.messageId) {
+                        locals_js_1.locals.set(chatHandoverMessageIdKey, handoverResult.output.messageId);
+                    }
+                    locals_js_1.locals.set(chatHandoverIsFinalKey, handoverResult.output.isFinal);
+                    // Synthesize a wire payload that the turn loop treats as a
+                    // normal first-turn message. The original user-history
+                    // messages came in via `payload.messages` at trigger time;
+                    // reuse them.
+                    currentWirePayload = {
+                        ...payload,
+                        trigger: "submit-message",
+                    };
+                }
                 for (let turn = 0; turn < maxTurns; turn++) {
                     try {
                         // Extract turn-level context before entering the span
@@ -2122,6 +2276,38 @@ function chatAgent(options) {
                                             if (lastModel)
                                                 turnNewModelMessages.push(lastModel);
                                         }
+                                        // If a `chat.handover` route handler signalled a
+                                        // mid-turn handover, splice its partial assistant
+                                        // response (text + pending tool-calls + the
+                                        // synthesized tool-approval round) onto the
+                                        // accumulator. `streamText` will hit AI SDK's
+                                        // initial-tool-execution branch, run the
+                                        // agent-side tool executes, and resume from step 2
+                                        // — skipping the first model call (already done
+                                        // by the handler).
+                                        //
+                                        // We also synthesize a UIMessage form of the
+                                        // partial assistant and push it to
+                                        // `accumulatedUIMessages`. AI SDK's
+                                        // `processUIMessageStream` (invoked when our
+                                        // run-loop calls `runResult.toUIMessageStream({
+                                        // onFinish })`) initializes `state.message` from
+                                        // the trailing assistant in `originalMessages`.
+                                        // Without that, the `tool-output-available`
+                                        // chunks emitted by the initial-tool-execution
+                                        // branch can't find their matching tool-call in
+                                        // state and AI SDK throws
+                                        // `UIMessageStreamError: No tool invocation found`.
+                                        const pendingHandoverPartial = locals_js_1.locals.get(chatHandoverPartialKey);
+                                        if (pendingHandoverPartial && pendingHandoverPartial.length > 0) {
+                                            accumulatedMessages.push(...pendingHandoverPartial);
+                                            const handoverMessageId = locals_js_1.locals.get(chatHandoverMessageIdKey);
+                                            const partialUI = synthesizeHandoverUIMessage(pendingHandoverPartial, handoverMessageId);
+                                            if (partialUI) {
+                                                accumulatedUIMessages.push(partialUI);
+                                            }
+                                            locals_js_1.locals.set(chatHandoverPartialKey, []); // consume once
+                                        }
                                     }
                                     else if (currentWirePayload.trigger === "regenerate-message") {
                                         // Regenerate: frontend sent full history with last assistant message
@@ -2281,6 +2467,18 @@ function chatAgent(options) {
                             });
                             let onFinishAttached = false;
                             let runResult;
+                            // Pure-text head-start: customer's step 1 IS the
+                            // final response. Skip the user's `run` callback
+                            // (no LLM call) and use the synthesized partial
+                            // UIMessage as `capturedResponseMessage`. The post-
+                            // turn flow (`onBeforeTurnComplete` →
+                            // `onTurnComplete` → trigger:turn-complete) fires
+                            // normally so persistence works.
+                            const headStartIsFinal = locals_js_1.locals.get(chatHandoverIsFinalKey);
+                            const isHeadStartFinalTurn = turn === 0 && headStartIsFinal === true;
+                            if (isHeadStartFinalTurn) {
+                                locals_js_1.locals.set(chatHandoverIsFinalKey, undefined); // consume once
+                            }
                             try {
                                 // Drain any messages injected by background work (e.g. self-review from previous turn).
                                 // Skip if the last message is a tool message — appending after it would
@@ -2292,20 +2490,35 @@ function chatAgent(options) {
                                 if (bgQueue && bgQueue.length > 0 && lastAccumulated?.role !== "tool") {
                                     accumulatedMessages.push(...bgQueue.splice(0));
                                 }
-                                runResult = await userRun({
-                                    ...restWire,
-                                    messages: await applyPrepareMessages(accumulatedMessages, "run"),
-                                    clientData,
-                                    continuation,
-                                    previousRunId,
-                                    preloaded,
-                                    previousTurnUsage,
-                                    totalUsage: cumulativeUsage,
-                                    ctx,
-                                    signal: combinedSignal,
-                                    cancelSignal,
-                                    stopSignal,
-                                });
+                                if (isHeadStartFinalTurn) {
+                                    // The synthesized partial UIMessage IS the response.
+                                    // It was pushed to `accumulatedUIMessages` during the
+                                    // submit-message branch's splice; recover it as the
+                                    // last assistant.
+                                    const lastUI = accumulatedUIMessages[accumulatedUIMessages.length - 1];
+                                    if (lastUI && lastUI.role === "assistant") {
+                                        capturedResponseMessage = lastUI;
+                                        capturedFinishReason = "stop";
+                                    }
+                                    // Don't call userRun. Don't pipe. Skip directly
+                                    // to the post-turn flow below.
+                                }
+                                else {
+                                    runResult = await userRun({
+                                        ...restWire,
+                                        messages: await applyPrepareMessages(accumulatedMessages, "run"),
+                                        clientData,
+                                        continuation,
+                                        previousRunId,
+                                        preloaded,
+                                        previousTurnUsage,
+                                        totalUsage: cumulativeUsage,
+                                        ctx,
+                                        signal: combinedSignal,
+                                        cancelSignal,
+                                        stopSignal,
+                                    });
+                                }
                                 // Auto-pipe if the run function returned a StreamTextResult or similar,
                                 // but only if pipeChat() wasn't already called manually during this turn.
                                 // We call toUIMessageStream ourselves to attach onFinish for response capture.