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

package/dist/esm/v3/transcriptStorage.d.ts

@@ -0,0 +1,229 @@
+import { type TaskRunContext, type TranscriptSnapshotEntry } from "@trigger.dev/core/v3";
+import type { ModelMessage, UIMessage } from "ai";
+/**
+ * One change to a transcript. Ops address messages by id; position is the
+ * storage's own concern.
+ *
+ * - `put` upserts by `message.id`: an unknown id appends, a known id is
+ *   replaced in place. `final` is false when the runtime captured a partial
+ *   assistant message from an errored or stopped turn; it defaults to true.
+ * - `remove` deletes by id and is a no-op for an unknown id.
+ * - `truncateAfter` drops every message ordered after `afterId` (a rollback)
+ *   and is a no-op when `afterId` is unknown.
+ * - `state` replaces the opaque runtime record; `null` clears it.
+ */
+export type TranscriptChange = {
+    op: "put";
+    message: UIMessage;
+    final?: boolean;
+} | {
+    op: "remove";
+    id: string;
+} | {
+    op: "truncateAfter";
+    afterId: string;
+} | {
+    op: "state";
+    value: unknown | null;
+};
+export type TranscriptChangeReason = "turn-complete" | "turn-error" | "action" | "compaction" | "recovery";
+export type TranscriptCursors = {
+    lastOutEventId?: string;
+    lastInEventId?: string;
+};
+/**
+ * What the runtime hands to `save`: the ordered changes since the last save
+ * (one transaction where the backend supports it), the whole transcript as
+ * it stands after those changes, and the stream cursors the next boot should
+ * resume from. A row-per-message store applies `changes`; a store that keeps
+ * the conversation as one document writes `transcript` as-is and needs no
+ * state of its own. Cursors are runtime-computed and persisted opaquely; a
+ * storage never interprets them.
+ */
+export type TranscriptChangeset = {
+    reason: TranscriptChangeReason;
+    changes: TranscriptChange[];
+    transcript: TranscriptState;
+    cursors?: TranscriptCursors;
+};
+/** The tenant scope of a read. A render read has no run, so this is all `load` gets. */
+export type TranscriptScope<TClientData = unknown> = {
+    chatId: string;
+    clientData: TClientData;
+};
+/** The run context of a write. Supplied by the runtime; always in-run. */
+export type TranscriptStorageContext<TClientData = unknown> = TranscriptScope<TClientData> & {
+    turn: number;
+    trigger: "submit-message" | "regenerate-message" | "action";
+    runId: string;
+    ctx: TaskRunContext;
+};
+export type TranscriptLoadOptions = {
+    /** Return at most this many messages, the most recent ones. */
+    limit?: number;
+    /** Return messages ordered before this message id (a `nextCursor` from a previous page). */
+    before?: string;
+};
+export type TranscriptLoadResult<TUIMessage extends UIMessage = UIMessage> = {
+    messages: TUIMessage[];
+    state: unknown | null;
+    cursors?: TranscriptCursors;
+    /** The id to pass as `before` for the previous page; absent on the last page. */
+    nextCursor?: string;
+    /**
+     * Ids among `messages` that were saved with `final: false` (a partial
+     * answer). A storage that keeps `final` returns them so a partial stays
+     * partial when a continuation saves it again unchanged; a storage that
+     * does not keep `final` may leave this out.
+     */
+    nonFinalIds?: string[];
+};
+/** What `loadContext` receives on every turn and action. */
+export type LoadContextEvent<TClientData = unknown, TUIMessage extends UIMessage = UIMessage> = {
+    chatId: string;
+    /** The turn number (0-indexed). */
+    turn: number;
+    trigger: "submit-message" | "regenerate-message" | "action";
+    /** The messages the frontend sent for this turn. Empty for actions. */
+    incomingMessages: TUIMessage[];
+    /** The runtime's transcript before this turn, including any tail it recovered. */
+    previousMessages: TUIMessage[];
+    clientData?: TClientData;
+    continuation: boolean;
+    previousRunId?: string;
+};
+/**
+ * A persistence adapter for a `chat.agent` transcript. The runtime calls
+ * `load` once at a continuation boot and `save` after every change to the
+ * conversation. Both are best-effort from the runtime's point of view: an
+ * error is logged and the turn continues.
+ *
+ * `loadContext` is optional. Its presence declares that the application
+ * owns the model's context: the runtime calls it on every turn and action
+ * and uses what it returns as the conversation, instead of the transcript
+ * it accumulated. Tail recovery still runs and `save` is still called.
+ */
+export type TranscriptStorage<TClientData = unknown> = {
+    load<TUIMessage extends UIMessage = UIMessage>(scope: TranscriptScope<TClientData>, opts?: TranscriptLoadOptions): Promise<TranscriptLoadResult<TUIMessage>>;
+    save(ctx: TranscriptStorageContext<TClientData>, changeset: TranscriptChangeset): Promise<void>;
+    loadContext?<TUIMessage extends UIMessage = UIMessage>(scope: TranscriptScope<TClientData>, event: LoadContextEvent<TClientData, TUIMessage>): Promise<TUIMessage[]> | TUIMessage[];
+};
+/** An in-memory transcript: ordered entries plus the opaque state record. */
+export type TranscriptState<TUIMessage extends UIMessage = UIMessage> = {
+    entries: TranscriptSnapshotEntry<TUIMessage>[];
+    state: unknown | null;
+};
+export declare function emptyTranscriptState<TUIMessage extends UIMessage = UIMessage>(): TranscriptState<TUIMessage>;
+/**
+ * Apply changes to a transcript, in order. Pure: returns a new state and
+ * never mutates the input. Replaying the same changes converges, which is
+ * what lets a storage retry a failed write without checking what landed.
+ */
+export declare function reduceTranscriptChanges<TUIMessage extends UIMessage = UIMessage>(prev: TranscriptState<TUIMessage>, changes: readonly TranscriptChange[]): TranscriptState<TUIMessage>;
+/**
+ * What the runtime remembers about the transcript it last handed to
+ * `save`: the ids in order and a fingerprint per message, so the next
+ * changeset can be derived from the accumulator without asking the storage.
+ */
+export type TranscriptShadow = {
+    ids: string[];
+    fingerprints: Map<string, string>;
+    /** Ids last saved with `final: false`. Everything else was saved final. */
+    nonFinal: Set<string>;
+};
+/**
+ * Build the shadow for `messages`. An id is non-final when this save says so
+ * (`nonFinalIds`) or when it was non-final before and its content has not
+ * changed: a partial answer stays partial until the message itself changes.
+ */
+export declare function createTranscriptShadow(messages: readonly UIMessage[], nonFinalIds?: ReadonlySet<string>, previous?: TranscriptShadow): TranscriptShadow;
+/**
+ * Derive the changes that take `shadow` to `next`.
+ *
+ * The common prefix (by id) is compared message by message and a changed
+ * message becomes an in-place `put`. Past the prefix, everything the shadow
+ * still had is dropped with one `truncateAfter` on the last common id (or
+ * one `remove` per message when there is no common prefix) and everything
+ * `next` has is appended with `put`, in order. Applying the result with
+ * {@link reduceTranscriptChanges} reproduces `next` exactly, including
+ * order, for any two lists.
+ */
+export declare function diffTranscript(shadow: TranscriptShadow, next: readonly UIMessage[], options?: {
+    nonFinalIds?: ReadonlySet<string>;
+}): {
+    changes: TranscriptChange[];
+    shadow: TranscriptShadow;
+};
+/**
+ * The built-in storage: the whole transcript as one versioned blob in the
+ * platform's object store, the same blob the Sessions dashboard renders.
+ *
+ * Stateless. Every changeset carries the whole transcript as it stands after
+ * the changes, so `save` serialises that and rewrites the blob: one PUT per
+ * turn, no read and nothing kept in memory between saves.
+ */
+export declare function snapshotTranscriptStorage(): TranscriptStorage<unknown>;
+/** The storage `chat.agent` uses when none is configured: {@link snapshotTranscriptStorage}. */
+export declare const defaultStorage: TranscriptStorage<unknown>;
+export type MemoryTranscriptStorage = TranscriptStorage<unknown> & {
+    /** The stored transcript for a chat, or `undefined` when nothing has been saved. */
+    transcript(chatId: string): (TranscriptState & {
+        cursors?: TranscriptCursors;
+    }) | undefined;
+    /** Every changeset `save` received, in order. */
+    readonly changesets: Array<{
+        ctx: TranscriptStorageContext<unknown>;
+        changeset: TranscriptChangeset;
+    }>;
+};
+/**
+ * A storage that keeps every transcript in process memory. The reference
+ * implementation for the conformance tests, and a way to inspect exactly
+ * what the runtime hands a storage.
+ */
+export declare function memoryTranscriptStorage(): MemoryTranscriptStorage;
+type ModelLaneInjection = {
+    afterId: string;
+    messages: ModelMessage[];
+};
+/**
+ * What the runtime keeps in the storage's `state` slot: the parts of the
+ * model's context that cannot be rebuilt from the transcript. Opaque to a
+ * storage; only the runtime reads it.
+ *
+ * `compaction` is the whole model lane after a compaction, valid for the
+ * transcript prefix ending at `throughId` whose fingerprint matches, so a
+ * rollback or edit of that prefix makes it unusable and the next save
+ * clears it. `injections` are conversational messages `chat.inject` added,
+ * anchored after the transcript message they followed.
+ */
+export type TranscriptRuntimeState = {
+    v: 1;
+    compaction?: {
+        modelMessages: ModelMessage[];
+        throughId: string;
+        fingerprint: string;
+    };
+    injections?: ModelLaneInjection[];
+    /** `chat.inject` messages queued but not yet drained into a turn when the save happened. */
+    queued?: ModelMessage[];
+};
+export declare function parseTranscriptRuntimeState(value: unknown): TranscriptRuntimeState | undefined;
+/**
+ * A 32-bit FNV-1a hash over the fingerprints of the messages up to and
+ * including `throughId`, in order. Cheap enough to compute on every save
+ * because the per-message fingerprints already exist in the shadow.
+ */
+export declare function prefixFingerprint(shadow: TranscriptShadow, throughId: string): string;
+/**
+ * Rebuild the model lane for a transcript at boot. Uses the persisted
+ * compacted lane when the transcript prefix it covers is unchanged, then
+ * converts the rest of the transcript, re-inserting persisted injections
+ * after the messages they followed.
+ */
+export declare function restoreModelLane<TUIMessage extends UIMessage>(messages: TUIMessage[], state: TranscriptRuntimeState | undefined, convert: (messages: TUIMessage[]) => Promise<ModelMessage[]>): Promise<{
+    messages: ModelMessage[];
+    compacted: boolean;
+    injections: ModelLaneInjection[];
+}>;
+export {};

package/dist/esm/v3/transcriptStorage.js

@@ -0,0 +1,309 @@
+import { apiClientManager, pageTranscriptEntries, } from "@trigger.dev/core/v3";
+import { readChatSnapshot, writeChatSnapshot } from "./chatSnapshotIo.js";
+export function emptyTranscriptState() {
+    return { entries: [], state: null };
+}
+/**
+ * Apply changes to a transcript, in order. Pure: returns a new state and
+ * never mutates the input. Replaying the same changes converges, which is
+ * what lets a storage retry a failed write without checking what landed.
+ */
+export function reduceTranscriptChanges(prev, changes) {
+    let entries = prev.entries.slice();
+    let state = prev.state;
+    for (const change of changes) {
+        switch (change.op) {
+            case "put": {
+                const message = change.message;
+                const entry = { id: message.id, final: change.final ?? true, message };
+                const idx = entries.findIndex((e) => e.id === message.id);
+                if (idx === -1)
+                    entries.push(entry);
+                else
+                    entries[idx] = entry;
+                break;
+            }
+            case "remove": {
+                entries = entries.filter((e) => e.id !== change.id);
+                break;
+            }
+            case "truncateAfter": {
+                const idx = entries.findIndex((e) => e.id === change.afterId);
+                if (idx !== -1)
+                    entries = entries.slice(0, idx + 1);
+                break;
+            }
+            case "state": {
+                state = change.value ?? null;
+                break;
+            }
+        }
+    }
+    return { entries, state };
+}
+function fingerprintMessage(message) {
+    return JSON.stringify(message);
+}
+/**
+ * Build the shadow for `messages`. An id is non-final when this save says so
+ * (`nonFinalIds`) or when it was non-final before and its content has not
+ * changed: a partial answer stays partial until the message itself changes.
+ */
+export function createTranscriptShadow(messages, nonFinalIds, previous) {
+    const ids = [];
+    const fingerprints = new Map();
+    const nonFinal = new Set();
+    for (const message of messages) {
+        const fingerprint = fingerprintMessage(message);
+        ids.push(message.id);
+        fingerprints.set(message.id, fingerprint);
+        if (nonFinalIds?.has(message.id) ||
+            (previous?.nonFinal.has(message.id) && previous.fingerprints.get(message.id) === fingerprint)) {
+            nonFinal.add(message.id);
+        }
+    }
+    return { ids, fingerprints, nonFinal };
+}
+/**
+ * Derive the changes that take `shadow` to `next`.
+ *
+ * The common prefix (by id) is compared message by message and a changed
+ * message becomes an in-place `put`. Past the prefix, everything the shadow
+ * still had is dropped with one `truncateAfter` on the last common id (or
+ * one `remove` per message when there is no common prefix) and everything
+ * `next` has is appended with `put`, in order. Applying the result with
+ * {@link reduceTranscriptChanges} reproduces `next` exactly, including
+ * order, for any two lists.
+ */
+export function diffTranscript(shadow, next, options = {}) {
+    const nextShadow = createTranscriptShadow(next, options.nonFinalIds, shadow);
+    const changes = [];
+    const put = (message) => {
+        const final = nextShadow.nonFinal.has(message.id) ? false : undefined;
+        changes.push(final === undefined ? { op: "put", message } : { op: "put", message, final });
+    };
+    let lcp = 0;
+    while (lcp < shadow.ids.length && lcp < next.length && shadow.ids[lcp] === next[lcp].id) {
+        lcp++;
+    }
+    for (let i = 0; i < lcp; i++) {
+        const message = next[i];
+        if (shadow.fingerprints.get(message.id) !== nextShadow.fingerprints.get(message.id) ||
+            shadow.nonFinal.has(message.id) !== nextShadow.nonFinal.has(message.id)) {
+            put(message);
+        }
+    }
+    if (shadow.ids.length > lcp) {
+        if (lcp > 0) {
+            changes.push({ op: "truncateAfter", afterId: shadow.ids[lcp - 1] });
+        }
+        else {
+            for (const id of shadow.ids)
+                changes.push({ op: "remove", id });
+        }
+    }
+    for (let i = lcp; i < next.length; i++) {
+        put(next[i]);
+    }
+    return { changes, shadow: nextShadow };
+}
+/**
+ * The built-in storage: the whole transcript as one versioned blob in the
+ * platform's object store, the same blob the Sessions dashboard renders.
+ *
+ * Stateless. Every changeset carries the whole transcript as it stands after
+ * the changes, so `save` serialises that and rewrites the blob: one PUT per
+ * turn, no read and nothing kept in memory between saves.
+ */
+export function snapshotTranscriptStorage() {
+    return {
+        async load(scope, opts) {
+            if (opts?.limit !== undefined || opts?.before !== undefined) {
+                const page = await readTranscriptPage(scope.chatId, opts);
+                if (page)
+                    return page;
+            }
+            const snapshot = await readChatSnapshot(scope.chatId);
+            const full = snapshot
+                ? { entries: snapshot.messages, state: snapshot.state }
+                : emptyTranscriptState();
+            return {
+                ...pageEntries(full.entries, opts),
+                state: full.state,
+                cursors: snapshot
+                    ? { lastOutEventId: snapshot.lastOutEventId, lastInEventId: snapshot.lastInEventId }
+                    : undefined,
+            };
+        },
+        async save(ctx, changeset) {
+            await writeChatSnapshot(ctx.chatId, {
+                version: 2,
+                savedAt: Date.now(),
+                messages: changeset.transcript.entries,
+                state: changeset.transcript.state,
+                lastOutEventId: changeset.cursors?.lastOutEventId,
+                lastInEventId: changeset.cursors?.lastInEventId,
+            });
+        },
+    };
+}
+/**
+ * A page of the platform transcript read server-side, for a render read with
+ * `limit`/`before` from an app server holding a secret key. `undefined` when
+ * the call is not possible from here (a run's public token cannot use the
+ * endpoint), so the caller falls back to reading the whole blob.
+ */
+async function readTranscriptPage(chatId, opts) {
+    try {
+        const page = await apiClientManager.clientOrThrow().getSessionTranscript(chatId, opts);
+        return {
+            messages: page.messages,
+            state: page.state ?? null,
+            cursors: page.cursors,
+            nextCursor: page.nextCursor,
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The storage `chat.agent` uses when none is configured: {@link snapshotTranscriptStorage}. */
+export const defaultStorage = snapshotTranscriptStorage();
+function pageEntries(all, opts) {
+    const page = pageTranscriptEntries(all, opts);
+    return {
+        messages: page.entries.map((e) => e.message),
+        nextCursor: page.nextCursor,
+        nonFinalIds: page.entries.filter((e) => !e.final).map((e) => e.id),
+    };
+}
+/**
+ * A storage that keeps every transcript in process memory. The reference
+ * implementation for the conformance tests, and a way to inspect exactly
+ * what the runtime hands a storage.
+ */
+export function memoryTranscriptStorage() {
+    const transcripts = new Map();
+    const changesets = [];
+    return {
+        changesets,
+        transcript(chatId) {
+            return transcripts.get(chatId);
+        },
+        async load(scope, opts) {
+            const stored = transcripts.get(scope.chatId);
+            if (!stored)
+                return { messages: [], state: null, cursors: undefined, nextCursor: undefined };
+            return {
+                ...pageEntries(stored.entries, opts),
+                state: stored.state,
+                cursors: stored.cursors,
+            };
+        },
+        async save(ctx, changeset) {
+            changesets.push({ ctx, changeset });
+            const prev = transcripts.get(ctx.chatId);
+            const next = reduceTranscriptChanges(prev ?? emptyTranscriptState(), changeset.changes);
+            transcripts.set(ctx.chatId, { ...next, cursors: changeset.cursors ?? prev?.cursors });
+        },
+    };
+}
+export function parseTranscriptRuntimeState(value) {
+    if (!value || typeof value !== "object")
+        return undefined;
+    const record = value;
+    if (record.v !== 1)
+        return undefined;
+    const out = { v: 1 };
+    const compaction = record.compaction;
+    if (compaction &&
+        typeof compaction === "object" &&
+        Array.isArray(compaction.modelMessages) &&
+        typeof compaction.throughId === "string" &&
+        typeof compaction.fingerprint === "string") {
+        out.compaction = {
+            modelMessages: compaction.modelMessages,
+            throughId: compaction.throughId,
+            fingerprint: compaction.fingerprint,
+        };
+    }
+    if (Array.isArray(record.injections)) {
+        out.injections = record.injections.flatMap((entry) => {
+            const inj = entry;
+            return inj && typeof inj.afterId === "string" && Array.isArray(inj.messages)
+                ? [{ afterId: inj.afterId, messages: inj.messages }]
+                : [];
+        });
+    }
+    if (Array.isArray(record.queued) && record.queued.length > 0) {
+        out.queued = record.queued;
+    }
+    return out;
+}
+/**
+ * A 32-bit FNV-1a hash over the fingerprints of the messages up to and
+ * including `throughId`, in order. Cheap enough to compute on every save
+ * because the per-message fingerprints already exist in the shadow.
+ */
+export function prefixFingerprint(shadow, throughId) {
+    let hash = 0x811c9dc5;
+    if (throughId === "")
+        return hash.toString(16).padStart(8, "0");
+    const mix = (s) => {
+        for (let i = 0; i < s.length; i++) {
+            hash ^= s.charCodeAt(i);
+            hash = Math.imul(hash, 0x01000193) >>> 0;
+        }
+    };
+    for (const id of shadow.ids) {
+        mix(id);
+        mix("");
+        mix(shadow.fingerprints.get(id) ?? "");
+        mix("
");
+        if (id === throughId)
+            return hash.toString(16).padStart(8, "0");
+    }
+    return "";
+}
+/**
+ * Rebuild the model lane for a transcript at boot. Uses the persisted
+ * compacted lane when the transcript prefix it covers is unchanged, then
+ * converts the rest of the transcript, re-inserting persisted injections
+ * after the messages they followed.
+ */
+export async function restoreModelLane(messages, state, convert) {
+    const lane = [];
+    let start = 0;
+    let compacted = false;
+    if (state?.compaction) {
+        const throughId = state.compaction.throughId;
+        const idx = throughId === "" ? -1 : messages.findIndex((m) => m.id === throughId);
+        if ((idx !== -1 || throughId === "") &&
+            prefixFingerprint(createTranscriptShadow(messages), throughId) ===
+                state.compaction.fingerprint) {
+            lane.push(...state.compaction.modelMessages);
+            start = idx + 1;
+            compacted = true;
+        }
+    }
+    const anchored = (state?.injections ?? [])
+        .map((inj) => ({
+        inj,
+        idx: inj.afterId === "" ? -1 : messages.findIndex((m) => m.id === inj.afterId),
+    }))
+        .filter(({ inj, idx }) => (inj.afterId === "" ? start === 0 : idx >= start))
+        .sort((a, b) => a.idx - b.idx);
+    let cursor = start;
+    for (const { inj, idx } of anchored) {
+        if (idx + 1 > cursor) {
+            lane.push(...(await convert(messages.slice(cursor, idx + 1))));
+            cursor = idx + 1;
+        }
+        lane.push(...inj.messages);
+    }
+    if (cursor < messages.length) {
+        lane.push(...(await convert(messages.slice(cursor))));
+    }
+    return { messages: lane, compacted, injections: anchored.map(({ inj }) => inj) };
+}
+//# sourceMappingURL=transcriptStorage.js.map

package/dist/esm/v3/transcriptStorage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transcriptStorage.js","sourceRoot":"","sources":["../../../src/v3/transcriptStorage.ts"],"names":[],"mappings":"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"}

package/dist/esm/version.js

@@ -1,2 +1,2 @@
-export const VERSION = "0.0.0-prerelease-20260908122921";
+export const VERSION = "0.0.0-prerelease-20260909071038";
 //# sourceMappingURL=version.js.map

package/docs/ai-chat/actions.mdx

@@ -83,9 +83,9 @@ onAction: async ({ action }) => {
 
 An action that returns nothing does not fire `onTurnComplete`, and that is where an app that owns its own transcript normally writes. What that means depends on which persistence model you use.
 
-**Platform-managed** (no `hydrateMessages`): nothing to do. After an action that changed the conversation, the runtime writes the snapshot, so the edit survives the run ending. An action that returns `chat.turn()` is followed by a turn, which persists its answer the way every turn does.
+**Transcript storage** (the default, or your own `storage`): nothing to do. After an action that changed the conversation, the runtime hands the storage a changeset with `reason: "action"`. An undo is one `truncateAfter`; a regenerate is a `truncateAfter` followed by the new answer's `put` when the turn completes; an edit is a `put` for the edited id. The changeset carries the same resume cursors as the last turn. See [Transcript storage](/ai-chat/transcript-storage#what-the-runtime-saves). An action that returns `chat.turn()` is followed by a turn, which persists its answer the way every turn does.
 
-**Your own store** (`hydrateMessages` registered): the runtime deliberately does not write, because your store is the source of truth. A history edit lives only in the running worker until you persist it, and a continuation rehydrates from your store, not from what the worker had in memory. Mirror each edit in your store, not only additions: a regenerate is a delete *and* an insert. The answer that follows `chat.turn()` reaches your store through `onTurnComplete`, like any turn's answer.
+**Your own store through the deprecated `hydrateMessages`**: the runtime deliberately does not write, because your store is the source of truth. A history edit lives only in the running worker until you persist it, and a continuation rehydrates from your store, not from what the worker had in memory. Mirror each edit in your store, not only additions: a regenerate is a delete *and* an insert. The answer that follows `chat.turn()` reaches your store through `onTurnComplete`, like any turn's answer.
 
 ```ts
 onAction: async ({ action, chatId }) => {

package/docs/ai-chat/background-injection.mdx

@@ -250,6 +250,8 @@ chat.inject(messages: ModelMessage[]): void
 
 Queue model messages for injection at the next opportunity. Messages persist across the idle wait between turns, and are not reset when a new turn starts.
 
+Lifetime: a conversational message (`role: "user"` or `"assistant"`) becomes part of the model's context from the next turn onward, for the rest of the conversation. It is written to the [transcript storage](/ai-chat/transcript-storage)'s `state`, anchored to the message it followed, so it survives a continuation run and comes back in the same place. It does not appear in the UI transcript. A history edit that rebuilds the context drops it. This holds however the message reached the model: drained before `run()` or at a step boundary inside a multi-step turn. A message that is still queued when the run ends (injected from the last `onTurnComplete` before an exit, for example) is carried in the storage's `state` too and is queued again when the next run boots, so it reaches the next turn. A `role: "system"` message is appended to the instructions for the next turn only and is consumed once. Injecting the same notice every turn adds a copy every turn; dedupe on your side.
+
 **Parameters:**
 
 | Parameter | Type | Description |

package/docs/ai-chat/compaction.mdx

@@ -61,6 +61,8 @@ After each turn completes:
 
 On the next turn, the LLM receives the compact summary instead of the full history — dramatically reducing token usage while preserving context.
 
+The compacted context is durable. The runtime writes it to the [transcript storage](/ai-chat/transcript-storage)'s `state` alongside the messages, so a new run that boots to continue the conversation starts from the summary rather than re-reading the whole transcript and summarising it again. An undo or edit that reaches into the summarised part of the conversation clears the stored summary, and compaction runs again from the edited history when the threshold is next crossed.
+
 <Note>
   This is Trigger.dev's provider-agnostic compaction. To persist a **provider's own** compaction across turns instead (Anthropic context editing or OpenAI stored responses), and to fall back between providers without re-sending history, see [Native compaction & provider fallback](/ai-chat/patterns/native-compaction).
 </Note>

package/docs/ai-chat/frontend.mdx

@@ -137,6 +137,8 @@ On page load, fetch both the messages and the session state from your database,
 
 Because the underlying Session row outlives individual runs, a chat you were in yesterday resumes against the same chat — even if the original run has long since exited. The transport hydrates from the persisted state and uses `lastEventId` to resubscribe; if the client tries to send a new message and no run is alive, the server triggers a fresh continuation run on the same session before the message is appended.
 
+If you do not keep your own copy of the conversation, load it from the agent's [transcript storage](/ai-chat/transcript-storage#reading-the-transcript) instead: `chat.createLoadTranscriptAction(storage)` on the server and `useLoadTranscript(chatId, action, { transport })` in the browser return the messages and seed the transport's resume cursor, for the default storage and your own alike.
+
 ```tsx app/chat/[chatId]/ChatPage.tsx
 "use client";
 

package/docs/ai-chat/lifecycle-hooks.mdx

@@ -86,7 +86,7 @@ export const myChat = chat.agent({
 
 Fires once on a continuation boot when the dead predecessor was mid-stream — a partial assistant survives on `session.out`. The runtime reconstructs context automatically via a smart default; this hook is the override path for policies that need something different.
 
-The hook does NOT fire when there's no partial — clean continuations after `chat.endRun()` or `chat.requestUpgrade()`, fresh chats, OOM retries on top of a complete snapshot. Those paths dispatch any in-flight user message as a normal turn on the new run without involving the hook. It also does NOT fire when [`hydrateMessages`](#hydratemessages) is registered (the customer owns persistence).
+The hook does NOT fire when there's no partial — clean continuations after `chat.endRun()` or `chat.requestUpgrade()`, fresh chats, OOM retries on top of a complete snapshot. Those paths dispatch any in-flight user message as a normal turn on the new run without involving the hook. It fires regardless of whether [`hydrateMessages`](#hydratemessages) or a [transcript storage](/ai-chat/transcript-storage) is registered: crash recovery is runtime-owned for every agent.
 
 ```ts
 export const myChat = chat.agent({
@@ -260,6 +260,10 @@ export const myChat = chat.agent({
 
 ## hydrateMessages
 
+<Warning>
+  `hydrateMessages` is deprecated. Give the agent a [transcript storage](/ai-chat/transcript-storage) instead: `loadContext` on the storage decides the model's context, and `save` persists every change, so crash recovery and durable compaction cover it. Existing agents keep working with a one-time warning. Setting `hydrateMessages` together with `storage` is an error.
+</Warning>
+
 Load the full message history from your backend on every turn, replacing the built-in linear accumulator. When set, the hook's return value becomes the accumulated state; the normal accumulation logic (append for submit, replace for regenerate) is skipped entirely.
 
 Use this when the backend should be the source of truth for message history: abuse prevention, branching conversations (DAGs), or rollback/undo support.
@@ -315,7 +319,7 @@ After the hook returns, the runtime overlays the wire's tool-state advances (`ou
 </Note>
 
 <Tip>
-  Registering `hydrateMessages` short-circuits the runtime's [snapshot + replay](/ai-chat/patterns/persistence-and-replay) reconstruction at run boot — your hook is the single source of truth for history, so the runtime skips reading or writing the snapshot entirely. No object storage traffic, no replay cost. The trade-off is that you own persistence end-to-end.
+  Registering `hydrateMessages` turns off the runtime's transcript reads and writes: your hook is the source of truth for history, and the runtime does not read or write its [snapshot](/ai-chat/patterns/persistence-and-replay). Crash recovery still runs. When a new run boots, the dead run's unfinished answer and unacknowledged messages are replayed from the session streams, `onRecoveryBoot` fires, and the hook receives the recovered tail in `previousMessages`. Persisting that tail is yours to do; a [transcript storage](/ai-chat/transcript-storage) does it for you.
 </Tip>
 
 <Note>