@trigger.dev/sdk 4.6.4 → 4.7.1

package/docs/ai-chat/patterns/human-in-the-loop.mdx

@@ -1,52 +1,49 @@
 ---
 title: "Human-in-the-loop"
 sidebarTitle: "Human-in-the-loop"
-description: "Pause the agent mid-response to ask the user a clarifying question, then resume with their answer."
+description: "Ask users to choose an option or approve a tool call, then continue the agent with their response."
 ---
 
-Some turns need to stop and ask the user something before they can finish — picking between options, confirming a destructive action, or clarifying an ambiguous request. The AI SDK calls this **human-in-the-loop** (HITL), and the building block is a tool with no `execute` function.
+**A chat agent can wait for a user to supply a tool result or approve a tool before it runs.** Choose the pattern based on what the user needs to provide:
 
-When the LLM calls a tool that has no `execute`, `streamText` ends with the tool call still pending. The turn completes cleanly, the frontend renders UI to collect the answer, and when the user responds, a new turn resumes with the answer merged into the same assistant message.
+| User interaction | Tool definition | Frontend response |
+| --- | --- | --- |
+| Answer a question or choose a candidate | Omit `execute` | `addToolOutput` supplies the result |
+| Approve or deny an action with known inputs | Set `needsApproval: true` and keep `execute` | `addToolApprovalResponse` authorizes or denies execution |
+
+The examples below use AI SDK 6 or later and build on the [Quick start](/ai-chat/quick-start), including its session and token server actions. For approve/deny buttons, see [Approve a tool before execution](#approve-a-tool-before-execution).
 
 ## How it works
 
-```
-Turn N:
-  User message → run()
-  LLM streams text → calls askUser tool (no execute)
-  streamText ends with tool-call in `input-available` state
-  onTurnComplete fires (finishReason = "tool-calls")
-  Agent suspends (compute freed) — maxDuration does not tick while paused
-
-Frontend:
-  Renders question + option buttons from tool input
-  User clicks → addToolOutput({ tool, toolCallId, output })
-  sendAutomaticallyWhen: lastAssistantMessageIsCompleteWithToolCalls
-  → sendMessage() fires next turn
-
-Turn N+1:
-  hydrateMessages / accumulator sees the updated assistant message
-  run() is called, LLM continues from the tool result
-  onTurnComplete fires (finishReason = "stop", responseMessage is the FULL merged message)
+When the model calls a tool without `execute`, `streamText` finishes with a pending tool call. Your frontend renders the question. Calling `addToolOutput` supplies the answer, and `sendAutomaticallyWhen` starts the next turn.
+
+```mermaid
+sequenceDiagram
+  participant Agent
+  participant UI as Your frontend
+  participant User
+  Agent->>UI: askUser tool call (input-available)
+  UI->>User: Show question and options
+  User->>UI: Choose an option
+  UI->>Agent: addToolOutput + automatic send
+  Agent->>UI: Continue with the answer
 ```
 
-The AI SDK's `toUIMessageStream` automatically reuses the assistant message ID across the pause (we pass `originalMessages` internally), so `responseMessage` in the post-resume `onTurnComplete` is the **full merged message** — the original text, the completed tool call, and any follow-up content — not just the new parts.
+The assistant message keeps its ID across the pause. After resuming, `onTurnComplete` receives the full merged `responseMessage`, including the question, tool result, and follow-up text.
 
 ## Duration and cost while paused
 
-A pause doesn't hold compute. After the model calls a no-execute tool, the turn finishes and the run stays warm for `idleTimeoutInSeconds` (default 30s), then **suspends** and frees its compute, the same way [`wait.for`](/wait-for) does. The user's `addToolOutput` wakes it back up.
-
-Because the run is suspended while it waits, the human's thinking time is not billed and does **not** count against [`maxDuration`](/runs/max-duration). `maxDuration` measures active CPU time and excludes suspended waitpoint time, exactly like `wait.for`, so a user can take minutes, hours, or days to answer without the run hitting `maxDuration`. The only time that counts is each turn's actual compute plus the short warm window before each suspend.
+After the turn finishes, the run stays active for `idleTimeoutInSeconds` (30 seconds by default), then suspends and releases compute. Set it to `0` to suspend immediately. The active idle window counts toward compute usage and [`maxDuration`](/runs/max-duration); suspended time doesn't.
 
-You don't need to raise `maxDuration` or end the run to support long human waits. How long a single suspended pause stays open is governed by the run's suspend timeout, not `maxDuration`; if a wait outlives it the run ends, and the next `addToolOutput` boots a fresh continuation that picks up the resolved tool result.
+[`turnTimeout`](/ai-chat/reference#chatagent) controls how long a run waits for the next message (default `"1h"`). When it expires, the run ends. A later answer starts a continuation run that restores the conversation from [transcript storage](/ai-chat/transcript-storage). Raising `maxDuration` isn't necessary for time spent suspended.
 
 ## Backend: define the tool
 
-A HITL tool has an `inputSchema` describing what the model can ask, but **no `execute` function**. When the LLM calls it, `streamText` returns control to your agent.
+Define an `inputSchema` for the question and omit `execute` so the frontend can supply the answer. When the model calls `askUser`, `streamText` returns control to your agent.
 
 ```ts trigger/my-chat.ts
-import { chat } from "@trigger.dev/sdk/ai";
-import { streamText, tool, stepCountIs } from "ai";
+import { chat, type InferChatUIMessageFromTools } from "@trigger.dev/sdk/ai";
+import { tool, stepCountIs } from "ai";
 import { anthropic } from "@ai-sdk/anthropic";
 import { z } from "zod";
 
@@ -67,14 +64,17 @@ const askUser = tool({
       .min(2)
       .max(4),
   }),
-  // No execute function — streamText ends, the frontend supplies the output
-  // via addToolOutput, and the next turn continues from the result.
+  outputSchema: z.object({ optionId: z.string(), label: z.string() }),
+  // The frontend supplies the result with addToolOutput.
 });
 
-export const myChat = chat.agent({
+const tools = { askUser };
+export type ChatMessage = InferChatUIMessageFromTools<typeof tools>;
+
+export const myChat = chat.withUIMessage<ChatMessage>().agent({
   id: "my-chat",
-  tools: { askUser },
-  run: async ({ messages, tools, signal }) => {
+  tools,
+  run: async ({ messages, tools, signal, streamText }) => {
     return streamText({
       model: anthropic("claude-sonnet-4-5"),
       messages,
@@ -90,190 +90,192 @@ Declaring `tools` on the config (and reading them back from the payload) is the
 
 ## Frontend: render the question and collect the answer
 
-Two pieces on the client:
+Render the question when its tool part reaches `input-available`. Use the AI SDK's [`lastAssistantMessageIsCompleteWithToolCalls`](https://ai-sdk.dev/docs/ai-sdk-ui/chatbot-tool-usage) helper to submit the answer automatically once every pending tool call has a result.
 
-1. **UI for the pending tool call** — render when the tool part is in `input-available` state, i.e. the LLM has called the tool but there's no output yet.
-2. **Auto-send on resolution** — use `sendAutomaticallyWhen: lastAssistantMessageIsCompleteWithToolCalls` so answering kicks off the next turn without the user having to hit "send."
+```tsx app/components/chat.tsx
+"use client";
 
-```tsx
-import { useChat, lastAssistantMessageIsCompleteWithToolCalls } from "@ai-sdk/react";
+import { useChat } from "@ai-sdk/react";
+import { lastAssistantMessageIsCompleteWithToolCalls } from "ai";
 import { useTriggerChatTransport } from "@trigger.dev/sdk/chat/react";
+import { mintChatAccessToken, startChatSession } from "@/app/actions";
+import type { ChatMessage, myChat } from "@/trigger/my-chat";
 
-function ChatView({ chatId }: { chatId: string }) {
-  const transport = useTriggerChatTransport({
+export function ChatView({ chatId }: { chatId: string }) {
+  const transport = useTriggerChatTransport<typeof myChat>({
     task: "my-chat",
     accessToken: ({ chatId }) => mintChatAccessToken(chatId),
     startSession: ({ chatId, clientData }) =>
       startChatSession({ chatId, clientData }),
   });
-  const { messages, sendMessage, addToolOutput } = useChat({
+  const { messages, sendMessage, addToolOutput, status } = useChat<ChatMessage>({
     id: chatId,
     transport,
     sendAutomaticallyWhen: lastAssistantMessageIsCompleteWithToolCalls,
   });
+  const busy = status === "submitted" || status === "streaming";
 
   return (
     <>
-      {messages.map((m) =>
-        m.parts.map((part, i) => {
-          if (part.type === "tool-askUser" && part.state === "input-available") {
-            return (
-              <AskUserCard
-                key={i}
-                question={part.input.question}
-                options={part.input.options}
-                onAnswer={(opt) =>
-                  addToolOutput({
-                    tool: "askUser",
-                    toolCallId: part.toolCallId,
-                    output: { optionId: opt.id, label: opt.label },
-                  })
-                }
-              />
-            );
-          }
-          if (part.type === "text") return <Markdown key={i}>{part.text}</Markdown>;
-          return null;
-        })
-      )}
+      {messages.map((message) => (
+        <div key={message.id}>
+          {message.parts.map((part, i) => {
+            if (part.type === "tool-askUser" && part.state === "input-available") {
+              return (
+                <fieldset key={part.toolCallId} disabled={busy}>
+                  <legend>{part.input.question}</legend>
+                  {part.input.options.map((option) => (
+                    <button
+                      key={option.id}
+                      type="button"
+                      onClick={() =>
+                        addToolOutput({
+                          tool: "askUser",
+                          toolCallId: part.toolCallId,
+                          output: { optionId: option.id, label: option.label },
+                        })
+                      }
+                    >
+                      {option.label}
+                      {option.description && <span> {option.description}</span>}
+                    </button>
+                  ))}
+                </fieldset>
+              );
+            }
+            if (part.type === "text") return <p key={i}>{part.text}</p>;
+            return null;
+          })}
+        </div>
+      ))}
+      <button disabled={busy} onClick={() => sendMessage({ text: "Help me choose a database." })}>
+        Start a conversation
+      </button>
     </>
   );
 }
 ```
 
-`addToolOutput` patches the assistant message locally with `state: "output-available"` and fills in `output`. `lastAssistantMessageIsCompleteWithToolCalls` detects that every pending tool call now has a result, and `useChat` fires a new `sendMessage` — the backend picks it up as the next turn.
+`addToolOutput` patches the assistant message locally with `state: "output-available"` and fills in `output`. `lastAssistantMessageIsCompleteWithToolCalls` detects that every pending tool call now has a result, and `useChat` fires a new `sendMessage`. The backend picks it up as the next turn.
 
-## Detecting a paused turn in `onTurnComplete`
+## Choose from tool results
 
-Two ways to detect "this turn paused for user input" vs "this turn finished normally":
+When a tool returns several candidates, run the search first, then ask the user to choose one before taking action. For example, a search might find several matching contacts, files, or brands.
 
-### Via `finishReason` (recommended)
+Keep the search, selection, and action as separate tool calls:
 
-The AI SDK's finish reason is surfaced on every `onTurnComplete` event. If the model stopped on tool calls, it's `"tool-calls"`:
+1. A search tool with `execute` returns candidates and saves them under a `searchId`.
+2. A selection tool without `execute` asks the frontend to show those candidates.
+3. An action tool with `execute` uses the selected ID after checking it on the server.
 
-```ts
-onTurnComplete: async ({ finishReason, responseMessage }) => {
-  if (finishReason === "tool-calls") {
-    // Turn paused — assistant message has pending tool call(s)
-    const pending = responseMessage?.parts.filter(
-      (p) => p.type.startsWith("tool-") && p.state === "input-available"
-    );
-    // Persist as a checkpoint / partial turn
-  } else {
-    // finishReason === "stop" — normal completion
-    // Persist as a completed turn
-  }
-};
+```ts trigger/tools/select-result.ts
+import { tool } from "ai";
+import { z } from "zod";
+
+export const selectResult = tool({
+  description:
+    "Ask the user to choose from a completed search. " +
+    "Copy searchId from the search result and wait for their answer.",
+  inputSchema: z.object({ searchId: z.string() }),
+  outputSchema: z.object({ selectedId: z.string().nullable() }),
+});
 ```
 
-<Note>
-  `finishReason` is only undefined for manual `chat.pipe()` flows or aborted streams. For the common `run() → return streamText(...)` pattern it's always populated.
-</Note>
+Render this tool's `input-available` part using the same approach as `askUser` above. Load the candidates from the saved search, display their original labels, and call `addToolOutput` with the selected ID. Return `{ selectedId: null }` for a "None of these" option. If a search has no results, ask for a different query before requesting a selection.
 
-### Via response parts
+Save search results durably and scope them to the authorized conversation so the picker still works after a reload or continuation. Use stable candidate IDs; names can be ambiguous.
 
-If you need more nuance (e.g. which specific tool is pending), use `chat.history.getPendingToolCalls()`:
+Before executing the action, read the completed selection from `chat.history`, validate its output, and check that the requested ID matches the user's answer and belongs to that saved search. A null answer must prevent the action. Enforce these checks in server code; tool descriptions alone don't enforce the choice.
 
-```ts
-const pending = chat.history.getPendingToolCalls();
-// [{ toolCallId, toolName, messageId }]
-```
+Use the selection's `toolCallId`, scoped to the chat, as the action's idempotency key. That keeps retries of the same choice from creating duplicate work, even if the model makes another action call. If the next step must be the action, use `prepareStep` to set `toolChoice` on the first model step after a valid selection.
 
-The result reflects the most recent assistant message: the one waiting on `addToolOutput`. Use it from `onAction` to gate fresh user turns ("can't send a new message while a HITL is open"), or from `onTurnComplete` to decide what to persist.
+You can also require approval on the action tool. The selection supplies an input; the approval confirms whether to execute with that input.
 
-Both `finishReason === "tool-calls"` and `chat.history.getPendingToolCalls().length > 0` are equivalent in practice. Use `finishReason` for dispatch, the helper for detail.
+## Approve a tool before execution
 
-### Acting once per net-new tool result
+With **AI SDK 6 or later**, set `needsApproval: true` on a tool that has an `execute` function. The SDK requests approval before calling `execute`. Approving the call runs it on the next turn; denying it skips execution.
 
-When the user's `addToolOutput` round-trips a tool answer back to the agent, the wire message carries the resolved tool part. If you want to fire side-effects (audit log, billing, notifications) exactly once per resolved tool call, do it in `hydrateMessages` before the runtime merges. `chat.history.extractNewToolResults(message)` returns only the parts whose `toolCallId` isn't already resolved on the chain:
-
-```ts
-hydrateMessages: async ({ incomingMessages }) => {
-  for (const msg of incomingMessages) {
-    if (msg.role !== "assistant") continue;
-    for (const r of chat.history.extractNewToolResults(msg)) {
-      await auditLog.record({
-        toolCallId: r.toolCallId,
-        toolName: r.toolName,
-        output: r.output,
-        errorText: r.errorText, // set only for output-error parts
-      });
-    }
-  }
-  return incomingMessages;
-},
+```ts trigger/tools/send-email.ts
+import { tool } from "ai";
+import { z } from "zod";
+import { sendEmail } from "@/lib/email";
+
+export const sendEmailTool = tool({
+  description: "Send an email after the user approves.",
+  inputSchema: z.object({ to: z.string(), subject: z.string(), body: z.string() }),
+  needsApproval: true,
+  execute: async (input) => sendEmail(input),
+});
 ```
 
-`extractNewToolResults` compares against the current `chat.history`. By the time `onTurnComplete` fires, the chain already contains `responseMessage`, so the helper returns `[]` there. Use it where the message is from outside the accumulator: `hydrateMessages`, `onAction` if the action carries a message, or any custom pre-merge code path.
+`sendEmail` is your application's email function. Keep authorization and idempotency checks there. Declare the tool on the agent and pass it to the `streamText` supplied to `run`, as in the question example.
 
-## Persistence: one message vs one record per pause
+On the frontend, render approve/deny buttons for `approval-requested` parts. Call `addToolApprovalResponse` with `part.approval.id` and the `approved` boolean, and use `lastAssistantMessageIsCompleteWithApprovalResponses` for automatic submission. The [frontend approval example](/ai-chat/frontend#tool-approvals) shows the full wiring.
 
-Because the AI SDK reuses the assistant message ID across the pause, the "same turn" from the user's perspective maps to **two `onTurnComplete` firings** on the server — but both receive a `responseMessage` with the **same `id`**, and the second firing's `responseMessage` contains the fully merged content.
+For conditional approval, [`needsApproval` also accepts a function](https://ai-sdk.dev/docs/ai-sdk-core/tools-and-tool-calling#dynamic-approval) that checks the tool input. Approval happens before `execute`, so a tool that searches inside `execute` can't use that approval prompt to display its search results. Run the search first, collect the selection, then call the action tool.
 
-Two common persistence patterns:
+If your agent uses both questions and approvals, combine the helpers:
 
-### Overwrite on every turn (simplest)
+```ts app/components/chat.tsx
+import {
+  lastAssistantMessageIsCompleteWithApprovalResponses,
+  lastAssistantMessageIsCompleteWithToolCalls,
+  type UIMessage,
+} from "ai";
 
-Just store the latest `uiMessages` array on every `onTurnComplete`. The paused-turn write is overwritten by the resume-turn write; the final DB state has the full merged message.
+export function sendAutomaticallyWhen({ messages }: { messages: UIMessage[] }) {
+  return (
+    lastAssistantMessageIsCompleteWithToolCalls({ messages }) ||
+    lastAssistantMessageIsCompleteWithApprovalResponses({ messages })
+  );
+}
+```
 
-```ts
-onTurnComplete: async ({ chatId, uiMessages }) => {
-  await db.chat.update({
-    where: { id: chatId },
-    data: { messages: uiMessages },
-  });
+## Detecting a paused turn in `onTurnComplete`
+
+Use `chat.history.getPendingToolCalls()` to find unanswered tool calls on the latest assistant message:
+
+```ts trigger/my-chat.ts
+onTurnComplete: async ({ stopped }) => {
+  if (stopped) return;
+  const pending = chat.history.getPendingToolCalls();
+  if (pending.length > 0) {
+    console.log("Waiting for user input", pending);
+  }
 },
 ```
 
-Use this unless you specifically need an audit trail.
+Each entry contains `toolCallId`, `toolName`, and `messageId`. Approval requests use a separate state: inspect `responseMessage.parts` for `approval-requested` when tracking approvals.
 
-### Checkpoint nodes (immutable history)
+`finishReason === "tool-calls"` describes why the model stopped. It can also occur when a step limit ends a loop of server-executed tools, so check the tool states before treating it as a human pause. Check `stopped` separately for interrupted turns.
 
-For apps that want every pause point recorded as its own immutable snapshot (branching, replay, diff review), save a checkpoint when paused and a sibling when complete:
+### Acting once per net-new tool result
 
-```ts
-onTurnComplete: async ({ chatId, responseMessage, finishReason, uiMessages }) => {
-  if (!responseMessage) return;
+`chat.history.extractNewToolResults(message)` returns resolved tool parts whose `toolCallId` isn't already resolved in the current history. Call it before the incoming message is merged. By `onTurnComplete`, the result is already in history and the helper returns `[]`.
 
-  if (finishReason === "tool-calls") {
-    // Paused — save a checkpoint
-    await db.turnCheckpoint.create({
-      data: {
-        chatId,
-        messageId: responseMessage.id,
-        parts: responseMessage.parts,
-        kind: "partial",
-      },
-    });
-  } else {
-    // Completed — save a sibling with the merged full message
-    await db.turnCheckpoint.create({
-      data: {
-        chatId,
-        messageId: responseMessage.id,
-        parts: responseMessage.parts,
-        kind: "final",
-      },
-    });
-  }
+This filters results against the current transcript; durable side effects still need an idempotency key. Use `chatId` and `toolCallId` to deduplicate a sync or audit write across retries. See [Tool result auditing](/ai-chat/patterns/tool-result-auditing) for existing `hydrateMessages` integrations.
 
-  // Always update the canonical chat record for `hydrateMessages` to load
-  await db.chat.update({
-    where: { id: chatId },
-    data: { messages: uiMessages },
-  });
-};
-```
+## Persistence: one message vs one record per pause
 
-Both writes see `responseMessage.id` as the same value — they're checkpoints of the same logical message. Grouping by `messageId` + ordering by `createdAt` gives you the progression.
+The default [transcript storage](/ai-chat/transcript-storage) saves the pending call and its resolved result. Use a storage adapter if you need the conversation in your own database.
+
+The pause and continuation share the assistant message ID. Upsert by `message.id` so the resolved message replaces the pending version. For an audit trail, keep separate snapshots alongside that canonical message and record whether it has pending questions, approval requests, or a stopped response.
 
 ## Multi-pause turns
 
-A single logical turn can pause more than once — the LLM asks question A, gets the answer, thinks, then asks question B before finishing. Each pause fires its own `onTurnComplete` with `finishReason === "tool-calls"`; only the last firing has `finishReason === "stop"`. The checkpoint pattern above handles this naturally — each pause adds a new checkpoint sharing the same `responseMessage.id`.
+A conversation can ask another question after receiving an answer. Each pause and continuation fires `onTurnComplete`; inspect the message's tool states at each callback. The merged assistant message includes the answers collected so far.
+
+## Verify the flow
+
+Send a request that needs clarification. Confirm that the question appears, choose an option, and check that the agent continues without another click on Send. The question's tool part should change from `input-available` to `output-available`.
+
+For a selection from search results, check that only the selected item is used. Choosing "None of these" must leave the action unexecuted. Reload a pending selection and confirm that the same candidates appear.
+
+For an approval tool, deny the first request and confirm that `execute` doesn't run. Approve a fresh request and confirm that it runs with the displayed inputs.
 
-## Gotchas
+## Common mistakes
 
-- **Don't set an `execute` function on the HITL tool.** If it has one, `streamText` will call it immediately instead of handing control back.
-- **The frontend must use `sendAutomaticallyWhen`.** Without it, the user has to press Enter after answering — `addToolOutput` updates local state but doesn't fire a new turn by itself.
-- **Don't mutate `responseMessage` in `onTurnComplete`.** It's the captured snapshot. To add custom parts, use `chat.response.append()` in `onBeforeTurnComplete` (while the stream is open).
-- **Stop handling.** If the user stops the run while a pause is active (`chat.stop()` on the transport), `onTurnComplete` fires with `stopped: true` and `finishReason` reflecting the last successful step. Treat stopped paused turns the same as stopped normal turns.
+- Give question tools no `execute` function. For tools that execute after approval, keep `execute` and set `needsApproval`.
+- `addToolOutput` updates local state. Configure `sendAutomaticallyWhen` or explicitly send the updated message to start the next turn.
+- Only show interactive controls for pending calls, and disable them while a request is streaming or submitted.
+- To add custom response parts, use `chat.response.append()` in `onBeforeTurnComplete` while the stream is open. Treat `responseMessage` in `onTurnComplete` as a snapshot.

package/docs/ai-chat/patterns/tool-result-auditing.mdx

@@ -1,23 +1,24 @@
 ---
 title: "Tool result auditing"
 sidebarTitle: "Tool result auditing"
-description: "Fire side effects exactly once per resolved tool call — audit logs, billing, notifications — using extractNewToolResults inside hydrateMessages or onTurnComplete."
+description: "Find new tool results before they merge into chat history, and deduplicate audit writes with a durable idempotency key."
 ---
 
-When a chat agent uses [tools](/ai-chat/tools) (especially [human-in-the-loop](/ai-chat/patterns/human-in-the-loop) tools that wait on `addToolOutput` from the frontend), you often need to fire side effects exactly once per resolved tool call:
+Use `chat.history.extractNewToolResults(message)` to find incoming tool results that aren't resolved in the current transcript. Make the resulting audit write idempotent in your database so retries can't create duplicate records.
 
-- **Audit logs** — record every tool result for compliance.
-- **Billing** — charge per tool invocation.
-- **Notifications** — alert downstream systems when a specific tool resolves.
-- **Search-index updates** — reflect tool outputs into a derived store.
+The helper applies to [human-in-the-loop](/ai-chat/patterns/human-in-the-loop) answers sent with `addToolOutput`. It compares the incoming message with the current history; it doesn't track whether an external write succeeded.
 
-The naive approach — "log every tool part you see" — over-counts. The same assistant message gets re-shown across re-renders, replays, and retries. You want a function of the form **"is this tool result one I haven't already logged?"** That's exactly what [`chat.history.extractNewToolResults`](/ai-chat/backend#chat-history) returns.
+<Note>
+  The `hydrateMessages` examples below apply to existing integrations. That hook is deprecated. For new conversation persistence, use [transcript storage](/ai-chat/transcript-storage).
+</Note>
 
 ## The pattern
 
 ```ts
 import { chat } from "@trigger.dev/sdk/ai";
 import { auditLog } from "@/lib/audit";
+import { db } from "@/lib/db";
+import { anthropic } from "@ai-sdk/anthropic";
 
 export const myChat = chat.agent({
   id: "my-chat",
@@ -35,7 +36,7 @@ export const myChat = chat.agent({
     }
     return await db.getMessages(chatId);
   },
-  run: async ({ messages, signal }) => {
+  run: async ({ messages, signal, streamText }) => {
     return streamText({ model: anthropic("claude-sonnet-4-5"), messages, abortSignal: signal });
   },
 });
@@ -43,10 +44,10 @@ export const myChat = chat.agent({
 
 The hook fires per turn. `incomingMessages` is the new wire message (0-or-1-length, see [v4.5 wire format change](/ai-chat/upgrade-guide#v45-wire-format-change)). For each new tool result on that message, write one audit row. Then return the canonical chain from your DB.
 
-`extractNewToolResults` compares the message against the current `chat.history` chain and returns only tool parts whose `toolCallId` is **not** already resolved. That's what makes the call exactly-once:
+`extractNewToolResults` compares the message against the current `chat.history` chain and returns only tool parts whose `toolCallId` is **not** already resolved. For results already present in that history:
 
-- A re-emitted message (same id, same toolCallId) returns `[]` — no duplicate log.
-- A genuinely new tool result on a known assistant message returns just the new ones.
+- A re-emitted message with the same resolved `toolCallId` returns `[]`.
+- A new tool result on a known assistant message is returned.
 - A first-time tool result returns the full set.
 
 ## Why `hydrateMessages` is the right hook
@@ -54,13 +55,13 @@ The hook fires per turn. `incomingMessages` is the new wire message (0-or-1-leng
 The pattern works in any pre-merge callback, but `hydrateMessages` is the canonical spot for two reasons:
 
 1. **It fires before the runtime merges** the incoming message into the accumulator. Once merged, the tool results are already on the chain, and `extractNewToolResults` returns `[]` for them.
-2. **It always fires per turn** — including HITL turns where the user resolved a tool with `addToolOutput`, which is the highest-volume audit event in most apps.
+2. **It fires on each turn**, including turns that receive a user's answer through `addToolOutput`.
 
 By the time `onTurnComplete` fires, the chain already contains `responseMessage`, so calling `extractNewToolResults(responseMessage)` there returns `[]`. Don't put audit logging there for the resolution path.
 
-## Without `hydrateMessages` — `onTurnComplete` for self-emitted tool calls
+## Audit server-executed tools in `onTurnComplete`
 
-If you don't use `hydrateMessages`, the runtime's snapshot+replay path handles persistence. You can still audit the agent's **own** tool executions in `onTurnComplete` — but compare against the prior message rather than the just-emitted one:
+If you don't use `hydrateMessages`, the runtime's snapshot+replay path handles persistence. You can still audit the agent's **own** tool executions in `onTurnComplete` by iterating the emitted parts and using an idempotent audit writer:
 
 ```ts
 onTurnComplete: async ({ chatId, newUIMessages }) => {
@@ -87,23 +88,23 @@ onTurnComplete: async ({ chatId, newUIMessages }) => {
 },
 ```
 
-`newUIMessages` is just the messages this turn produced — no prior-chain noise. Each tool part shows up exactly once.
+`newUIMessages` contains the messages this turn produced. Retries and merged assistant messages can expose a tool result again, so deduplicate these writes in your database too.
 
-This works for tools the agent itself calls (no HITL pause). For HITL flows where the user resolves a tool with `addToolOutput`, the resolution arrives on the **next** turn's wire message, not in `newUIMessages` of the resolving turn — use `hydrateMessages` for those.
+This works for tools the agent itself calls (no HITL pause). For HITL flows where the user resolves a tool with `addToolOutput`, the resolution arrives on the **next** turn's wire message, not in `newUIMessages` of the resolving turn. Use `hydrateMessages` for those in existing integrations.
 
 ## Idempotency at the storage layer
 
-Even with `extractNewToolResults`, transient failures (e.g. an audit-log POST that times out and is retried) can produce duplicates. Make the audit-log writer idempotent on `toolCallId`:
+Even with `extractNewToolResults`, transient failures (e.g. an audit-log POST that times out and is retried) can produce duplicates. Make the audit-log writer idempotent on `(chatId, toolCallId)`:
 
 ```ts
 await auditLog.upsert({
-  where: { toolCallId: r.toolCallId },
+  where: { chatId_toolCallId: { chatId, toolCallId: r.toolCallId } },
   create: { /* ... */ },
   update: { /* timestamp, retry count, etc. */ },
 });
 ```
 
-`toolCallId` is unique per tool invocation (assigned by the AI SDK when the model emits the tool call) and stable across retries — perfect for an idempotency key.
+A replay of the same tool call keeps its `toolCallId`. A new model-generated invocation can have a new ID; use an application operation ID as well when separate calls must refer to the same external action.
 
 ## What `extractNewToolResults` returns
 
@@ -116,17 +117,17 @@ type ChatNewToolResult = {
 };
 ```
 
-Tool parts in `input-available` state (the model called the tool but it hasn't resolved yet) are not returned — only **resolved** results count.
+Tool parts in `input-available` state (the model called the tool but it hasn't resolved yet) aren't returned. The helper returns resolved results.
 
 ## Combining with HITL
 
-[Human-in-the-loop](/ai-chat/patterns/human-in-the-loop) tools pause the turn waiting for `addToolOutput` from the frontend. When the user submits, the wire message carries an updated assistant message with the tool now in `output-available` state. `extractNewToolResults` against that message returns the just-resolved tool — exactly one audit row per user resolution:
+[Human-in-the-loop](/ai-chat/patterns/human-in-the-loop) tools pause the turn waiting for `addToolOutput` from the frontend. When the user submits, the wire message carries an updated assistant message with the tool now in `output-available` state. `extractNewToolResults` against that message returns the newly resolved tool. An idempotent audit writer keeps one row per resolution:
 
 ```ts
 hydrateMessages: async ({ chatId, incomingMessages }) => {
   for (const msg of incomingMessages) {
     for (const r of chat.history.extractNewToolResults(msg)) {
-      // Fires once per ask_user / approval / similar resolution
+      // Deduplicate the write by chatId and toolCallId.
       await auditLog.record({ chatId, /* ... */ });
     }
   }
@@ -134,11 +135,11 @@ hydrateMessages: async ({ chatId, incomingMessages }) => {
 }
 ```
 
-This is the original motivator for the helper — see the [HITL pattern's net-new-tool-result section](/ai-chat/patterns/human-in-the-loop#acting-once-per-net-new-tool-result).
+See the [HITL pattern's net-new-tool-result section](/ai-chat/patterns/human-in-the-loop#acting-once-per-net-new-tool-result).
 
 ## See also
 
-- [`chat.history`](/ai-chat/backend#chat-history) — full reference for `extractNewToolResults`, `getPendingToolCalls`, `getResolvedToolCalls`
-- [Human-in-the-loop](/ai-chat/patterns/human-in-the-loop) — the pattern this auditing hook complements
-- [`hydrateMessages`](/ai-chat/lifecycle-hooks#hydratemessages) — where pre-merge auditing lives
-- [Persistence and replay](/ai-chat/patterns/persistence-and-replay) — how the runtime rebuilds chains, and why `extractNewToolResults` works against them
+- [`chat.history`](/ai-chat/backend#chat-history): full reference for `extractNewToolResults`, `getPendingToolCalls`, `getResolvedToolCalls`
+- [Human-in-the-loop](/ai-chat/patterns/human-in-the-loop): the pattern this auditing hook complements
+- [`hydrateMessages`](/ai-chat/lifecycle-hooks#hydratemessages): where pre-merge auditing lives
+- [Persistence and replay](/ai-chat/patterns/persistence-and-replay): how the runtime rebuilds chains, and why `extractNewToolResults` works against them