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

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,43 @@ 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 +695,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);
@@ -1186,6 +1237,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 +1363,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.
@@ -2234,11 +2336,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 +2364,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 +2532,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 +2728,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 +2738,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 +2788,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 });
@@ -3866,18 +3998,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
                                     }
                                 }
@@ -5437,8 +5561,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 +5643,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 +5834,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,13 +5869,46 @@ 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)
@@ -5788,6 +6015,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 +6051,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") {
@@ -5975,7 +6237,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 };
                 },
             };
@@ -6218,8 +6481,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 +6506,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
                 ? {
@@ -6421,10 +6698,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 }),