@tanstack/ai 0.41.0 → 0.43.0

package/skills/ai-core/middleware/SKILL.md

@@ -8,10 +8,11 @@ description: >
   execution order. NOT onEnd/onFinish callbacks on chat() — use middleware.
 type: sub-skill
 library: tanstack-ai
-library_version: '0.10.0'
+library_version: '0.42.0'
 sources:
   - 'TanStack/ai:docs/advanced/middleware.md'
   - 'TanStack/ai:docs/sandbox/observability.md'
+  - 'TanStack/ai:docs/persistence/overview.md'
 ---
 
 # Middleware
@@ -57,6 +58,7 @@ Every hook receives a `ChatMiddlewareContext` as its first argument, which provi
 | `onStructuredOutputConfig` | Once at the structured-output boundary (only when `chat({ outputSchema })`)                        | `StructuredOutputMiddlewareConfig` (return partial) |
 | `onStart`                  | Once after initial `onConfig`                                                                      | none                                                |
 | `onIteration`              | Start of each agent loop iteration                                                                 | `IterationInfo`                                     |
+| `onShouldContinue`         | Whether to start another agent-loop iteration (AND with strategy; `false` stops)                   | `AgentLoopState`                                    |
 | `onChunk`                  | Every streamed chunk                                                                               | `StreamChunk` (return void/chunk/chunk[]/null)      |
 | `onBeforeToolCall`         | Before each tool executes                                                                          | `ToolCallHookContext` (return decision or void)     |
 | `onAfterToolCall`          | After each tool executes                                                                           | `AfterToolCallInfo`                                 |
@@ -116,17 +118,25 @@ onStructuredOutputConfig?: (
   | void
   | null
   | Partial<StructuredOutputMiddlewareConfig>
-  | Promise<void | Partial<StructuredOutputMiddlewareConfig>>
+  | Promise<void | null | Partial<StructuredOutputMiddlewareConfig>>
 ```
 
 **`StructuredOutputMiddlewareConfig` shape:**
 
 ```ts
-interface StructuredOutputMiddlewareConfig extends ChatMiddlewareConfig {
+interface StructuredOutputMiddlewareConfig extends Omit<
+  ChatMiddlewareConfig,
+  'tools'
+> {
   outputSchema: JSONSchema // The JSON Schema being sent to the provider
 }
 ```
 
+Note the `Omit<…, 'tools'>`: there is **no `config.tools`** on this hook. The
+structured-output call is the final, tool-free call, so reading or returning
+`tools` here is a compile error, not a no-op. Transform tools in `onConfig`
+instead.
+
 **Ordering rule:**
 
 - `onStructuredOutputConfig` fires **before** `onConfig` at the structured-output boundary.
@@ -211,11 +221,18 @@ const toolGuard: ChatMiddleware = {
       return { type: 'abort', reason: 'Dangerous operation blocked' }
     }
 
-    // Enforce default arguments
-    if (hookCtx.toolName === 'search' && !hookCtx.args.limit) {
-      return {
-        type: 'transformArgs',
-        args: { ...hookCtx.args, limit: 10 },
+    // Enforce default arguments. `hookCtx.args` is `unknown` — the provider
+    // sent it — so narrow before reading it. No `as` casts.
+    if (hookCtx.toolName === 'search') {
+      const args =
+        typeof hookCtx.args === 'object' && hookCtx.args !== null
+          ? hookCtx.args
+          : {}
+      if (!('limit' in args)) {
+        return {
+          type: 'transformArgs',
+          args: { ...args, limit: 10 },
+        }
       }
     }
 
@@ -346,6 +363,52 @@ const stream = chat({
 | `onUsage`                  | Sequential                                    | All run in order                           |
 | `onFinish/onAbort/onError` | Sequential                                    | All run in order                           |
 
+## Pattern: tool-call budget (app-owned)
+
+Not a built-in. Cap fan-out with `onBeforeToolCall` skip + `onShouldContinue`.
+See `docs/chat/agentic-cycle.md` ("Tool-call budgets").
+
+```typescript
+import { chat, maxIterations, type ChatMiddleware } from '@tanstack/ai'
+
+function toolCallBudget(opts: {
+  max?: number
+  maxPerTurn?: number
+}): ChatMiddleware {
+  let perTurn = 0
+  return {
+    onIteration: () => {
+      perTurn = 0
+    },
+    onToolPhaseComplete: () => {
+      perTurn = 0
+    },
+    onBeforeToolCall: () => {
+      if (opts.maxPerTurn == null) return undefined
+      if (++perTurn > opts.maxPerTurn) {
+        return {
+          type: 'skip',
+          result: {
+            error: `Skipped: exceeded maxToolCallsPerTurn (${opts.maxPerTurn})`,
+          },
+        }
+      }
+      return undefined
+    },
+    onShouldContinue: (_ctx, state) =>
+      opts.max != null && state.toolCallCount >= opts.max ? false : undefined,
+  }
+}
+
+chat({
+  adapter,
+  messages,
+  tools: [weatherTool],
+  agentLoopStrategy: maxIterations(20),
+  middleware: [toolCallBudget({ maxPerTurn: 10, max: 20 })],
+})
+```
+
 ## Built-in: toolCacheMiddleware
 
 Caches tool call results by name + arguments. Import from `@tanstack/ai/middlewares`:
@@ -372,6 +435,148 @@ Options: `maxSize` (default 100), `ttl` (default Infinity), `toolNames` (default
 `keyFn` (custom cache key), `storage` (custom backend like Redis). See
 `docs/advanced/middleware.md` for custom storage examples.
 
+## Server State Persistence: withPersistence
+
+`withPersistence(persistence)` (from `@tanstack/ai-persistence`) is a
+`ChatMiddleware` that persists **state** for `chat()` — thread messages, run
+records (status/timing/usage/errors), and interrupt state — to a backend store.
+Add it to the `middleware` array like any other middleware. It never mutates the
+chunk stream; replaying a dropped/reloaded _stream_ is a separate transport-layer
+concern (see ai-core/chat-experience/SKILL.md resumability, not this middleware).
+
+```typescript
+import {
+  chat,
+  chatParamsFromRequest,
+  toServerSentEventsResponse,
+} from '@tanstack/ai'
+import { openaiText } from '@tanstack/ai-openai'
+import { withPersistence, memoryPersistence } from '@tanstack/ai-persistence'
+
+// memoryPersistence() is the in-process reference backend (dev/tests). For a
+// durable one, implement the store contracts against your database — see the
+// @tanstack/ai-persistence skills.
+const persistence = memoryPersistence()
+
+export async function POST(request: Request) {
+  const params = await chatParamsFromRequest(request)
+
+  const stream = chat({
+    adapter: openaiText('gpt-5.5'),
+    messages: params.messages,
+    threadId: params.threadId,
+    runId: params.runId,
+    ...(params.resume ? { resume: params.resume } : {}),
+    middleware: [withPersistence(persistence)],
+  })
+
+  return toServerSentEventsResponse(stream)
+}
+```
+
+### Authoritative-history contract
+
+The middleware treats each request's `messages` as the source of truth for the
+thread:
+
+- **Non-empty `messages`** → on a successful finish (and at an interrupt
+  boundary) the middleware **overwrites** the entire stored thread with that
+  array. Post the **complete** transcript, never just the newest message(s) — a
+  delta would replace and destroy the stored history.
+- **Empty `messages`** → the middleware **loads** the stored thread and runs the
+  turn from the server's copy. This is how you continue a conversation without
+  resending history from the client.
+
+### Backends
+
+`@tanstack/ai-persistence` ships **contracts, not a database backend**. It
+provides the four store interfaces (`messages`, `runs`, `interrupts`,
+`metadata`), the middleware that drives them, `memoryPersistence()` for
+dev/tests, and a conformance testkit. For anything durable you implement the
+stores against your own database and pass the result to `withPersistence`.
+
+Annotate your factory with a named shape (`ChatPersistence` /
+`ChatTranscriptPersistence`) — bare `AIPersistence` is the all-optional bag and
+`withPersistence` rejects it.
+
+Locks are separate from state and are **not** a `stores` key: wire a
+`LockStore` with `withLocks(lockStore)`.
+
+The `runs` store in that list is typed against `RunStore`, which ships in
+`@tanstack/ai` alongside `RunRecord`, `RunStatus`, `TerminalRunStatus`,
+`RunError`, `isTerminalRunStatus`, `defineRunStore`, and `InMemoryRunStore`. A
+`RunRecord` tracks one run: `runId`, `threadId`, `status`, `startedAt`, plus
+optional `finishedAt`, `error`, `usage`, `sandboxKey`, `detachedSince`,
+`cancelRequested`, and `driverEpoch`. A backend must round-trip **all** of
+them: `cancelRequested` is the durable out-of-band cancel channel
+(`requestRunCancel` writes it, `wasCancelRequested` reads it), and
+`driverEpoch` is the monotonic fencing token each host bumps when it claims a
+run, so a superseded host can discover it lost. Omit either and a durable
+sandboxed run loses a mechanism silently — Stop stops reaching a remote
+driver, or nothing fences a dead host's writes.
+`error` is a structured `RunError` (`{ message: string, code?: string }`), not
+a bare string: `message` is the provider's prose, `code` is the stable,
+machine-branchable classification a consumer switches on. Only
+`createOrResume`, `update`, `get`, and `findActiveRun` are required on a
+`RunStore`; `listByThread` and `listReclaimable` are optional, so a backend can
+leave either out and callers feature-detect
+(`store.listReclaimable?.(opts)`). Shape your own store with
+`defineRunStore` for autocomplete without a separate `: RunStore` annotation,
+matching `defineLock`; `defineRunStore<const T extends RunStore>(store: T): T`
+returns the argument's own type, so an optional method your store implements
+stays known-present on the result instead of collapsing to `| undefined`.
+`isTerminalRunStatus(status)` is a type predicate narrowing `RunStatus` to
+`TerminalRunStatus`, so code inside the guard can pass `status` where a
+`TerminalRunStatus` is required without a cast. When a backend omits an
+optional `RunStore` method, declare the omission when running the conformance
+testkit (`ai-persistence/stores`'s `skipMethods` option) rather than leaving it
+undeclared.
+
+### `StreamDurability.snapshot()`
+
+A `StreamDurability` (the event-log backend `memoryStream` / `durableStream`
+implement, and what `@tanstack/ai-sandbox`'s run driver resolves per run — its
+`RunDeps.durability` / `sandboxRunDriver({ durability })` is a factory
+`(runId) => StreamDurability`, because one log is bound to one run) requires a
+`snapshot()` method alongside `append`, `read`, and `close`:
+
+```ts
+snapshot: () => Promise<Array<{ offset: TOffset; chunk: StreamChunk }>>
+```
+
+It returns everything stored for a run right now, in append order, then
+resolves. Use it, not `read()`, when a caller needs to inspect a run's stored
+prefix and get an answer back: `read()` tails and only resolves once the log
+is terminalized with `close()` or the caller aborts, so it never resolves
+against a producer that crashed without calling `close()`, and its log stays
+open indefinitely. `snapshot()` resolves immediately with what is stored,
+including while the log is still open, and resolves to an empty array for a
+run with nothing stored yet.
+
+**Full guidance lives in the package's own skills** — start at
+`node_modules/@tanstack/ai-persistence/skills/ai-persistence/SKILL.md`,
+which routes to the server, client, stores, locks, and adapter-recipe
+(Drizzle / Prisma / Cloudflare) sub-skills.
+
+### Resume reconstruction is the middleware's job (server-authoritative path)
+
+When a thread has pending interrupts, the middleware **records** them and
+**gates** new input: a request that carries pending interrupts must include a
+`resume` batch that references them, or `onConfig` throws. On a valid resume
+batch the middleware also **builds `ChatResumeToolState`** (approvals /
+client-tool results) and **clears `config.resume`** so the chat engine skips
+its ephemeral reconstruction — that path needs client message history the
+persistence flow deliberately omits when the server owns the transcript.
+Resumes accepted in `onConfig` are committed (marked resolved/cancelled) only
+once the run reaches a successful boundary, so a provider failure between
+accepting a resume and finishing leaves the interrupt pending and a retry with
+the same resume succeeds.
+
+> A companion `withGenerationPersistence(persistence)` tracks run records for
+> non-chat generation activities (image, audio, TTS, video, transcription).
+
+Source: docs/persistence/overview.md
+
 ## Sandbox File-Event Hooks (`sandbox` group)
 
 Declare a `sandbox: ChatSandboxHooks` group on `defineChatMiddleware` to react
@@ -507,35 +712,38 @@ has no effect on the stream output.
 
 Source: docs/advanced/middleware.md
 
-### b. MEDIUM: Middleware exceptions breaking the stream
+### b. MEDIUM: Middleware exceptions breaking the stream — in `onChunk` / `onConfig`
+
+Know which hooks the framework already guards. **The terminal hooks
+(`onFinish`, `onAbort`, `onError`) are individually wrapped** by core's
+`runTerminalHook`: a throw there is logged on the `errors` channel and the next
+middleware's terminal hook still runs, so a failed analytics `POST` in `onFinish`
+cannot break the stream or replace the abort reason. Guarding those is about
+keeping your own bookkeeping intact, not about protecting the run.
+
+**`onChunk` and `onConfig` are NOT guarded, deliberately** — they are transforms
+on the data path, where swallowing a throw would forward a chunk or a config the
+middleware had decided to reject. A throw from either fails the whole stream. That
+is where an unhandled error actually costs you a response:
 
 ```typescript
-// WRONG -- unhandled error kills the entire streaming response
+// WRONG -- an unhandled error in onChunk kills the entire streaming response
 const fragile: ChatMiddleware = {
-  name: 'fragile-analytics',
-  onFinish: async (ctx, info) => {
-    // If this fetch fails, the stream breaks
-    await fetch('/api/analytics', {
-      method: 'POST',
-      body: JSON.stringify({ duration: info.duration }),
-    })
+  name: 'fragile-chunk-logger',
+  onChunk: (ctx, chunk) => {
+    // A logger that throws on an unexpected chunk shape takes the stream with it
+    logChunk(chunk)
+  },
+  onConfig: (ctx, config) => {
+    // Same for a config transform that reads an env var that is not set
+    return { model: requireEnv('MODEL_OVERRIDE') }
   },
 }
 
-// CORRECT -- wrap in try-catch and/or use ctx.defer()
+// CORRECT -- own the failure inside the unguarded hooks
 const resilient: ChatMiddleware = {
-  name: 'resilient-analytics',
-  onFinish: (ctx, info) => {
-    // Option 1: defer (non-blocking, errors are isolated)
-    ctx.defer(
-      fetch('/api/analytics', {
-        method: 'POST',
-        body: JSON.stringify({ duration: info.duration }),
-      }),
-    )
-  },
+  name: 'resilient-chunk-logger',
   onChunk: (ctx, chunk) => {
-    // Option 2: try-catch for synchronous/critical hooks
     try {
       logChunk(chunk)
     } catch (err) {
@@ -543,17 +751,34 @@ const resilient: ChatMiddleware = {
     }
     // Return void to pass through
   },
+  onConfig: (ctx, config) => {
+    const override = process.env.MODEL_OVERRIDE
+    // Decide, do not throw: no override means no transform.
+    return override === undefined ? undefined : { model: override }
+  },
+  onFinish: (ctx, info) => {
+    // Already guarded by core — but prefer ctx.defer() anyway, so a slow
+    // analytics call does not delay the terminal fan-out at all.
+    ctx.defer(
+      fetch('/api/analytics', {
+        method: 'POST',
+        body: JSON.stringify({ duration: info.duration }),
+      }),
+    )
+  },
 }
 ```
 
-Wrap all middleware hooks in try-catch to prevent analytics or logging failures
-from killing the chat stream. For async side effects, prefer `ctx.defer()` which
-runs after the terminal hook and isolates failures.
+Rule: put the try-catch where the framework has none — `onChunk` and `onConfig`
+(and the other transform hooks: `onStructuredOutputConfig`, `onBeforeToolCall`,
+`onAfterToolCall`). For async side effects in the terminal hooks, prefer
+`ctx.defer()`, which runs after the terminal hook and isolates failures.
 
-Source: docs/advanced/middleware.md
+Source: docs/advanced/middleware.md, `packages/ai/src/activities/chat/middleware/compose.ts`
 
 ## Cross-References
 
 - See also: **ai-core/chat-experience/SKILL.md** -- Middleware hooks into the chat lifecycle
 - See also: **ai-core/structured-outputs/SKILL.md** -- Middleware now wraps the final structured-output call; use `onStructuredOutputConfig` for JSON-Schema transforms
 - See also: **ai-core/ag-ui-protocol/SKILL.md** -- Reading the `sandbox.file` / `sandbox.file.diff` `CUSTOM` chunks the sandbox runtime emits alongside these `sandbox` hooks, via `ChatStream`'s typed `KnownCustomEvent` narrowing
+- See also: **`@tanstack/ai-persistence` skills** (`skills/ai-persistence/SKILL.md` in that package) -- Full persistence suite (`withPersistence`, client storage, store contracts, adapter recipes, locks). This file only sketches server `withPersistence`.

package/skills/ai-core/structured-outputs/SKILL.md

@@ -13,7 +13,7 @@ description: >
   part. convertSchemaToJsonSchema() for manual schema conversion.
 type: sub-skill
 library: tanstack-ai
-library_version: '0.10.0'
+library_version: '0.42.0'
 sources:
   - 'TanStack/ai:docs/structured-outputs/overview.md'
   - 'TanStack/ai:docs/structured-outputs/one-shot.md'

package/skills/ai-core/tool-calling/SKILL.md

@@ -4,12 +4,12 @@ description: >
   Isomorphic tool system: toolDefinition() with Zod schemas,
   .server() and .client() implementations, passing tools to both
   chat() on server and useChat/clientTools on client, tool approval
-  flows with needsApproval and addToolApprovalResponse(), lazy tool
+  flows with needsApproval and bound interrupts (resolveInterrupt), lazy tool
   discovery with lazy:true, rendering ToolCallPart and ToolResultPart
   in UI.
 type: sub-skill
 library: tanstack-ai
-library_version: '0.10.0'
+library_version: '0.42.0'
 sources:
   - 'TanStack/ai:docs/tools/tools.md'
   - 'TanStack/ai:docs/tools/server-tools.md'
@@ -108,14 +108,14 @@ function ChatPage() {
     connection: fetchServerSentEvents("/api/chat"),
     tools,
   });
-  type Messages = InferChatMessages<typeof chatOptions>;
-
   const { messages, sendMessage } = useChat(chatOptions);
+  // InferChatMessages ties part types to the configured tools when needed:
+  // type Messages = InferChatMessages<typeof chatOptions>
 
   return (
     <div>
       <span>Cart: {cartCount}</span>
-      {(messages as Messages).map((msg) => (
+      {messages.map((msg) => (
         <div key={msg.id}>
           {msg.parts.map((part) => {
             if (part.type === "text") return <p>{part.content}</p>;
@@ -239,9 +239,11 @@ function ChatPage() {
 
 ### Pattern 3: Tool with Approval Flow
 
-Set `needsApproval: true` in the definition. Execution pauses until the client
-calls `addToolApprovalResponse()`. The part has `state: "approval-requested"`
-and an `approval` object with an `id`.
+Set `needsApproval: true` in the definition. Execution pauses with
+`RUN_FINISHED.outcome.type === 'interrupt'`. The primary client API is bound
+`interrupts` + `resolveInterrupt` / `resolveInterrupts` / `cancel`.
+`addToolApprovalResponse` and `pendingInterrupts` remain as deprecated
+compatibility shims during migration.
 
 ```typescript
 import { toolDefinition } from '@tanstack/ai'
@@ -265,59 +267,40 @@ export const sendEmail = sendEmailDef.server(async ({ to, subject, body }) => {
 })
 ```
 
-Client -- render approval UI and respond:
+Server route must forward `resume` / `parentRunId` (via `chatParamsFromRequest`
+or equivalent). Client -- render bound interrupts:
 
 ```typescript
 import { useChat, fetchServerSentEvents } from "@tanstack/ai-react";
 
 function ChatPage() {
-  const { messages, addToolApprovalResponse } = useChat({
+  const { messages, interrupts, sendMessage } = useChat({
     connection: fetchServerSentEvents("/api/chat"),
   });
 
   return (
     <div>
+      {interrupts.map((interrupt) => {
+        if (interrupt.kind !== "tool-approval") return null;
+        return (
+          <div key={interrupt.id}>
+            <p>Approve "{interrupt.toolName}"?</p>
+            <pre>{JSON.stringify(interrupt.originalArgs, null, 2)}</pre>
+            <button onClick={() => interrupt.resolveInterrupt(true)}>
+              Approve
+            </button>
+            <button onClick={() => interrupt.resolveInterrupt(false)}>
+              Deny
+            </button>
+            <button onClick={() => interrupt.cancel()}>Cancel</button>
+          </div>
+        );
+      })}
       {messages.map((msg) => (
         <div key={msg.id}>
-          {msg.parts.map((part) => {
-            if (part.type === "text") return <p>{part.content}</p>;
-            if (
-              part.type === "tool-call" &&
-              part.state === "approval-requested" &&
-              part.approval
-            ) {
-              return (
-                <div key={part.id}>
-                  <p>Approve "{part.name}"?</p>
-                  {/* `part.input` is the parsed, typed object (populated once
-                      the arguments are complete, as they are at approval
-                      time); `part.arguments` remains the raw JSON string. */}
-                  <pre>{JSON.stringify(part.input, null, 2)}</pre>
-                  <button
-                    onClick={() =>
-                      addToolApprovalResponse({
-                        id: part.approval!.id,
-                        approved: true,
-                      })
-                    }
-                  >
-                    Approve
-                  </button>
-                  <button
-                    onClick={() =>
-                      addToolApprovalResponse({
-                        id: part.approval!.id,
-                        approved: false,
-                      })
-                    }
-                  >
-                    Deny
-                  </button>
-                </div>
-              );
-            }
-            return null;
-          })}
+          {msg.parts.map((part) =>
+            part.type === "text" ? <p key={part.content}>{part.content}</p> : null
+          )}
         </div>
       ))}
     </div>
@@ -325,14 +308,24 @@ function ChatPage() {
 }
 ```
 
-> **Type-safe approval:** With typed `tools`, `part.approval` exists **only**
-> on parts for tools defined with `needsApproval: true`. Tools without approval
-> have no `approval` field (reading it is a compile error). For a
-> tool-agnostic handler over a typed union, narrow with `'approval' in part`
-> (`if (part.type === 'tool-call' && 'approval' in part && part.approval)`),
-> or type a shared component against the base `ToolCallPart`. An untyped
-> `useChat()` keeps `approval` on every tool-call part, which is why the
-> snippet above (no `tools` generic) reads it directly.
+Batch all pending approvals with `resolveInterrupts` (void — submission is
+async; watch `resuming` / `interruptErrors`):
+
+```typescript
+// Payloadless tool-approvals only
+resolveInterrupts(true)
+
+// Or per-item:
+resolveInterrupts((interrupt) => {
+  if (interrupt.kind === 'tool-approval') {
+    interrupt.resolveInterrupt(true)
+  }
+})
+```
+
+Migration: `pendingInterrupts` aliases `interrupts`; `addToolApprovalResponse`
+forwards to the matching bound approval when present. Prefer the bound methods
+above for new code. See `docs/interrupts/`.
 
 ### Pattern 4: Lazy Tool Discovery
 
@@ -375,6 +368,8 @@ export async function POST(request: Request) {
     adapter: openaiText('gpt-5.5'),
     messages,
     tools: [getProducts, compareProducts],
+    // maxIterations bounds model turns, not tool calls. For tool budgets,
+    // use middleware onBeforeToolCall + onShouldContinue (see agentic-cycle docs).
     agentLoopStrategy: maxIterations(20),
   })
   return toServerSentEventsResponse(stream)
@@ -647,7 +642,7 @@ import { anthropicText } from '@tanstack/ai-anthropic'
 export async function POST(request: Request) {
   const { messages } = await request.json()
   const stream = chat({
-    adapter: anthropicText('claude-sonnet-4-5'),
+    adapter: anthropicText('claude-sonnet-4-6'),
     messages,
     tools: [
       codeExecutionTool(
@@ -683,7 +678,7 @@ import { openaiText } from '@tanstack/ai-openai'
 export async function POST(request: Request) {
   const { messages } = await request.json()
   const stream = chat({
-    adapter: openaiText('gpt-5.2'),
+    adapter: openaiText('gpt-5.5'),
     messages,
     tools: [
       shellTool({

package/src/activities/chat/agent-loop-strategies.ts

@@ -1,9 +1,15 @@
 import type { AgentLoopStrategy } from '../../types'
 
 /**
- * Creates a strategy that continues for a maximum number of iterations
+ * Creates a strategy that continues for a maximum number of **model turns**
+ * (iterations), not tool calls.
  *
- * @param max - Maximum number of iterations to allow
+ * One iteration can still emit many parallel tool calls. For a tool-call
+ * budget, use middleware with `onBeforeToolCall` (per-turn cap) and
+ * `onShouldContinue` (cumulative run budget) — see the docs recipe under
+ * Agentic Cycle.
+ *
+ * @param max - Maximum number of model turns to allow
  * @returns AgentLoopStrategy that stops after max iterations
  *
  * @example
@@ -13,7 +19,7 @@ import type { AgentLoopStrategy } from '../../types'
  *   model: "gpt-4o",
  *   messages: [...],
  *   tools: [weatherTool],
- *   agentLoopStrategy: maxIterations(3), // Max 3 iterations
+ *   agentLoopStrategy: maxIterations(3), // Max 3 model turns
  * });
  * ```
  */
@@ -60,7 +66,7 @@ export function untilFinishReason(
  * All strategies must return true to continue
  *
  * @param strategies - Array of strategies to combine
- * @returns AgentLoopStrategy that continues only if all strategies return true
+ * @returns AgentLoopStrategy that continues only if all strategies agree
  *
  * @example
  * ```typescript