@trigger.dev/sdk 4.5.15 → 4.6.0

package/dist/esm/v3/transcriptStorage.js

@@ -0,0 +1,360 @@
+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 };
+}
+/**
+ * The content identity the transcript shadow compares messages by. @internal
+ */
+export 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 };
+}
+/**
+ * Roughly how many messages the snapshot keeps once a conversation has
+ * compacted. Raising it costs bytes on every save; lowering it shortens how far
+ * back a conversation can be rendered from the platform's own store.
+ */
+const SNAPSHOT_KEEP_MESSAGES = 100;
+/**
+ * The built-in storage: the transcript in the platform's object store, read by
+ * the Sessions dashboard and the transcript API.
+ *
+ * One object per conversation, rewritten each turn, holding the transcript plus
+ * the runtime state. Once a conversation has been compacted, it keeps roughly
+ * the last hundred messages rather than all of them, so the object stops
+ * growing with the conversation. An app that needs the full history keeps its
+ * own transcript storage.
+ */
+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) {
+            const entries = trimTranscriptForSnapshot(changeset.transcript.entries, changeset.transcript.state, { keep: SNAPSHOT_KEEP_MESSAGES });
+            await writeChatSnapshot(ctx.chatId, {
+                version: 2,
+                savedAt: Date.now(),
+                messages: entries,
+                state: normalizeRuntimeStateForWindow(changeset.transcript.state, entries.map((entry) => entry.id)),
+                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.
+ *
+ * Carries no runtime `state`: the endpoint serves the transcript only, so a
+ * paged result always reports `state: null`. The model lane is restored from
+ * the whole-blob read instead, which is reachable only with private auth.
+ */
+async function readTranscriptPage(chatId, opts) {
+    try {
+        const page = await apiClientManager.clientOrThrow().getSessionTranscript(chatId, opts);
+        return {
+            messages: page.messages,
+            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 });
+        },
+    };
+}
+/**
+ * The slice of a transcript worth storing, which is the last `keep` messages
+ * once a conversation has compacted, and all of it before that.
+ *
+ * Expressed relative to the compaction watermark rather than as a plain tail,
+ * because everything after the watermark is live context that the next boot
+ * converts and must never be dropped. The runtime stamps the watermark at the
+ * newest message on each compacted save, so in practice the two coincide and
+ * this keeps the last `keep`; the watermark-relative form is what keeps it
+ * correct if a watermark ever lands earlier in the transcript.
+ *
+ * Without a watermark nothing is dropped: every entry is still context.
+ *
+ * This is what stops the object rewritten each turn from growing with the
+ * conversation. An app that needs the whole history keeps its own transcript
+ * storage.
+ */
+export function trimTranscriptForSnapshot(entries, state, opts) {
+    const throughId = parseTranscriptRuntimeState(state)?.compaction?.throughId;
+    if (throughId === undefined || throughId === "")
+        return entries;
+    const idx = entries.findIndex((entry) => entry.id === throughId);
+    if (idx === -1)
+        return entries;
+    // Keep the watermark entry itself, so a restored lane can still find it.
+    const start = Math.max(0, idx + 1 - Math.max(1, opts.keep));
+    return start === 0 ? entries : entries.slice(start);
+}
+/**
+ * Rewrite runtime state so it still describes the transcript window being
+ * persisted.
+ *
+ * A compaction watermark that has moved out of the window becomes `""`, which
+ * is how a restored lane says "the compacted messages cover everything before
+ * this window". Left as-is, the watermark would name an entry the window does
+ * not contain, and restoring the lane would discard the compacted messages and
+ * re-convert the window from scratch — an agent that has silently forgotten the
+ * conversation. Injections anchored outside the window go too: the span they
+ * belonged to is already inside the compacted lane.
+ */
+export function normalizeRuntimeStateForWindow(state, windowIds) {
+    const runtimeState = parseTranscriptRuntimeState(state);
+    if (!runtimeState)
+        return state;
+    const ids = new Set(windowIds);
+    const compaction = runtimeState.compaction;
+    const watermarkOutside = compaction !== undefined && compaction.throughId !== "" && !ids.has(compaction.throughId);
+    const injections = runtimeState.injections?.filter((injection) => injection.afterId === "" || ids.has(injection.afterId));
+    if (!watermarkOutside && injections?.length === runtimeState.injections?.length) {
+        return state;
+    }
+    return {
+        ...runtimeState,
+        ...(compaction
+            ? {
+                compaction: {
+                    modelMessages: compaction.modelMessages,
+                    throughId: watermarkOutside ? "" : compaction.throughId,
+                },
+            }
+            : {}),
+        ...(injections ? { injections } : {}),
+    };
+}
+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 = "4.5.15";
+export const VERSION = "4.6.0";
 //# 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

package/docs/ai-chat/anatomy.mdx

@@ -1,10 +1,10 @@
 ---
 title: "Anatomy of an agent"
 sidebarTitle: "Anatomy"
-description: "The moving parts of a chat agent — the agent task, the session, the frontend transport — and which page covers each."
+description: "The three parts of a chat agent — the agent task that runs the turn loop, the durable session that carries messages, and the frontend transport — what each does and where it's documented."
 ---
 
-**A chat agent is three parts: a long-lived agent task that runs the turn loop, a durable Session carrying messages in and the response stream out, and a frontend transport that plugs the session into `useChat`.** The pages in this section each own one part of that picture. This page is the map — if you'd rather read mechanics end to end, skip to [How it works](/ai-chat/how-it-works).
+**A chat agent is three parts: an agent task that runs the turn loop, a durable session that carries messages in and streams the response out, and a frontend transport that connects the session to `useChat`.** This page is your map of the Building agents section — what each part does, how a single message flows through them, and which page to open next.
 
 ```mermaid
 flowchart LR
@@ -14,31 +14,57 @@ flowchart LR
   OUT -- "streamed response" --> FE
 ```
 
-Everything below maps onto one annotated agent:
+## Follow one message
+
+A single turn moves through all three parts in order:
+
+1. The **frontend transport** sends the user's message to the session's inbound stream (`.in`).
+2. The **agent task** wakes on the new message, runs your turn loop, and streams the model's response into the session's outbound stream (`.out`).
+3. The **frontend transport** reads `.out` and renders tokens into `useChat` as they arrive.
+
+The session sits in the middle so both sides never have to be online at the same moment — the task keeps writing to `.out` even if the browser reloads mid-stream.
+
+## The three parts
+
+### The agent task
+
+`chat.agent()` is the code you write: a long-lived agent whose `run` function is the turn loop. Messages arrive accumulated, you call `streamText`, and the returned stream is piped back to the frontend for you. [Tools](/ai-chat/tools) the model can call and [lifecycle hooks](/ai-chat/lifecycle-hooks) that fire around each turn both hang off the same config. See [Backend](/ai-chat/backend) for the full `chat.agent()` surface.
+
+### The session
+
+The conversation lives in a [session](/ai-chat/sessions), not in the task's memory: a pair of durable streams — `.in` and `.out` — keyed on your `chatId`. Because the session is durable, a conversation survives page refreshes, deploys, and the run boundaries between turns. The task can restart and pick up the same session. [How it works](/ai-chat/how-it-works) covers the mechanics of what survives and why.
+
+### The frontend transport
+
+One hook — `useTriggerChatTransport` — connects the Vercel AI SDK's `useChat` to the agent's session. There are no API routes to write: the transport talks to the session directly using a scoped token. See [Frontend](/ai-chat/frontend) for wiring, tokens, and starting sessions.
+
+## An annotated agent
+
+Everything above maps onto one task:
 
 ```ts trigger/my-agent.ts
 import { chat } from "@trigger.dev/sdk/ai";
-import { streamText, stepCountIs } from "ai";
+import { stepCountIs } from "ai";
 import { anthropic } from "@ai-sdk/anthropic";
 
 export const myAgent = chat.agent({
   id: "my-agent",
 
-  // Tools declared on the config survive history re-conversion
-  // across turns — see Tools.
+  // Tools the model can call, declared on the config so they
+  // survive history re-conversion across turns — see Tools.
   tools: { searchDocs },
 
-  // Hooks fire around each turn: validation, persistence,
-  // post-turn work — see Lifecycle hooks.
+  // A lifecycle hook: fires after each turn, here to persist
+  // the response — see Lifecycle hooks.
   onTurnComplete: async ({ responseMessage }) => {
     await db.messages.save(responseMessage);
   },
 
-  // The turn loop. Messages arrive accumulated; you stream back.
-  // Options, levels, and alternatives — see Backend.
-  run: async ({ messages, tools, signal }) =>
+  // The turn loop. Messages arrive accumulated; the returned
+  // stream is piped back to the frontend — see Backend.
+  run: async ({ messages, tools, signal, streamText }) =>
     streamText({
-      ...chat.toStreamTextOptions({ tools }),
+      tools,
       model: anthropic("claude-sonnet-4-5"),
       messages,
       abortSignal: signal,
@@ -47,21 +73,15 @@ export const myAgent = chat.agent({
 });
 ```
 
-The frontend side is one hook — `useTriggerChatTransport` connects `useChat` to the agent's session, no API routes ([Frontend](/ai-chat/frontend)). Underneath, the conversation lives on a [Session](/ai-chat/sessions): a pair of durable streams keyed on your `chatId` that survives refreshes, deploys, and run boundaries.
+## Related pages
 
-## Where each part is covered
+Beyond the three core parts:
 
-| Part                                                  | Page                                           |
-| ----------------------------------------------------- | ---------------------------------------------- |
-| `chat.agent()` options, the turn loop, piping         | [Backend](/ai-chat/backend)                    |
-| Hooks around each turn (`onTurnComplete`, hydration)  | [Lifecycle hooks](/ai-chat/lifecycle-hooks)    |
-| Declaring tools, typed payloads, `toModelOutput`      | [Tools](/ai-chat/tools)                        |
-| `useChat` wiring, tokens, starting sessions           | [Frontend](/ai-chat/frontend)                  |
-| Driving a chat from your server instead of a browser  | [Server-side chat](/ai-chat/server-chat)       |
-| The durable substrate under every agent               | [Sessions](/ai-chat/sessions)                  |
-| Per-run typed state inside the loop                   | [chat.local](/ai-chat/chat-local)              |
-| Type-safe payloads, client data, and messages         | [Types](/ai-chat/types)                        |
-| Building without the managed lifecycle                | [Custom agents](/ai-chat/custom-agents)        |
-| End-to-end mechanics: what survives a refresh and why | [How it works](/ai-chat/how-it-works)          |
+| Page                                        | What it covers                                          |
+| ------------------------------------------- | ------------------------------------------------------- |
+| [Server-side chat](/ai-chat/server-chat)    | Driving a chat from your backend instead of a browser   |
+| [chat.local](/ai-chat/chat-local)           | Per-run typed state inside the turn loop                |
+| [Types](/ai-chat/types)                     | Type-safe payloads, client data, and messages           |
+| [Custom agents](/ai-chat/custom-agents)     | Building without the managed lifecycle                  |
 
-Beyond this section: [Features](/ai-chat/fast-starts) covers opt-in capabilities (Head Start, compaction, steering, actions), and [Patterns](/ai-chat/patterns/sub-agents) covers production recipes (sub-agents, HITL approvals, persistence, recovery).
+[Features](/ai-chat/fast-starts) covers opt-in capabilities (Head Start, compaction, steering, actions), and [Patterns](/ai-chat/patterns/sub-agents) covers production recipes (sub-agents, HITL approvals, persistence, recovery).