@trigger.dev/sdk 0.0.0-prerelease-20260909121655 → 0.0.0-prerelease-20260911153544

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

@@ -149,6 +149,41 @@ export declare const ai: {
  * ```
  */
 declare function createChatAccessToken<TTask extends AnyTask>(taskId: TaskIdentifier<TTask>): Promise<string>;
+/**
+ * Register work that must land before anything from this turn reaches the
+ * frontend.
+ *
+ * Like {@link chatDefer} the work starts immediately and is never awaited by
+ * the hook that registered it, so it runs alongside the model and costs no
+ * time to first token. Unlike `chat.defer`, the output stream waits for it:
+ * no chunk of the answer is written to the session until it settles. That
+ * makes it the right home for a write the next page load has to see (a
+ * conversation row, a message insert), because a reader that can see the
+ * answer can also see what the write persisted.
+ *
+ * Reach for `chat.defer` instead when the timing does not matter for a
+ * reload: analytics, audit logs, search-index updates.
+ *
+ * This is not a consistency barrier for the turn. The work is still in flight
+ * while the model runs, so a tool, a `prepareStep`, or anything else executing
+ * during the turn can still read the state as it was before the write. It
+ * orders the write against what the frontend can see, nothing more. When the
+ * turn's own code has to read the write back, `await` it instead and accept
+ * the cost.
+ *
+ * A write registered here that fails, or outlasts the internal timeout, lets
+ * the stream through rather than stalling the conversation.
+ *
+ * @example
+ * ```ts
+ * onTurnStart: async ({ chatId, uiMessages }) => {
+ *   chat.deferBeforeOutput(
+ *     db.chat.update({ where: { id: chatId }, data: { messages: uiMessages } })
+ *   );
+ * },
+ * ```
+ */
+declare function chatDeferBeforeOutput(promiseOrFn: Promise<unknown> | (() => Promise<unknown>)): void;
 /**
  * A stream writer passed to chat lifecycle callbacks (`onPreload`, `onChatStart`,
  * `onTurnStart`, `onTurnComplete`, `onCompacted`).
@@ -3382,6 +3417,7 @@ export declare const chat: {
     cleanupAbortedParts: typeof cleanupAbortedParts;
     /** Register background work that runs in parallel with streaming. See {@link chatDefer}. */
     defer: typeof chatDefer;
+    deferBeforeOutput: typeof chatDeferBeforeOutput;
     /** Queue model messages for injection at the next `prepareStep` boundary. See {@link injectBackgroundContext}. */
     inject: typeof injectBackgroundContext;
     /** Typed chat output stream for writing custom chunks or piping from subtasks. */

package/dist/commonjs/v3/ai.js

@@ -683,31 +683,143 @@ exports.ai = {
 function createChatAccessToken(taskId) {
     return auth_js_1.auth.createTriggerPublicToken(taskId, { expirationTime: "24h" });
 }
-// ---------------------------------------------------------------------------
-// Chat transport helpers — backend side
-// ---------------------------------------------------------------------------
+function createChatOutGate() {
+    let resolveOpened;
+    const opened = new Promise((resolve) => {
+        resolveOpened = resolve;
+    });
+    const gate = {
+        pending: new Set(),
+        open: false,
+        opened,
+        failOpen() {
+            if (gate.open)
+                return;
+            gate.open = true;
+            resolveOpened();
+        },
+    };
+    return gate;
+}
+const chatOutGateKey = locals_js_1.locals.create("chat.outGate");
+/**
+ * How long a write waits on the gate before giving up. A storage that hangs
+ * degrades to an ungated write rather than stalling the conversation.
+ * @internal
+ */
+const CHAT_OUT_GATE_TIMEOUT_MS = 10_000;
+async function awaitChatOutGate() {
+    const gate = locals_js_1.locals.get(chatOutGateKey);
+    if (!gate || gate.open)
+        return;
+    const deadline = Date.now() + CHAT_OUT_GATE_TIMEOUT_MS;
+    while (gate.pending.size > 0) {
+        const remaining = deadline - Date.now();
+        if (remaining <= 0) {
+            gate.failOpen();
+            return;
+        }
+        const waitingOn = [...gate.pending];
+        let timedOut = false;
+        let timer;
+        try {
+            await Promise.race([
+                Promise.allSettled(waitingOn),
+                gate.opened,
+                new Promise((resolve) => {
+                    timer = setTimeout(() => {
+                        timedOut = true;
+                        resolve();
+                    }, remaining);
+                }),
+            ]);
+        }
+        finally {
+            if (timer)
+                clearTimeout(timer);
+        }
+        if (gate.open)
+            return;
+        if (timedOut) {
+            gate.failOpen();
+            return;
+        }
+        for (const settled of waitingOn)
+            gate.pending.delete(settled);
+    }
+}
 /**
- * Typed chat output stream — `.writer()`, `.pipe()`, `.append()`, and
- * `.read()` methods pre-bound to this run's Session `.out` channel and
- * typed to `UIMessageChunk`.
+ * Register work that must land before anything from this turn reaches the
+ * frontend.
+ *
+ * Like {@link chatDefer} the work starts immediately and is never awaited by
+ * the hook that registered it, so it runs alongside the model and costs no
+ * time to first token. Unlike `chat.defer`, the output stream waits for it:
+ * no chunk of the answer is written to the session until it settles. That
+ * makes it the right home for a write the next page load has to see (a
+ * conversation row, a message insert), because a reader that can see the
+ * answer can also see what the write persisted.
+ *
+ * Reach for `chat.defer` instead when the timing does not matter for a
+ * reload: analytics, audit logs, search-index updates.
  *
- * Use from within a `chat.agent` run to write custom chunks:
+ * This is not a consistency barrier for the turn. The work is still in flight
+ * while the model runs, so a tool, a `prepareStep`, or anything else executing
+ * during the turn can still read the state as it was before the write. It
+ * orders the write against what the frontend can see, nothing more. When the
+ * turn's own code has to read the write back, `await` it instead and accept
+ * the cost.
+ *
+ * A write registered here that fails, or outlasts the internal timeout, lets
+ * the stream through rather than stalling the conversation.
+ *
+ * @example
  * ```ts
- * const { waitUntilComplete } = chat.stream.writer({
- *   execute: ({ write }) => {
- *     write({ type: "text-start", id: "status-1" });
- *     write({ type: "text-delta", id: "status-1", delta: "Processing..." });
- *     write({ type: "text-end", id: "status-1" });
- *   },
- * });
- * await waitUntilComplete();
+ * onTurnStart: async ({ chatId, uiMessages }) => {
+ *   chat.deferBeforeOutput(
+ *     db.chat.update({ where: { id: chatId }, data: { messages: uiMessages } })
+ *   );
+ * },
  * ```
- *
- * Backed by the Session primitive so a chat's output outlives any single
- * run — subscribers (browser transport, server-side `ChatStream`) read
- * the session's `.out`, not a per-run stream. Run-scoped `target`
- * options on `.pipe()` are honoured as no-ops; the session is the target.
  */
+function chatDeferBeforeOutput(promiseOrFn) {
+    const gate = locals_js_1.locals.get(chatOutGateKey);
+    const work = typeof promiseOrFn === "function" ? promiseOrFn() : promiseOrFn;
+    if (!gate || gate.open)
+        return;
+    gate.pending.add(work);
+}
+function gateWriterOptions(options) {
+    return {
+        ...options,
+        execute: async (api) => {
+            await awaitChatOutGate();
+            return await options.execute(api);
+        },
+    };
+}
+function gateOutStream(value) {
+    return (async function* () {
+        await awaitChatOutGate();
+        if (isReadableStream(value)) {
+            const reader = value.getReader();
+            try {
+                while (true) {
+                    const { done, value: chunk } = await reader.read();
+                    if (done)
+                        break;
+                    yield chunk;
+                }
+            }
+            finally {
+                reader.releaseLock();
+            }
+        }
+        else {
+            yield* value;
+        }
+    })();
+}
 const chatStream = {
     // Stable opaque label for the run-scoped `RealtimeDefinedStream` shape.
     // `chatStream` is backed by the Session's `.out` channel — this id is
@@ -717,7 +829,7 @@ const chatStream = {
     id: "chat",
     pipe(value, options) {
         const { target: _target, ...sessionOptions } = (options ?? {});
-        return getChatSession().out.pipe(value, sessionOptions);
+        return getChatSession().out.pipe(gateOutStream(value), sessionOptions);
     },
     async read(_runId, options) {
         // Session channels don't need a runId — the session is the address.
@@ -727,10 +839,11 @@ const chatStream = {
     },
     async append(value, options) {
         const { target: _target, ...sessionOptions } = (options ?? {});
+        await awaitChatOutGate();
         return getChatSession().out.append(value, sessionOptions);
     },
     writer(options) {
-        return getChatSession().out.writer(options);
+        return getChatSession().out.writer(gateWriterOptions(options));
     },
 };
 // ---------------------------------------------------------------------------
@@ -780,9 +893,13 @@ function createLazyChatWriter() {
     let mergeImpl = null;
     let waitPromise = null;
     let resolveExecute = null;
+    let started = false;
+    const bufferedParts = [];
+    const bufferedStreams = [];
     function ensureInitialized() {
-        if (writeImpl)
+        if (started)
             return;
+        started = true;
         const executePromise = new Promise((resolve) => {
             resolveExecute = resolve;
         });
@@ -792,7 +909,11 @@ function createLazyChatWriter() {
             execute: ({ write, merge }) => {
                 writeImpl = write;
                 mergeImpl = merge;
-                return executePromise; // Keep execute alive until flush()
+                for (const part of bufferedParts.splice(0))
+                    write(part);
+                for (const stream of bufferedStreams.splice(0))
+                    merge(stream);
+                return executePromise;
             },
         });
         waitPromise = waitUntilComplete;
@@ -802,11 +923,17 @@ function createLazyChatWriter() {
             write(part) {
                 ensureInitialized();
                 queueResponsePart(part);
-                writeImpl(part);
+                if (writeImpl)
+                    writeImpl(part);
+                else
+                    bufferedParts.push(part);
             },
             merge(stream) {
                 ensureInitialized();
-                mergeImpl(stream);
+                if (mergeImpl)
+                    mergeImpl(stream);
+                else
+                    bufferedStreams.push(stream);
             },
         },
         async flush() {
@@ -1615,15 +1742,11 @@ async function installChatInputRouter(chatId, options) {
             checkpoint.appliedThrough = Math.max(checkpoint.appliedThrough ?? replayWindowEnd, replayWindowEnd);
         }
     }
-    // A boot that replayed `.in` itself has already answered everything up to
-    // `recoveredThrough`, so the floor has to cover it before the tail opens.
-    if (options?.recoveredThrough !== undefined) {
-        const recovered = options.recoveredThrough;
-        checkpoint.resumeFrom = Math.max(checkpoint.resumeFrom ?? recovered, recovered);
-        checkpoint.appliedThrough = Math.max(checkpoint.appliedThrough ?? checkpoint.resumeFrom, checkpoint.resumeFrom);
-    }
     const router = entry.router;
     router.restore(checkpoint);
+    if (options?.recoveredSeqNums && options.recoveredSeqNums.length > 0) {
+        router.markRecovered(options.recoveredSeqNums);
+    }
     const floor = router.resumeFrom();
     if (floor !== undefined) {
         v3_1.sessionStreams.setLastSeqNum(chatId, "in", floor);
@@ -3959,6 +4082,17 @@ function chatAgent(options) {
              * keeps an action's write cursor-neutral.
              */
             let lastSnapshotOutEventId;
+            /**
+             * The `lastInEventId` the most recent snapshot carried.
+             *
+             * A turn-start save happens after the incoming message has been handed to
+             * the turn loop, so the router's live resume floor has already advanced
+             * past it. Persisting that floor before the turn runs would let the next
+             * boot resume past a message this run never answered, which is exactly
+             * what a deferred or recovered message depends on. Turn-start carries
+             * this instead.
+             */
+            let lastSnapshotInEventId;
             const storageTrigger = (trigger) => trigger === "regenerate-message"
                 ? "regenerate-message"
                 : trigger === "action" || trigger === "action-turn"
@@ -3972,7 +4106,8 @@ function chatAgent(options) {
              */
             /** The runtime's opaque state as of the last save; carried on every changeset's transcript. */
             let transcriptState = null;
-            const saveTranscript = async (opts) => {
+            let transcriptSaveChain = Promise.resolve();
+            const runSaveTranscript = async (opts) => {
                 const { changes, shadow } = (0, transcriptStorage_js_1.diffTranscript)(transcriptShadow, opts.messages, {
                     nonFinalIds: opts.nonFinalIds,
                 });
@@ -3996,8 +4131,15 @@ function chatAgent(options) {
                 if (runtimeState !== null || persistedStateSet) {
                     changes.push({ op: "state", value: runtimeState });
                 }
+                if (opts.skipIfUnchanged && changes.length === 0)
+                    return;
                 transcriptState = runtimeState;
-                const inCursor = chatInputRouter().resumeFloor();
+                const liveInCursor = chatInputRouter().resumeFloor();
+                const inCursor = opts.carryInCursor
+                    ? lastSnapshotInEventId
+                    : liveInCursor !== undefined
+                        ? String(liveInCursor)
+                        : undefined;
                 await transcriptStorage.save({
                     chatId: payload.chatId,
                     clientData: opts.clientData,
@@ -4018,12 +4160,28 @@ function chatAgent(options) {
                     },
                     cursors: {
                         lastOutEventId: opts.lastOutEventId,
-                        lastInEventId: inCursor !== undefined ? String(inCursor) : undefined,
+                        lastInEventId: inCursor,
                     },
                 });
                 transcriptShadow = shadow;
+                lastSnapshotInEventId = inCursor;
                 persistedStateSet = runtimeState !== null;
             };
+            /**
+             * Serialise every save onto one chain. `runSaveTranscript` derives its
+             * changeset from `transcriptShadow` and only advances it once the write
+             * lands, so two overlapping saves would diff against stale state. The
+             * message list is copied on the way in because the accumulator keeps
+             * mutating while a queued save waits its turn. A rejection is handed to
+             * the caller but never poisons the chain.
+             */
+            const saveTranscript = (opts) => {
+                const queued = { ...opts, messages: [...opts.messages] };
+                const run = () => runSaveTranscript(queued);
+                const next = transcriptSaveChain.then(run, run);
+                transcriptSaveChain = next.then(() => undefined, () => undefined);
+                return next;
+            };
             /**
              * Persist the accumulator outside a turn.
              *
@@ -4074,6 +4232,13 @@ function chatAgent(options) {
             // default, `inFlightUsers`). The turn-loop checks this queue ahead of
             // `messagesInput.waitWithIdleTimeout` so recovered turns fire first.
             const bootInjectedQueue = [];
+            const recoveredSeqByPayload = new WeakMap();
+            const dispatchBootInjected = () => bootInjectedQueue.shift();
+            const settleRecoveredTurn = (wirePayload) => {
+                const settledSeq = recoveredSeqByPayload.get(wirePayload);
+                if (settledSeq !== undefined)
+                    chatInputRouter().settleRecovered(settledSeq);
+            };
             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
@@ -4123,6 +4288,7 @@ function chatAgent(options) {
                     // turn (chain self-bootstraps from turn 2), so this is purely an
                     // optimization to keep continuation runs bounded from the first turn.
                     lastSnapshotOutEventId = bootSnapshot?.lastOutEventId;
+                    lastSnapshotInEventId = bootSnapshot?.lastInEventId;
                     if (bootSnapshot?.lastOutEventId !== undefined) {
                         const seeded = Number.parseInt(bootSnapshot.lastOutEventId, 10);
                         if (Number.isFinite(seeded)) {
@@ -4214,16 +4380,10 @@ function chatAgent(options) {
             }
             // ── session.in router ──────────────────────────────────────────
             //
-            // Reads the turn boundary and subscribes in one call. `bootInCursor` is
-            // only a fallback: the boot block above may already have resolved a
-            // cursor from the snapshot, which is used when the boundary itself
-            // carries none. Everything the boot replayed off `.in` is dispatched from
-            // `bootInjectedQueue` below, so it goes into the floor here — folded in
-            // after the subscription opens, the live tail re-delivers it as a turn.
-            const lastRecoveredInSeq = replayedInTail.length > 0 ? replayedInTail[replayedInTail.length - 1].seqNum : undefined;
+            const recoveredSeqNums = replayedInTail.map((r) => r.seqNum);
             await installChatInputRouter(payload.chatId, {
                 fallbackResumeFrom: bootInCursorResolved ? bootInCursor : undefined,
-                recoveredThrough: lastRecoveredInSeq,
+                recoveredSeqNums,
                 resuming: Boolean(payload.continuation) || ctx.attempt.number > 1,
             });
             // ── Recovery boot + chain reconstruction ────────────────────────
@@ -4306,7 +4466,7 @@ function chatAgent(options) {
                 // branches: at n=1 the orphan partial is dropped and the interrupted
                 // user is re-dispatched as a fresh turn instead.
                 let seedChain;
-                let recoveredTurns;
+                let recoveredEntries;
                 if (hookChain !== undefined) {
                     seedChain = hookChain;
                 }
@@ -4317,13 +4477,26 @@ function chatAgent(options) {
                     seedChain = settledMessages;
                 }
                 if (hookRecoveredTurns !== undefined) {
-                    recoveredTurns = hookRecoveredTurns;
+                    const seqNumsByRecoveredId = new Map();
+                    for (const entry of replayedInTail) {
+                        const existing = seqNumsByRecoveredId.get(entry.message.id);
+                        if (existing)
+                            existing.push(entry.seqNum);
+                        else
+                            seqNumsByRecoveredId.set(entry.message.id, [entry.seqNum]);
+                    }
+                    recoveredEntries = hookRecoveredTurns.map((message) => ({
+                        message,
+                        seqNum: seqNumsByRecoveredId.get(message.id)?.shift(),
+                    }));
                 }
                 else if (partialAssistant !== undefined && inFlightUsers.length > 1) {
-                    recoveredTurns = inFlightUsers.slice(1);
+                    recoveredEntries = replayedInTail
+                        .slice(1)
+                        .map((r) => ({ message: r.message, seqNum: r.seqNum }));
                 }
                 else {
-                    recoveredTurns = inFlightUsers;
+                    recoveredEntries = replayedInTail.map((r) => ({ message: r.message, seqNum: r.seqNum }));
                 }
                 // `beforeBoot` errors bubble — the customer opted into blocking
                 // persistence and a failure there should fail the run rather than
@@ -4353,13 +4526,14 @@ function chatAgent(options) {
                 for (const entry of replayedInTail) {
                     metadataById.set(entry.message.id, entry.metadata);
                 }
-                for (const msg of recoveredTurns) {
+                const dispatchedRecoveredSeqs = new Set();
+                for (const { message: msg, seqNum } of recoveredEntries) {
                     if (wireMessageId && msg.id === wireMessageId)
                         continue;
                     const recoveredMetadata = metadataById.has(msg.id)
                         ? metadataById.get(msg.id)
                         : payload.metadata;
-                    bootInjectedQueue.push({
+                    const injectedPayload = {
                         chatId: payload.chatId,
                         sessionId: payload.sessionId,
                         metadata: recoveredMetadata,
@@ -4368,7 +4542,17 @@ function chatAgent(options) {
                         messageId: msg.id,
                         continuation: payload.continuation,
                         previousRunId: payload.previousRunId,
-                    });
+                    };
+                    bootInjectedQueue.push(injectedPayload);
+                    if (seqNum !== undefined) {
+                        recoveredSeqByPayload.set(injectedPayload, seqNum);
+                        dispatchedRecoveredSeqs.add(seqNum);
+                    }
+                }
+                for (const entry of replayedInTail) {
+                    if (!dispatchedRecoveredSeqs.has(entry.seqNum)) {
+                        chatInputRouter().settleRecovered(entry.seqNum);
+                    }
                 }
                 accumulatedUIMessages = seedChain;
                 // ── Head-start bootstrap ─────────────────────────────────────
@@ -4528,7 +4712,7 @@ function chatAgent(options) {
                  */
                 let dispatchedRecoveredFirstTurn = false;
                 if (preloaded && bootInjectedQueue.length > 0) {
-                    currentWirePayload = bootInjectedQueue.shift();
+                    currentWirePayload = dispatchBootInjected();
                     dispatchedRecoveredFirstTurn = true;
                 }
                 // Handle preloaded runs — fire onPreload, then wait for the first real message
@@ -4736,7 +4920,7 @@ function chatAgent(options) {
                     // waiting on the live session.in. Subsequent recovered turns
                     // get drained by the end-of-turn picker below.
                     if (bootInjectedQueue.length > 0) {
-                        currentWirePayload = bootInjectedQueue.shift();
+                        currentWirePayload = dispatchBootInjected();
                     }
                     else {
                         const effectiveIdleTimeout = idleTimeoutInSeconds ?? payload.idleTimeoutInSeconds;
@@ -4854,6 +5038,7 @@ function chatAgent(options) {
                             // (errors are caught by the outer try/catch which writes an error chunk)
                             locals_js_1.locals.set(chatPipeCountKey, 0);
                             locals_js_1.locals.set(chatDeferKey, new Set());
+                            locals_js_1.locals.set(chatOutGateKey, createChatOutGate());
                             locals_js_1.locals.set(chatCompactionStateKey, undefined);
                             locals_js_1.locals.set(chatSteeringQueueKey, []);
                             locals_js_1.locals.set(chatPendingBackgroundKey, []);
@@ -5300,6 +5485,7 @@ function chatAgent(options) {
                                     chatId: currentWirePayload.chatId,
                                     messageId: currentWirePayload.messageId,
                                 });
+                                settleRecoveredTurn(currentWirePayload);
                                 await writeTurnCompleteChunk(currentWirePayload.chatId);
                                 // Not a turn — don't consume an iteration.
                                 turn--;
@@ -5341,6 +5527,23 @@ function chatAgent(options) {
                             // A no-op turn skips this block, and with it `followSessionPin`:
                             // there is nothing to answer, so nothing to hand over.
                             if ((!isAction || actionTurn) && !isNoOpTurn) {
+                                if (!hydrateMessages) {
+                                    chatDeferBeforeOutput(saveTranscript({
+                                        reason: "turn-start",
+                                        messages: accumulatedUIMessages,
+                                        turn,
+                                        trigger: storageTrigger(currentWirePayload.trigger),
+                                        clientData,
+                                        lastOutEventId: lastSnapshotOutEventId,
+                                        skipIfUnchanged: true,
+                                        carryInCursor: true,
+                                    }).catch((error) => {
+                                        v3_1.logger.warn("chat.agent: turn-start transcript write failed; a reload mid-answer may not show the message being answered", {
+                                            error: error instanceof Error ? error.message : String(error),
+                                            sessionId: sessionIdForSnapshot,
+                                        });
+                                    }));
+                                }
                                 // Mint a scoped public access token once per turn, reused for
                                 // onChatStart, onTurnStart, onTurnComplete, and the turn-complete chunk.
                                 const currentRunId = ctx.run.id;
@@ -6015,6 +6218,7 @@ function chatAgent(options) {
                                     }
                                     locals_js_1.locals.set(chatResponsePartsKey, []);
                                 }
+                                settleRecoveredTurn(currentWirePayload);
                                 // Write turn-complete control chunk — closes the frontend stream.
                                 const turnCompleteResult = await writeTurnCompleteChunk(currentWirePayload.chatId, turnAccessToken);
                                 // Fire onTurnComplete — stream is closed, use for persistence.
@@ -6126,7 +6330,7 @@ function chatAgent(options) {
                             // produced these from in-flight user messages on session.in
                             // that the dead predecessor never acknowledged.
                             if (bootInjectedQueue.length > 0) {
-                                currentWirePayload = bootInjectedQueue.shift();
+                                currentWirePayload = dispatchBootInjected();
                                 return "continue";
                             }
                             // chat.requestUpgrade() was called — exit the loop; the handover
@@ -6446,7 +6650,7 @@ function chatAgent(options) {
                         // recovered turn shouldn't strand the rest of the boot queue
                         // until an unrelated live message arrives.
                         if (bootInjectedQueue.length > 0) {
-                            currentWirePayload = bootInjectedQueue.shift();
+                            currentWirePayload = dispatchBootInjected();
                             continue;
                         }
                         // Wait for the next message — same as after a successful turn
@@ -8816,6 +9020,7 @@ exports.chat = {
     cleanupAbortedParts,
     /** Register background work that runs in parallel with streaming. See {@link chatDefer}. */
     defer: chatDefer,
+    deferBeforeOutput: chatDeferBeforeOutput,
     /** Queue model messages for injection at the next `prepareStep` boundary. See {@link injectBackgroundContext}. */
     inject: injectBackgroundContext,
     /** Typed chat output stream for writing custom chunks or piping from subtasks. */