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

package/dist/esm/v3/ai.js

@@ -1,4 +1,4 @@
-import { accessoryAttributes, apiClientManager, getSchemaParseFn, headerValue, InputStreamOncePromise, isSchemaZodEsque, logger, ManualWaitpointPromise, OutOfMemoryError, sessionStreams, SemanticInternalAttributes, taskContext, SESSION_IN_EVENT_ID_HEADER, TRIGGER_CONTROL_SUBTYPE, generateJWT, } from "@trigger.dev/core/v3";
+import { accessoryAttributes, apiClientManager, controlSubtype, getSchemaParseFn, headerValue, InputStreamOncePromise, isSchemaZodEsque, logger, ManualWaitpointPromise, OutOfMemoryError, sessionStreams, SemanticInternalAttributes, taskContext, SESSION_IN_EVENT_ID_HEADER, TRIGGER_CONTROL_SUBTYPE, generateJWT, } from "@trigger.dev/core/v3";
 // Runtime VALUES go through the ESM/CJS shim so the CJS build can `require`
 // ESM-only `ai@7` (see ../imports/ai-runtime.ts).
 import { convertToModelMessages, dynamicTool, generateId as generateMessageId, getToolName, isToolUIPart, jsonSchema, readUIMessageStream, tool as aiTool, zodSchema, } from "../imports/ai-runtime.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
@@ -68,51 +72,78 @@ const lastTurnCompleteSeqNumKey = locals.create("chat.lastTurnCompleteSeqNum");
  * the `.in` subscription so already-processed user messages don't get
  * replayed from S2.
  *
- * Implementation streams the SSE endpoint and listens for `turn-complete`
- * via the transport's `onControl` callback; the data-chunk for-await is
- * just there to drive the stream. The scan is O(1 turn) because
- * `session.out` is bounded to roughly one turn at steady state — every
- * successful turn-complete is followed by an S2 trim back to the
- * previous one (see `writeTurnCompleteChunk`).
+ * Implementation is a non-blocking records read (`wait=0`) — the
+ * endpoint returns everything currently stored (including pre-trim
+ * records, since S2 trims are eventually consistent) in one shot, and
+ * we keep the LAST matching header. The previous SSE-based scan had to
+ * idle-wait a full 5s window to know it reached the tail, which put a
+ * constant ~6s tax on every continuation boot.
  *
  * Returns `undefined` if no `turn-complete` carrying the header has been
  * written yet — first-turn-ever, first turn post-OOM-with-no-prior-runs,
- * or a `turn-complete` written before this header existed (cross-version
- * boot). Callers fall back to subscribing `.in` from seq 0 in that case;
- * the slim-wire merge handles any dedup against snapshot-restored
- * messages.
+ * a `turn-complete` written before this header existed, or a server old
+ * enough that the records endpoint doesn't serialize headers. Callers
+ * fall back to subscribing `.in` from seq 0 in that case; the slim-wire
+ * merge handles any dedup against snapshot-restored messages.
  * @internal
  */
 async function findLatestSessionInCursor(chatId) {
     const apiClient = apiClientManager.clientOrThrow();
+    const response = await apiClient.readSessionStreamRecords(chatId, "out");
     let latestCursor;
-    const stream = await apiClient.subscribeToSessionStream(chatId, "out", {
-        // 5s rather than 1s: S2 trim is eventually-consistent (10-60s
-        // window), so a worker booting just after a trim could still see
-        // pre-trim records and need a bit longer to drain them all before
-        // the SSE long-poll closes. Without enough headroom the scan would
-        // fall back to `undefined`, the `.in` cursor wouldn't be seeded,
-        // and the next subscribe would replay messages already processed.
-        timeoutInSeconds: 5,
-        onControl: (event) => {
-            if (event.subtype !== TRIGGER_CONTROL_SUBTYPE.TURN_COMPLETE)
-                return;
-            const raw = headerValue(event.headers, SESSION_IN_EVENT_ID_HEADER);
-            if (!raw)
-                return;
-            const parsed = Number.parseInt(raw, 10);
-            if (Number.isFinite(parsed))
-                latestCursor = parsed;
-        },
-    });
-    // Drain the stream so the underlying SSE reader runs to completion. We
-    // don't accumulate chunks; `onControl` fires inline as turn-complete
-    // records arrive.
-    for await (const _ of stream) {
-        // intentionally empty
+    for (const record of response.records) {
+        if (controlSubtype(record.headers) !== TRIGGER_CONTROL_SUBTYPE.TURN_COMPLETE)
+            continue;
+        const raw = headerValue(record.headers, SESSION_IN_EVENT_ID_HEADER);
+        if (!raw)
+            continue;
+        const parsed = Number.parseInt(raw, 10);
+        if (Number.isFinite(parsed))
+            latestCursor = parsed;
     }
     return latestCursor;
 }
+/** Test-only entry point for the records-based cursor scan. @internal */
+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;
@@ -664,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);
@@ -980,8 +1021,15 @@ const messagesInput = {
     on(handler) {
         return getChatSession().in.on((chunk) => {
             if (chunk.kind === "message") {
-                return handler(chunk.payload);
+                // Returning `true` marks the record CONSUMED at the manager level:
+                // it is neither buffered for a later `once()` nor re-delivered by
+                // the buffer drain when the next turn re-attaches its handler.
+                // Without this, a message arriving mid-stream was delivered twice
+                // and ran a duplicate turn.
+                void Promise.resolve(handler(chunk.payload)).catch(() => { });
+                return true;
             }
+            return undefined;
         });
     },
     once(options) {
@@ -1075,8 +1123,13 @@ const stopInput = {
     on(handler) {
         return getChatSession().in.on((chunk) => {
             if (chunk.kind === "stop") {
-                return handler({ stop: true, message: chunk.message });
+                // Consume stop records (see the messages facade above). A stop is
+                // only meaningful to the turn it interrupts — buffering it would
+                // let a stale stop abort a future turn.
+                void Promise.resolve(handler({ stop: true, message: chunk.message })).catch(() => { });
+                return true;
             }
+            return undefined;
         });
     },
     once(options) {
@@ -1184,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.
@@ -1230,6 +1313,9 @@ const chatHandoverIsFinalKey = locals.create("chat.handoverIsFinal");
  * `tool-approval-response` rows are AI-SDK-internal and don't need a
  * UIMessage representation. We map:
  *   - `text` parts → `{ type: "text", text }`
+ *   - `reasoning` parts → `{ type: "reasoning", text, state: "done" }`
+ *      (provider metadata carried so an Anthropic thinking signature
+ *      survives a UIMessage → ModelMessage round trip)
  *   - `tool-call` parts → `{ type: "tool-${name}", toolCallId,
  *      state: "input-available", input }`
  *   - `tool-approval-request` parts → skipped (AI SDK derives the
@@ -1246,6 +1332,14 @@ function synthesizeHandoverUIMessage(partial, messageId) {
         if (part.type === "text" && typeof part.text === "string") {
             parts.push({ type: "text", text: part.text });
         }
+        else if (part.type === "reasoning" && typeof part.text === "string") {
+            parts.push({
+                type: "reasoning",
+                text: part.text,
+                state: "done",
+                ...(part.providerOptions ? { providerMetadata: part.providerOptions } : {}),
+            });
+        }
         else if (part.type === "tool-call" && part.toolCallId && part.toolName) {
             parts.push({
                 type: `tool-${part.toolName}`,
@@ -1269,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.
@@ -2221,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,
@@ -2242,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.
@@ -2407,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) {
@@ -2589,10 +2728,20 @@ 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
+            // this the slot is undefined and the trim never runs, so `.out`
+            // grows without bound for the whole custom-agent surface.
+            locals.set(lastTurnCompleteSeqNumKey, { value: undefined });
             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);
         },
     });
@@ -2639,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 });
@@ -2715,6 +2865,11 @@ function chatAgent(options) {
             // `messagesInput.waitWithIdleTimeout` so recovered turns fire first.
             const bootInjectedQueue = [];
             const couldHavePriorState = payload.continuation === true || ctx.attempt.number > 1;
+            // `.in` resume cursor, computed at most once per boot. The boot
+            // block below resolves it (snapshot field or records scan) and the
+            // resume-cursor block reuses it instead of re-scanning.
+            let bootInCursor;
+            let bootInCursorResolved = false;
             if (!hydrateMessages && couldHavePriorState) {
                 // Single parent span for the whole boot read phase — snapshot
                 // read, session.out replay, session.in replay. Per-phase timing
@@ -2750,23 +2905,28 @@ function chatAgent(options) {
                                 slot.value = seeded;
                         }
                     }
-                    // session.out replay
-                    const replayOutStart = Date.now();
-                    try {
-                        const replayResult = await replaySessionOutTail(sessionIdForSnapshot, { lastEventId: bootSnapshot?.lastOutEventId });
-                        replayedSettled = replayResult.settled;
-                        replayedPartial = replayResult.partial;
-                        replayedPartialRaw = replayResult.partialRaw;
-                    }
-                    catch (error) {
-                        logger.warn("chat.agent: session.out replay failed; using snapshot only", {
-                            error: error instanceof Error ? error.message : String(error),
-                            sessionId: sessionIdForSnapshot,
-                        });
-                    }
-                    bootSpan.setAttribute("chat.boot.replay.out.durationMs", Date.now() - replayOutStart);
-                    bootSpan.setAttribute("chat.boot.replay.out.settledCount", replayedSettled.length);
-                    bootSpan.setAttribute("chat.boot.replay.out.partialPresent", replayedPartial !== undefined);
+                    // The `.out` replay and the `.in` cursor + tail read are
+                    // independent (both depend only on the snapshot) — run them
+                    // concurrently. Each phase keeps its own catch + duration
+                    // attribute.
+                    const replayOutPhase = async () => {
+                        const replayOutStart = Date.now();
+                        try {
+                            const replayResult = await replaySessionOutTail(sessionIdForSnapshot, { lastEventId: bootSnapshot?.lastOutEventId });
+                            replayedSettled = replayResult.settled;
+                            replayedPartial = replayResult.partial;
+                            replayedPartialRaw = replayResult.partialRaw;
+                        }
+                        catch (error) {
+                            logger.warn("chat.agent: session.out replay failed; using snapshot only", {
+                                error: error instanceof Error ? error.message : String(error),
+                                sessionId: sessionIdForSnapshot,
+                            });
+                        }
+                        bootSpan.setAttribute("chat.boot.replay.out.durationMs", Date.now() - replayOutStart);
+                        bootSpan.setAttribute("chat.boot.replay.out.settledCount", replayedSettled.length);
+                        bootSpan.setAttribute("chat.boot.replay.out.partialPresent", replayedPartial !== undefined);
+                    };
                     // session.in tail read
                     //
                     // session.in carries the user-side of the conversation
@@ -2777,20 +2937,43 @@ function chatAgent(options) {
                     // visible via the live SSE subscription — by which point they
                     // would arrive AFTER the partial-assistant orphan and look like
                     // brand-new turns to the model, producing inverted chains.
-                    const replayInStart = Date.now();
-                    const lastInEventId = await findLatestSessionInCursor(payload.chatId)
-                        .then((cursor) => (cursor !== undefined ? String(cursor) : undefined))
-                        .catch(() => undefined);
-                    try {
-                        replayedInTail = await replaySessionInTail(payload.chatId, {
-                            lastEventId: lastInEventId,
-                        });
-                    }
-                    catch (error) {
-                        logger.warn("chat.agent: session.in replay failed; in-flight users may not be recovered", { error: error instanceof Error ? error.message : String(error) });
-                    }
-                    bootSpan.setAttribute("chat.boot.replay.in.durationMs", Date.now() - replayInStart);
-                    bootSpan.setAttribute("chat.boot.replay.in.userCount", replayedInTail.length);
+                    //
+                    // The cursor comes from the snapshot when present (written
+                    // there since `lastInEventId` was added) — otherwise from a
+                    // records scan of `.out`'s latest turn-complete header.
+                    const replayInPhase = async () => {
+                        const replayInStart = Date.now();
+                        const snapshotInCursor = bootSnapshot?.lastInEventId !== undefined
+                            ? Number.parseInt(bootSnapshot.lastInEventId, 10)
+                            : undefined;
+                        if (snapshotInCursor !== undefined && Number.isFinite(snapshotInCursor)) {
+                            bootInCursor = snapshotInCursor;
+                            bootInCursorResolved = true;
+                        }
+                        else {
+                            try {
+                                bootInCursor = await findLatestSessionInCursor(payload.chatId);
+                                bootInCursorResolved = true;
+                            }
+                            catch {
+                                // Transient scan failure: leave unresolved so the
+                                // resume-cursor block below retries the lookup.
+                                bootInCursor = undefined;
+                            }
+                        }
+                        bootSpan.setAttribute("chat.boot.replay.in.cursorFromSnapshot", snapshotInCursor !== undefined);
+                        try {
+                            replayedInTail = await replaySessionInTail(payload.chatId, {
+                                lastEventId: bootInCursor !== undefined ? String(bootInCursor) : undefined,
+                            });
+                        }
+                        catch (error) {
+                            logger.warn("chat.agent: session.in replay failed; in-flight users may not be recovered", { error: error instanceof Error ? error.message : String(error) });
+                        }
+                        bootSpan.setAttribute("chat.boot.replay.in.durationMs", Date.now() - replayInStart);
+                        bootSpan.setAttribute("chat.boot.replay.in.userCount", replayedInTail.length);
+                    };
+                    await Promise.all([replayOutPhase(), replayInPhase()]);
                 }, {
                     attributes: {
                         [SemanticInternalAttributes.STYLE_ICON]: "tabler-rotate-clockwise",
@@ -2831,7 +3014,12 @@ function chatAgent(options) {
                 bootSnapshot !== undefined;
             if (needsResumeCursor) {
                 try {
-                    const cursor = await findLatestSessionInCursor(payload.chatId);
+                    // Reuse the cursor the boot block already resolved (snapshot
+                    // field or records scan) — only scan here when the boot block
+                    // was skipped (hydrateMessages, or snapshot-only signals).
+                    const cursor = bootInCursorResolved
+                        ? bootInCursor
+                        : await findLatestSessionInCursor(payload.chatId);
                     if (cursor !== undefined) {
                         sessionStreams.setLastSeqNum(payload.chatId, "in", cursor);
                         sessionStreams.setLastDispatchedSeqNum(payload.chatId, "in", cursor);
@@ -3595,6 +3783,18 @@ function chatAgent(options) {
                             // therefore a delta merge, not a full-history reset.
                             if (currentWirePayload.trigger !== "action") {
                                 let cleanedUIMessages = cleanedIncomingMessages;
+                                // Turn-0 head-start with hydrateMessages: the boot seeding from
+                                // `payload.headStartMessages` is non-hydrate-only, so ship the
+                                // route handler's first-turn history to the hydrate hook as
+                                // incoming messages instead (gated on the pending handover).
+                                if (turn === 0 &&
+                                    hydrateMessages &&
+                                    cleanedUIMessages.length === 0 &&
+                                    (locals.get(chatHandoverPartialKey)?.length ?? 0) > 0 &&
+                                    Array.isArray(payload.headStartMessages) &&
+                                    payload.headStartMessages.length > 0) {
+                                    cleanedUIMessages = payload.headStartMessages;
+                                }
                                 // Validate/transform UIMessages before conversion — catches malformed
                                 // messages from storage or untrusted input before they reach the model.
                                 // Slim wire: triggers like `regenerate-message` carry no incoming
@@ -3773,40 +3973,39 @@ function chatAgent(options) {
                                     // `preload` / `close` / `handover-prepare` and submits
                                     // with no incoming message fall through with the boot-
                                     // seeded accumulator unchanged.
-                                    if (turn === 0) {
-                                        // Head-start handover splice (turn 0 only): the
-                                        // `chat.handover` route handler signalled a mid-turn
-                                        // handover, so splice its partial assistant response
-                                        // (text + pending tool-calls + the synthesized
-                                        // tool-approval round) onto the accumulator.
-                                        // `streamText` then hits AI SDK's initial-tool-
-                                        // execution branch, runs the agent-side tool executes,
-                                        // and resumes 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` so
-                                        // AI SDK's `processUIMessageStream` (invoked when the
-                                        // run loop calls `runResult.toUIMessageStream({
-                                        // onFinish })`) can initialize `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.get(chatHandoverPartialKey);
-                                        if (pendingHandoverPartial && pendingHandoverPartial.length > 0) {
-                                            accumulatedMessages.push(...pendingHandoverPartial);
-                                            const handoverMessageId = locals.get(chatHandoverMessageIdKey);
-                                            const partialUI = synthesizeHandoverUIMessage(pendingHandoverPartial, handoverMessageId);
-                                            if (partialUI) {
-                                                accumulatedUIMessages.push(partialUI);
-                                            }
-                                            locals.set(chatHandoverPartialKey, []); // consume once
-                                        }
+                                }
+                                if (turn === 0) {
+                                    // Head-start handover splice (turn 0 only, BOTH
+                                    // accumulation branches — hydrate and default): the
+                                    // `chat.handover` route handler signalled a mid-turn
+                                    // handover, so splice its partial assistant response
+                                    // (text + pending tool-calls + the synthesized
+                                    // tool-approval round) onto the accumulator.
+                                    // `streamText` then hits AI SDK's initial-tool-
+                                    // execution branch, runs the agent-side tool executes,
+                                    // and resumes 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` so
+                                    // AI SDK's `processUIMessageStream` (invoked when the
+                                    // run loop calls `runResult.toUIMessageStream({
+                                    // onFinish })`) can initialize `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.get(chatHandoverPartialKey);
+                                    if (pendingHandoverPartial && pendingHandoverPartial.length > 0) {
+                                        spliceHandoverPartial(accumulatedMessages, accumulatedUIMessages, {
+                                            partialAssistantMessage: pendingHandoverPartial,
+                                            messageId: locals.get(chatHandoverMessageIdKey),
+                                        });
+                                        locals.set(chatHandoverPartialKey, []); // consume once
                                     }
-                                    locals.set(chatCurrentUIMessagesKey, accumulatedUIMessages);
                                 }
+                                locals.set(chatCurrentUIMessagesKey, accumulatedUIMessages);
                             } // end if (trigger !== "action")
                             // ── Action result handling ──────────────────────────────
                             // For action turns, skip the turn machinery entirely.
@@ -4503,11 +4702,15 @@ function chatAgent(options) {
                                 if (!hydrateMessages) {
                                     try {
                                         await tracer.startActiveSpan("snapshot.write", async () => {
+                                            const snapshotInCursor = getChatSession().in.lastDispatchedSeqNum();
                                             await writeChatSnapshot(sessionIdForSnapshot, {
                                                 version: 1,
                                                 savedAt: Date.now(),
                                                 messages: accumulatedUIMessages,
                                                 lastOutEventId: turnCompleteResult?.lastEventId,
+                                                lastInEventId: snapshotInCursor !== undefined
+                                                    ? String(snapshotInCursor)
+                                                    : undefined,
                                             });
                                         }, {
                                             attributes: {
@@ -4644,17 +4847,100 @@ function chatAgent(options) {
                         if (turnError instanceof OutOfMemoryError) {
                             throw turnError;
                         }
+                        let errorTurnCompleteResult;
                         try {
                             await withChatWriter(async (writer) => {
                                 const errorText = turnError instanceof Error ? turnError.message : "An unexpected error occurred";
                                 writer.write({ type: "error", errorText });
                             });
                             // Signal turn complete so the client knows this turn is done
-                            await writeTurnCompleteChunk(currentWirePayload.chatId);
+                            errorTurnCompleteResult = await writeTurnCompleteChunk(currentWirePayload.chatId);
                         }
                         catch {
                             // Best-effort — if stream write fails, let the run continue anyway
                         }
+                        // The submit-message merge into the accumulator may not have run
+                        // yet (a pre-run hook threw), so fold the wire message in for the
+                        // error event + snapshot — the cursor has already advanced past it,
+                        // so otherwise it survives in neither the snapshot nor the `.in` tail.
+                        const erroredWireMessage = currentWirePayload.message;
+                        const erroredUIMessages = erroredWireMessage &&
+                            !accumulatedUIMessages.some((m) => m.id === erroredWireMessage.id)
+                            ? [...accumulatedUIMessages, erroredWireMessage]
+                            : accumulatedUIMessages;
+                        // Fire onTurnComplete on the error path too — the docs promise it
+                        // runs "after every turn, successful or errored" so customers can
+                        // mark the turn failed. `responseMessage` is undefined/partial and
+                        // `error` carries the thrown value.
+                        if (onTurnComplete) {
+                            try {
+                                await tracer.startActiveSpan("onTurnComplete()", async () => {
+                                    await onTurnComplete({
+                                        ctx,
+                                        chatId: currentWirePayload.chatId,
+                                        messages: accumulatedMessages,
+                                        uiMessages: erroredUIMessages,
+                                        newMessages: [],
+                                        newUIMessages: erroredWireMessage ? [erroredWireMessage] : [],
+                                        responseMessage: undefined,
+                                        rawResponseMessage: undefined,
+                                        turn,
+                                        runId: ctx.run.id,
+                                        chatAccessToken: "",
+                                        // Parsed `clientData` isn't reliably in scope here (parsing
+                                        // may itself be the failure), and the raw metadata is the
+                                        // wrong shape — leave it undefined on the error path.
+                                        clientData: undefined,
+                                        stopped: false,
+                                        continuation,
+                                        previousRunId,
+                                        preloaded,
+                                        totalUsage: cumulativeUsage,
+                                        finishReason: "error",
+                                        error: turnError,
+                                        lastEventId: errorTurnCompleteResult?.lastEventId,
+                                    });
+                                }, {
+                                    attributes: {
+                                        [SemanticInternalAttributes.STYLE_ICON]: "task-hook-onComplete",
+                                        [SemanticInternalAttributes.COLLAPSED]: true,
+                                        "chat.id": currentWirePayload.chatId,
+                                        "chat.turn": turn + 1,
+                                        "chat.errored": true,
+                                    },
+                                });
+                            }
+                            catch {
+                                // A throwing onTurnComplete on the error path must not crash
+                                // the run — keep the conversation alive for the next message.
+                            }
+                        }
+                        // Persist a snapshot so the failed turn's user message isn't
+                        // stranded. `writeTurnCompleteChunk` already advanced the `.in`
+                        // cursor past it (via the session-in-event-id header), and the
+                        // success-path snapshot write is skipped on error — without this
+                        // the next boot would resume past a message that exists in
+                        // neither the snapshot nor the replayable `.in` tail.
+                        if (!hydrateMessages) {
+                            try {
+                                const errorSnapshotInCursor = getChatSession().in.lastDispatchedSeqNum();
+                                await writeChatSnapshot(sessionIdForSnapshot, {
+                                    version: 1,
+                                    savedAt: Date.now(),
+                                    messages: erroredUIMessages,
+                                    lastOutEventId: errorTurnCompleteResult?.lastEventId,
+                                    lastInEventId: errorSnapshotInCursor !== undefined
+                                        ? String(errorSnapshotInCursor)
+                                        : undefined,
+                                });
+                            }
+                            catch (error) {
+                                logger.warn("chat.agent: error-path snapshot write failed", {
+                                    error: error instanceof Error ? error.message : String(error),
+                                    sessionId: sessionIdForSnapshot,
+                                });
+                            }
+                        }
                         // chat.requestUpgrade() / chat.endRun() — exit after error turn too
                         if (locals.get(chatUpgradeRequestedKey) ||
                             locals.get(chatEndRunRequestedKey)) {
@@ -5275,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();
@@ -5346,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)]);
@@ -5482,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 });
@@ -5513,25 +5869,72 @@ 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++;
-                    // First turn: handle preload — wait for the first real message
-                    if (turn === 0 && currentPayload.trigger === "preload") {
+                    // 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)) {
                         const result = await messagesInput.waitWithIdleTimeout({
                             idleTimeoutInSeconds: sessionIdleTimeoutOpt ?? currentPayload.idleTimeoutInSeconds ?? 30,
                             timeout,
-                            spanName: "waiting for first message",
+                            spanName: currentPayload.trigger === "preload"
+                                ? "waiting for first message"
+                                : "waiting for first message (continuation)",
                         });
                         if (!result.ok || runSignal.aborted) {
                             stop.cleanup();
                             return { done: true, value: undefined };
                         }
+                        const continuationBoot = isMessagelessContinuationBoot;
                         currentPayload = result.output;
+                        // Preserve the continuation flag — the wire payload of the next
+                        // message doesn't carry it, and `turn.continuation` is how the
+                        // user knows to seed history (e.g. `turn.setMessages(stored)`).
+                        if (continuationBoot && currentPayload.continuation === undefined) {
+                            currentPayload = { ...currentPayload, continuation: true };
+                        }
                     }
                     // Subsequent turns: wait for the next message
                     if (turn > 0) {
@@ -5612,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();
@@ -5638,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") {
@@ -5684,14 +6122,22 @@ function createChatSession(payload, options) {
                                     locals.set(chatResponsePartsKey, []);
                                 }
                             }
-                            // Capture token usage from the streamText result
+                            // Capture token usage from the streamText result. Race with a 2s
+                            // timeout — on stop-abort the AI SDK's totalUsage promise can hang
+                            // indefinitely, which would wedge the turn loop (same guard as
+                            // chat.agent's turn loop).
                             let turnUsage;
                             if (typeof source.totalUsage?.then === "function") {
                                 try {
-                                    const usage = await source.totalUsage;
-                                    turnUsage = usage;
-                                    previousTurnUsage = usage;
-                                    cumulativeUsage = addUsage(cumulativeUsage, usage);
+                                    const usage = (await Promise.race([
+                                        source.totalUsage,
+                                        new Promise((r) => setTimeout(() => r(undefined), 2_000)),
+                                    ]));
+                                    if (usage) {
+                                        turnUsage = usage;
+                                        previousTurnUsage = usage;
+                                        cumulativeUsage = addUsage(cumulativeUsage, usage);
+                                    }
                                 }
                                 catch {
                                     /* non-fatal */
@@ -5791,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 };
                 },
             };
@@ -6034,6 +6481,7 @@ 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 ?? [];
+        // 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 = {
@@ -6058,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
                 ? {
@@ -6236,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 }),
@@ -6332,8 +6804,19 @@ async function writeTurnCompleteChunk(_chatId, publicAccessToken) {
     // 2. Trim back to the previous turn-complete, if we have one. Skipping on
     //    first-turn-ever (or first turn post-OOM without a snapshot seed) is
     //    fine — the chain catches up next turn.
-    const slot = locals.get(lastTurnCompleteSeqNumKey);
-    const prev = slot?.value;
+    //
+    // Lazily create the slot if a caller reached here without one (a plain
+    // `task()` driving `chat.createSession` / `chat.writeTurnComplete`, vs.
+    // chatAgent/chatCustomAgent which seed it at boot). The first call then
+    // does no trim (nothing before it) and records its seq; later calls trim
+    // — so `.out` is bounded for every writeTurnComplete caller, not just the
+    // built-in agents.
+    let slot = locals.get(lastTurnCompleteSeqNumKey);
+    if (!slot) {
+        slot = { value: undefined };
+        locals.set(lastTurnCompleteSeqNumKey, slot);
+    }
+    const prev = slot.value;
     if (slot && prev !== undefined) {
         try {
             await session.out.trimTo(prev);