@trigger.dev/sdk 0.0.0-prerelease-20260911094758 → 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");
 /**
- * Typed chat output stream — `.writer()`, `.pipe()`, `.append()`, and
- * `.read()` methods pre-bound to this run's Session `.out` channel and
- * typed to `UIMessageChunk`.
+ * 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);
+    }
+}
+/**
+ * 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.
  *
- * Use from within a `chat.agent` run to write custom chunks:
+ * 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() {
@@ -3955,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"
@@ -3968,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,
                 });
@@ -3992,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,
@@ -4014,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.
              *
@@ -4126,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)) {
@@ -4875,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, []);
@@ -5363,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;
@@ -8839,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. */