@trigger.dev/sdk 0.0.0-prerelease-streamfix-20260909094302 → 0.0.0-prerelease-20260909121655

package/dist/esm/v3/ai.js

@@ -1,8 +1,18 @@
-import { accessoryAttributes, apiClientManager, controlSubtype, generateJWT, getSchemaParseFn, headerValue, InputStreamOncePromise, isAdditionalApiKey, isSchemaZodEsque, logger, ManualWaitpointPromise, OutOfMemoryError, resourceCatalog, SemanticInternalAttributes, SESSION_IN_CONSUMED_ID_HEADER, SESSION_IN_EVENT_ID_HEADER, sessionStreams, SessionChannelRouter, InputStreamTimeoutError, taskContext, TRIGGER_CONTROL_SUBTYPE, } from "@trigger.dev/core/v3";
+import { accessoryAttributes, apiClientManager, controlSubtype, generateJWT, getSchemaParseFn, headerValue, InputStreamOncePromise, isAdditionalApiKey, isSchemaZodEsque, logger, ManualWaitpointPromise, OutOfMemoryError, resourceCatalog, SemanticInternalAttributes, SESSION_IN_CONSUMED_ID_HEADER, SESSION_IN_EVENT_ID_HEADER, sessionStreams, SessionChannelRouter, InputStreamTimeoutError, taskContext, TRIGGER_CONTROL_SUBTYPE, SESSION_CLOSED_HEADER, SESSION_CLOSED_REASON_HEADER, tryCatch, } from "@trigger.dev/core/v3";
 // Runtime VALUES go through the ESM/CJS shim so the CJS build can `require`
 // ESM-only `ai@7` (see ../imports/ai-runtime.ts).
 import { trace } from "@opentelemetry/api";
-import { tool as aiTool, convertToModelMessages, dynamicTool, generateId as generateMessageId, getToolName, isToolUIPart, jsonSchema, readUIMessageStream, zodSchema, } from "../imports/ai-runtime.js";
+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, 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";
@@ -17,6 +27,8 @@ import { metadata } from "./metadata.js";
 // pulled in transitively here never reach a client chunk.
 import { readFileInSkill, runBashInSkill } from "./agentSkillsRuntime.js";
 import { ensureAiSdkTelemetry } from "./aiAutoTelemetry.js";
+import { withResolvedExternalDeploymentId } from "./externalDeploymentId.js";
+import { resolvePinToFollow } from "./chatVersionSkew.js";
 import { sessions, } from "./sessions.js";
 import { createTask } from "./shared.js";
 import { markChatAgentRunForStreamsWarning } from "./streams.js";
@@ -103,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
@@ -1027,7 +865,7 @@ async function writeChatCustomAgentClientDataErrorToStream(payload) {
     }
 }
 async function reportChatCustomAgentClientDataError(payload, error, options) {
-    const errorText = error instanceof Error ? error.message : "An unexpected error occurred";
+    const errorText = error instanceof Error && error.message ? error.message : "An unexpected error occurred";
     logger.warn("chat.customAgent: clientData validation failed", {
         chatId: payload.chatId,
         trigger: payload.trigger,
@@ -1754,6 +1592,13 @@ 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);
     const floor = router.resumeFrom();
@@ -1762,6 +1607,10 @@ async function installChatInputRouter(chatId, options) {
         sessionStreams.setLastDispatchedSeqNum(chatId, "in", floor);
     }
     sessionStreams.onRecord(chatId, "in", (record) => {
+        // The floor is the tail's `Last-Event-ID`, but a reconnect can still
+        // re-deliver below it and a replayable route would re-queue it.
+        if (floor !== undefined && record.seqNum <= floor)
+            return true;
         router.ingest(record);
         return true;
     });
@@ -1933,6 +1782,35 @@ 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.
+ *
+ * Kept apart from the message queue because ai@7 rejects a system message inside
+ * `messages` for every provider — `standardizePrompt` throws upstream of any
+ * provider call, and its own advice is to use the instructions option. Instructions
+ * accept `Array<SystemModelMessage>`, so a system-role injection has a correct
+ * home: appended as another system block rather than smuggled into the transcript.
+ *
+ * This is also the only way to inject *trusted* context. A message injected as
+ * `user` is untrusted by construction, and a well-aligned model treats it that
+ * way — it will say so, and re-derive the answer from tools instead.
+ */
+const chatInjectedInstructionsKey = locals.create("chat.injectedInstructions");
+/**
+ * What a turn already consumed from the instructions lane, so a second
+ * `toStreamTextOptions()` call in the same turn sees the same blocks.
+ *
+ * Consumed blocks are moved here rather than left in the pending lane: leaving
+ * them there means an injection made during the consumed turn sits behind them,
+ * and clearing the lane on the next turn destroys both.
+ */
+const chatInstructionsConsumedKey = locals.create("chat.injectedInstructionsConsumed");
 /**
  * Run-scoped pipe counter. Stored in locals so concurrent runs in the
  * same worker don't share state.
@@ -2443,12 +2321,31 @@ const chatToolsOptionKey = locals.create("chat.toolsOption");
 const chatResolvedToolsKey = locals.create("chat.resolvedTools");
 /** @internal Flag set by `chat.requestUpgrade()` to exit the loop after the current turn. */
 const chatUpgradeRequestedKey = locals.create("chat.upgradeRequested");
+/** @internal Target for the upgrade handoff, set by `chat.requestUpgrade({ externalDeploymentId })`. */
+const chatUpgradeExternalDeploymentIdKey = locals.create("chat.upgradeExternalDeploymentId");
 /**
  * @internal Flag set by `chat.endRun()` to exit the loop after the current
  * turn completes, without any upgrade semantics. Checked at the same
  * post-turn / pre-wait sites as `chatUpgradeRequestedKey`.
  */
 const chatEndRunRequestedKey = locals.create("chat.endRunRequested");
+/**
+ * @internal Set by `chat.close()`. Holds the close request (and its reason)
+ * for the rest of the run: the loop writes the terminal `session-closed`
+ * record, closes the session row, and exits at the same post-turn /
+ * pre-wait sites as `chatEndRunRequestedKey`.
+ */
+const chatCloseRequestedKey = locals.create("chat.closeRequested");
+/** @internal Matches the server's `CloseSessionRequestBody.reason` cap. */
+const CHAT_CLOSE_REASON_MAX_LENGTH = 256;
+/** @internal Set once the session row is closed, so the close happens once. */
+const chatClosePerformedKey = locals.create("chat.closePerformed");
+/**
+ * @internal Set once the terminal `.out` record is written. Tracked apart from
+ * {@link chatClosePerformedKey} so a retried close does not emit a second
+ * client-visible event.
+ */
+const chatCloseRecordWrittenKey = locals.create("chat.closeRecordWritten");
 /** @internal */
 const chatAgentCompactionKey = locals.create("chat.agentCompaction");
 /**
@@ -2465,6 +2362,32 @@ export { PENDING_MESSAGE_INJECTED_TYPE, upsertIncomingMessage };
 const chatPendingMessagesKey = locals.create("chat.pendingMessages");
 /** @internal */
 const chatSteeringQueueKey = locals.create("chat.steeringQueue");
+/**
+ * This turn's new messages, as `onTurnComplete.newUIMessages` will see them.
+ *
+ * Held in locals because `drainSteeringQueue` runs outside the turn closure and
+ * has to append the messages it injects. Without that, an injected message
+ * reaches the model and the browser but no hook, so an app persisting from
+ * `onTurnComplete` never learns it existed.
+ */
+const chatTurnNewUIMessagesKey = locals.create("chat.turnNewUIMessages");
+/**
+ * Steering messages a drain consumed that the model accumulator has not been
+ * given yet.
+ *
+ * The two accumulators are maintained separately, and the model one is
+ * normally advanced by appending each turn's delta. A drained message is
+ * appended to the UI one but reaches the model only through the `prepareStep`
+ * return value, which is per-step: without this the model lane never learns
+ * the message exists and every later turn of the run answers without it,
+ * while the browser, the snapshot and `chat.history.*` all still show it.
+ *
+ * Held as the messages rather than a "rebuild me" flag because the model lane
+ * can only be appended to, never reconstructed. Compaction replaces it with a
+ * summary and deliberately leaves the UI lane whole, so reconverting the UI
+ * lane restores every message the summary replaced.
+ */
+const chatPendingSteerKey = locals.create("chat.pendingSteer");
 /** @internal — IDs of messages that were successfully injected via prepareStep */
 const chatInjectedMessageIdsKey = locals.create("chat.injectedMessageIds");
 /** @internal — non-transient data parts queued via chat.response or writer.write() for accumulation into the response message */
@@ -2817,20 +2740,32 @@ function chatCompactionStep(options) {
         return result.type === "skipped" ? undefined : result;
     };
 }
-// ---------------------------------------------------------------------------
-// Steering queue drain — shared by toStreamTextOptions, session, accumulator
-// ---------------------------------------------------------------------------
+const EMPTY_DRAIN = { injected: [], claimed: [] };
+/**
+ * The model messages to record for one claimed message. Without `prepare`
+ * each entry's own conversion is used. With it, `prepare` returned one list
+ * for the whole batch, so the first claimed message carries all of it and the
+ * rest carry none, which keeps the total exactly what the model received.
+ */
+function modelFormOf(m, batch, injected) {
+    return batch[0] === m ? injected : [];
+}
 /**
  * Drain the steering queue as a batch. Calls `shouldInject` once with all
  * pending messages. If it returns true, calls `prepareMessages` once to
  * transform the batch, then clears the queue.
- * Returns the model messages to inject (empty if none).
+ * Returns the model messages to inject and the UI messages actually claimed.
+ *
+ * `claimed` is returned rather than only published to locals because each
+ * surface files it somewhere different: `chat.agent` has an accumulator in
+ * locals, while `chat.createSession` keeps its own. Publishing to locals alone
+ * is silently a no-op for any surface that never set the key.
  * @internal
  */
 async function drainSteeringQueue(config, messages, steps, queueOverride) {
     const queue = queueOverride ?? locals.get(chatSteeringQueueKey);
     if (!queue || queue.length === 0)
-        return [];
+        return EMPTY_DRAIN;
     const ctx = locals.get(chatTurnContextKey);
     const stepNumber = steps.length - 1;
     /**
@@ -2853,7 +2788,7 @@ async function drainSteeringQueue(config, messages, steps, queueOverride) {
     // Call shouldInject once for the whole batch
     const shouldInject = config.shouldInject ? await config.shouldInject(batchEvent) : false;
     if (!shouldInject)
-        return [];
+        return EMPTY_DRAIN;
     const textOfUIMessage = (m) => (m.parts ?? [])
         .filter((p) => p.type === "text")
         .map((p) => p.text)
@@ -2899,7 +2834,7 @@ async function drainSteeringQueue(config, messages, steps, queueOverride) {
                 queue.splice(at, 1);
         }
         if (claimed.length === 0)
-            return [];
+            return EMPTY_DRAIN;
         /**
          * Give the claim back if the transform fails. `prepare` is caller code and
          * can throw; the records have already left the router by this point, so
@@ -2929,6 +2864,37 @@ async function drainSteeringQueue(config, messages, steps, queueOverride) {
             for (const m of claimedUIMessages)
                 injectedIds.add(m.id);
         }
+        // Record them as part of the conversation.
+        //
+        // The model has them and the browser has them; without this the
+        // accumulator does not, so they reach neither `uiMessages` nor
+        // `newUIMessages` on `onTurnComplete` and an app that persists from there
+        // silently loses the instruction the answer was shaped by. Appending here
+        // rather than at turn end keeps them in the order they happened: after the
+        // message that started the turn, before the response that answers it.
+        //
+        // De-duplicated by id because a step boundary can drain more than once per
+        // turn, and because a message that failed to inject falls back to becoming
+        // its own turn, where it is accumulated the normal way.
+        const currentUIMessages = locals.get(chatCurrentUIMessagesKey);
+        const turnNew = locals.get(chatTurnNewUIMessagesKey);
+        for (const m of claimedUIMessages) {
+            if (currentUIMessages && !currentUIMessages.some((existing) => existing.id === m.id)) {
+                currentUIMessages.push(m);
+            }
+            if (turnNew && !turnNew.some((existing) => existing.id === m.id)) {
+                turnNew.push(m);
+            }
+        }
+        if (claimedUIMessages.length > 0 && currentUIMessages) {
+            const pendingSteer = locals.get(chatPendingSteerKey) ?? [];
+            for (const m of claimedUIMessages) {
+                if (!pendingSteer.some((existing) => existing.ui.id === m.id)) {
+                    pendingSteer.push({ ui: m, model: modelFormOf(m, claimedUIMessages, injected) });
+                }
+            }
+            locals.set(chatPendingSteerKey, pendingSteer);
+        }
         // Write injection confirmation chunk to the stream so the frontend
         // knows which messages were injected and where in the response.
         if (injected.length > 0) {
@@ -2970,7 +2936,7 @@ async function drainSteeringQueue(config, messages, steps, queueOverride) {
                 /* non-fatal */
             }
         }
-        return injected;
+        return { injected, claimed: claimedUIMessages };
     }, {
         attributes: {
             [SemanticInternalAttributes.STYLE_ICON]: "tabler-message-forward",
@@ -3196,32 +3162,149 @@ export function buildSkillTools(skills) {
     return { loadSkill, readFile, bash };
 }
 /**
- * Returns an options object ready to spread into `streamText()`.
- *
- * Includes `system`, `experimental_telemetry`, and any config fields
- * (temperature, maxTokens, etc.) from the stored prompt.
- *
- * When a `registry` is provided and the prompt has a `model` string,
- * the resolved `LanguageModel` is included as `model`.
+ * A `streamText` with the agent's managed options already applied.
+ *
+ * Handed to `run()` so the managed state cannot be missed by omission. Spreading
+ * `chat.toStreamTextOptions()` is still supported and equivalent; this exists
+ * because forgetting the spread silently drops the managed prompt, the skill
+ * tools, telemetry, and the `prepareStep` that delivers steering, compaction and
+ * conversational injection.
+ *
+ * Caller options win for everything the caller owns (model, messages, signal,
+ * stopWhen). The three that would otherwise clobber managed behaviour are
+ * merged instead of replaced:
+ *
+ * - `tools` are passed into the helper, so skill tools survive.
+ * - `prepareStep` is composed after the managed one, so a caller's per-step
+ *   overrides apply on top of steering and compaction instead of disabling them.
+ *
+ * `system` may be set at the call site, on `chat.agent({ system })`, or
+ * through `chat.prompt.set()`, but only in one of them. Setting it in two
+ * places throws: no shape merges two system values on every supported
+ * version, and dropping one silently is the failure this seam exists to
+ * prevent. Injected instructions append to whichever one is in play.
+ */
+/**
+ * The agent-level managed options (`registry`, `system`, `cacheControl`,
+ * `systemProviderOptions`), published for the run so that
+ * `chat.toStreamTextOptions()` applies them too. Without this only the bound
+ * `streamText` saw them, and the documented spread form silently ran without
+ * the agent's system prompt or model.
+ */
+const chatAgentManagedConfigKey = locals.create("chat.agentManagedConfig");
+/**
+ * The caller's `streamText` options merged with the agent's managed ones.
  *
- * If no prompt has been set, returns `{}` (no-op spread).
+ * Pure, and separate from the call so it can be asserted directly: everything
+ * the caller did not name has to survive the merge, and the way to be sure of
+ * that is to look at the merged object rather than at what the model received.
  */
+function buildManagedStreamTextOptions(options, config) {
+    const { registry, system: agentSystem, cacheControl, systemProviderOptions, tools: agentTools, } = config;
+    /**
+     * Only the three keys that collide are intercepted. Everything else, telemetry
+     * included, stays in `rest` and reaches `streamText` untouched, with the
+     * caller's value winning because `rest` is spread after `managed`. Pulling a
+     * key out to "handle" it is how a caller's option gets silently dropped.
+     */
+    const { tools, system: callerSystem, prepareStep: callerPrepareStep, ...rest } = options;
+    const managed = toStreamTextOptions({
+        registry,
+        system: callerSystem ?? agentSystem,
+        cacheControl,
+        systemProviderOptions,
+        /**
+         * A call site that names `tools` replaces the agent's set rather than
+         * adding to it, so narrowing the tools for one call still works. Omitting
+         * `tools` falls back to the agent's, which is what an `onAction`
+         * regenerate needs: without it a regenerated answer can call nothing.
+         */
+        tools: (tools ?? agentTools),
+    });
+    const promptSystem = locals.get(chatPromptKey)?.text;
+    /**
+     * Two managed sources conflict too, not only a caller against a managed one.
+     * `toStreamTextOptions` resolves `prompt?.text || agentSystem`, so the prompt
+     * would win and `chat.agent({ system })` would go nowhere.
+     */
+    if (promptSystem && agentSystem) {
+        throw new Error("chat.agent: `system` is set both on chat.agent({ system }) and by chat.prompt.set(), and only one " +
+            "of them can apply. The prompt would win and the agent's `system` would go nowhere. Keep it in one " +
+            "place, and add per-turn context with chat.inject({ role: 'system' }).");
+    }
+    const managedSystem = promptSystem || agentSystem;
+    if (callerSystem !== undefined && managedSystem) {
+        throw new Error("chat.agent: `system` is already set " +
+            (promptSystem ? "by chat.prompt.set()" : "on chat.agent({ system })") +
+            ", so it cannot also be passed to the `streamText` given to run(). Set it in one place, and add " +
+            "per-turn context with chat.inject({ role: 'system' }) rather than a second system value.");
+    }
+    const managedPrepareStep = managed.prepareStep;
+    if (typeof callerPrepareStep === "function") {
+        managed.prepareStep = async (arg) => {
+            const first = managedPrepareStep ? await managedPrepareStep(arg) : undefined;
+            const second = await callerPrepareStep({ ...arg, ...(first ?? {}) });
+            return { ...(first ?? {}), ...(second ?? {}) };
+        };
+    }
+    return { ...managed, ...rest };
+}
+/** @internal Test hook for {@link buildManagedStreamTextOptions}. */
+export const __buildManagedStreamTextOptionsForTests = buildManagedStreamTextOptions;
+function createBoundStreamText(registry, agentSystem, agentCacheControl, agentSystemProviderOptions) {
+    const bound = (options = {}) => aiStreamText(buildManagedStreamTextOptions(options, {
+        registry,
+        system: agentSystem,
+        cacheControl: agentCacheControl,
+        systemProviderOptions: agentSystemProviderOptions,
+        /** Read per call, so per-turn tools resolved after binding are included. */
+        tools: locals.get(chatResolvedToolsKey),
+    }));
+    return bound;
+}
 function toStreamTextOptions(options) {
+    const agentDefaults = locals.get(chatAgentManagedConfigKey);
+    if (agentDefaults) {
+        options = {
+            registry: agentDefaults.registry,
+            system: agentDefaults.system,
+            cacheControl: agentDefaults.cacheControl,
+            systemProviderOptions: agentDefaults.systemProviderOptions,
+            ...options,
+        };
+    }
     const prompt = locals.get(chatPromptKey);
     const skills = locals.get(chatSkillsKey);
     const result = {};
     // Build the combined system prompt: stored prompt + skills preamble.
-    const promptText = prompt?.text ?? "";
+    const baseSystem = options?.system;
+    const baseSystemText = typeof baseSystem === "string"
+        ? baseSystem
+        : typeof baseSystem?.content === "string"
+            ? baseSystem.content
+            : "";
+    const promptText = prompt?.text || baseSystemText;
     const skillsText = skills && skills.length > 0 ? buildSkillsSystemPrompt(skills) : "";
     if (promptText || skillsText) {
         const systemText = [promptText, skillsText].filter(Boolean).join("\n\n");
-        // Resolve system-prompt provider options for caching. Precedence (most
-        // specific wins, no deep merge): explicit `systemProviderOptions` →
-        // `cacheControl` sugar → `providerOptions` stored on `chat.prompt.set()`.
+        /**
+         * Resolve system-prompt provider options for caching. Precedence, most
+         * specific first and no deep merge: explicit `systemProviderOptions`, the
+         * `cacheControl` sugar, the ones carried on a structured `system` message,
+         * then whatever `chat.prompt.set()` stored.
+         *
+         * A structured `system` counts only when its own text is the one being
+         * sent. When `chat.prompt.set()` supplied the text, its provider options
+         * are the ones that describe it.
+         */
+        const baseSystemProviderOptions = !prompt?.text && baseSystem && typeof baseSystem !== "string"
+            ? baseSystem.providerOptions
+            : undefined;
         const systemProviderOptions = options?.systemProviderOptions ??
             (options?.cacheControl
                 ? { anthropic: { cacheControl: options.cacheControl } }
                 : undefined) ??
+            baseSystemProviderOptions ??
             locals.get(chatPromptProviderOptionsKey);
         // A bare string stays a bare string (the unchanged default). With provider
         // options, emit a structured `SystemModelMessage` so the provider can cache
@@ -3230,6 +3313,88 @@ function toStreamTextOptions(options) {
             ? { role: "system", content: systemText, providerOptions: systemProviderOptions }
             : systemText;
     }
+    /**
+     * Append anything injected as system context, in whichever shape the installed
+     * AI SDK accepts.
+     *
+     * `system` widened over time: on ai@5 it is `string` only, and from ai@6 it is
+     * `string | SystemModelMessage | Array<SystemModelMessage>`. This package's peer
+     * range still spans all three, so emitting an array unconditionally would break
+     * v5 consumers — for whom a system-role injection used to work, since v5 accepted
+     * a system message inside `messages` that v7 rejects.
+     *
+     * So: concatenate into one string when the base is a plain string, which every
+     * version accepts and which loses nothing (separate blocks only matter for
+     * per-block `providerOptions`). Use the array form only when the base is already
+     * a structured message — that path requires v6+ regardless, because it is how
+     * prompt caching marks the system block, and flattening it would silently throw
+     * the cache away.
+     *
+     * Either way the injected text goes last: the base prompt keeps its position for
+     * caching, and the addition reads as a later amendment. A changed prefix does
+     * cost the first call its cache hit, on turns that actually injected.
+     */
+    /**
+     * Consumed once per turn, not once per read, and moved out of the lane rather
+     * than marked read in place.
+     *
+     * Per turn, because a `run()` that builds options twice (a cheap classifier
+     * pass and then the answer) has to see the injection in both, and draining on
+     * read hands it to whichever call ran first. Moved out, because blocks left in
+     * the lane sit in front of anything injected during the same turn, and
+     * clearing the lane on the next turn then destroys both. Outside a turn there
+     * is no turn to scope the stash to, so the lane drains on read there.
+     */
+    const injectedInstructions = locals.get(chatInjectedInstructionsKey);
+    const currentTurn = locals.get(chatTurnContextKey)?.turn;
+    const consumedThisTurn = currentTurn === undefined ? undefined : locals.get(chatInstructionsConsumedKey);
+    let injectedBlocks = [];
+    if (consumedThisTurn && consumedThisTurn.turn === currentTurn) {
+        injectedBlocks = consumedThisTurn.blocks;
+        // Anything injected since the stash was taken joins it, so an instruction
+        // added after an action read the lane still reaches the real turn that
+        // shares the action's turn number, rather than the one after.
+        if (injectedInstructions && injectedInstructions.length > 0) {
+            injectedBlocks.push(...injectedInstructions.splice(0));
+        }
+    }
+    else if (injectedInstructions && injectedInstructions.length > 0) {
+        injectedBlocks = injectedInstructions.splice(0);
+        if (currentTurn !== undefined) {
+            locals.set(chatInstructionsConsumedKey, { turn: currentTurn, blocks: injectedBlocks });
+        }
+    }
+    if (injectedBlocks.length > 0) {
+        const blocks = injectedBlocks;
+        const injectedText = blocks
+            .map((block) => (typeof block.content === "string" ? block.content : ""))
+            .filter(Boolean)
+            .join("\n\n");
+        const base = result.system;
+        if (base === undefined) {
+            result.system = injectedText;
+        }
+        else if (typeof base === "string") {
+            result.system = [base, injectedText].filter(Boolean).join("\n\n");
+        }
+        else {
+            // Merged into the existing block rather than added as a second one. An array
+            // of system blocks would keep the base block's cache entry, but ai@5 rejects
+            // it outright ("Invalid prompt: system must be a string") while accepting a
+            // single structured block, and this package's peer range still spans v5.
+            // Choosing per version would mean resolving the installed version at runtime,
+            // which is not something to build on: `import.meta.url` is illegal in this
+            // package's CommonJS output, and a bundled task may have no resolvable `ai`
+            // to read. One shape that works everywhere beats a cache hit.
+            const baseBlock = base;
+            result.system = {
+                ...baseBlock,
+                content: [typeof baseBlock.content === "string" ? baseBlock.content : "", injectedText]
+                    .filter(Boolean)
+                    .join("\n\n"),
+            };
+        }
+    }
     // Prompt-related options (only if chat.prompt.set() was called)
     if (prompt) {
         // Resolve model via registry if both are present
@@ -3284,7 +3449,7 @@ function toStreamTextOptions(options) {
             }
             // 2. Pending message injection (steering)
             if (taskPendingMessages) {
-                const injected = await drainSteeringQueue(taskPendingMessages, resultMessages ?? messages, steps);
+                const { injected } = await drainSteeringQueue(taskPendingMessages, resultMessages ?? messages, steps);
                 if (injected.length > 0) {
                     resultMessages = [...(resultMessages ?? messages), ...injected];
                 }
@@ -3294,18 +3459,89 @@ 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;
         };
     }
     return result;
 }
+const actionTurnBrand = Symbol.for("trigger.dev/chat/actionTurn");
+/**
+ * Turn the current action into a turn.
+ *
+ * Return it from `onAction` after editing history. The action's own work is
+ * finished first (the edit is applied and snapshotted), then a turn runs on the
+ * result exactly as a message turn does: `onTurnStart`, `run()` with the edited
+ * history, `onBeforeTurnComplete`, `onTurnComplete`, and the turn counter
+ * advances. That gives the answer everything a turn has, the system prompt,
+ * tools, steering, compaction, injected instructions and persistence, with no
+ * action-specific handling.
+ *
+ * @example
+ * ```ts
+ * onAction: async ({ action }) => {
+ *   if (action.type === "regenerate") {
+ *     chat.history.slice(0, -1);
+ *     return chat.turn();
+ *   }
+ *   if (action.type === "undo") chat.history.slice(0, -2); // no turn
+ * },
+ * ```
+ */
+function chatTurn() {
+    return { [actionTurnBrand]: true };
+}
+function isActionTurn(value) {
+    return typeof value === "object" && value !== null && value[actionTurnBrand] === true;
+}
+/**
+ * Replace, in a model lane, the run of messages one UI message contributed.
+ *
+ * Used when a UI message is replaced in place (a tool-approval continuation
+ * merging onto the trailing assistant, a captured response reusing an existing
+ * id, a partial replacing an existing message). Reconverting the whole lane
+ * from the UI lane would also replace a compaction summary with the full
+ * transcript and drop the model forms `pendingMessages.prepare` produced.
+ *
+ * The replaced message is the trailing one, so its run is the lane's tail,
+ * before any steer forms appended after it this turn (`tailAfter`). If the
+ * tail does not match the old message's conversion, nothing is changed and
+ * `false` is returned so the caller can fall back to a full reconversion.
+ */
+async function replaceModelRun(lane, oldUi, newUi, tailAfter) {
+    const oldRun = await toModelMessages([stripProviderMetadata(oldUi)]);
+    const newRun = await toModelMessages([stripProviderMetadata(newUi)]);
+    const end = lane.length - tailAfter;
+    const start = end - oldRun.length;
+    if (start < 0 || end > lane.length)
+        return false;
+    if (JSON.stringify(lane.slice(start, end)) !== JSON.stringify(oldRun))
+        return false;
+    lane.splice(start, oldRun.length, ...newRun);
+    return true;
+}
 function isUIMessageStreamable(value) {
     return (typeof value === "object" &&
         value !== null &&
         "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)
@@ -3438,10 +3674,22 @@ function chatCustomAgent(options) {
             await installChatInputRouter(payload.chatId, {
                 resuming: Boolean(payload.continuation),
             });
+            // A custom agent's loop is the customer's, so there is no exit site the
+            // SDK controls. Perform a requested close when `run()` returns, whatever
+            // shape the loop had. Idempotent, so the createSession iterator having
+            // already closed on its own exit costs nothing.
+            const withClose = async (result) => {
+                try {
+                    return await result;
+                }
+                finally {
+                    await performChatClose();
+                }
+            };
             // Keep the schema-free path identical to the original custom-agent
             // wrapper, including when userRun starts executing.
             if (!parseClientData) {
-                return userRun(payload, runOptions);
+                return withClose(userRun(payload, runOptions));
             }
             const isHandoverBoot = payload.trigger === "handover-prepare";
             const isMessagelessBoot = payload.trigger === "preload" ||
@@ -3457,7 +3705,7 @@ function chatCustomAgent(options) {
                 writeErrorToStream: !isMessagelessBoot && !isHandoverBoot,
             });
             if (validated.ok) {
-                return userRun(validated.payload, runOptions);
+                return withClose(userRun(validated.payload, runOptions));
             }
             if (isHandoverBoot) {
                 const signal = await waitForHandover({
@@ -3493,7 +3741,7 @@ function chatCustomAgent(options) {
                 sessionId: next.output.sessionId ?? payload.sessionId,
                 idleTimeoutInSeconds: next.output.idleTimeoutInSeconds ?? payload.idleTimeoutInSeconds,
             };
-            return userRun(recoveredPayload, runOptions);
+            return withClose(userRun(recoveredPayload, runOptions));
         },
     });
     // Register clientDataSchema so the CLI converts it to JSONSchema
@@ -3506,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, ...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
@@ -3589,6 +3849,42 @@ 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
+             * from the UI lane, so a model-only compaction summary survives. Called
+             * on both the success and the error path, before the response or the
+             * partial joins the lane, so the order stays steer-then-answer.
+             */
+            const reconcilePendingSteer = (options) => {
+                const pending = locals.get(chatPendingSteerKey);
+                if (!pending || pending.length === 0)
+                    return [];
+                locals.set(chatPendingSteerKey, []);
+                for (const entry of pending) {
+                    accumulatedMessages.push(...entry.model);
+                    options?.turnNew?.push(...entry.model);
+                }
+                return pending;
+            };
             // Accumulated UI messages for persistence. Mirrors the model accumulator
             // but in frontend-friendly UIMessage format (with parts, id, etc.).
             let accumulatedUIMessages = [];
@@ -3606,7 +3902,156 @@ 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.
+             *
+             * A snapshot written outside a turn — after an action mutates history — has
+             * no turn cursor of its own, and writing `undefined` there would drop the
+             * resume point and make the next boot replay from further back. Retaining it
+             * 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,
+                                },
+                            }
+                            : {}),
+                        ...(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 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, turnContext) => {
+                if (hydrateMessages)
+                    return;
+                try {
+                    await tracer.startActiveSpan("snapshot.write", async () => {
+                        await saveTranscript({
+                            reason: "action",
+                            messages: accumulatedUIMessages,
+                            turn: turnContext.turn,
+                            trigger: "action",
+                            clientData: turnContext.clientData,
+                            lastOutEventId: lastSnapshotOutEventId,
+                        });
+                    }, {
+                        attributes: {
+                            [SemanticInternalAttributes.STYLE_ICON]: "task-hook-onStart",
+                            [SemanticInternalAttributes.COLLAPSED]: true,
+                            "chat.snapshot.reason": reason,
+                            "chat.messages.count": accumulatedUIMessages.length,
+                        },
+                    });
+                }
+                catch (error) {
+                    logger.warn("chat.agent: snapshot write outside a turn failed; the change may not survive a continuation", {
+                        error: error instanceof Error ? error.message : String(error),
+                        sessionId: sessionIdForSnapshot,
+                        reason,
+                    });
+                }
+            };
             let replayedSettled = [];
             let replayedPartial;
             let replayedPartialRaw;
@@ -3622,7 +4067,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.
@@ -3630,18 +4075,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
@@ -3649,6 +4109,7 @@ function chatAgent(options) {
                     // Without seeding, the new worker would emit no trim on its first
                     // 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;
                     if (bootSnapshot?.lastOutEventId !== undefined) {
                         const seeded = Number.parseInt(bootSnapshot.lastOutEventId, 10);
                         if (Number.isFinite(seeded)) {
@@ -3743,13 +4204,17 @@ function chatAgent(options) {
             // 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.
+            // 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;
             await installChatInputRouter(payload.chatId, {
                 fallbackResumeFrom: bootInCursorResolved ? bootInCursor : undefined,
+                recoveredThrough: lastRecoveredInSeq,
                 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;
@@ -3853,16 +4318,6 @@ function chatAgent(options) {
                 if (hookBeforeBoot) {
                     await hookBeforeBoot();
                 }
-                // Advance the session.in cursor past every recovered user so
-                // the live subscription doesn't re-deliver them.
-                if (replayedInTail.length > 0) {
-                    const lastRecoveredSeq = replayedInTail[replayedInTail.length - 1].seqNum;
-                    const currentCursor = sessionStreams.lastSeqNum(payload.chatId, "in");
-                    if (currentCursor === undefined || lastRecoveredSeq > currentCursor) {
-                        sessionStreams.setLastSeqNum(payload.chatId, "in", lastRecoveredSeq);
-                        sessionStreams.setLastDispatchedSeqNum(payload.chatId, "in", lastRecoveredSeq);
-                    }
-                }
                 // Synthesize wire payloads for each recoveredTurn. The turn-loop
                 // pops these ahead of `messagesInput.waitWithIdleTimeout` so they
                 // dispatch as normal turns with the existing hook stack.
@@ -3912,7 +4367,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) {
@@ -3941,7 +4397,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", {
@@ -3955,6 +4421,12 @@ function chatAgent(options) {
                 // before any hook (`onChatStart`, `onTurnStart`, etc.) fires.
                 locals.set(chatCurrentUIMessagesKey, accumulatedUIMessages);
             }
+            locals.set(chatAgentManagedConfigKey, {
+                registry: promptRegistry,
+                system: agentSystem,
+                cacheControl: agentCacheControl,
+                systemProviderOptions: agentSystemProviderOptions,
+            });
             // Token usage tracking across turns
             let previousTurnUsage;
             let cumulativeUsage = emptyUsage();
@@ -4312,6 +4784,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;
@@ -4333,6 +4806,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`.
@@ -4369,6 +4843,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
@@ -4450,6 +4925,10 @@ function chatAgent(options) {
                             // Track new messages for this turn (user input + assistant response).
                             const turnNewModelMessages = [];
                             const turnNewUIMessages = [];
+                            locals.set(chatTurnNewUIMessagesKey, turnNewUIMessages);
+                            // A head-start handover deliberately resumes from an assistant
+                            // message it spliced in, so it isn't a no-op turn.
+                            let splicedHandoverPartial = false;
                             // ── Action handling ──────────────────────────────────────
                             // Actions arrive on the same input stream but with
                             // trigger === "action". They are NOT turns — only
@@ -4460,16 +4939,25 @@ function chatAgent(options) {
                             // an action, return a `StreamTextResult` (auto-piped),
                             // string, or UIMessage from `onAction`. Turn counter
                             // does not advance.
-                            let actionStreamResult = undefined;
+                            let actionResult = undefined;
+                            /** Set when `onAction` returned `chat.turn()`: the turn block below runs. */
+                            let actionTurn = false;
+                            /**
+                             * Whether this action changed the conversation, by rolling history
+                             * back or by streaming a response. Drives the single snapshot write
+                             * at the end — an action never reaches the turn-complete path that
+                             * normally does it.
+                             */
+                            let actionChangedHistory = false;
                             if (isAction) {
                                 // Parse and validate the action payload
                                 const parsedAction = parseAction
                                     ? 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",
@@ -4489,12 +4977,14 @@ function chatAgent(options) {
                                     });
                                     accumulatedUIMessages = [...hydrated];
                                     accumulatedMessages = await toModelMessages(hydrated);
+                                    laneCompacted = false;
+                                    laneInjections = [];
                                     locals.set(chatCurrentUIMessagesKey, accumulatedUIMessages);
                                 }
                                 // Fire onAction — handler may mutate state via
                                 // `chat.history.*` and / or return a model response.
                                 if (onAction) {
-                                    actionStreamResult = await tracer.startActiveSpan("onAction()", async () => {
+                                    actionResult = await tracer.startActiveSpan("onAction()", async () => {
                                         return await onAction({
                                             action: parsedAction,
                                             chatId: currentWirePayload.chatId,
@@ -4519,7 +5009,10 @@ function chatAgent(options) {
                                         locals.set(chatOverrideMessagesKey, undefined);
                                         accumulatedUIMessages = [...actionOverride];
                                         accumulatedMessages = await toModelMessages(actionOverride);
+                                        laneCompacted = false;
+                                        laneInjections = [];
                                         locals.set(chatCurrentUIMessagesKey, accumulatedUIMessages);
+                                        actionChangedHistory = true;
                                     }
                                 }
                                 else {
@@ -4540,7 +5033,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) &&
@@ -4570,7 +5063,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
@@ -4588,7 +5081,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,
@@ -4627,6 +5120,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
@@ -4672,6 +5167,8 @@ function chatAgent(options) {
                                             accumulatedUIMessages.pop();
                                         }
                                         accumulatedMessages = await toModelMessages(accumulatedUIMessages);
+                                        laneCompacted = false;
+                                        laneInjections = [];
                                     }
                                     else if (cleanedUIMessages.length > 0) {
                                         // Submit-message (and the special-cased
@@ -4688,6 +5185,7 @@ function chatAgent(options) {
                                         // where AI SDK regenerates the id (TRI-9137) still
                                         // applies via `rewriteIncomingIdViaToolCallMap`.
                                         let replaced = false;
+                                        const replacedPairs = [];
                                         for (const raw of cleanedUIMessages) {
                                             let incoming = raw;
                                             let idx = accumulatedUIMessages.findIndex((m) => m.id === incoming.id);
@@ -4699,7 +5197,9 @@ function chatAgent(options) {
                                                 }
                                             }
                                             if (idx !== -1) {
-                                                accumulatedUIMessages[idx] = mergeIncomingIntoHydrated(accumulatedUIMessages[idx], incoming);
+                                                const previous = accumulatedUIMessages[idx];
+                                                accumulatedUIMessages[idx] = mergeIncomingIntoHydrated(previous, incoming);
+                                                replacedPairs.push({ previous, merged: accumulatedUIMessages[idx] });
                                                 replaced = true;
                                             }
                                             else {
@@ -4709,9 +5209,19 @@ function chatAgent(options) {
                                             recordToolCallIdsFromMessage(incoming);
                                         }
                                         if (replaced) {
-                                            // Replacement changes structure — reconvert all model
-                                            // messages instead of appending.
-                                            accumulatedMessages = await toModelMessages(accumulatedUIMessages);
+                                            let inPlace = true;
+                                            for (const { previous, merged } of replacedPairs) {
+                                                if (!(await replaceModelRun(accumulatedMessages, previous, merged, 0))) {
+                                                    inPlace = false;
+                                                    break;
+                                                }
+                                            }
+                                            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 {
                                             const incomingModelMessages = await toModelMessages(cleanedUIMessages);
@@ -4754,10 +5264,33 @@ function chatAgent(options) {
                                             messageId: locals.get(chatHandoverMessageIdKey),
                                         });
                                         locals.set(chatHandoverPartialKey, []); // consume once
+                                        splicedHandoverPartial = true;
                                     }
                                 }
                                 locals.set(chatCurrentUIMessagesKey, accumulatedUIMessages);
                             } // end if (trigger !== "action")
+                            // ── No-op turn ──────────────────────────────────────────
+                            //
+                            // A submit that added no new user message and leaves the model
+                            // chain ending on an assistant message has nothing to answer —
+                            // calling the model would prefill its own last reply. Keyed on
+                            // the model tail, so a `tool`-terminated chain (a merged tool
+                            // approval) still runs.
+                            const isNoOpTurn = !isAction &&
+                                !splicedHandoverPartial &&
+                                currentWirePayload.trigger === "submit-message" &&
+                                turnNewUIMessages.length === 0 &&
+                                accumulatedMessages[accumulatedMessages.length - 1]?.role === "assistant";
+                            if (isNoOpTurn) {
+                                msgSub?.off();
+                                logger.warn("chat.agent: turn added no new user message; skipping the model", {
+                                    chatId: currentWirePayload.chatId,
+                                    messageId: currentWirePayload.messageId,
+                                });
+                                await writeTurnCompleteChunk(currentWirePayload.chatId);
+                                // Not a turn — don't consume an iteration.
+                                turn--;
+                            }
                             // ── Action result handling ──────────────────────────────
                             // For action turns, skip the turn machinery entirely.
                             // If `onAction` returned a stream / string / UIMessage,
@@ -4767,34 +5300,34 @@ function chatAgent(options) {
                             // The turn counter is decremented so the next iteration
                             // sees the same `turn` value — actions don't count.
                             if (isAction) {
-                                msgSub?.off();
-                                if ((locals.get(chatPipeCountKey) ?? 0) === 0 &&
-                                    isUIMessageStreamable(actionStreamResult)) {
-                                    try {
-                                        const resolvedOptions = resolveUIMessageStreamOptions();
-                                        const uiStream = actionStreamResult.toUIMessageStream({
-                                            ...resolvedOptions,
-                                            generateMessageId: resolvedOptions.generateMessageId ?? generateMessageId,
-                                        });
-                                        await pipeChat(uiStream, {
-                                            signal: combinedSignal,
-                                            spanName: "stream response",
-                                        });
+                                if (isActionTurn(actionResult)) {
+                                    // Persist the edit before the turn starts, so a turn that is
+                                    // cancelled or runs out of memory continues from the edited
+                                    // history rather than from the snapshot the edit replaced.
+                                    // The turn then does its own hooks, completion and snapshot.
+                                    if (actionChangedHistory) {
+                                        await writeSnapshotOutsideTurn("action", { turn, clientData });
                                     }
-                                    catch (error) {
-                                        if (error instanceof Error &&
-                                            error.name === "AbortError" &&
-                                            runSignal.aborted) {
-                                            return "exit";
-                                        }
-                                        throw error;
+                                    actionTurn = true;
+                                }
+                                else if (actionResult !== undefined) {
+                                    throw new Error("chat.agent: onAction returned a value. An action is a state edit; to answer " +
+                                        "after the edit, return chat.turn() and a turn runs on the edited history. " +
+                                        "Returning a StreamTextResult, string or UIMessage is no longer supported.");
+                                }
+                                else {
+                                    msgSub?.off();
+                                    if (actionChangedHistory) {
+                                        await writeSnapshotOutsideTurn("action", { turn, clientData });
                                     }
+                                    await writeTurnCompleteChunk(currentWirePayload.chatId);
+                                    // Don't consume a turn iteration — actions aren't turns.
+                                    turn--;
                                 }
-                                await writeTurnCompleteChunk(currentWirePayload.chatId);
-                                // Don't consume a turn iteration — actions aren't turns.
-                                turn--;
                             }
-                            if (!isAction) {
+                            // 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) {
                                 // Mint a scoped public access token once per turn, reused for
                                 // onChatStart, onTurnStart, onTurnComplete, and the turn-complete chunk.
                                 const currentRunId = ctx.run.id;
@@ -4883,6 +5416,8 @@ function chatAgent(options) {
                                             locals.set(chatOverrideMessagesKey, undefined);
                                             accumulatedUIMessages = [...turnStartOverride];
                                             accumulatedMessages = await toModelMessages(turnStartOverride);
+                                            laneCompacted = false;
+                                            laneInjections = [];
                                             locals.set(chatCurrentUIMessagesKey, accumulatedUIMessages);
                                         }
                                     }, {
@@ -4899,9 +5434,11 @@ function chatAgent(options) {
                                         },
                                     });
                                 }
+                                await followSessionPin(currentWirePayload.chatId, versionSkew);
                                 // chat.requestUpgrade() called in onTurnStart (or onValidateMessages) —
-                                // skip run() and signal the transport to re-trigger the same message
-                                // on the new version.
+                                // skip run() and hand over to a fresh run on the new version. The
+                                // successor picks the message up off session.in; the transport only
+                                // keeps reading.
                                 if (locals.get(chatUpgradeRequestedKey)) {
                                     await writeUpgradeRequiredChunk();
                                     return "exit";
@@ -4941,7 +5478,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.
@@ -4960,6 +5502,9 @@ function chatAgent(options) {
                                         const preparedMessages = await applyPrepareMessages(accumulatedMessages, "run");
                                         runResult = await userRun({
                                             ...restWire,
+                                            // A turn requested by chat.turn() is not the action itself:
+                                            // a run() that short-circuits on "action" must still answer.
+                                            ...(actionTurn ? { trigger: "action-turn" } : {}),
                                             messages: preparedMessages,
                                             clientData,
                                             continuation,
@@ -4972,6 +5517,7 @@ function chatAgent(options) {
                                             signal: combinedSignal,
                                             cancelSignal,
                                             stopSignal,
+                                            streamText: createBoundStreamText(promptRegistry, agentSystem, agentCacheControl, agentSystemProviderOptions),
                                         });
                                     }
                                     // Auto-pipe if the run function returned a StreamTextResult or similar,
@@ -5085,7 +5631,21 @@ function chatAgent(options) {
                                 if (runOverride) {
                                     locals.set(chatOverrideMessagesKey, undefined);
                                     accumulatedUIMessages = [...runOverride];
-                                    accumulatedMessages = await toModelMessages(runOverride);
+                                    /**
+                                     * Steers the drain consumed are left out of the rebuild and
+                                     * appended by the reconciliation below instead, so the lane
+                                     * gets the form the model actually received rather than a
+                                     * reconversion of the UI message, and gets it once. A steer
+                                     * the edit removed is dropped from the pending list too, so
+                                     * the edit is honoured.
+                                     */
+                                    const overrideIds = new Set(runOverride.map((m) => m.id));
+                                    const pending = (locals.get(chatPendingSteerKey) ?? []).filter((e) => overrideIds.has(e.ui.id));
+                                    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).
@@ -5108,6 +5668,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));
@@ -5115,10 +5677,20 @@ function chatAgent(options) {
                                 }
                                 // Determine if the user stopped generation this turn (not a full run cancel).
                                 const wasStopped = stopController.signal.aborted && !runSignal.aborted;
+                                // Give the model accumulator the steering messages the drain
+                                // consumed. Appended, never reconverted from the UI lane, so a
+                                // model-only compaction summary set just above survives; and done
+                                // before the response is appended so the order stays
+                                // steer-then-answer. Outside the `capturedResponseMessage`
+                                // branches below, so a turn that captured no response is covered.
+                                const steerTailThisTurn = reconcilePendingSteer({
+                                    turnNew: turnNewModelMessages,
+                                }).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.
                                 let rawResponseMessage;
+                                let responseWasSkipped = false;
                                 if (capturedResponseMessage) {
                                     // Keep the raw message before cleanup for users who want custom handling
                                     rawResponseMessage = capturedResponseMessage;
@@ -5144,43 +5716,56 @@ function chatAgent(options) {
                                         };
                                         locals.set(chatResponsePartsKey, []);
                                     }
-                                    // Tool-approval continuations: the AI SDK reuses the trailing
-                                    // assistant's ID (via originalMessages) so the captured response
-                                    // carries the same ID as an existing message. Replace in place
-                                    // instead of pushing a duplicate. For action turns this never
-                                    // matches because originalMessages is omitted (fresh ID).
-                                    const existingIdx = capturedResponseMessage.id
-                                        ? accumulatedUIMessages.findIndex((m) => m.id === capturedResponseMessage.id)
-                                        : -1;
-                                    if (existingIdx !== -1) {
-                                        accumulatedUIMessages[existingIdx] = capturedResponseMessage;
-                                    }
-                                    else {
-                                        accumulatedUIMessages.push(capturedResponseMessage);
-                                    }
-                                    turnNewUIMessages.push(capturedResponseMessage);
-                                    locals.set(chatCurrentUIMessagesKey, accumulatedUIMessages);
-                                    // Record toolCallId → head messageId so a HITL
-                                    // continuation next turn can recover the head id
-                                    // even if the AI SDK regenerates it. See
-                                    // `chatToolCallToMessageIdKey` for the full
-                                    // rationale (TRI-9137).
-                                    recordToolCallIdsFromMessage(capturedResponseMessage);
-                                    try {
-                                        const responseModelMessages = await toModelMessages([
-                                            stripProviderMetadata(capturedResponseMessage),
-                                        ]);
+                                    const responseHasContent = capturedResponseMessage.parts.some((part) => part.type !== "step-start");
+                                    if (responseHasContent) {
+                                        // Tool-approval continuations: the AI SDK reuses the trailing
+                                        // assistant's ID (via originalMessages) so the captured response
+                                        // carries the same ID as an existing message. Replace in place
+                                        // instead of pushing a duplicate. For action turns this never
+                                        // matches because originalMessages is omitted (fresh ID).
+                                        const existingIdx = capturedResponseMessage.id
+                                            ? accumulatedUIMessages.findIndex((m) => m.id === capturedResponseMessage.id)
+                                            : -1;
+                                        const previousAtIdx = existingIdx !== -1 ? accumulatedUIMessages[existingIdx] : undefined;
                                         if (existingIdx !== -1) {
-                                            // Reconvert all model messages since we replaced rather than appended
-                                            accumulatedMessages = await toModelMessages(accumulatedUIMessages);
+                                            accumulatedUIMessages[existingIdx] = capturedResponseMessage;
                                         }
                                         else {
-                                            accumulatedMessages.push(...responseModelMessages);
+                                            accumulatedUIMessages.push(capturedResponseMessage);
+                                        }
+                                        turnNewUIMessages.push(capturedResponseMessage);
+                                        locals.set(chatCurrentUIMessagesKey, accumulatedUIMessages);
+                                        // Record toolCallId → head messageId so a HITL
+                                        // continuation next turn can recover the head id
+                                        // even if the AI SDK regenerates it. See
+                                        // `chatToolCallToMessageIdKey` for the full
+                                        // rationale (TRI-9137).
+                                        recordToolCallIdsFromMessage(capturedResponseMessage);
+                                        try {
+                                            const responseModelMessages = await toModelMessages([
+                                                stripProviderMetadata(capturedResponseMessage),
+                                            ]);
+                                            if (existingIdx !== -1) {
+                                                const ok = previousAtIdx !== undefined &&
+                                                    (await replaceModelRun(accumulatedMessages, previousAtIdx, capturedResponseMessage, steerTailThisTurn));
+                                                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 {
+                                                accumulatedMessages.push(...responseModelMessages);
+                                            }
+                                            turnNewModelMessages.push(...responseModelMessages);
+                                        }
+                                        catch {
+                                            // Conversion failed — skip accumulation for this turn
                                         }
-                                        turnNewModelMessages.push(...responseModelMessages);
                                     }
-                                    catch {
-                                        // Conversion failed — skip accumulation for this turn
+                                    else {
+                                        responseWasSkipped = true;
                                     }
                                 }
                                 // If there's no captured response (manual pipe mode) but there are
@@ -5280,6 +5865,8 @@ function chatAgent(options) {
                                                                 ],
                                                             },
                                                         ];
+                                                    laneCompacted = true;
+                                                    laneInjections = [];
                                                     // UI messages: callback or default (preserve all)
                                                     if (outerCompaction.compactUIMessages) {
                                                         accumulatedUIMessages = (await outerCompaction.compactUIMessages(outerCompactEvent));
@@ -5369,6 +5956,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;
@@ -5397,6 +5986,19 @@ function chatAgent(options) {
                                         capturedPartialResponse = capturedResponseMessage;
                                         turnCompleteEvent.responseMessage = capturedResponseMessage;
                                         turnCompleteEvent.uiMessages = accumulatedUIMessages;
+                                        locals.set(chatCurrentUIMessagesKey, accumulatedUIMessages);
+                                    }
+                                    else if (responseWasSkipped) {
+                                        capturedResponseMessage = {
+                                            ...capturedResponseMessage,
+                                            parts: [...(capturedResponseMessage.parts ?? []), ...lateParts],
+                                        };
+                                        accumulatedUIMessages.push(capturedResponseMessage);
+                                        turnNewUIMessages.push(capturedResponseMessage);
+                                        capturedPartialResponse = capturedResponseMessage;
+                                        turnCompleteEvent.responseMessage = capturedResponseMessage;
+                                        turnCompleteEvent.uiMessages = accumulatedUIMessages;
+                                        locals.set(chatCurrentUIMessagesKey, accumulatedUIMessages);
                                     }
                                     locals.set(chatResponsePartsKey, []);
                                 }
@@ -5415,6 +6017,8 @@ function chatAgent(options) {
                                             locals.set(chatOverrideMessagesKey, undefined);
                                             accumulatedUIMessages = [...turnCompleteOverride];
                                             accumulatedMessages = await toModelMessages(turnCompleteOverride);
+                                            laneCompacted = false;
+                                            laneInjections = [];
                                             locals.set(chatCurrentUIMessagesKey, accumulatedUIMessages);
                                         }
                                     }, {
@@ -5468,13 +6072,18 @@ function chatAgent(options) {
                                 if (!hydrateMessages) {
                                     try {
                                         await tracer.startActiveSpan("snapshot.write", async () => {
-                                            const snapshotInCursor = chatInputRouter().resumeFloor();
-                                            await writeChatSnapshot(sessionIdForSnapshot, {
-                                                version: 1,
-                                                savedAt: Date.now(),
+                                            lastSnapshotOutEventId =
+                                                turnCompleteResult?.lastEventId ?? lastSnapshotOutEventId;
+                                            await saveTranscript({
+                                                reason: "turn-complete",
                                                 messages: accumulatedUIMessages,
-                                                lastOutEventId: turnCompleteResult?.lastEventId,
-                                                lastInEventId: snapshotInCursor !== undefined ? String(snapshotInCursor) : undefined,
+                                                turn,
+                                                trigger: storageTrigger(currentWirePayload.trigger),
+                                                clientData,
+                                                lastOutEventId: lastSnapshotOutEventId,
+                                                nonFinalIds: wasStopped && capturedResponseMessage?.id
+                                                    ? new Set([capturedResponseMessage.id])
+                                                    : undefined,
                                             });
                                         }, {
                                             attributes: {
@@ -5507,10 +6116,17 @@ function chatAgent(options) {
                                 currentWirePayload = bootInjectedQueue.shift();
                                 return "continue";
                             }
-                            // chat.requestUpgrade() was called — exit the loop so the
-                            // transport triggers a new run on the latest version.
+                            // chat.requestUpgrade() was called — exit the loop; the handover
+                            // has already triggered a new run on the latest version.
                             // chat.endRun() — same exit, no upgrade semantics.
+                            if (locals.get(chatCloseRequestedKey)) {
+                                await performChatClose();
+                                return "exit";
+                            }
                             if (locals.get(chatUpgradeRequestedKey) || locals.get(chatEndRunRequestedKey)) {
+                                if (locals.get(chatUpgradeRequestedKey)) {
+                                    await persistUpgradeHandoff();
+                                }
                                 return "exit";
                             }
                             // Wait for the next message — stay idle briefly, then suspend
@@ -5612,11 +6228,17 @@ function chatAgent(options) {
                         let errorTurnCompleteResult;
                         try {
                             await withChatWriter(async (writer) => {
-                                const errorText = turnError instanceof Error ? turnError.message : "An unexpected error occurred";
+                                const errorText = turnError instanceof Error && turnError.message
+                                    ? turnError.message
+                                    : "An unexpected error occurred";
                                 writer.write({ type: "error", errorText });
                             });
                             // Signal turn complete so the client knows this turn is done
                             errorTurnCompleteResult = await writeTurnCompleteChunk(currentWirePayload.chatId);
+                            // A later action's snapshot reuses this cursor, so it has to move
+                            // here too or that snapshot resumes from before the failed turn.
+                            lastSnapshotOutEventId =
+                                errorTurnCompleteResult?.lastEventId ?? lastSnapshotOutEventId;
                         }
                         catch {
                             // Best-effort — if stream write fails, let the run continue anyway
@@ -5661,15 +6283,47 @@ function chatAgent(options) {
                             : partialIdx === -1
                                 ? [...erroredUIMessages, partialResponse]
                                 : erroredUIMessages.map((m, i) => i === partialIdx ? partialResponse : m);
-                        let erroredNewUIMessages = erroredWireMessage ? [erroredWireMessage] : [];
-                        if (includePartial) {
-                            erroredNewUIMessages.push(partialResponse);
-                        }
+                        /**
+                         * Seeded from the per-turn list, not just the wire message and the
+                         * partial, so a steering message the drain consumed is reported too.
+                         * An app persisting from `newUIMessages` would otherwise lose the
+                         * instruction whenever the turn it steered went on to fail.
+                         */
+                        const buildErroredNew = () => {
+                            const out = [];
+                            const addUnique = (m) => {
+                                if (m && !out.some((existing) => existing.id === m.id))
+                                    out.push(m);
+                            };
+                            addUnique(erroredWireMessage);
+                            for (const m of (locals.get(chatTurnNewUIMessagesKey) ?? [])) {
+                                addUnique(m);
+                            }
+                            if (includePartial)
+                                addUnique(partialResponse);
+                            return out;
+                        };
+                        let erroredNewUIMessages = buildErroredNew();
                         let erroredNewModelMessages = [];
+                        const reconciledSteer = reconcilePendingSteer();
+                        const backgroundTailThisTurn = reconcilePendingBackground();
                         if (!responseCommitted) {
                             try {
                                 if (erroredNewUIMessages.length > 0) {
-                                    erroredNewModelMessages = await toModelMessages(erroredNewUIMessages.map((m) => stripProviderMetadata(m)));
+                                    /**
+                                     * Built in order from the recorded forms rather than by
+                                     * converting the UI list, so a steer appears in the delta as
+                                     * the model received it (what `prepare` produced), matching the
+                                     * lane. The wire message and partial are converted as before.
+                                     */
+                                    const steerModelById = new Map(reconciledSteer.map((e) => [e.ui.id, e.model]));
+                                    for (const m of erroredNewUIMessages) {
+                                        const recorded = steerModelById.get(m.id);
+                                        if (recorded)
+                                            erroredNewModelMessages.push(...recorded);
+                                        else
+                                            erroredNewModelMessages.push(...(await toModelMessages([stripProviderMetadata(m)])));
+                                    }
                                 }
                                 if (erroredUIMessagesWithPartial !== accumulatedUIMessages) {
                                     if (partialIdx === -1) {
@@ -5677,7 +6331,14 @@ function chatAgent(options) {
                                         accumulatedMessages.push(...(await toModelMessages(appended.map((m) => stripProviderMetadata(m)))));
                                     }
                                     else {
-                                        accumulatedMessages = await toModelMessages(erroredUIMessagesWithPartial);
+                                        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;
                                     locals.set(chatCurrentUIMessagesKey, accumulatedUIMessages);
@@ -5686,7 +6347,7 @@ function chatAgent(options) {
                             catch {
                                 erroredNewModelMessages = [];
                                 erroredUIMessagesWithPartial = erroredUIMessages;
-                                erroredNewUIMessages = erroredWireMessage ? [erroredWireMessage] : [];
+                                erroredNewUIMessages = buildErroredNew().filter((m) => m !== partialResponse);
                             }
                         }
                         if (onTurnComplete) {
@@ -5740,13 +6401,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) {
@@ -5756,8 +6418,15 @@ function chatAgent(options) {
                                 });
                             }
                         }
+                        if (locals.get(chatCloseRequestedKey)) {
+                            await performChatClose();
+                            return;
+                        }
                         // chat.requestUpgrade() / chat.endRun() — exit after error turn too
                         if (locals.get(chatUpgradeRequestedKey) || locals.get(chatEndRunRequestedKey)) {
+                            if (locals.get(chatUpgradeRequestedKey)) {
+                                await persistUpgradeHandoff();
+                            }
                             return;
                         }
                         // Drain remaining recovered turns before idling — a thrown
@@ -5780,6 +6449,12 @@ function chatAgent(options) {
                             return; // Timed out — end run gracefully
                         }
                         currentWirePayload = next.output;
+                        // Same close check the success path makes. Without it a close
+                        // record that lands after a failed turn is consumed as if it were
+                        // a turn payload, and the loop runs on against a closed session.
+                        if (currentWirePayload.trigger === "close") {
+                            return;
+                        }
                         // Continue to next iteration of the for loop
                     }
                     finally {
@@ -5788,6 +6463,11 @@ function chatAgent(options) {
                 }
             }
             finally {
+                // Safety net for a close requested on a path that exits without
+                // reaching one of the loop's close checks (a turn timeout, an OOM
+                // re-throw). `performChatClose` is idempotent, so the ordinary path
+                // having already run it costs nothing here.
+                await performChatClose();
                 // `stopSub` is registered post-preload so the close-during-preload
                 // early-return path may exit before it ever attached. Guard the
                 // cleanup so a missing subscription doesn't throw.
@@ -6125,15 +6805,22 @@ function isStopped() {
 // Version upgrade
 // ---------------------------------------------------------------------------
 /**
- * Request that the current run exits so the next message starts on the latest
- * deployed version (via the standard continuation mechanism).
+ * Hand the conversation over to another deployment.
+ *
+ * The handover happens immediately and server-side: a successor run is created
+ * and picks the conversation up from `session.in`. The transport keeps reading
+ * the same session output, so no client action is needed and nothing waits for
+ * the next message.
+ *
+ * Without a target the session's pin is cleared, so the successor lands on the
+ * latest deployed version; with `externalDeploymentId` the session is re-pinned
+ * to that deployment.
  *
  * When called from `onTurnStart` or `onValidateMessages`, `run()` is skipped
- * entirely — the run exits immediately and the transport re-triggers the
- * same message on the new version.
+ * entirely and the successor answers the message that opened the turn.
  *
  * When called from `run()` or `chat.defer()`, the current turn completes
- * normally and the run exits afterward instead of waiting for the next message.
+ * normally and the handover happens afterward.
  *
  * Call from `onTurnStart`, `onValidateMessages`, `onChatResume`, `run()`,
  * or inside `chat.defer()`.
@@ -6153,8 +6840,37 @@ function isStopped() {
  * });
  * ```
  */
-function requestUpgrade() {
+function requestUpgrade(options) {
     locals.set(chatUpgradeRequestedKey, true);
+    // Without a target the handoff clears the session's pin; with one it re-pins to that deployment.
+    const target = options?.externalDeploymentId?.trim();
+    if (target)
+        locals.set(chatUpgradeExternalDeploymentIdKey, target);
+}
+/** @internal Requests a handoff when the session's pin no longer names this deployment. */
+async function followSessionPin(chatId, policy) {
+    if (!chatId) {
+        return;
+    }
+    const deployedExternalId = locals.get(chatAgentRunContextKey)?.deployment?.externalId;
+    if (policy !== "hold" && !deployedExternalId) {
+        logger.debug("chat.versionSkew: cannot follow the session pin", {
+            chatId,
+            reason: "the run context carries no deployment.externalId",
+        });
+    }
+    const target = await resolvePinToFollow({
+        policy,
+        deployedExternalId,
+        upgradeAlreadyRequested: locals.get(chatUpgradeRequestedKey) === true,
+        readPin: async () => (await sessions.retrieve(chatId, { retry: { maxAttempts: 2, randomize: true } }))
+            .triggerConfig,
+    });
+    if (!target) {
+        return;
+    }
+    logger.info("chat.versionSkew: following the session pin", { chatId, target });
+    requestUpgrade({ externalDeploymentId: target });
 }
 /**
  * Hand off the current custom agent Session to a fresh run.
@@ -6193,20 +6909,31 @@ async function endAndContinue() {
     if ((locals.get(chatActiveSessionIteratorsKey) ?? 0) > 0) {
         throw new Error("chat.endAndContinue() cannot be called while a chat.createSession() iterator is active. Close the iterator, then call chat.endAndContinue().");
     }
-    await performEndAndContinue();
+    await performEndAndContinue({ reason: "continuation" });
 }
 /** @internal Shared server handoff used by managed and custom agent loops. */
-async function performEndAndContinue() {
+async function performEndAndContinue(options) {
     const chatId = locals.get(chatExternalIdKey);
     const callingRunId = locals.get(chatAgentRunContextKey)?.run.id;
     if (!chatId || !callingRunId) {
         throw new Error("Cannot end and continue without an active chat agent run");
     }
+    const externalDeploymentId = options.externalDeploymentId;
     const apiClient = apiClientManager.clientOrThrow();
-    await apiClient.endAndContinueSession(chatId, {
+    const result = await apiClient.endAndContinueSession(chatId, {
         callingRunId,
-        reason: "upgrade",
+        reason: options.reason,
+        ...(externalDeploymentId ? { externalDeploymentId } : {}),
     });
+    if (result?.pendingVersion !== true) {
+        return;
+    }
+    // The successor parked. Say so on `.out` while this run still can — the transport's
+    // subscription survives the swap, so the client learns without waiting for its next send.
+    const [error] = await tryCatch(getChatSession().out.writeControl(TRIGGER_CONTROL_SUBTYPE.PENDING_VERSION));
+    if (error) {
+        logger.warn("could not signal a parked handoff", { chatId, error });
+    }
 }
 /**
  * Exit the run after the current turn completes, without waiting for the
@@ -6237,6 +6964,124 @@ async function performEndAndContinue() {
 function endRun() {
     locals.set(chatEndRunRequestedKey, true);
 }
+/**
+ * End the whole conversation, permanently. The session row is closed, further
+ * appends are refused, and the run exits without scheduling a continuation.
+ *
+ * This is the session-level stop. {@link endRun} ends the current run and lets
+ * the next message start a fresh one; `chat.close()` ends the session itself,
+ * so there is no next message. Use it for a budget cap, a completed goal,
+ * abuse detection, or a user signing out.
+ *
+ * In a `chat.agent`, call it from `run()`, `prepareStep`, or
+ * `onBeforeTurnComplete`. Called mid-step, it aborts the in-flight
+ * `streamText` the same way the stop signal does, so the partial response is
+ * still captured and streamed. The turn then completes normally, a terminal
+ * `session-closed` record carrying `reason` is written to the response stream,
+ * and the loop exits.
+ *
+ * Prefer `onBeforeTurnComplete` over `onTurnComplete`. It carries the same
+ * fields but still runs while the stream is open, so the closed state rides
+ * out on the turn's final record. `onTurnComplete` runs after that record, so
+ * a close decided there does not reach a reader that has already finished the
+ * turn, and the user only finds out when their next message is refused.
+ *
+ * In a `chat.customAgent`, call it anywhere in your own loop. The close is
+ * performed when `run()` returns, so it lands whether you break out of a
+ * `chat.createSession` loop, return early, or hand-roll the loop entirely.
+ *
+ * Closing is one-way: a closed session cannot be reopened. Its transcript
+ * stays readable.
+ *
+ * @example
+ * ```ts
+ * chat.agent({
+ *   id: "budgeted-agent",
+ *   onBeforeTurnComplete: async ({ usage }) => {
+ *     if (await overBudget(usage)) {
+ *       chat.close({ reason: "Monthly budget reached" });
+ *     }
+ *   },
+ * });
+ * ```
+ */
+function close(options) {
+    if (!locals.get(chatExternalIdKey)) {
+        throw new Error("chat.close() can only be called from inside a chat.agent() or chat.customAgent() run");
+    }
+    // Bound the reason once, here. It goes out on S2 record headers as well as
+    // the close API, and an oversized value would fail the turn-complete write
+    // that carries the turn boundary, costing the client far more than the
+    // reason text.
+    // Trailing high surrogate: the cut landed between the two halves of an
+    // astral character, and encoding the orphan to UTF-8 for a record header
+    // yields a replacement character. Drop it rather than ship mojibake.
+    const reason = options?.reason
+        ?.slice(0, CHAT_CLOSE_REASON_MAX_LENGTH)
+        .replace(/[\uD800-\uDBFF]$/, "");
+    locals.set(chatCloseRequestedKey, reason ? { reason } : {});
+    // Mid-step call: unblock the in-flight streamText exactly like the stop
+    // signal, so the turn can reach its turn boundary instead of running the
+    // model out to completion after the decision to close has been made.
+    locals.get(chatStopControllerKey)?.abort(reason ?? "closed");
+}
+/**
+ * @internal Terminal close sequence, run once at whichever exit site observes
+ * the close request. Writes the standalone `session-closed` record, then closes
+ * the session row.
+ *
+ * The record lands after the turn's `turn-complete`, so a client reading that
+ * turn's stream has already terminated on it and will not see this one. It is
+ * there for a reconnect and for replay. What a live client reads is the
+ * `session-closed` header stamped onto `turn-complete` itself by
+ * `writeTurnCompleteChunk`, which fires whenever the close was decided before
+ * the turn ended. A close decided from `onTurnComplete` is past that point, so
+ * the client learns from the 409 on its next send.
+ */
+async function performChatClose() {
+    const request = locals.get(chatCloseRequestedKey);
+    if (!request || locals.get(chatClosePerformedKey))
+        return;
+    const reason = request.reason;
+    // Two flags, not one. The record is a client-visible event and must not be
+    // written twice, but the row close is the part that actually ends the
+    // conversation: flagging it as done before it succeeds would let a transient
+    // failure leave the session open with no later call willing to retry.
+    if (!locals.get(chatCloseRecordWrittenKey)) {
+        locals.set(chatCloseRecordWrittenKey, true);
+        try {
+            const session = getChatSession();
+            await session.out.writeControl(TRIGGER_CONTROL_SUBTYPE.SESSION_CLOSED, reason ? [[SESSION_CLOSED_REASON_HEADER, reason]] : undefined);
+        }
+        catch (error) {
+            logger.warn("chat.close: failed to write the session-closed record", {
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    const chatId = locals.get(chatExternalIdKey);
+    if (!chatId)
+        return;
+    try {
+        await sessions.close(chatId, {
+            ...(reason ? { reason } : {}),
+            ...(locals.get(chatAgentRunContextKey)?.run.id
+                ? { callingRunId: locals.get(chatAgentRunContextKey).run.id }
+                : {}),
+        });
+        locals.set(chatClosePerformedKey, true);
+    }
+    catch (error) {
+        // Deliberately NOT flagged as performed: the close API is idempotent, so a
+        // later exit site on this run gets to retry it. Losing every retry to a
+        // transient failure would leave the row open and the conversation alive.
+        // Non-fatal either way — the run still exits.
+        logger.error("chat.close: failed to close the session", {
+            chatId,
+            error: error instanceof Error ? error.message : String(error),
+        });
+    }
+}
 // ---------------------------------------------------------------------------
 // Per-turn deferred work
 // ---------------------------------------------------------------------------
@@ -6298,9 +7143,18 @@ function chatDefer(promiseOrFn) {
  * ```
  */
 function injectBackgroundContext(messages) {
-    const queue = locals.get(chatBackgroundQueueKey) ?? [];
-    queue.push(...messages);
-    locals.set(chatBackgroundQueueKey, queue);
+    const systemBlocks = messages.filter((message) => message.role === "system");
+    const conversational = messages.filter((message) => message.role !== "system");
+    if (systemBlocks.length > 0) {
+        const instructions = locals.get(chatInjectedInstructionsKey) ?? [];
+        instructions.push(...systemBlocks);
+        locals.set(chatInjectedInstructionsKey, instructions);
+    }
+    if (conversational.length > 0) {
+        const queue = locals.get(chatBackgroundQueueKey) ?? [];
+        queue.push(...conversational);
+        locals.set(chatBackgroundQueueKey, queue);
+    }
 }
 // ---------------------------------------------------------------------------
 // Aborted message cleanup
@@ -6713,10 +7567,12 @@ class ChatMessageAccumulator {
         // a duplicate, mirroring the chat.agent accumulator.
         const existingIdx = this.uiMessages.findIndex((m) => m.id === response.id);
         if (existingIdx !== -1) {
+            const previous = this.uiMessages[existingIdx];
             this.uiMessages[existingIdx] = response;
             try {
-                // Reconvert all model messages since we replaced rather than appended.
-                this.modelMessages = await toModelMessages(this.uiMessages.map((m) => stripProviderMetadata(m)));
+                if (!(await replaceModelRun(this.modelMessages, previous, response, 0))) {
+                    this.modelMessages = await toModelMessages(this.uiMessages.map((m) => stripProviderMetadata(m)));
+                }
             }
             catch {
                 // Conversion failed — leave the existing model messages in place
@@ -6752,6 +7608,28 @@ class ChatMessageAccumulator {
         const modelMsgs = await toModelMessages([message]);
         this._steeringQueue.push({ uiMessage: message, modelMessages: modelMsgs });
     }
+    /**
+     * Record the messages a steering drain consumed.
+     *
+     * The drain only puts them in this step's prompt, so without this they
+     * shape one answer and then exist in neither lane: not in `uiMessages`,
+     * which is what an app persists from, and not in `modelMessages`, which is
+     * what every later turn sends.
+     *
+     * Both lanes are appended to. The model lane is never reconverted from the
+     * UI lane, because `compactIfNeeded` replaces it with a summary and leaves
+     * the UI lane whole: a reconversion would restore everything the summary
+     * replaced.
+     */
+    async absorbSteering(claimed, injected) {
+        const fresh = claimed.filter((m) => !this.uiMessages.some((e) => e.id === m.id));
+        if (fresh.length === 0)
+            return;
+        this.uiMessages.push(...fresh);
+        // Record what the model received. Only when the whole batch is new is
+        // `injected` known to describe exactly these messages.
+        this.modelMessages.push(...(injected && fresh.length === claimed.length ? injected : await toModelMessages(fresh)));
+    }
     /**
      * Get and clear unconsumed steering messages.
      */
@@ -6784,7 +7662,8 @@ class ChatMessageAccumulator {
             }
             // 2. Pending message injection
             if (pm && queue.length > 0) {
-                const injected = await drainSteeringQueue(pm, resultMessages ?? messages, steps, queue);
+                const { injected, claimed } = await drainSteeringQueue(pm, resultMessages ?? messages, steps, queue);
+                await this.absorbSteering(claimed, injected);
                 if (injected.length > 0) {
                     resultMessages = [...(resultMessages ?? messages), ...injected];
                 }
@@ -6973,7 +7852,7 @@ function trackActiveChatSessionIterator(iterator) {
  * ```
  */
 function createChatSession(payload, options) {
-    const { signal: runSignal, idleTimeoutInSeconds: sessionIdleTimeoutOpt, timeout = "1h", maxTurns = 100, compaction: sessionCompaction, pendingMessages: sessionPendingMessages, } = options;
+    const { signal: runSignal, idleTimeoutInSeconds: sessionIdleTimeoutOpt, timeout = "1h", maxTurns = 100, compaction: sessionCompaction, pendingMessages: sessionPendingMessages, versionSkew: sessionVersionSkew, } = options;
     const idleTimeoutInSeconds = sessionIdleTimeoutOpt ?? 30;
     return {
         [Symbol.asyncIterator]() {
@@ -7062,8 +7941,16 @@ function createChatSession(payload, options) {
                      * without suspending.
                      */
                     if (turn > 0) {
+                        if (locals.get(chatCloseRequestedKey)) {
+                            await performChatClose();
+                            stop.cleanup();
+                            return { done: true, value: undefined };
+                        }
                         // chat.requestUpgrade() / chat.endRun() — exit before waiting
                         if (locals.get(chatUpgradeRequestedKey) || locals.get(chatEndRunRequestedKey)) {
+                            if (locals.get(chatUpgradeRequestedKey)) {
+                                await persistUpgradeHandoff();
+                            }
                             stop.cleanup();
                             return { done: true, value: undefined };
                         }
@@ -7166,6 +8053,7 @@ function createChatSession(payload, options) {
                         }
                         accumulator.applyHandover(pendingHandoverSignal);
                     }
+                    await followSessionPin(currentPayload.chatId, sessionVersionSkew);
                     // chat.requestUpgrade() called before this turn — signal transport and exit
                     if (locals.get(chatUpgradeRequestedKey)) {
                         await writeUpgradeRequiredChunk();
@@ -7382,7 +8270,8 @@ function createChatSession(payload, options) {
                                     }
                                 }
                                 if (sessionPendingMessages) {
-                                    const injected = await drainSteeringQueue(sessionPendingMessages, resultMessages ?? stepMsgs, steps, turnSteeringQueue);
+                                    const { injected, claimed } = await drainSteeringQueue(sessionPendingMessages, resultMessages ?? stepMsgs, steps, turnSteeringQueue);
+                                    await accumulator.absorbSteering(claimed, injected);
                                     if (injected.length > 0) {
                                         resultMessages = [...(resultMessages ?? stepMsgs), ...injected];
                                     }
@@ -7396,6 +8285,11 @@ function createChatSession(payload, options) {
                 async return() {
                     activeMsgSub?.off();
                     activeMsgSub = undefined;
+                    // Reached when the consumer leaves the `for await` early (`break`,
+                    // `return`, a throw). A `chat.close()` from the loop body would
+                    // otherwise be dropped: the exit that performs it lives in `next()`,
+                    // and `next()` is never called again.
+                    await performChatClose();
                     // `stop` only exists once next() has booted the iterator.
                     stop?.cleanup();
                     return { done: true, value: undefined };
@@ -7652,6 +8546,11 @@ function createChatStartSessionAction(taskId, options) {
         const maxAttempts = params.triggerConfig?.maxAttempts ?? options?.triggerConfig?.maxAttempts;
         const maxDuration = params.triggerConfig?.maxDuration ?? options?.triggerConfig?.maxDuration;
         const idleTimeoutInSeconds = params.triggerConfig?.idleTimeoutInSeconds ?? options?.triggerConfig?.idleTimeoutInSeconds;
+        // Only `undefined` means "not supplied": a per-call `null` (opt out) has to beat a pinning
+        // action default, which neither truthiness nor `??` would allow.
+        const externalDeploymentId = params.triggerConfig?.externalDeploymentId !== undefined
+            ? params.triggerConfig.externalDeploymentId
+            : options?.triggerConfig?.externalDeploymentId;
         const triggerConfig = {
             basePayload: {
                 messages: [],
@@ -7678,6 +8577,10 @@ function createChatStartSessionAction(taskId, options) {
                     lockToVersion: params.triggerConfig?.lockToVersion ?? options?.triggerConfig?.lockToVersion,
                 }
                 : {}),
+            ...(params.triggerConfig?.ttl !== undefined || options?.triggerConfig?.ttl !== undefined
+                ? { ttl: params.triggerConfig?.ttl ?? options?.triggerConfig?.ttl }
+                : {}),
+            ...(externalDeploymentId !== undefined ? { externalDeploymentId } : {}),
             ...(idleTimeoutInSeconds !== undefined ? { idleTimeoutInSeconds } : {}),
         };
         const startBody = {
@@ -7722,6 +8625,7 @@ function createChatStartSessionAction(taskId, options) {
             publicAccessToken,
             runId: created.runId,
             sessionId: created.id,
+            ...(created.pendingVersion ? { pendingVersion: true } : {}),
         };
     };
 }
@@ -7755,7 +8659,8 @@ async function callSessionsCreateWithOverride(args) {
     const init = {
         method: "POST",
         headers: overrideRequestHeaders(accessToken),
-        body: JSON.stringify(args.body),
+        // This path bypasses `sessions.start`, so it resolves the pin itself.
+        body: JSON.stringify(withResolvedExternalDeploymentId(args.body)),
     };
     const response = args.fetchOverride
         ? await args.fetchOverride(url, init, ctx)
@@ -7820,6 +8725,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,
@@ -7831,8 +8771,12 @@ 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}. */
+    turn: chatTurn,
     /** Create a per-run typed local. See {@link chatLocal}. */
     local: chatLocal,
     /** Create a public access token for a chat task. See {@link createChatAccessToken}. */
@@ -7853,6 +8797,8 @@ export const chat = {
     endAndContinue,
     /** Exit the run after the current turn completes, without any upgrade signal. See {@link endRun}. */
     endRun,
+    /** End the conversation permanently: close the session and exit the run. See {@link close}. */
+    close,
     /** Clean up aborted parts from a UIMessage. See {@link cleanupAbortedParts}. */
     cleanupAbortedParts,
     /** Register background work that runs in parallel with streaming. See {@link chatDefer}. */
@@ -8000,6 +8946,16 @@ async function writeTurnCompleteChunk(_chatId, publicAccessToken) {
     if (consumedCursor !== undefined) {
         extraHeaders.push([SESSION_IN_CONSUMED_ID_HEADER, String(consumedCursor)]);
     }
+    // A close decided before this turn ended rides out on turn-complete. Readers
+    // terminate their stream on turn-complete, so a standalone record written
+    // after it only reaches a reconnect — this header is what a live client sees.
+    const pendingClose = locals.get(chatCloseRequestedKey);
+    if (pendingClose) {
+        extraHeaders.push([SESSION_CLOSED_HEADER, "true"]);
+        if (pendingClose.reason) {
+            extraHeaders.push([SESSION_CLOSED_REASON_HEADER, pendingClose.reason]);
+        }
+    }
     const result = await session.out.writeControl(TRIGGER_CONTROL_SUBTYPE.TURN_COMPLETE, extraHeaders);
     const T_N = result.lastEventId ? Number.parseInt(result.lastEventId, 10) : undefined;
     // 2. Trim back to the previous turn-complete, if we have one. Skipping on
@@ -8057,12 +9013,47 @@ async function writeTurnCompleteChunk(_chatId, publicAccessToken) {
  *
  * @internal
  */
+/**
+ * Persists an upgrade requested after the turn has already run.
+ *
+ * The pre-turn sites reach {@link performEndAndContinue} through
+ * {@link writeUpgradeRequiredChunk}, which is what clears (or re-points) the
+ * session's stored `externalDeploymentId`. The post-turn exits had no such path,
+ * so a `chat.requestUpgrade()` from `run()` or `chat.defer()` left the pin intact
+ * and every continuation re-pinned to the deployment the agent asked to leave.
+ *
+ * No `upgrade-required` chunk is written here: the turn already produced its
+ * answer, so there is nothing for a client to be told about.
+ */
+async function persistUpgradeHandoff() {
+    const chatId = locals.get(chatExternalIdKey);
+    const callingRunId = locals.get(chatAgentRunContextKey)?.run.id;
+    if (!chatId || !callingRunId) {
+        return;
+    }
+    try {
+        await performEndAndContinue({
+            reason: "upgrade",
+            externalDeploymentId: locals.get(chatUpgradeExternalDeploymentIdKey),
+        });
+    }
+    catch (error) {
+        logger.warn("upgrade handoff failed; session keeps its current version pin", {
+            chatId,
+            callingRunId,
+            error,
+        });
+    }
+}
 async function writeUpgradeRequiredChunk() {
     const chatId = locals.get(chatExternalIdKey);
     const callingRunId = locals.get(chatAgentRunContextKey)?.run.id;
     if (chatId && callingRunId) {
         try {
-            await performEndAndContinue();
+            await performEndAndContinue({
+                reason: "upgrade",
+                externalDeploymentId: locals.get(chatUpgradeExternalDeploymentIdKey),
+            });
         }
         catch (error) {
             // Non-fatal: the next `.in/append` re-triggers via the probe.