@trigger.dev/sdk 4.5.0-rc.6 → 4.5.0

package/dist/esm/v3/ai.js

@@ -49,6 +49,10 @@ const chatTurnContextKey = locals.create("chat.turnContext");
  * @internal
  */
 const chatSessionHandleKey = locals.create("chat.sessionHandle");
+// The external `chatId` from the boot payload — the value `ToolCallExecutionOptions.chatId`
+// is documented to carry. Custom-agent loops never set per-turn context, so subtask tool
+// metadata reads this directly rather than the Session handle id.
+const chatExternalIdKey = locals.create("chat.externalId");
 /**
  * S2 seq_num of the most recent `turn-complete` control record written by
  * this worker. Read by `writeTurnCompleteChunk` to know what to trim back
@@ -103,6 +107,45 @@ async function findLatestSessionInCursor(chatId) {
 export async function __findLatestSessionInCursorForTests(chatId) {
     return findLatestSessionInCursor(chatId);
 }
+/**
+ * Seed the `.in` resume cursor for custom-agent loops (`chat.customAgent`
+ * raw loops and `chat.createSession`) the way `chat.agent`'s boot does.
+ *
+ * MUST run before anything attaches a `.in` listener (`createStopSignal`,
+ * `chat.messages.on`, the first wait): attaching opens the SSE tail with
+ * `Last-Event-ID` from the seeded cursor, so attach-then-seed replays
+ * every record from seq 0 — already-answered user messages get delivered
+ * into the new run's first wait and the loop re-answers them.
+ *
+ * Seeds both cursors: `setLastSeqNum` controls the SSE `Last-Event-ID`,
+ * `setLastDispatchedSeqNum` gates waiter dispatch — seeding only the
+ * former still re-delivers records the manager buffered before the seed.
+ *
+ * No-ops on fresh boots and when a cursor is already seeded (e.g. the
+ * `chatCustomAgent` wrapper ran before a nested `createChatSession`).
+ * @internal
+ */
+async function seedSessionInResumeCursorForCustomLoop(payload) {
+    if (sessionStreams.lastSeqNum(payload.chatId, "in") !== undefined)
+        return;
+    // No continuation/attempt gate: the wire may omit `continuation` on a
+    // run that still has prior turns (chat.agent covers that case via its
+    // snapshot). The scan doubles as the prior-state probe — a fresh
+    // session has no turn-complete on `.out`, returns no cursor, and
+    // seeds nothing. Cost on fresh boots is one non-blocking records read.
+    try {
+        const cursor = await findLatestSessionInCursor(payload.chatId);
+        if (cursor !== undefined) {
+            sessionStreams.setLastSeqNum(payload.chatId, "in", cursor);
+            sessionStreams.setLastDispatchedSeqNum(payload.chatId, "in", cursor);
+        }
+    }
+    catch (error) {
+        logger.warn("chat session: session.in resume cursor lookup failed; old messages may replay", {
+            error: error instanceof Error ? error.message : String(error),
+        });
+    }
+}
 let readChatSnapshotImpl;
 export function __setReadChatSnapshotImplForTests(impl) {
     readChatSnapshotImpl = impl;
@@ -654,6 +697,16 @@ function createTaskToolExecuteHandler(task) {
             toolMeta.continuation = chatCtx.continuation;
             toolMeta.clientData = chatCtx.clientData;
         }
+        else {
+            // Hand-rolled chat.customAgent loops never set per-turn context, but
+            // the wrapper records the boot payload's external chatId at run boot
+            // — thread it so subtask chat helpers (`chat.stream.writer` with
+            // target "root") can open the parent's session.
+            const chatExternalId = locals.get(chatExternalIdKey);
+            if (chatExternalId) {
+                toolMeta.chatId = chatExternalId;
+            }
+        }
         const chatLocals = {};
         for (const entry of chatLocalRegistry) {
             const value = locals.get(entry.key);
@@ -1176,8 +1229,7 @@ const handoverInput = {
             const result = await getChatSession().in.waitWithIdleTimeout(options);
             if (!result.ok)
                 return result;
-            if (result.output.kind === "handover" ||
-                result.output.kind === "handover-skip") {
+            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.
@@ -1186,6 +1238,36 @@ const handoverInput = {
         }
     },
 };
+/**
+ * Wait for a `chat.headStart` handover signal inside a custom-agent loop or
+ * `chat.createSession`. Returns:
+ * - `null` — this run is not a `handover-prepare` boot, or the wait idled out /
+ *   the warm handler crashed before signaling. Treat as "no handover".
+ * - `{ kind: "handover-skip" }` — the warm handler aborted; exit without a turn.
+ * - `{ kind: "handover", partialAssistantMessage, messageId?, isFinal }` — splice
+ *   the partial (`chat.MessageAccumulator.applyHandover`) and, when `isFinal` is
+ *   false, fall through to `streamText` to run the handed-over tool round.
+ *
+ * For the common case prefer `accumulator.consumeHandover()`, which also seeds
+ * `payload.headStartMessages` and applies the partial for you.
+ *
+ * Must be called at turn 0 before any `chat.messages.waitWithIdleTimeout` —
+ * that facade consumes and discards non-message chunks, which would swallow the
+ * handover signal.
+ */
+async function waitForHandover(options) {
+    if (options.payload.trigger !== "handover-prepare")
+        return null;
+    const result = await handoverInput.waitWithIdleTimeout({
+        idleTimeoutInSeconds: options.idleTimeoutInSeconds ?? options.payload.idleTimeoutInSeconds ?? 60,
+        timeout: options.timeout,
+        spanName: options.spanName ?? "waiting for handover signal",
+    });
+    // Non-ok = idle timeout or the warm handler crashed without signaling.
+    if (!result.ok)
+        return null;
+    return result.output;
+}
 /**
  * Per-turn deferred promises. Registered via `chat.defer()`, awaited
  * before `onTurnComplete` fires. Reset each turn.
@@ -1282,6 +1364,27 @@ function synthesizeHandoverUIMessage(partial, messageId) {
         parts,
     };
 }
+/**
+ * Splice a head-start handover partial into an accumulating message pair
+ * (model + UI). Dedups by `messageId` against the UI chain (so a hydrated
+ * history that already persisted the partial isn't doubled), then pushes the
+ * partial into `modelMessages` and the synthesized UIMessage into `uiMessages`.
+ * Shared by the `chat.agent` turn-0 splice and `ChatMessageAccumulator.applyHandover`.
+ * @internal
+ */
+function spliceHandoverPartial(modelMessages, uiMessages, signal) {
+    if (!signal.partialAssistantMessage || signal.partialAssistantMessage.length === 0) {
+        return;
+    }
+    // Skip if the hydrated chain already persisted the partial under this id.
+    const alreadyInChain = signal.messageId !== undefined && uiMessages.some((m) => m.id === signal.messageId);
+    if (alreadyInChain)
+        return;
+    modelMessages.push(...signal.partialAssistantMessage);
+    const partialUI = synthesizeHandoverUIMessage(signal.partialAssistantMessage, signal.messageId);
+    if (partialUI)
+        uiMessages.push(partialUI);
+}
 /**
  * Per-turn background context queue. Messages added via `chat.backgroundWork.inject()`
  * are drained at the next `prepareStep` boundary and appended to the model messages.
@@ -1837,6 +1940,55 @@ function isStepBoundarySafe(step) {
         .map((p) => p.toolCallId));
     return ![...callIds].some((id) => !settledIds.has(id));
 }
+/**
+ * True when a model message is a `tool` message carrying a
+ * `tool-approval-response` part — the trailing row a head-start handover
+ * reshapes a pending first-turn tool call into. AI SDK's `collectToolApprovals`
+ * only inspects the conversation's last message, so this row must survive to
+ * `streamText` intact for the agent to execute the handed-over call.
+ * @internal
+ */
+function hasToolApprovalResponse(message) {
+    return (message?.role === "tool" &&
+        Array.isArray(message.content) &&
+        message.content.some((part) => part != null &&
+            typeof part === "object" &&
+            part.type === "tool-approval-response"));
+}
+/**
+ * Keep a head-start handover's tool-approval tail intact across `prepareMessages`.
+ *
+ * The handover reshapes the warm step-1's pending tool call into AI SDK's
+ * tool-approval round: a `tool-approval-request` on the assistant plus a
+ * trailing `tool` message with `tool-approval-response { approved: true }`. The
+ * agent's next `streamText` runs `collectToolApprovals`, which ONLY looks at the
+ * last message — so that tool row must stay last and unmodified for the pending
+ * call to execute. A user `prepareMessages` hook that rewrites or drops the last
+ * message (e.g. rolling a provider cache breakpoint onto it) silently breaks the
+ * resume: the agent sends a bare `tool_use` and the turn dies with
+ * "tool_use ids were found without tool_result". If the hook's input ended with
+ * that approval tail, re-assert the original tail as the last message.
+ *
+ * No-op for every normal turn — only fires when the input genuinely ended with a
+ * pending tool-approval response (i.e. a head-start resume).
+ * @internal
+ */
+function preserveToolApprovalTail(original, prepared) {
+    const originalTail = original[original.length - 1];
+    if (!hasToolApprovalResponse(originalTail))
+        return prepared;
+    // Hook left the exact tail object in place — nothing to do.
+    if (prepared[prepared.length - 1] === originalTail)
+        return prepared;
+    // Otherwise drop only the trailing approval tail the hook produced (the
+    // original moved, or a rewritten copy) and re-append the original so it is
+    // last and intact. Older approval rounds deeper in history must survive.
+    const withoutMovedOriginal = prepared.filter((m) => m !== originalTail);
+    while (hasToolApprovalResponse(withoutMovedOriginal[withoutMovedOriginal.length - 1])) {
+        withoutMovedOriginal.pop();
+    }
+    return [...withoutMovedOriginal, originalTail];
+}
 /**
  * Apply the prepareMessages hook if one is set in locals.
  * @internal
@@ -1846,7 +1998,7 @@ async function applyPrepareMessages(messages, reason) {
     if (!hook)
         return messages;
     const turnCtx = locals.get(chatTurnContextKey);
-    return tracer.startActiveSpan("prepareMessages()", async () => {
+    const prepared = await tracer.startActiveSpan("prepareMessages()", async () => {
         return hook({
             messages,
             reason,
@@ -1862,6 +2014,9 @@ async function applyPrepareMessages(messages, reason) {
             "chat.prepareMessages.messageCount": messages.length,
         },
     });
+    // A user hook must never be able to break the head-start handover resume by
+    // disturbing the trailing tool-approval row (see preserveToolApprovalTail).
+    return preserveToolApprovalTail(messages, prepared);
 }
 /**
  * Resolve the `tools` option into a concrete `ToolSet` and cache it in locals so
@@ -2234,11 +2389,18 @@ function isCompactionSafe(messages) {
 }
 /** @internal */
 const chatPromptKey = locals.create("chat.prompt");
+/**
+ * @internal Provider options attached to the system message that
+ * `toStreamTextOptions()` builds from the stored prompt — lets a provider cache
+ * the system block. Stored separately so it works for both the `ResolvedPrompt`
+ * and plain-string forms without mutating the prompt object.
+ */
+const chatPromptProviderOptionsKey = locals.create("chat.prompt.providerOptions");
 /**
  * Store a resolved prompt (or plain string) for the current run.
  * Call from any hook (`onPreload`, `onChatStart`, `onTurnStart`) or `run()`.
  */
-function setChatPrompt(resolved) {
+function setChatPrompt(resolved, options) {
     if (typeof resolved === "string") {
         locals.set(chatPromptKey, {
             text: resolved,
@@ -2255,6 +2417,9 @@ function setChatPrompt(resolved) {
     else {
         locals.set(chatPromptKey, resolved);
     }
+    // Always overwrite the slot (even with undefined) so a later prompt.set with
+    // no options clears a previous prompt's cache opt-in rather than leaking it.
+    locals.set(chatPromptProviderOptionsKey, options?.providerOptions);
 }
 /**
  * Read the stored prompt. Throws if `chat.prompt.set()` has not been called.
@@ -2420,7 +2585,21 @@ function toStreamTextOptions(options) {
     const promptText = prompt?.text ?? "";
     const skillsText = skills && skills.length > 0 ? buildSkillsSystemPrompt(skills) : "";
     if (promptText || skillsText) {
-        result.system = [promptText, skillsText].filter(Boolean).join("\n\n");
+        const systemText = [promptText, skillsText].filter(Boolean).join("\n\n");
+        // Resolve system-prompt provider options for caching. Precedence (most
+        // specific wins, no deep merge): explicit `systemProviderOptions` →
+        // `cacheControl` sugar → `providerOptions` stored on `chat.prompt.set()`.
+        const systemProviderOptions = options?.systemProviderOptions ??
+            (options?.cacheControl
+                ? { anthropic: { cacheControl: options.cacheControl } }
+                : undefined) ??
+            locals.get(chatPromptProviderOptionsKey);
+        // A bare string stays a bare string (the unchanged default). With provider
+        // options, emit a structured `SystemModelMessage` so the provider can cache
+        // the system block — `streamText`'s `system` accepts string | message.
+        result.system = systemProviderOptions
+            ? { role: "system", content: systemText, providerOptions: systemProviderOptions }
+            : systemText;
     }
     // Prompt-related options (only if chat.prompt.set() was called)
     if (prompt) {
@@ -2602,6 +2781,7 @@ function chatCustomAgent(options) {
             // `chat.createStartSessionAction`) before this run is triggered.
             // No client-side upsert needed.
             locals.set(chatSessionHandleKey, sessions.open(payload.chatId));
+            locals.set(chatExternalIdKey, payload.chatId);
             locals.set(chatAgentRunContextKey, runOptions.ctx);
             // Initialize the turn-complete trim slot so `chat.writeTurnComplete`
             // trims `session.out` back to the previous turn boundary. Without
@@ -2611,6 +2791,10 @@ function chatCustomAgent(options) {
             markChatAgentRunForStreamsWarning();
             taskContext.setConversationId(payload.chatId);
             stampConversationIdOnActiveSpan(payload.chatId);
+            // Seed the `.in` resume cursor before user code attaches any `.in`
+            // listener — otherwise a continuation boot replays already-answered
+            // messages into the loop's first wait.
+            await seedSessionInResumeCursorForCustomLoop(payload);
             return userRun(payload, runOptions);
         },
     });
@@ -2657,6 +2841,7 @@ function chatAgent(options) {
             // `chat.createStartSessionAction` or browser-direct) before this
             // run is triggered — no client-side upsert needed here.
             locals.set(chatSessionHandleKey, sessions.open(payload.chatId));
+            locals.set(chatExternalIdKey, payload.chatId);
             // Mutable holder; advances in `writeTurnCompleteChunk` after each turn
             // and is the trim target for the NEXT turn's trim record.
             locals.set(lastTurnCompleteSeqNumKey, { value: undefined });
@@ -2780,7 +2965,9 @@ function chatAgent(options) {
                     const replayOutPhase = async () => {
                         const replayOutStart = Date.now();
                         try {
-                            const replayResult = await replaySessionOutTail(sessionIdForSnapshot, { lastEventId: bootSnapshot?.lastOutEventId });
+                            const replayResult = await replaySessionOutTail(sessionIdForSnapshot, {
+                                lastEventId: bootSnapshot?.lastOutEventId,
+                            });
                             replayedSettled = replayResult.settled;
                             replayedPartial = replayResult.partial;
                             replayedPartialRaw = replayResult.partialRaw;
@@ -2877,9 +3064,7 @@ function chatAgent(options) {
             //    crashed / was canceled / requested upgrade
             //  - Snapshot exists at all (catches edge cases where the wire
             //    didn't set `continuation` but a snapshot indicates prior turns)
-            const needsResumeCursor = ctx.attempt.number > 1 ||
-                payload.continuation === true ||
-                bootSnapshot !== undefined;
+            const needsResumeCursor = ctx.attempt.number > 1 || payload.continuation === true || bootSnapshot !== undefined;
             if (needsResumeCursor) {
                 try {
                     // Reuse the cursor the boot block already resolved (snapshot
@@ -3226,9 +3411,7 @@ function chatAgent(options) {
                     // 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 effectivePreloadIdleTimeout = preloadIdleTimeoutInSeconds ?? idleTimeoutInSeconds ?? payload.idleTimeoutInSeconds;
                     const effectivePreloadTimeout = metadata.get(TURN_TIMEOUT_METADATA_KEY) ??
                         preloadTimeout ??
                         turnTimeout;
@@ -3473,7 +3656,9 @@ function chatAgent(options) {
                         if (lastUserMessage) {
                             turnAttributes["chat.user_message"] = lastUserMessage;
                             // Show a truncated preview of the user message as an accessory
-                            const preview = lastUserMessage.length > 80 ? lastUserMessage.slice(0, 80) + "..." : lastUserMessage;
+                            const preview = lastUserMessage.length > 80
+                                ? lastUserMessage.slice(0, 80) + "..."
+                                : lastUserMessage;
                             Object.assign(turnAttributes, accessoryAttributes({
                                 items: [{ text: preview, variant: "normal" }],
                                 style: "codepath",
@@ -3760,8 +3945,7 @@ function chatAgent(options) {
                                     if (currentWirePayload.trigger === "submit-message" &&
                                         cleanedUIMessages.length > 0) {
                                         const lastUI = cleanedUIMessages[cleanedUIMessages.length - 1];
-                                        const matchedExisting = lastUI.id !== undefined &&
-                                            previouslyKnownMessageIds.has(lastUI.id);
+                                        const matchedExisting = lastUI.id !== undefined && previouslyKnownMessageIds.has(lastUI.id);
                                         if (!matchedExisting) {
                                             turnNewUIMessages.push(lastUI);
                                             const lastModel = (await toModelMessages([lastUI]))[0];
@@ -3866,18 +4050,10 @@ function chatAgent(options) {
                                     // `UIMessageStreamError: No tool invocation found`.
                                     const pendingHandoverPartial = locals.get(chatHandoverPartialKey);
                                     if (pendingHandoverPartial && pendingHandoverPartial.length > 0) {
-                                        const handoverMessageId = locals.get(chatHandoverMessageIdKey);
-                                        // Skip if the hydrated chain already persisted the
-                                        // partial under the handover messageId.
-                                        const alreadyInChain = handoverMessageId !== undefined &&
-                                            accumulatedUIMessages.some((m) => m.id === handoverMessageId);
-                                        if (!alreadyInChain) {
-                                            accumulatedMessages.push(...pendingHandoverPartial);
-                                            const partialUI = synthesizeHandoverUIMessage(pendingHandoverPartial, handoverMessageId);
-                                            if (partialUI) {
-                                                accumulatedUIMessages.push(partialUI);
-                                            }
-                                        }
+                                        spliceHandoverPartial(accumulatedMessages, accumulatedUIMessages, {
+                                            partialAssistantMessage: pendingHandoverPartial,
+                                            messageId: locals.get(chatHandoverMessageIdKey),
+                                        });
                                         locals.set(chatHandoverPartialKey, []); // consume once
                                     }
                                 }
@@ -4104,7 +4280,8 @@ function chatAgent(options) {
                                     // We call toUIMessageStream ourselves to attach onFinish for response capture.
                                     // Pass originalMessages so the AI SDK reuses message IDs across turns
                                     // (e.g. for tool approval continuations / HITL flows).
-                                    if ((locals.get(chatPipeCountKey) ?? 0) === 0 && isUIMessageStreamable(runResult)) {
+                                    if ((locals.get(chatPipeCountKey) ?? 0) === 0 &&
+                                        isUIMessageStreamable(runResult)) {
                                         onFinishAttached = true;
                                         const resolvedOptions = resolveUIMessageStreamOptions();
                                         // For action turns, don't pass originalMessages: the response
@@ -4117,9 +4294,7 @@ function chatAgent(options) {
                                             // Pass originalMessages so the AI SDK reuses message IDs across
                                             // turns (e.g. for tool approval continuations / HITL flows).
                                             // Omit for action turns to force a fresh response ID.
-                                            ...(isActionTurn
-                                                ? {}
-                                                : { originalMessages: accumulatedUIMessages }),
+                                            ...(isActionTurn ? {} : { originalMessages: accumulatedUIMessages }),
                                             // Always provide generateMessageId so the start chunk carries a
                                             // messageId. Without this, the frontend and backend generate IDs
                                             // independently and they won't match for ID-based dedup.
@@ -4130,7 +4305,10 @@ function chatAgent(options) {
                                                 resolveOnFinish();
                                             },
                                         });
-                                        await pipeChat(uiStream, { signal: combinedSignal, spanName: "stream response" });
+                                        await pipeChat(uiStream, {
+                                            signal: combinedSignal,
+                                            spanName: "stream response",
+                                        });
                                     }
                                 }
                                 catch (error) {
@@ -4165,7 +4343,8 @@ function chatAgent(options) {
                                 // never reports final usage), which would block the turn loop
                                 // from ever firing onTurnComplete / writeTurnComplete.
                                 let turnUsage;
-                                if (runResult != null && typeof runResult.totalUsage?.then === "function") {
+                                if (runResult != null &&
+                                    typeof runResult.totalUsage?.then === "function") {
                                     try {
                                         turnUsage = (await Promise.race([
                                             runResult.totalUsage,
@@ -4251,7 +4430,10 @@ function chatAgent(options) {
                                     // may produce a message with an empty ID since IDs are normally
                                     // assigned by the frontend's useChat).
                                     if (!capturedResponseMessage.id) {
-                                        capturedResponseMessage = { ...capturedResponseMessage, id: generateMessageId() };
+                                        capturedResponseMessage = {
+                                            ...capturedResponseMessage,
+                                            id: generateMessageId(),
+                                        };
                                     }
                                     // Append any non-transient data parts queued via chat.response or writer.write()
                                     const queuedParts = locals.get(chatResponsePartsKey);
@@ -4552,7 +4734,9 @@ function chatAgent(options) {
                                                 ? { "gen_ai.usage.total_tokens": turnUsage.totalTokens }
                                                 : {}),
                                             ...(cumulativeUsage.totalTokens != null
-                                                ? { "gen_ai.usage.cumulative_total_tokens": cumulativeUsage.totalTokens }
+                                                ? {
+                                                    "gen_ai.usage.cumulative_total_tokens": cumulativeUsage.totalTokens,
+                                                }
                                                 : {}),
                                         },
                                     });
@@ -4584,9 +4768,7 @@ function chatAgent(options) {
                                                 savedAt: Date.now(),
                                                 messages: accumulatedUIMessages,
                                                 lastOutEventId: turnCompleteResult?.lastEventId,
-                                                lastInEventId: snapshotInCursor !== undefined
-                                                    ? String(snapshotInCursor)
-                                                    : undefined,
+                                                lastInEventId: snapshotInCursor !== undefined ? String(snapshotInCursor) : undefined,
                                             });
                                         }, {
                                             attributes: {
@@ -4628,8 +4810,7 @@ function chatAgent(options) {
                             // chat.requestUpgrade() was called — exit the loop so the
                             // transport triggers a new run on the latest version.
                             // chat.endRun() — same exit, no upgrade semantics.
-                            if (locals.get(chatUpgradeRequestedKey) ||
-                                locals.get(chatEndRunRequestedKey)) {
+                            if (locals.get(chatUpgradeRequestedKey) || locals.get(chatEndRunRequestedKey)) {
                                 return "exit";
                             }
                             // Wait for the next message — stay idle briefly, then suspend
@@ -4709,7 +4890,9 @@ function chatAgent(options) {
                         // Turn error handler: write an error chunk + turn-complete to the stream
                         // so the client sees the error, then wait for the next message instead
                         // of killing the entire run. This keeps the conversation alive.
-                        if (turnError instanceof Error && turnError.name === "AbortError" && runSignal.aborted) {
+                        if (turnError instanceof Error &&
+                            turnError.name === "AbortError" &&
+                            runSignal.aborted) {
                             // Full run cancellation — exit immediately
                             throw turnError;
                         }
@@ -4805,9 +4988,7 @@ function chatAgent(options) {
                                     savedAt: Date.now(),
                                     messages: erroredUIMessages,
                                     lastOutEventId: errorTurnCompleteResult?.lastEventId,
-                                    lastInEventId: errorSnapshotInCursor !== undefined
-                                        ? String(errorSnapshotInCursor)
-                                        : undefined,
+                                    lastInEventId: errorSnapshotInCursor !== undefined ? String(errorSnapshotInCursor) : undefined,
                                 });
                             }
                             catch (error) {
@@ -4818,8 +4999,7 @@ function chatAgent(options) {
                             }
                         }
                         // chat.requestUpgrade() / chat.endRun() — exit after error turn too
-                        if (locals.get(chatUpgradeRequestedKey) ||
-                            locals.get(chatEndRunRequestedKey)) {
+                        if (locals.get(chatUpgradeRequestedKey) || locals.get(chatEndRunRequestedKey)) {
                             return;
                         }
                         // Drain remaining recovered turns before idling — a thrown
@@ -4852,7 +5032,7 @@ function chatAgent(options) {
                 // cleanup so a missing subscription doesn't throw.
                 stopSub?.off();
             }
-        }
+        },
     });
     // Register clientDataSchema so the CLI converts it to JSONSchema
     // and stores it as payloadSchema — used by the Playground UI
@@ -4944,7 +5124,7 @@ function createChatBuilder(config) {
         agent(options) {
             const mergedUiStream = config.uiStreamOptions && options.uiMessageStreamOptions
                 ? { ...config.uiStreamOptions, ...options.uiMessageStreamOptions }
-                : options.uiMessageStreamOptions ?? config.uiStreamOptions;
+                : (options.uiMessageStreamOptions ?? config.uiStreamOptions);
             return chatAgent({
                 ...options,
                 ...(config.clientDataSchema ? { clientDataSchema: config.clientDataSchema } : {}),
@@ -5437,8 +5617,19 @@ async function pipeChatAndCapture(source, options) {
     const onFinishPromise = new Promise((r) => {
         resolveOnFinish = r;
     });
+    const resolvedOptions = resolveUIMessageStreamOptions();
     const uiStream = source.toUIMessageStream({
-        ...resolveUIMessageStreamOptions(),
+        ...resolvedOptions,
+        // Thread the prior chain (incl. a spliced handover partial) so a resumed
+        // tool round's tool-output chunks merge into the originating tool-call
+        // instead of throwing "No tool invocation found".
+        ...(options?.originalMessages ? { originalMessages: options.originalMessages } : {}),
+        // Stamp a server-generated id on the start chunk, same as chat.agent's
+        // pipe. Without it the AI SDK regenerates the assistant id when a
+        // prepareStep injection (steering) starts a new step mid-stream, and
+        // the frontend replaces the partial message — wiping the
+        // pre-injection text from the UI and the captured response.
+        generateMessageId: resolvedOptions.generateMessageId ?? generateMessageId,
         onFinish: ({ responseMessage }) => {
             captured = responseMessage;
             resolveOnFinish();
@@ -5508,10 +5699,65 @@ class ChatMessageAccumulator {
         this.uiMessages = [...uiMessages];
         this.modelMessages = await toModelMessages(uiMessages);
     }
+    /**
+     * Splice a `chat.headStart` handover partial into the accumulator (the warm
+     * step-1 response). Dedups by `messageId` so a seeded/hydrated history that
+     * already carries the partial isn't doubled. Seed any prior history first
+     * (e.g. `setMessages(payload.headStartMessages)`). Low-level — see
+     * `consumeHandover` for the wait+seed+apply convenience.
+     */
+    applyHandover(signal) {
+        spliceHandoverPartial(this.modelMessages, this.uiMessages, signal);
+    }
+    /**
+     * One-call `chat.headStart` handover for a custom-agent loop: waits for the
+     * handover signal, seeds prior history from `payload.headStartMessages`,
+     * applies the warm step-1 partial, and reports what to do next.
+     *
+     * Returns `{ isFinal, skipped }`:
+     * - `skipped: true` — not a `handover-prepare` run, the wait idled out, or the
+     *   warm handler aborted. Exit the run without a turn.
+     * - `isFinal: true` — step 1 IS the response (pure text). Write turn-complete
+     *   and continue; do not call `streamText`.
+     * - `isFinal: false` — fall through to `streamText`, which runs the pending
+     *   tool round handed over from step 1.
+     */
+    async consumeHandover(options) {
+        const signal = await waitForHandover({
+            payload: options.payload,
+            idleTimeoutInSeconds: options.idleTimeoutInSeconds,
+            timeout: options.timeout,
+        });
+        if (!signal || signal.kind === "handover-skip") {
+            return { isFinal: false, skipped: true };
+        }
+        if (options.payload.headStartMessages && options.payload.headStartMessages.length > 0) {
+            await this.setMessages(options.payload.headStartMessages);
+        }
+        this.applyHandover(signal);
+        return { isFinal: signal.isFinal, skipped: false };
+    }
     async addResponse(response) {
         if (!response.id) {
             response = { ...response, id: generateMessageId() };
         }
+        // Tool-approval and handover-resume continuations reuse the trailing
+        // assistant's ID (via originalMessages on the pipe), so the captured
+        // response can carry the same ID as a message already in the chain
+        // (e.g. a spliced handover partial). Replace in place instead of pushing
+        // a duplicate, mirroring the chat.agent accumulator.
+        const existingIdx = this.uiMessages.findIndex((m) => m.id === response.id);
+        if (existingIdx !== -1) {
+            this.uiMessages[existingIdx] = response;
+            try {
+                // Reconvert all model messages since we replaced rather than appended.
+                this.modelMessages = await toModelMessages(this.uiMessages.map((m) => stripProviderMetadata(m)));
+            }
+            catch {
+                // Conversion failed — leave the existing model messages in place
+            }
+            return;
+        }
         this.uiMessages.push(response);
         try {
             const msgs = await toModelMessages([stripProviderMetadata(response)]);
@@ -5644,14 +5890,18 @@ class ChatMessageAccumulator {
  * signaling, and idle/suspend between turns. You control: initialization,
  * model/tool selection, persistence, and any custom per-turn logic.
  *
+ * Call from inside a `chat.customAgent()` run — the wrapper binds the
+ * backing Session that the iterator's stop signal and message channels
+ * resolve to. (A plain `task()` does not bind it, so `createSession`
+ * would throw "session handle is not initialized".)
+ *
  * @example
  * ```ts
- * import { task } from "@trigger.dev/sdk";
  * import { chat, type ChatTaskWirePayload } from "@trigger.dev/sdk/ai";
  * import { streamText } from "ai";
  * import { openai } from "@ai-sdk/openai";
  *
- * export const myChat = task({
+ * export const myChat = chat.customAgent({
  *   id: "my-chat",
  *   run: async (payload: ChatTaskWirePayload, { signal }) => {
  *     const session = chat.createSession(payload, { signal });
@@ -5675,20 +5925,56 @@ function createChatSession(payload, options) {
         [Symbol.asyncIterator]() {
             let currentPayload = payload;
             let turn = -1;
-            const stop = createStopSignal();
+            // Created on the first next() call, AFTER the resume-cursor seed —
+            // createStopSignal attaches the `.in` SSE tail, and attaching
+            // before the seed replays every record from seq 0 (the seed is a
+            // no-op when the chatCustomAgent wrapper already ran it).
+            let stop;
+            let booted = false;
             const accumulator = new ChatMessageAccumulator();
             let previousTurnUsage;
             let cumulativeUsage = emptyUsage();
             return {
                 async next() {
+                    if (!booted) {
+                        booted = true;
+                        await seedSessionInResumeCursorForCustomLoop(currentPayload);
+                        stop = createStopSignal();
+                    }
                     turn++;
+                    // Head-start handover: the server triggered this run with
+                    // `trigger: "handover-prepare"` and signals the warm step-1 partial on
+                    // `session.in`. Wait for it BEFORE any `messagesInput.waitWithIdleTimeout`
+                    // (that facade consumes-and-discards non-message chunks and would swallow
+                    // the signal). Turn-0 only — continuation boots never carry this trigger.
+                    let handoverThisTurn = null;
+                    let pendingHandoverSignal = null;
+                    if (turn === 0 && currentPayload.trigger === "handover-prepare") {
+                        const signal = await waitForHandover({
+                            payload: currentPayload,
+                            idleTimeoutInSeconds: sessionIdleTimeoutOpt ??
+                                currentPayload.idleTimeoutInSeconds ??
+                                idleTimeoutInSeconds,
+                            timeout,
+                        });
+                        if (!signal || signal.kind === "handover-skip" || runSignal.aborted) {
+                            stop.cleanup();
+                            return { done: true, value: undefined };
+                        }
+                        pendingHandoverSignal = signal;
+                        handoverThisTurn = { isFinal: signal.isFinal };
+                        // Rewrite to a normal first-turn message turn so the rest of the loop
+                        // (steering setup, addIncoming, turnObj) runs unchanged.
+                        currentPayload = { ...currentPayload, trigger: "submit-message", message: undefined };
+                    }
                     // First turn: wait when the boot payload carries no message.
                     // Preload boots wait for the first real message; continuation
                     // boots (fresh run via `ensureRunForSession` / end-and-continue)
                     // arrive with the sticky boot-payload fields stripped, so running
                     // a turn immediately would invoke the model with no user input.
                     const isMessagelessContinuationBoot = currentPayload.continuation === true && !currentPayload.message;
-                    if (turn === 0 && (currentPayload.trigger === "preload" || isMessagelessContinuationBoot)) {
+                    if (turn === 0 &&
+                        (currentPayload.trigger === "preload" || isMessagelessContinuationBoot)) {
                         const result = await messagesInput.waitWithIdleTimeout({
                             idleTimeoutInSeconds: sessionIdleTimeoutOpt ?? currentPayload.idleTimeoutInSeconds ?? 30,
                             timeout,
@@ -5712,8 +5998,7 @@ function createChatSession(payload, options) {
                     // Subsequent turns: wait for the next message
                     if (turn > 0) {
                         // chat.requestUpgrade() / chat.endRun() — exit before waiting
-                        if (locals.get(chatUpgradeRequestedKey) ||
-                            locals.get(chatEndRunRequestedKey)) {
+                        if (locals.get(chatUpgradeRequestedKey) || locals.get(chatEndRunRequestedKey)) {
                             stop.cleanup();
                             return { done: true, value: undefined };
                         }
@@ -5788,6 +6073,16 @@ function createChatSession(payload, options) {
                         ? [currentPayload.message]
                         : [];
                     const messages = await accumulator.addIncoming(incomingForAccumulator, currentPayload.trigger, turn);
+                    // Apply the head-start handover AFTER addIncoming — turn-0 addIncoming
+                    // replaces accumulator state, which would wipe a pre-applied splice.
+                    // Seed prior history first, then splice the warm step-1 partial.
+                    if (pendingHandoverSignal) {
+                        const priorHistory = currentPayload.headStartMessages;
+                        if (priorHistory && priorHistory.length > 0) {
+                            await accumulator.setMessages(priorHistory);
+                        }
+                        accumulator.applyHandover(pendingHandoverSignal);
+                    }
                     // chat.requestUpgrade() called before this turn — signal transport and exit
                     if (locals.get(chatUpgradeRequestedKey)) {
                         await writeUpgradeRequiredChunk();
@@ -5814,13 +6109,38 @@ function createChatSession(payload, options) {
                         continuation: currentPayload.continuation ?? false,
                         previousTurnUsage,
                         totalUsage: cumulativeUsage,
+                        handover: handoverThisTurn,
                         async setMessages(uiMessages) {
                             await accumulator.setMessages(uiMessages);
                         },
                         async complete(source) {
+                            // Head-start final turn: the warm step-1 partial is already spliced
+                            // into the accumulator and IS the response — nothing to pipe. Only
+                            // valid on a final handover; a missing source on any other turn is a
+                            // mistake (it would silently finalize without an assistant response).
+                            if (!source) {
+                                if (!handoverThisTurn?.isFinal) {
+                                    throw new Error("turn.complete() requires a stream source unless turn.handover.isFinal is true");
+                                }
+                                const response = accumulator.uiMessages.at(-1);
+                                if (!response || response.role !== "assistant") {
+                                    throw new Error("turn.complete() could not find the spliced handover response");
+                                }
+                                sessionMsgSub.off();
+                                await chatWriteTurnComplete();
+                                return response;
+                            }
                             let response;
                             try {
-                                response = await pipeChatAndCapture(source, { signal: combinedSignal });
+                                response = await pipeChatAndCapture(source, {
+                                    signal: combinedSignal,
+                                    // On a non-final handover turn, thread the spliced partial so a
+                                    // resumed tool round's tool-output chunks merge into the
+                                    // handed-over tool-call. Gated on the handover turn only — a
+                                    // normal turn must not pass originalMessages (it would merge the
+                                    // fresh response into the prior assistant message).
+                                    ...(handoverThisTurn ? { originalMessages: accumulator.uiMessages } : {}),
+                                });
                             }
                             catch (error) {
                                 if (error instanceof Error && error.name === "AbortError") {
@@ -5925,7 +6245,8 @@ function createChatSession(payload, options) {
                                             },
                                         ];
                                     if (sessionCompaction.compactUIMessages) {
-                                        accumulator.uiMessages = await sessionCompaction.compactUIMessages(compactEvent);
+                                        accumulator.uiMessages =
+                                            await sessionCompaction.compactUIMessages(compactEvent);
                                     }
                                 }
                             }
@@ -5937,7 +6258,10 @@ function createChatSession(payload, options) {
                             // Append any non-transient data parts queued via chat.response or writer.write()
                             const queuedParts = locals.get(chatResponsePartsKey);
                             if (queuedParts && queuedParts.length > 0) {
-                                response = { ...response, parts: [...(response.parts ?? []), ...queuedParts] };
+                                response = {
+                                    ...response,
+                                    parts: [...(response.parts ?? []), ...queuedParts],
+                                };
                                 locals.set(chatResponsePartsKey, []);
                             }
                             await accumulator.addResponse(response);
@@ -5975,7 +6299,8 @@ function createChatSession(payload, options) {
                     return { done: false, value: turnObj };
                 },
                 async return() {
-                    stop.cleanup();
+                    // `stop` only exists once next() has booted the iterator.
+                    stop?.cleanup();
                     return { done: true, value: undefined };
                 },
             };
@@ -6205,6 +6530,12 @@ function createChatStartSessionAction(taskId, options) {
         if (!params.chatId) {
             throw new Error("chat.createStartSessionAction: params.chatId is required — used as the session externalId.");
         }
+        // Scope the action to `apiClient`'s env: re-enter without it so the body
+        // runs once, under that config (read via apiClientManager.accessToken/.baseURL).
+        if (options?.apiClient) {
+            const { apiClient, ...rest } = options;
+            return apiClientManager.runWithConfig(apiClient, () => createChatStartSessionAction(taskId, rest)(params));
+        }
         // The first run boots before the user's first message lands on
         // `.in/append`, so it sees an empty `messages` array and `trigger:
         // "preload"`. This matches the pre-Sessions preload semantics:
@@ -6218,8 +6549,8 @@ function createChatStartSessionAction(taskId, options) {
         // run-list filter by chat works without the customer having to wire it
         // up. Mirrors the browser-mediated `TriggerChatTransport.doStart` path.
         const userTags = params.triggerConfig?.tags ?? options?.triggerConfig?.tags ?? [];
-        // Platform cap is 10 tags per run; the auto chat tag takes one slot.
-        const tags = [`chat:${params.chatId}`, ...userTags].slice(0, 10);
+        // SessionTriggerConfig.tags allows at most 5; the auto chat tag takes one slot.
+        const tags = [`chat:${params.chatId}`, ...userTags].slice(0, 5);
         const clientDataMetadata = params.clientData !== undefined ? { metadata: params.clientData } : {};
         const triggerConfig = {
             basePayload: {
@@ -6243,6 +6574,20 @@ function createChatStartSessionAction(taskId, options) {
                     maxAttempts: params.triggerConfig?.maxAttempts ?? options?.triggerConfig?.maxAttempts,
                 }
                 : {}),
+            ...(options?.triggerConfig?.maxDuration !== undefined ||
+                params.triggerConfig?.maxDuration !== undefined
+                ? {
+                    maxDuration: params.triggerConfig?.maxDuration ?? options?.triggerConfig?.maxDuration,
+                }
+                : {}),
+            ...(options?.triggerConfig?.region || params.triggerConfig?.region
+                ? { region: params.triggerConfig?.region ?? options?.triggerConfig?.region }
+                : {}),
+            ...(options?.triggerConfig?.lockToVersion || params.triggerConfig?.lockToVersion
+                ? {
+                    lockToVersion: params.triggerConfig?.lockToVersion ?? options?.triggerConfig?.lockToVersion,
+                }
+                : {}),
             ...(options?.triggerConfig?.idleTimeoutInSeconds !== undefined ||
                 params.triggerConfig?.idleTimeoutInSeconds !== undefined
                 ? {
@@ -6298,9 +6643,7 @@ function createChatStartSessionAction(taskId, options) {
 }
 function resolveChatStartBaseURL(endpoint, chatId, option) {
     const fallback = apiClientManager.baseURL ?? "https://api.trigger.dev";
-    const raw = typeof option === "function"
-        ? option({ endpoint, chatId })
-        : option ?? fallback;
+    const raw = typeof option === "function" ? option({ endpoint, chatId }) : (option ?? fallback);
     return raw.replace(/\/$/, "");
 }
 function overrideRequestHeaders(accessToken) {
@@ -6421,10 +6764,20 @@ export const chat = {
     MessageAccumulator: ChatMessageAccumulator,
     /** Create a chat session (async iterator). See {@link createChatSession}. */
     createSession: createChatSession,
+    /**
+     * Wait for a `chat.headStart` handover signal inside a `chat.customAgent`
+     * loop (turn 0). See {@link waitForHandover}. For most loops prefer the
+     * `chat.MessageAccumulator.consumeHandover()` convenience, which also seeds
+     * `payload.headStartMessages` and applies the partial.
+     */
+    waitForHandover,
     /**
      * Store and retrieve a resolved prompt for the current run.
      *
      * - `chat.prompt.set(resolved)` — store a `ResolvedPrompt` or plain string
+     * - `chat.prompt.set(resolved, { providerOptions })` — also attach provider
+     *   options to the system block so a provider can cache it (e.g. Anthropic
+     *   prompt caching). See the prompt-caching guide.
      * - `chat.prompt()` — read the stored prompt (throws if not set)
      */
     prompt: Object.assign(getChatPrompt, { set: setChatPrompt }),