@trigger.dev/sdk 0.0.0-prerelease-20260908122921 → 0.0.0-prerelease-20260909071038

package/dist/esm/v3/ai.js

@@ -3,6 +3,16 @@ import { accessoryAttributes, apiClientManager, controlSubtype, generateJWT, get
 // ESM-only `ai@7` (see ../imports/ai-runtime.ts).
 import { trace } from "@opentelemetry/api";
 import { tool as aiTool, convertToModelMessages, dynamicTool, generateId as generateMessageId, getToolName, isToolUIPart, jsonSchema, readUIMessageStream, streamText as aiStreamText, zodSchema, } from "../imports/ai-runtime.js";
+import { createTranscriptShadow, defaultStorage, diffTranscript, parseTranscriptRuntimeState, prefixFingerprint, restoreModelLane, } from "./transcriptStorage.js";
+let transcriptStorageOverride;
+/**
+ * Test-only override for the storage `chat.agent` persists through, so a
+ * test can capture the exact changesets the runtime produces.
+ * @internal
+ */
+export function __setTranscriptStorageForTests(storage) {
+    transcriptStorageOverride = storage;
+}
 import { PENDING_MESSAGE_INJECTED_TYPE, upsertIncomingMessage, chatRunTags, } from "./ai-shared.js";
 import { auth } from "./auth.js";
 import { locals } from "./locals.js";
@@ -105,182 +115,8 @@ async function findLatestSessionInCursor(chatId) {
     }
     return latestCursor;
 }
-let readChatSnapshotImpl;
-export function __setReadChatSnapshotImplForTests(impl) {
-    readChatSnapshotImpl = impl;
-}
-let writeChatSnapshotImpl;
-export function __setWriteChatSnapshotImplForTests(impl) {
-    writeChatSnapshotImpl = impl;
-}
-/**
- * Read the persisted snapshot for a session. Returns `undefined` on:
- *   - missing object (404 from the presigned GET — fresh session, never
- *     persisted)
- *   - presign failure (network/auth issue)
- *   - malformed JSON
- *   - version mismatch (forward-compat — older runtimes ignore newer blobs)
- *
- * Always swallows errors via `logger.warn`. The agent boot loop must stay
- * available even if S3 hiccups; the worst case is replaying more of
- * `session.out` than strictly necessary.
- * @internal
- */
-async function readChatSnapshot(sessionId) {
-    if (readChatSnapshotImpl) {
-        return (await readChatSnapshotImpl(sessionId)) ?? undefined;
-    }
-    const apiClient = apiClientManager.clientOrThrow();
-    let presignedUrl;
-    try {
-        const resp = await apiClient.getChatSnapshotUrl(sessionId);
-        presignedUrl = resp.presignedUrl;
-    }
-    catch (error) {
-        logger.warn("chat.agent: snapshot presign (read) failed; continuing without snapshot", {
-            error: error instanceof Error ? error.message : String(error),
-            sessionId,
-        });
-        return undefined;
-    }
-    let response;
-    try {
-        response = await fetch(presignedUrl, { method: "GET" });
-    }
-    catch (error) {
-        logger.warn("chat.agent: snapshot fetch failed; continuing without snapshot", {
-            error: error instanceof Error ? error.message : String(error),
-            sessionId,
-        });
-        return undefined;
-    }
-    if (response.status === 404) {
-        // First-ever boot for this session — no snapshot yet. Caller falls
-        // through to replay-only.
-        return undefined;
-    }
-    if (!response.ok) {
-        logger.warn("chat.agent: snapshot fetch returned non-OK; continuing without snapshot", {
-            status: response.status,
-            sessionId,
-        });
-        return undefined;
-    }
-    let parsed;
-    try {
-        parsed = await response.json();
-    }
-    catch (error) {
-        logger.warn("chat.agent: snapshot JSON parse failed; continuing without snapshot", {
-            error: error instanceof Error ? error.message : String(error),
-            sessionId,
-        });
-        return undefined;
-    }
-    if (!parsed || typeof parsed !== "object")
-        return undefined;
-    const candidate = parsed;
-    if (candidate.version !== 1 || !Array.isArray(candidate.messages)) {
-        logger.warn("chat.agent: snapshot version/shape mismatch; ignoring", {
-            version: candidate.version,
-            sessionId,
-        });
-        return undefined;
-    }
-    return candidate;
-}
-/**
- * Persist the snapshot for a session. Awaited by callers immediately after
- * `onTurnComplete` — the agent may suspend right after this point, and
- * fire-and-forget promises don't reliably complete on suspend.
- *
- * Errors are swallowed via `logger.warn`. A failed write means the next
- * boot replays slightly more of `session.out` (back to the previous
- * snapshot's cursor) instead of failing — the conversation stays
- * coherent, only the boot path does marginally more work.
- * @internal
- */
-async function writeChatSnapshot(sessionId, snapshot) {
-    if (writeChatSnapshotImpl) {
-        await writeChatSnapshotImpl(sessionId, snapshot);
-        return;
-    }
-    const apiClient = apiClientManager.clientOrThrow();
-    let presignedUrl;
-    try {
-        const resp = await apiClient.createChatSnapshotUploadUrl(sessionId);
-        presignedUrl = resp.presignedUrl;
-    }
-    catch (error) {
-        logger.warn("chat.agent: snapshot presign (write) failed; next run will replay further", {
-            error: error instanceof Error ? error.message : String(error),
-            sessionId,
-        });
-        return;
-    }
-    let response;
-    try {
-        response = await fetch(presignedUrl, {
-            method: "PUT",
-            headers: { "content-type": "application/json" },
-            body: JSON.stringify(snapshot),
-        });
-    }
-    catch (error) {
-        logger.warn("chat.agent: snapshot upload failed; next run will replay further", {
-            error: error instanceof Error ? error.message : String(error),
-            sessionId,
-        });
-        return;
-    }
-    if (!response.ok) {
-        logger.warn("chat.agent: snapshot upload returned non-OK; next run will replay further", {
-            status: response.status,
-            sessionId,
-        });
-    }
-}
-/**
- * Test-only entry point that bypasses `__setReadChatSnapshotImplForTests`
- * and reaches the real `apiClient.getPayloadUrl` + `fetch` + JSON-parse path.
- * Used by `chat-snapshot.test.ts` to verify 404 / 500 / malformed JSON /
- * version-mismatch / network-error behavior end-to-end. Tests mock global
- * `fetch` and the api-client config; this wrapper lets them drive the
- * production code without the override hook short-circuiting.
- *
- * Not part of the public API. The `__` prefix and `ForTests` suffix mirror
- * the override-hook setters above.
- * @internal
- */
-export async function __readChatSnapshotProductionPathForTests(sessionId) {
-    const saved = readChatSnapshotImpl;
-    readChatSnapshotImpl = undefined;
-    try {
-        return await readChatSnapshot(sessionId);
-    }
-    finally {
-        readChatSnapshotImpl = saved;
-    }
-}
-/**
- * Test-only entry point that bypasses `__setWriteChatSnapshotImplForTests`
- * and reaches the real `apiClient.createUploadPayloadUrl` + `fetch` PUT
- * path. Pairs with `__readChatSnapshotProductionPathForTests` — see that
- * function's note for the rationale.
- *
- * Not part of the public API.
- * @internal
- */
-export async function __writeChatSnapshotProductionPathForTests(sessionId, snapshot) {
-    const saved = writeChatSnapshotImpl;
-    writeChatSnapshotImpl = undefined;
-    try {
-        await writeChatSnapshot(sessionId, snapshot);
-    }
-    finally {
-        writeChatSnapshotImpl = saved;
-    }
-}
+export { __readChatSnapshotProductionPathForTests, __setReadChatSnapshotImplForTests, __setWriteChatSnapshotImplForTests, __writeChatSnapshotProductionPathForTests, } from "./chatSnapshotIo.js";
+export { defaultStorage, memoryTranscriptStorage, reduceTranscriptChanges, snapshotTranscriptStorage, } from "./transcriptStorage.js";
 /**
  * Merge two `UIMessage[]` lists by `id`, with the second list winning on
  * collision. Used at run boot to combine the snapshot's persisted history
@@ -1946,6 +1782,12 @@ function spliceHandoverPartial(modelMessages, uiMessages, signal) {
  * @internal
  */
 const chatBackgroundQueueKey = locals.create("chat.backgroundQueue");
+/**
+ * Background injections a step-boundary drain handed to the model this turn,
+ * with the transcript message they followed. Reconciled into the model lane
+ * and the persisted injections once the turn's response is in.
+ */
+const chatPendingBackgroundKey = locals.create("chat.pendingBackground");
 /**
  * System-role context injected mid-conversation, held for the instructions lane.
  *
@@ -3617,6 +3459,12 @@ function toStreamTextOptions(options) {
             if (bgQueue && bgQueue.length > 0) {
                 const injected = bgQueue.splice(0); // drain
                 resultMessages = [...(resultMessages ?? messages), ...injected];
+                const pendingBackground = locals.get(chatPendingBackgroundKey) ?? [];
+                pendingBackground.push({
+                    afterId: locals.get(chatCurrentUIMessagesKey)?.at(-1)?.id ?? "",
+                    messages: injected,
+                });
+                locals.set(chatPendingBackgroundKey, pendingBackground);
             }
             return resultMessages ? { messages: resultMessages } : undefined;
         };
@@ -3684,6 +3532,16 @@ function isUIMessageStreamable(value) {
         "toUIMessageStream" in value &&
         typeof value.toUIMessageStream === "function");
 }
+const warnedHydrateMessagesDeprecated = new Set();
+function warnHydrateMessagesDeprecatedOnce(agentId) {
+    if (warnedHydrateMessagesDeprecated.has(agentId))
+        return;
+    warnedHydrateMessagesDeprecated.add(agentId);
+    console.warn(`[chat.agent] \`hydrateMessages\` on "${agentId}" is deprecated. Give the agent a transcript ` +
+        "storage instead: `save` receives every change to the conversation and `loadContext` " +
+        "lets the application own the model's context, with crash recovery and durable " +
+        "compaction that `hydrateMessages` never had.");
+}
 let warnedMissingOnAction = false;
 function warnMissingOnActionOnce() {
     if (warnedMissingOnAction)
@@ -3896,7 +3754,19 @@ function chatCustomAgent(options) {
     return task;
 }
 function chatAgent(options) {
-    const { run: userRun, clientDataSchema, onBoot, onRecoveryBoot, onPreload, onChatStart, onValidateMessages, hydrateMessages, actionSchema, onAction, onTurnStart, onBeforeTurnComplete, onCompacted, compaction, pendingMessages: pendingMessagesConfig, prepareMessages, tools: toolsOption, onTurnComplete, maxTurns = 100, turnTimeout = "1h", idleTimeoutInSeconds = 30, chatAccessTokenTTL = "1h", preloadIdleTimeoutInSeconds, preloadTimeout, uiMessageStreamOptions, onChatSuspend, onChatResume, exitAfterPreloadIdle = false, oomMachine, registry: promptRegistry, system: agentSystem, cacheControl: agentCacheControl, systemProviderOptions: agentSystemProviderOptions, versionSkew, ...restOptions } = options;
+    const { run: userRun, clientDataSchema, onBoot, onRecoveryBoot, onPreload, onChatStart, onValidateMessages, hydrateMessages, storage, actionSchema, onAction, onTurnStart, onBeforeTurnComplete, onCompacted, compaction, pendingMessages: pendingMessagesConfig, prepareMessages, tools: toolsOption, onTurnComplete, maxTurns = 100, turnTimeout = "1h", idleTimeoutInSeconds = 30, chatAccessTokenTTL = "1h", preloadIdleTimeoutInSeconds, preloadTimeout, uiMessageStreamOptions, onChatSuspend, onChatResume, exitAfterPreloadIdle = false, oomMachine, registry: promptRegistry, system: agentSystem, cacheControl: agentCacheControl, systemProviderOptions: agentSystemProviderOptions, versionSkew, ...restOptions } = options;
+    if (hydrateMessages) {
+        if (storage) {
+            throw new Error(`chat.agent: "${options.id}" sets both \`hydrateMessages\` and \`storage\`. ` +
+                "`hydrateMessages` is deprecated and replaced by the storage: `save` receives every " +
+                "change and `loadContext` on the storage owns the model's context. Remove `hydrateMessages`.");
+        }
+        if (typeof (transcriptStorageOverride ?? defaultStorage).loadContext === "function") {
+            throw new Error(`chat.agent: "${options.id}" sets \`hydrateMessages\` and uses a transcript storage with ` +
+                "`loadContext`. Both would own the model's context; keep one.");
+        }
+        warnHydrateMessagesDeprecatedOnce(options.id);
+    }
     const parseClientData = clientDataSchema ? getSchemaParseFn(clientDataSchema) : undefined;
     const parseAction = actionSchema ? getSchemaParseFn(actionSchema) : undefined;
     // chat.agent does not expose generic retry options (see docstring on
@@ -3979,6 +3849,24 @@ function chatAgent(options) {
             // durable snapshot + `session.out` replay (or `hydrateMessages` if
             // registered) — the wire is delta-only now, no longer a seed.
             let accumulatedMessages = [];
+            /**
+             * Give the model accumulator the background injections a step-boundary
+             * drain handed to the model this turn, and record them for persistence.
+             * Returns how many model messages were appended.
+             */
+            const reconcilePendingBackground = () => {
+                const pending = locals.get(chatPendingBackgroundKey);
+                if (!pending || pending.length === 0)
+                    return 0;
+                locals.set(chatPendingBackgroundKey, []);
+                let appended = 0;
+                for (const entry of pending) {
+                    accumulatedMessages.push(...entry.messages);
+                    laneInjections.push(entry);
+                    appended += entry.messages.length;
+                }
+                return appended;
+            };
             /**
              * Give the model accumulator the steering messages a drain consumed,
              * in the form the model actually received. Appended, never reconverted
@@ -4014,7 +3902,41 @@ function chatAgent(options) {
             // collectively cost ~600ms on every first-message TTFC. Both reads
             // swallow errors internally; the agent stays available either way.
             const sessionIdForSnapshot = payload.sessionId ?? payload.chatId;
+            const transcriptStorage = storage ??
+                transcriptStorageOverride ??
+                defaultStorage;
+            const storageLoadContext = transcriptStorage.loadContext?.bind(transcriptStorage);
+            /**
+             * Who supplies the model's context each turn: the deprecated
+             * `hydrateMessages` hook, the storage's `loadContext`, or (undefined)
+             * the runtime's own transcript.
+             */
+            const loadContextHook = hydrateMessages
+                ? (event) => hydrateMessages(event)
+                : storageLoadContext
+                    ? (event) => storageLoadContext({ chatId: event.chatId, clientData: event.clientData }, event)
+                    : undefined;
+            let transcriptShadow = createTranscriptShadow([]);
+            let bootTranscriptState = null;
+            /**
+             * True while the model lane holds a compaction summary, so it cannot be
+             * rebuilt from the transcript and has to be persisted as state. Reset
+             * wherever the lane is reconverted from the UI lane.
+             */
+            let laneCompacted = false;
+            /** Conversational `chat.inject` messages in the lane, anchored to the transcript. */
+            let laneInjections = [];
+            let persistedStateSet = false;
             let bootSnapshot;
+            let bootClientData = payload.metadata;
+            if (parseClientData) {
+                try {
+                    bootClientData = await parseClientData(payload.metadata);
+                }
+                catch {
+                    bootClientData = payload.metadata;
+                }
+            }
             /**
              * The `lastOutEventId` the most recent snapshot carried.
              *
@@ -4024,31 +3946,95 @@ function chatAgent(options) {
              * keeps an action's write cursor-neutral.
              */
             let lastSnapshotOutEventId;
+            const storageTrigger = (trigger) => trigger === "regenerate-message"
+                ? "regenerate-message"
+                : trigger === "action" || trigger === "action-turn"
+                    ? "action"
+                    : "submit-message";
+            /**
+             * Hand the runtime's view of the transcript to the storage as a
+             * changeset: the diff against what was last saved, plus the cursors the
+             * next boot resumes from. The shadow only advances when the save
+             * succeeds, so a failed save is folded into the next changeset.
+             */
+            /** The runtime's opaque state as of the last save; carried on every changeset's transcript. */
+            let transcriptState = null;
+            const saveTranscript = async (opts) => {
+                const { changes, shadow } = diffTranscript(transcriptShadow, opts.messages, {
+                    nonFinalIds: opts.nonFinalIds,
+                });
+                const throughId = opts.messages.at(-1)?.id ?? "";
+                const queued = locals.get(chatBackgroundQueueKey) ?? [];
+                const runtimeState = laneCompacted || laneInjections.length > 0 || queued.length > 0
+                    ? {
+                        v: 1,
+                        ...(laneCompacted
+                            ? {
+                                compaction: {
+                                    modelMessages: accumulatedMessages,
+                                    throughId,
+                                    fingerprint: prefixFingerprint(shadow, throughId),
+                                },
+                            }
+                            : {}),
+                        ...(laneInjections.length > 0 ? { injections: laneInjections } : {}),
+                        ...(queued.length > 0 ? { queued: [...queued] } : {}),
+                    }
+                    : null;
+                if (runtimeState !== null || persistedStateSet) {
+                    changes.push({ op: "state", value: runtimeState });
+                }
+                transcriptState = runtimeState;
+                const inCursor = chatInputRouter().resumeFloor();
+                await transcriptStorage.save({
+                    chatId: payload.chatId,
+                    clientData: opts.clientData,
+                    turn: opts.turn,
+                    trigger: opts.trigger,
+                    runId: ctx.run.id,
+                    ctx,
+                }, {
+                    reason: opts.reason,
+                    changes,
+                    transcript: {
+                        entries: opts.messages.map((message) => ({
+                            id: message.id,
+                            final: !shadow.nonFinal.has(message.id),
+                            message,
+                        })),
+                        state: transcriptState,
+                    },
+                    cursors: {
+                        lastOutEventId: opts.lastOutEventId,
+                        lastInEventId: inCursor !== undefined ? String(inCursor) : undefined,
+                    },
+                });
+                transcriptShadow = shadow;
+                persistedStateSet = runtimeState !== null;
+            };
             /**
              * Persist the accumulator outside a turn.
              *
              * An action is not a turn, so it never reaches the turn-complete path where
-             * the snapshot is normally written — but it can change the conversation in
-             * two ways: a `chat.history` mutation, and a response streamed back from
-             * `onAction`. Both have to survive, and one write at the end of the action
-             * covers both rather than writing twice for a regenerate that does both.
+             * the transcript is normally saved, but a `chat.history` mutation changes
+             * the conversation and has to survive the run ending.
              *
              * Cursor-neutral: an action has no turn cursor of its own, and writing
              * `undefined` would drop the resume point the last turn established and make
              * the next boot replay from further back.
              */
-            const writeSnapshotOutsideTurn = async (reason) => {
+            const writeSnapshotOutsideTurn = async (reason, turnContext) => {
                 if (hydrateMessages)
                     return;
                 try {
                     await tracer.startActiveSpan("snapshot.write", async () => {
-                        const snapshotInCursor = chatInputRouter().resumeFloor();
-                        await writeChatSnapshot(sessionIdForSnapshot, {
-                            version: 1,
-                            savedAt: Date.now(),
+                        await saveTranscript({
+                            reason: "action",
                             messages: accumulatedUIMessages,
+                            turn: turnContext.turn,
+                            trigger: "action",
+                            clientData: turnContext.clientData,
                             lastOutEventId: lastSnapshotOutEventId,
-                            lastInEventId: snapshotInCursor !== undefined ? String(snapshotInCursor) : undefined,
                         });
                     }, {
                         attributes: {
@@ -4082,7 +4068,7 @@ function chatAgent(options) {
             // resume-cursor block reuses it instead of re-scanning.
             let bootInCursor;
             let bootInCursorResolved = false;
-            if (!hydrateMessages && couldHavePriorState) {
+            if (couldHavePriorState) {
                 // Single parent span for the whole boot read phase — snapshot
                 // read, session.out replay, session.in replay. Per-phase timing
                 // + result counts are attributes on the span.
@@ -4090,18 +4076,33 @@ function chatAgent(options) {
                     // snapshot read
                     const snapStart = Date.now();
                     try {
-                        bootSnapshot = await readChatSnapshot(sessionIdForSnapshot);
+                        const loaded = hydrateMessages
+                            ? undefined
+                            : await transcriptStorage.load({
+                                chatId: payload.chatId,
+                                clientData: bootClientData,
+                            });
+                        if (loaded) {
+                            transcriptShadow = createTranscriptShadow(loaded.messages, new Set(loaded.nonFinalIds ?? []));
+                            bootTranscriptState = loaded.state;
+                            transcriptState = loaded.state ?? null;
+                            persistedStateSet = loaded.state !== null && loaded.state !== undefined;
+                            bootSnapshot = {
+                                messages: loaded.messages,
+                                lastOutEventId: loaded.cursors?.lastOutEventId,
+                                lastInEventId: loaded.cursors?.lastInEventId,
+                            };
+                        }
                     }
                     catch (error) {
-                        // `readChatSnapshot` already swallows + warns internally; this catch
-                        // is just belt-and-suspenders against tracer/span errors.
-                        logger.warn("chat.agent: snapshot read failed; continuing without snapshot", {
+                        logger.warn("chat.agent: transcript load failed; continuing from the stream tail", {
                             error: error instanceof Error ? error.message : String(error),
                             sessionId: sessionIdForSnapshot,
                         });
                     }
                     bootSpan.setAttribute("chat.boot.snapshot.durationMs", Date.now() - snapStart);
-                    bootSpan.setAttribute("chat.boot.snapshot.present", !!bootSnapshot);
+                    bootSpan.setAttribute("chat.boot.snapshot.present", bootSnapshot !== undefined &&
+                        (bootSnapshot.messages.length > 0 || bootSnapshot.lastOutEventId !== undefined));
                     bootSpan.setAttribute("chat.boot.snapshot.messageCount", bootSnapshot?.messages?.length ?? 0);
                     // Seed the trim chain from the snapshot's `lastOutEventId` (the SSE
                     // id of the previous turn's `turn-complete` control record). The
@@ -4214,7 +4215,7 @@ function chatAgent(options) {
                 resuming: Boolean(payload.continuation) || ctx.attempt.number > 1,
             });
             // ── Recovery boot + chain reconstruction ────────────────────────
-            if (!hydrateMessages) {
+            {
                 const settledMessages = mergeByIdReplaceWins(bootSnapshot?.messages ?? [], replayedSettled);
                 const inFlightUsers = replayedInTail.map((r) => r.message);
                 const partialAssistant = replayedPartial;
@@ -4367,7 +4368,8 @@ function chatAgent(options) {
                 // path where wire-borne UIMessage[] still seeds the accumulator,
                 // and it's safe because the route handler isn't subject to the
                 // `/in/append` 512 KiB cap.
-                if (accumulatedUIMessages.length === 0 &&
+                if (!loadContextHook &&
+                    accumulatedUIMessages.length === 0 &&
                     payload.trigger === "handover-prepare" &&
                     Array.isArray(payload.headStartMessages) &&
                     payload.headStartMessages.length > 0) {
@@ -4396,7 +4398,17 @@ function chatAgent(options) {
                         }
                     }
                     try {
-                        accumulatedMessages = await toModelMessages(accumulatedUIMessages);
+                        const bootRuntimeState = parseTranscriptRuntimeState(bootTranscriptState);
+                        const restored = await restoreModelLane(accumulatedUIMessages, bootRuntimeState, (messages) => toModelMessages(messages));
+                        accumulatedMessages = restored.messages;
+                        laneCompacted = restored.compacted;
+                        laneInjections = restored.injections;
+                        if (bootRuntimeState?.queued && bootRuntimeState.queued.length > 0) {
+                            locals.set(chatBackgroundQueueKey, [
+                                ...(locals.get(chatBackgroundQueueKey) ?? []),
+                                ...bootRuntimeState.queued,
+                            ]);
+                        }
                     }
                     catch (error) {
                         logger.warn("chat.agent: toModelMessages failed at boot; starting empty", {
@@ -4773,6 +4785,7 @@ function chatAgent(options) {
                     } // end else (no boot-injected first turn)
                 }
                 for (let turn = 0; turn < maxTurns; turn++) {
+                    let turnClientData = payload.metadata;
                     // Declared here so the finally can detach it — a handler leaked past
                     // its turn duplicates every mid-stream message into the shared buffer.
                     let turnMsgSub;
@@ -4794,6 +4807,7 @@ function chatAgent(options) {
                         // `cleanupAbortedParts` no longer has to be re-applied below.
                         const cleanedIncomingMessages = incomingMessages.map((msg) => msg.role === "assistant" ? cleanupAbortedParts(msg) : msg);
                         const clientData = (parseClientData ? await parseClientData(wireMetadata) : wireMetadata);
+                        turnClientData = clientData;
                         const lastUserMessage = extractLastUserMessageText(cleanedIncomingMessages);
                         // Actions are not turns. They use a different span name
                         // and don't carry a turn.number. Branched on at `isAction`.
@@ -4830,6 +4844,7 @@ function chatAgent(options) {
                             locals.set(chatDeferKey, new Set());
                             locals.set(chatCompactionStateKey, undefined);
                             locals.set(chatSteeringQueueKey, []);
+                            locals.set(chatPendingBackgroundKey, []);
                             locals.set(chatResponsePartsKey, []);
                             // NOTE: chatBackgroundQueueKey is NOT reset here — messages injected
                             // by deferred work from the previous turn's onTurnComplete need to
@@ -4941,9 +4956,9 @@ function chatAgent(options) {
                                     ? await parseAction(currentWirePayload.action)
                                     : currentWirePayload.action;
                                 // Hydrate messages from backend if configured
-                                if (hydrateMessages) {
+                                if (loadContextHook) {
                                     const hydrated = await tracer.startActiveSpan("hydrateMessages()", async () => {
-                                        return hydrateMessages({
+                                        return loadContextHook({
                                             chatId: currentWirePayload.chatId,
                                             turn,
                                             trigger: "action",
@@ -4963,6 +4978,8 @@ function chatAgent(options) {
                                     });
                                     accumulatedUIMessages = [...hydrated];
                                     accumulatedMessages = await toModelMessages(hydrated);
+                                    laneCompacted = false;
+                                    laneInjections = [];
                                     locals.set(chatCurrentUIMessagesKey, accumulatedUIMessages);
                                 }
                                 // Fire onAction — handler may mutate state via
@@ -4993,6 +5010,8 @@ function chatAgent(options) {
                                         locals.set(chatOverrideMessagesKey, undefined);
                                         accumulatedUIMessages = [...actionOverride];
                                         accumulatedMessages = await toModelMessages(actionOverride);
+                                        laneCompacted = false;
+                                        laneInjections = [];
                                         locals.set(chatCurrentUIMessagesKey, accumulatedUIMessages);
                                         actionChangedHistory = true;
                                     }
@@ -5015,7 +5034,7 @@ function chatAgent(options) {
                                 // route handler's first-turn history to the hydrate hook as
                                 // incoming messages instead (gated on the pending handover).
                                 if (turn === 0 &&
-                                    hydrateMessages &&
+                                    loadContextHook &&
                                     cleanedUIMessages.length === 0 &&
                                     (locals.get(chatHandoverPartialKey)?.length ?? 0) > 0 &&
                                     Array.isArray(payload.headStartMessages) &&
@@ -5045,7 +5064,7 @@ function chatAgent(options) {
                                         },
                                     }));
                                 }
-                                if (hydrateMessages) {
+                                if (loadContextHook) {
                                     // Snapshot the ids the accumulator knew BEFORE this
                                     // turn ran — used below to decide whether an
                                     // incoming wire message is genuinely new or just a
@@ -5063,7 +5082,7 @@ function chatAgent(options) {
                                     // was always true for `submit-message` is now true for every
                                     // trigger.
                                     const hydrated = await tracer.startActiveSpan("hydrateMessages()", async () => {
-                                        return hydrateMessages({
+                                        return loadContextHook({
                                             chatId: currentWirePayload.chatId,
                                             turn,
                                             trigger: currentWirePayload.trigger,
@@ -5102,6 +5121,8 @@ function chatAgent(options) {
                                     }
                                     accumulatedUIMessages = merged;
                                     accumulatedMessages = await toModelMessages(merged);
+                                    laneCompacted = false;
+                                    laneInjections = [];
                                     locals.set(chatCurrentUIMessagesKey, accumulatedUIMessages);
                                     // Track new messages for onTurnComplete.newUIMessages.
                                     // Only push for genuinely new ids — HITL continuations
@@ -5147,6 +5168,8 @@ function chatAgent(options) {
                                             accumulatedUIMessages.pop();
                                         }
                                         accumulatedMessages = await toModelMessages(accumulatedUIMessages);
+                                        laneCompacted = false;
+                                        laneInjections = [];
                                     }
                                     else if (cleanedUIMessages.length > 0) {
                                         // Submit-message (and the special-cased
@@ -5197,6 +5220,8 @@ function chatAgent(options) {
                                             if (!inPlace) {
                                                 logger.warn("chat.agent: replaced message not found at the model lane tail; reconverting the lane");
                                                 accumulatedMessages = await toModelMessages(accumulatedUIMessages);
+                                                laneCompacted = false;
+                                                laneInjections = [];
                                             }
                                         }
                                         else {
@@ -5282,7 +5307,7 @@ function chatAgent(options) {
                                     // history rather than from the snapshot the edit replaced.
                                     // The turn then does its own hooks, completion and snapshot.
                                     if (actionChangedHistory) {
-                                        await writeSnapshotOutsideTurn("action");
+                                        await writeSnapshotOutsideTurn("action", { turn, clientData });
                                     }
                                     actionTurn = true;
                                 }
@@ -5294,7 +5319,7 @@ function chatAgent(options) {
                                 else {
                                     msgSub?.off();
                                     if (actionChangedHistory) {
-                                        await writeSnapshotOutsideTurn("action");
+                                        await writeSnapshotOutsideTurn("action", { turn, clientData });
                                     }
                                     await writeTurnCompleteChunk(currentWirePayload.chatId);
                                     // Don't consume a turn iteration — actions aren't turns.
@@ -5392,6 +5417,8 @@ function chatAgent(options) {
                                             locals.set(chatOverrideMessagesKey, undefined);
                                             accumulatedUIMessages = [...turnStartOverride];
                                             accumulatedMessages = await toModelMessages(turnStartOverride);
+                                            laneCompacted = false;
+                                            laneInjections = [];
                                             locals.set(chatCurrentUIMessagesKey, accumulatedUIMessages);
                                         }
                                     }, {
@@ -5452,7 +5479,12 @@ function chatAgent(options) {
                                     const lastAccumulated = accumulatedMessages[accumulatedMessages.length - 1];
                                     const bgQueue = locals.get(chatBackgroundQueueKey);
                                     if (bgQueue && bgQueue.length > 0 && lastAccumulated?.role !== "tool") {
-                                        accumulatedMessages.push(...bgQueue.splice(0));
+                                        const injected = bgQueue.splice(0);
+                                        accumulatedMessages.push(...injected);
+                                        laneInjections.push({
+                                            afterId: accumulatedUIMessages.at(-1)?.id ?? "",
+                                            messages: injected,
+                                        });
                                     }
                                     if (isHeadStartFinalTurn) {
                                         // The synthesized partial UIMessage IS the response.
@@ -5613,6 +5645,8 @@ function chatAgent(options) {
                                     locals.set(chatPendingSteerKey, pending);
                                     const pendingIds = new Set(pending.map((e) => e.ui.id));
                                     accumulatedMessages = await toModelMessages(runOverride.filter((m) => !pendingIds.has(m.id)));
+                                    laneCompacted = false;
+                                    laneInjections = [];
                                     locals.set(chatCurrentUIMessagesKey, accumulatedUIMessages);
                                 }
                                 // Check if compaction set a model-only override (preserves UI messages).
@@ -5635,6 +5669,8 @@ function chatAgent(options) {
                                     accumulatedMessages = taskCompactionConfig?.compactModelMessages
                                         ? await taskCompactionConfig.compactModelMessages(compactEvent)
                                         : modelOnlyOverride;
+                                    laneCompacted = true;
+                                    laneInjections = [];
                                     // Apply UI messages: callback or default (preserve all)
                                     if (taskCompactionConfig?.compactUIMessages) {
                                         accumulatedUIMessages = (await taskCompactionConfig.compactUIMessages(compactEvent));
@@ -5650,7 +5686,7 @@ function chatAgent(options) {
                                 // branches below, so a turn that captured no response is covered.
                                 const steerTailThisTurn = reconcilePendingSteer({
                                     turnNew: turnNewModelMessages,
-                                }).reduce((n, e) => n + e.model.length, 0);
+                                }).reduce((n, e) => n + e.model.length, 0) + reconcilePendingBackground();
                                 // Append the assistant's response (partial or complete) to the accumulator.
                                 // The onFinish callback fires even on abort/stop, so partial responses
                                 // from stopped generation are captured correctly.
@@ -5713,6 +5749,8 @@ function chatAgent(options) {
                                             if (!ok) {
                                                 logger.warn("chat.agent: replaced response not found at the model lane tail; reconverting the lane");
                                                 accumulatedMessages = await toModelMessages(accumulatedUIMessages);
+                                                laneCompacted = false;
+                                                laneInjections = [];
                                             }
                                         }
                                         else {
@@ -5821,6 +5859,8 @@ function chatAgent(options) {
                                                                 ],
                                                             },
                                                         ];
+                                                    laneCompacted = true;
+                                                    laneInjections = [];
                                                     // UI messages: callback or default (preserve all)
                                                     if (outerCompaction.compactUIMessages) {
                                                         accumulatedUIMessages = (await outerCompaction.compactUIMessages(outerCompactEvent));
@@ -5910,6 +5950,8 @@ function chatAgent(options) {
                                             locals.set(chatOverrideMessagesKey, undefined);
                                             accumulatedUIMessages = [...override];
                                             accumulatedMessages = await toModelMessages(override);
+                                            laneCompacted = false;
+                                            laneInjections = [];
                                             locals.set(chatCurrentUIMessagesKey, accumulatedUIMessages);
                                             // Update event so onTurnComplete sees compacted messages
                                             turnCompleteEvent.messages = accumulatedMessages;
@@ -5956,6 +5998,8 @@ function chatAgent(options) {
                                             locals.set(chatOverrideMessagesKey, undefined);
                                             accumulatedUIMessages = [...turnCompleteOverride];
                                             accumulatedMessages = await toModelMessages(turnCompleteOverride);
+                                            laneCompacted = false;
+                                            laneInjections = [];
                                             locals.set(chatCurrentUIMessagesKey, accumulatedUIMessages);
                                         }
                                     }, {
@@ -6009,15 +6053,18 @@ function chatAgent(options) {
                                 if (!hydrateMessages) {
                                     try {
                                         await tracer.startActiveSpan("snapshot.write", async () => {
-                                            const snapshotInCursor = chatInputRouter().resumeFloor();
                                             lastSnapshotOutEventId =
                                                 turnCompleteResult?.lastEventId ?? lastSnapshotOutEventId;
-                                            await writeChatSnapshot(sessionIdForSnapshot, {
-                                                version: 1,
-                                                savedAt: Date.now(),
+                                            await saveTranscript({
+                                                reason: "turn-complete",
                                                 messages: accumulatedUIMessages,
+                                                turn,
+                                                trigger: storageTrigger(currentWirePayload.trigger),
+                                                clientData,
                                                 lastOutEventId: lastSnapshotOutEventId,
-                                                lastInEventId: snapshotInCursor !== undefined ? String(snapshotInCursor) : undefined,
+                                                nonFinalIds: wasStopped && capturedResponseMessage?.id
+                                                    ? new Set([capturedResponseMessage.id])
+                                                    : undefined,
                                             });
                                         }, {
                                             attributes: {
@@ -6238,6 +6285,7 @@ function chatAgent(options) {
                         let erroredNewUIMessages = buildErroredNew();
                         let erroredNewModelMessages = [];
                         const reconciledSteer = reconcilePendingSteer();
+                        const backgroundTailThisTurn = reconcilePendingBackground();
                         if (!responseCommitted) {
                             try {
                                 if (erroredNewUIMessages.length > 0) {
@@ -6262,10 +6310,13 @@ function chatAgent(options) {
                                         accumulatedMessages.push(...(await toModelMessages(appended.map((m) => stripProviderMetadata(m)))));
                                     }
                                     else {
-                                        const ok = await replaceModelRun(accumulatedMessages, erroredUIMessages[partialIdx], partialResponse, reconciledSteer.reduce((n, e) => n + e.model.length, 0));
+                                        const ok = await replaceModelRun(accumulatedMessages, erroredUIMessages[partialIdx], partialResponse, reconciledSteer.reduce((n, e) => n + e.model.length, 0) +
+                                            backgroundTailThisTurn);
                                         if (!ok) {
                                             logger.warn("chat.agent: replaced partial not found at the model lane tail; reconverting the lane");
                                             accumulatedMessages = await toModelMessages(erroredUIMessagesWithPartial);
+                                            laneCompacted = false;
+                                            laneInjections = [];
                                         }
                                     }
                                     accumulatedUIMessages = erroredUIMessagesWithPartial;
@@ -6329,13 +6380,14 @@ function chatAgent(options) {
                         // neither the snapshot nor the replayable `.in` tail.
                         if (!hydrateMessages) {
                             try {
-                                const errorSnapshotInCursor = chatInputRouter().resumeFloor();
-                                await writeChatSnapshot(sessionIdForSnapshot, {
-                                    version: 1,
-                                    savedAt: Date.now(),
+                                await saveTranscript({
+                                    reason: "turn-error",
                                     messages: erroredUIMessagesWithPartial,
-                                    lastOutEventId: errorTurnCompleteResult?.lastEventId,
-                                    lastInEventId: errorSnapshotInCursor !== undefined ? String(errorSnapshotInCursor) : undefined,
+                                    turn,
+                                    trigger: storageTrigger(currentWirePayload.trigger),
+                                    clientData: turnClientData,
+                                    lastOutEventId: lastSnapshotOutEventId,
+                                    nonFinalIds: includePartial && partialResponse ? new Set([partialResponse.id]) : undefined,
                                 });
                             }
                             catch (error) {
@@ -8652,6 +8704,41 @@ async function mintPublicTokenWithOverride(args) {
         expirationTime: args.expirationTime,
     });
 }
+/**
+ * Creates a server-side helper that reads a conversation from a transcript
+ * storage, for rendering history before the chat connects. Works the same
+ * for every storage, the platform default included, so the browser never
+ * reads a store directly and the secret key stays on the server.
+ *
+ * Wrap it in a Next.js server action (or any server-side handler), scope it
+ * to the authenticated user through `clientData`, and pass the result to
+ * `useLoadTranscript` in the browser.
+ *
+ * @example
+ * ```ts
+ * // actions.ts
+ * "use server";
+ * import { chat, defaultStorage } from "@trigger.dev/sdk/ai";
+ *
+ * export const loadTranscript = chat.createLoadTranscriptAction(defaultStorage, { limit: 50 });
+ * ```
+ */
+function createChatLoadTranscriptAction(storage, options) {
+    return async (params) => {
+        if (!params.chatId) {
+            throw new Error("chat.createLoadTranscriptAction: params.chatId is required.");
+        }
+        if (options?.apiClient) {
+            const { apiClient, ...rest } = options;
+            return apiClientManager.runWithConfig(apiClient, () => createChatLoadTranscriptAction(storage, rest)(params));
+        }
+        const limit = params.limit ?? options?.limit;
+        return storage.load({ chatId: params.chatId, clientData: params.clientData }, {
+            ...(limit !== undefined ? { limit } : {}),
+            ...(params.before !== undefined ? { before: params.before } : {}),
+        });
+    };
+}
 export const chat = {
     /** Create a chat agent. See {@link chatAgent}. */
     agent: chatAgent,
@@ -8663,6 +8750,8 @@ export const chat = {
     withClientData,
     /** Create a server-side helper for starting (or resuming) a Session for a chatId. See {@link createChatStartSessionAction}. */
     createStartSessionAction: createChatStartSessionAction,
+    /** Returns a server-side helper that reads a conversation from a transcript storage. */
+    createLoadTranscriptAction: createChatLoadTranscriptAction,
     /** Pipe a stream to the chat transport. See {@link pipeChat}. */
     pipe: pipeChat,
     /** Return from `onAction` to run a turn on the edited history. See {@link chatTurn}. */