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

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

@@ -0,0 +1,224 @@
+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, covering the
+ * transcript prefix ending at `throughId`. It is used as long as `throughId`
+ * still exists in the transcript, so a rollback or truncation that removes it
+ * rebuilds the lane from the transcript instead. Editing a message before
+ * `throughId` in place is unsupported and does not invalidate the lane.
+ * `injections` are conversational messages `chat.inject` added, anchored
+ * after the transcript message they followed.
+ */
+export type TranscriptRuntimeState = {
+    v: 1;
+    compaction?: {
+        modelMessages: ModelMessage[];
+        throughId: 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;
+/**
+ * Rebuild the model lane for a transcript at boot. Uses the persisted
+ * compacted lane while the transcript still contains its `throughId`
+ * boundary, 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,280 @@
+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") {
+        out.compaction = {
+            modelMessages: compaction.modelMessages,
+            throughId: compaction.throughId,
+        };
+    }
+    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;
+}
+/**
+ * Rebuild the model lane for a transcript at boot. Uses the persisted
+ * compacted lane while the transcript still contains its `throughId`
+ * boundary, 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 === "") {
+            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-streamfix-20260909094302";
+export const VERSION = "0.0.0-prerelease-20260909121655";
 //# sourceMappingURL=version.js.map

package/docs/ai-chat/actions.mdx

@@ -1,7 +1,7 @@
 ---
 title: "Actions"
 sidebarTitle: "Actions"
-description: "Custom commands sent from the frontend that mutate chat state without consuming a turn — undo, rollback, edit, regenerate."
+description: "Custom commands sent from the frontend that mutate chat state without consuming a turn: undo, rollback, edit, regenerate."
 ---
 
 ## Overview
@@ -44,7 +44,7 @@ export const myChat = chat.agent({
     // returning void → side-effect-only, no model call
   },
 
-  run: async ({ messages, signal }) => {
+  run: async ({ messages, signal, streamText }) => {
     return streamText({ model: anthropic("claude-sonnet-4-5"), messages, abortSignal: signal });
   },
 });
@@ -52,36 +52,68 @@ export const myChat = chat.agent({
 
 **Lifecycle flow:** Wake → parse action against `actionSchema` → `hydrateMessages` (if set) → **`onAction`** → apply `chat.history` mutations → emit `trigger:turn-complete` → wait for next message.
 
-## Returning a model response from an action
+When `onAction` returns `chat.turn()`, the flow continues instead of emitting `trigger:turn-complete`: the edit is snapshotted, then a turn runs on the edited history with `trigger: "action-turn"`, so `onTurnStart`, `run()`, `onBeforeTurnComplete` and `onTurnComplete` all fire and the answer is persisted like any turn's. See [Answering after an action](#answering-after-an-action).
 
-`onAction` can return a `StreamTextResult`, `string`, or `UIMessage` to produce a response. The returned stream is auto-piped to the frontend just like a normal turn, but the rest of the turn machinery (`onTurnStart`, `onTurnComplete`, etc.) still does not fire.
+## Answering after an action
+
+An action is a state edit. To answer after the edit, return `chat.turn()`: the edit is applied and snapshotted, then a turn runs on the edited history exactly as a message turn does. `onTurnStart`, `run()`, `onBeforeTurnComplete` and `onTurnComplete` fire, the turn counter advances, and the answer gets everything a turn has: the agent's system prompt and tools, steering, compaction, injected instructions and persistence.
 
 ```ts
-onAction: async ({ action, messages }) => {
-  if (action.type === "regenerate") {
-    chat.history.slice(0, -1); // drop the last assistant
-    return streamText({
-      model: anthropic("claude-sonnet-4-5"),
-      messages,
-      stopWhen: stepCountIs(15),
-    });
+onAction: async ({ action }) => {
+  switch (action.type) {
+    case "undo":
+      chat.history.slice(0, -2);
+      return; // edit only, no turn
+
+    case "regenerate":
+      chat.history.slice(0, -1);
+      return chat.turn(); // answer the edited history
+
+    case "retry-formal":
+      chat.history.slice(0, -1);
+      chat.inject([{ role: "system", content: "Answer formally this time." }]);
+      return chat.turn(); // with a one-shot instruction
   }
-  // other actions return void → side-effect only
 }
 ```
 
-This is useful for actions that both mutate state and want a fresh model response (regenerate-from-here, retry-with-different-style). Persistence is your responsibility inside `onAction` itself; you have access to the streamed response object.
+`run()` receives the edited history with no incoming user message, the same shape as a `regenerate-message` turn, and its `trigger` is `"action-turn"`, so a `run()` that returns early on `"action"` (the pre-May behaviour, when actions invoked `run()` directly) still answers. Returning anything other than `chat.turn()` or nothing is an error; a response can no longer be returned from `onAction` directly.
+
+### Actions and persistence
+
+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.
+
+**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 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 }) => {
+  if (action.type === "undo") {
+    chat.history.slice(0, -2);
+    await db.deleteLastExchange(chatId); // the rollback is yours to persist
+  }
+  if (action.type === "regenerate") {
+    chat.history.slice(0, -1);
+    await db.deleteLastAssistant(chatId); // the delete half
+    return chat.turn(); // the insert half arrives in onTurnComplete
+  }
+},
+onTurnComplete: async ({ chatId, newUIMessages }) => {
+  await db.saveMessages(chatId, newUIMessages);
+},
+```
 
 ## Gating actions on HITL state
 
 If you have a [human-in-the-loop](/ai-chat/patterns/human-in-the-loop) tool waiting on `addToolOutput`, you usually want to refuse competing actions like `regenerate` until the answer arrives. [`chat.history.getPendingToolCalls()`](/ai-chat/backend#chat-history) gives you exactly that signal:
 
 ```ts
-onAction: async ({ action, messages, signal }) => {
+onAction: async ({ action }) => {
   if (action.type === "regenerate") {
     if (chat.history.getPendingToolCalls().length > 0) return; // gated
     chat.history.slice(0, -1);
-    return streamText({ model: anthropic("claude-sonnet-4-5"), messages, abortSignal: signal });
+    return chat.turn();
   }
 },
 ```
@@ -89,10 +121,10 @@ onAction: async ({ action, messages, signal }) => {
 ## Sending actions from the frontend
 
 ```ts
-// Browser — TriggerChatTransport
+// Browser: TriggerChatTransport
 const stream = await transport.sendAction(chatId, { type: "undo" });
 
-// Server — AgentChat
+// Server: AgentChat
 const stream = await agentChat.sendAction({ type: "rollback", targetMessageId: "msg-3" });
 ```
 
@@ -104,8 +136,8 @@ The action payload is validated against `actionSchema` on the backend; invalid a
 
 ## See also
 
-- [`chat.history`](/ai-chat/backend#chat-history) — the imperative API actions use to mutate state
-- [Sending actions from the frontend](/ai-chat/frontend#sending-actions) — `transport.sendAction` ergonomics
-- [`hydrateMessages`](/ai-chat/lifecycle-hooks#hydratemessages) — fires before `onAction` when set
-- [Branching conversations](/ai-chat/patterns/branching-conversations) — pairs action handlers with backend-controlled history
-- [Human-in-the-loop](/ai-chat/patterns/human-in-the-loop) — gating fresh actions while a tool is waiting
+- [`chat.history`](/ai-chat/backend#chat-history): the imperative API actions use to mutate state
+- [Sending actions from the frontend](/ai-chat/frontend#sending-actions): sending actions through `useChat` so a turn that follows one renders like any turn
+- [`hydrateMessages`](/ai-chat/lifecycle-hooks#hydratemessages): fires before `onAction` when set
+- [Branching conversations](/ai-chat/patterns/branching-conversations): pairs action handlers with backend-controlled history
+- [Human-in-the-loop](/ai-chat/patterns/human-in-the-loop): gating fresh actions while a tool is waiting