@tanstack/ai 0.41.0 → 0.42.0

package/dist/esm/index.d.ts

@@ -16,7 +16,7 @@ export { ToolCallManager } from './activities/chat/tools/tool-calls.js';
 export { DISCOVERY_TOOL_NAME } from './activities/chat/tools/lazy-tool-manager.js';
 export type { ProviderTool } from './tools/provider-tool.js';
 export { brandProviderTool } from './tools/provider-tool.js';
-export { maxIterations, untilFinishReason, combineStrategies, } from './activities/chat/agent-loop-strategies.js';
+export { maxIterations, maxToolCalls, untilFinishReason, combineStrategies, } from './activities/chat/agent-loop-strategies.js';
 export { createToolRegistry, createFrozenRegistry, type ToolRegistry, } from './tool-registry.js';
 export type { ChatMiddleware, ChatMiddlewareContext, ChatMiddlewarePhase, ChatMiddlewareConfig, StructuredOutputMiddlewareConfig, ToolCallHookContext, BeforeToolCallDecision, AfterToolCallInfo, IterationInfo, ToolPhaseCompleteInfo, UsageInfo, FinishInfo, AbortInfo, ErrorInfo, SandboxFileEvent, SandboxFileHookEvent, ChatSandboxHooks, } from './activities/chat/middleware/index.js';
 export type { GenerationMiddleware, GenerationMiddlewareContext, GenerationActivity, GenerationUsageInfo, GenerationFinishInfo, GenerationAbortInfo, GenerationErrorInfo, AnyGenerationMiddleware, } from './activities/middleware/index.js';

package/dist/esm/index.js

@@ -12,7 +12,7 @@ import { streamToText, toHttpResponse, toHttpStream, toServerSentEventsResponse,
 import { ToolCallManager } from "./activities/chat/tools/tool-calls.js";
 import { DISCOVERY_TOOL_NAME } from "./activities/chat/tools/lazy-tool-manager.js";
 import { brandProviderTool } from "./tools/provider-tool.js";
-import { combineStrategies, maxIterations, untilFinishReason } from "./activities/chat/agent-loop-strategies.js";
+import { combineStrategies, maxIterations, maxToolCalls, untilFinishReason } from "./activities/chat/agent-loop-strategies.js";
 import { createFrozenRegistry, createToolRegistry } from "./tool-registry.js";
 import { firstSentence, renderLazyCatalogEntry } from "./activities/chat/tools/lazy-tools.js";
 import { buildBaseUsage } from "./utilities/usage.js";
@@ -89,6 +89,7 @@ export {
   isProviderExecutedToolCall,
   isStandardSchema,
   maxIterations,
+  maxToolCalls,
   mergeAgentTools,
   modelMessageToUIMessage,
   modelMessagesToUIMessages,

package/dist/esm/types.d.ts

@@ -654,12 +654,24 @@ export interface ResponseFormat<TData = any> {
  * State passed to agent loop strategy for determining whether to continue
  */
 export interface AgentLoopState {
-    /** Current iteration count (0-indexed) */
+    /** Current iteration count (0-indexed). One iteration = one model turn. */
     iterationCount: number;
     /** Current messages array */
     messages: Array<ModelMessage>;
     /** Finish reason from the last response */
     finishReason: string | null;
+    /**
+     * Cumulative tool calls counted so far in this run (model-emitted during the
+     * agent loop, including ones skipped by `maxToolCallsPerTurn`, and pending
+     * tools from the inbound message list when resumed). Not a recount of full
+     * message history; not model turns.
+     */
+    toolCallCount: number;
+    /**
+     * Tool calls in the most recent budgeted batch — a live model turn or a
+     * pending/resume batch (0 when the last phase produced no tool calls).
+     */
+    lastTurnToolCallCount: number;
 }
 /**
  * Strategy function that determines whether the agent loop should continue
@@ -669,8 +681,10 @@ export interface AgentLoopState {
  *
  * @example
  * ```typescript
- * // Continue for up to 5 iterations
+ * // Continue for up to 5 iterations (model turns, not tool calls)
  * const strategy: AgentLoopStrategy = ({ iterationCount }) => iterationCount < 5;
+ * // Cap total tool calls across the run
+ * const byTools: AgentLoopStrategy = ({ toolCallCount }) => toolCallCount < 20;
  * ```
  */
 export type AgentLoopStrategy = (state: AgentLoopState) => boolean;
@@ -702,6 +716,24 @@ export interface TextOptions<TProviderOptionsSuperset extends Record<string, any
      */
     systemPrompts?: Array<SystemPrompt>;
     agentLoopStrategy?: AgentLoopStrategy;
+    /**
+     * Maximum number of tool calls to **execute** from a single model turn (or
+     * pending/resume batch). `0` skips all execution for that batch.
+     *
+     * Models can emit many parallel tool calls in one turn. `agentLoopStrategy`
+     * (including `maxIterations` / `maxToolCalls`) is only evaluated between
+     * turns, so without this cap a single runaway turn can still execute an
+     * unbounded fan-out.
+     *
+     * When set, only the first `maxToolCallsPerTurn` calls are executed; the
+     * remainder receive error tool results so the message history stays
+     * consistent. Unset means no per-turn execution cap. Must be a non-negative
+     * finite number when set.
+     *
+     * Pair with the `maxToolCalls(n)` strategy for a cumulative **emitted**-call
+     * budget across the run (skipped calls still count toward that budget).
+     */
+    maxToolCallsPerTurn?: number;
     /**
      * Optional configuration for lazy-tool discovery (tools marked `lazy: true`).
      * Tunes how much of each lazy tool's description appears in the discovery

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/ai",
-  "version": "0.41.0",
+  "version": "0.42.0",
   "description": "Type-safe TypeScript AI SDK for streaming chat, tool calling, agents, structured outputs, and multimodal generation.",
   "author": "Tanner Linsley",
   "license": "MIT",

package/skills/ai-core/chat-experience/SKILL.md

@@ -409,6 +409,64 @@ export const Route = createFileRoute('/api/chat')({
 })
 ```
 
+### 7. Queueing Messages Sent While Streaming
+
+By default, a `sendMessage` call that arrives while a stream is in flight is
+**queued** and sent automatically once the run settles **successfully** —
+this is a behavior change: such sends used to be silently dropped. Configure
+it with the `queue` option on `useChat`:
+
+```typescript
+import { useChat, fetchServerSentEvents } from '@tanstack/ai-react'
+
+const { messages, queue, sendMessage, cancelQueued, isLoading } = useChat({
+  connection: fetchServerSentEvents('/api/chat'),
+  queue: { whenBusy: 'queue', drain: 'fifo', maxSize: 5, onOverflow: 'reject' },
+})
+```
+
+- **`whenBusy`** — `'queue'` (default) holds the message until a successful
+  settle; `'drop'` ignores the send (never appears in `queue`/`messages`);
+  `'interrupt'` aborts the current stream and sends immediately (unlike
+  `stop()`, does **not** flush already-queued items — they drain after the
+  interrupting send **succeeds**).
+- **`drain`** — `'fifo'` (default) sends queued items one at a time in
+  order; `'batch'` merges everything queued into a single send once the
+  run settles successfully.
+- **`maxSize`** / **`onOverflow`** — cap the queue length; `'reject'`
+  (default) silently ignores overflow sends (does not throw),
+  `'drop-oldest'` evicts the oldest queued item to make room.
+
+The top-level `queue` option also accepts a plain `WhenBusy` string
+shorthand (e.g. `queue: 'interrupt'`) or a `QueueStrategy` function for
+per-send action control. Strategy form always drains FIFO; actions are
+`'queue' | 'drop' | 'interrupt'`.
+
+**Drain vs flush:** queued messages auto-send only after a **successful**
+settle. They are **discarded** on stream error/abort of the active
+generation, `stop()`, `clear()`, `unsubscribe()`, and `reload()`.
+`interrupt` does not flush.
+
+`queue: Array<QueuedMessage>` (`{ id, content, createdAt }`) is separate
+from `messages` — render pending sends distinctly and cancel with
+`cancelQueued(id)`:
+
+```typescript
+{queue.map((q) => (
+  <div key={q.id}>
+    {typeof q.content === 'string' ? q.content : '[attachment]'}
+    <button onClick={() => cancelQueued(q.id)}>Cancel</button>
+  </div>
+))}
+```
+
+Override the configured policy for a single send with the second argument
+to `sendMessage`:
+
+```typescript
+sendMessage('Never mind, do this instead', { whenBusy: 'interrupt' })
+```
+
 ## Common Mistakes
 
 ### a. CRITICAL: Using Vercel AI SDK patterns (streamText, generateText)

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

@@ -375,6 +375,8 @@ export async function POST(request: Request) {
     adapter: openaiText('gpt-5.5'),
     messages,
     tools: [getProducts, compareProducts],
+    // maxIterations bounds model turns, not tool calls. Prefer maxToolCalls
+    // (and maxToolCallsPerTurn) when you need a tool-call budget.
     agentLoopStrategy: maxIterations(20),
   })
   return toServerSentEventsResponse(stream)

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

@@ -1,9 +1,14 @@
 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. Prefer
+ * {@link maxToolCalls} (and optionally `maxToolCallsPerTurn` on `chat()`)
+ * when you need a tool-call budget.
+ *
+ * @param max - Maximum number of model turns to allow
  * @returns AgentLoopStrategy that stops after max iterations
  *
  * @example
@@ -13,7 +18,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
  * });
  * ```
  */
@@ -21,6 +26,40 @@ export function maxIterations(max: number): AgentLoopStrategy {
   return ({ iterationCount }) => iterationCount < max
 }
 
+/**
+ * Creates a strategy that continues while `toolCallCount < max`.
+ *
+ * Unlike {@link maxIterations} (which counts model turns), this bounds
+ * **emitted** tool calls counted during the run (including ones skipped by
+ * `maxToolCallsPerTurn`). Strategies only run between turns, so the turn that
+ * crosses `max` is not truncated — the final count (and executions, unless
+ * `maxToolCallsPerTurn` is set) may exceed `max`. Pair with
+ * `chat({ maxToolCallsPerTurn })` to also cap parallel fan-out inside a single
+ * turn.
+ *
+ * @param max - Maximum cumulative emitted tool calls before stopping further turns
+ * @returns AgentLoopStrategy that returns true while `toolCallCount < max`
+ *
+ * @example
+ * ```typescript
+ * import { chat, combineStrategies, maxIterations, maxToolCalls } from '@tanstack/ai'
+ *
+ * const stream = chat({
+ *   adapter: openaiText('gpt-4o'),
+ *   messages: [...],
+ *   tools: [weatherTool],
+ *   maxToolCallsPerTurn: 10,
+ *   agentLoopStrategy: combineStrategies([
+ *     maxIterations(20),
+ *     maxToolCalls(20),
+ *   ]),
+ * })
+ * ```
+ */
+export function maxToolCalls(max: number): AgentLoopStrategy {
+  return ({ toolCallCount }) => toolCallCount < max
+}
+
 /**
  * Creates a strategy that continues until a specific finish reason is encountered
  *
@@ -71,6 +110,7 @@ export function untilFinishReason(
  *   tools: [weatherTool],
  *   agentLoopStrategy: combineStrategies([
  *     maxIterations(10),
+ *     maxToolCalls(20),
  *     ({ messages }) => messages.length < 100,
  *   ]),
  * });

package/src/activities/chat/index.ts

@@ -240,6 +240,11 @@ export interface TextActivityOptions<
   abortController?: TextOptions['abortController']
   /** Strategy for controlling the agent loop */
   agentLoopStrategy?: TextOptions['agentLoopStrategy']
+  /**
+   * Cap how many tool calls from a single model turn are executed.
+   * Excess calls receive error results. See {@link TextOptions.maxToolCallsPerTurn}.
+   */
+  maxToolCallsPerTurn?: TextOptions['maxToolCallsPerTurn']
   /**
    * Optional configuration for lazy-tool discovery (tools marked `lazy: true`).
    * Tunes how much of each lazy tool's description appears in the discovery
@@ -473,6 +478,23 @@ interface TextEngineConfig<
 type ToolPhaseResult = 'continue' | 'stop' | 'wait'
 type CyclePhase = 'processText' | 'executeToolCalls'
 
+/**
+ * Validate and normalize `maxToolCallsPerTurn`.
+ * Unset → unlimited. `0` → execute none. Negatives / non-finite → throw
+ * (Array#slice treats negatives as "from end", which is not a useful cap).
+ */
+function resolveMaxToolCallsPerTurn(
+  cap: number | undefined,
+): number | undefined {
+  if (cap == null) return undefined
+  if (!Number.isFinite(cap) || cap < 0) {
+    throw new Error(
+      `maxToolCallsPerTurn must be a non-negative finite number, got ${cap}`,
+    )
+  }
+  return Math.floor(cap)
+}
+
 /**
  * Combine two optional AbortSignals into one that aborts when either does.
  * Returns the other signal directly when one is absent or already aborted.
@@ -519,6 +541,12 @@ class TextEngine<
 
   private messages: Array<ModelMessage>
   private iterationCount = 0
+  /** Cumulative tool calls counted in this run (emitted + pending resume). */
+  private toolCallCount = 0
+  /** Tool calls in the most recent budgeted batch (0 when none). */
+  private lastTurnToolCallCount = 0
+  /** Tool call IDs already counted toward `toolCallCount` (avoids double-count on resume). */
+  private readonly countedToolCallIds = new Set<string>()
   private lastFinishReason: string | null = null
   private streamStartTime = 0
   private totalChunkCount = 0
@@ -534,6 +562,7 @@ class TextEngine<
   private earlyTermination = false
   private toolPhase: ToolPhaseResult = 'continue'
   private cyclePhase: CyclePhase = 'processText'
+  private readonly maxToolCallsPerTurn: number | undefined
   // Client state extracted from initial messages (before conversion to ModelMessage)
   private readonly initialApprovals: Map<string, boolean>
   private readonly initialClientToolResults: Map<string, any>
@@ -599,6 +628,9 @@ class TextEngine<
     this.systemPrompts = config.params.systemPrompts || []
     this.loopStrategy =
       config.params.agentLoopStrategy || maxIterationsStrategy(5)
+    this.maxToolCallsPerTurn = resolveMaxToolCallsPerTurn(
+      config.params.maxToolCallsPerTurn,
+    )
     this.initialMessageCount = config.params.messages.length
 
     // Extract client state (approvals, client tool results) from original messages BEFORE conversion
@@ -1302,9 +1334,14 @@ class TextEngine<
 
     const finishEvent = this.createSyntheticFinishedEvent()
 
+    // Same fan-out budget as live model turns (seeded history / resume).
+    // Count is deduped so wait→resume after a live turn does not double-count.
+    const { toExecute: budgetedToolCalls, skippedResults } =
+      this.applyToolCallBudget(pendingToolCalls)
+
     // Handle undiscovered lazy tool calls with self-correcting error messages
     const undiscoveredLazyResults: Array<ToolResult> = []
-    const executablePendingCalls = pendingToolCalls.filter((tc) => {
+    const executablePendingCalls = budgetedToolCalls.filter((tc) => {
       if (this.lazyToolManager.isUndiscoveredLazyTool(tc.function.name)) {
         undiscoveredLazyResults.push({
           toolCallId: tc.id,
@@ -1321,16 +1358,27 @@ class TextEngine<
       return true
     })
 
-    if (undiscoveredLazyResults.length > 0) {
-      for (const chunk of this.buildToolResultChunks(
-        undiscoveredLazyResults,
-        finishEvent,
-      )) {
-        yield* this.pipeThroughMiddleware(chunk)
-      }
+    // Non-executed outcomes (undiscovered lazy + per-turn fan-out skips).
+    // Emitted after executed results so the stream prefers real results first.
+    const deferredErrorResults = [...undiscoveredLazyResults, ...skippedResults]
+
+    // Build args lookup so buildToolResultChunks can emit TOOL_CALL_START +
+    // TOOL_CALL_ARGS before TOOL_CALL_END during continuation re-executions.
+    const argsMap = new Map<string, string>()
+    for (const tc of pendingToolCalls) {
+      argsMap.set(tc.id, tc.function.arguments)
     }
 
     if (executablePendingCalls.length === 0) {
+      if (deferredErrorResults.length > 0) {
+        for (const chunk of this.buildToolResultChunks(
+          deferredErrorResults,
+          finishEvent,
+          argsMap,
+        )) {
+          yield* this.pipeThroughMiddleware(chunk)
+        }
+      }
       return 'continue'
     }
 
@@ -1384,28 +1432,23 @@ class TextEngine<
       return 'stop'
     }
 
+    const allResults = [...executionResult.results, ...deferredErrorResults]
+
     // Notify middleware of tool phase completion (devtools emits aggregate events here)
     await this.middlewareRunner.runOnToolPhaseComplete(this.middlewareCtx, {
       toolCalls: pendingToolCalls,
-      results: executionResult.results,
+      results: allResults,
       needsApproval: executionResult.needsApproval,
       needsClientExecution: executionResult.needsClientExecution,
     })
 
-    // Build args lookup so buildToolResultChunks can emit TOOL_CALL_START +
-    // TOOL_CALL_ARGS before TOOL_CALL_END during continuation re-executions.
-    const argsMap = new Map<string, string>()
-    for (const tc of pendingToolCalls) {
-      argsMap.set(tc.id, tc.function.arguments)
-    }
-
     if (
       executionResult.needsApproval.length > 0 ||
       executionResult.needsClientExecution.length > 0
     ) {
-      if (executionResult.results.length > 0) {
+      if (allResults.length > 0) {
         for (const chunk of this.buildToolResultChunks(
-          executionResult.results,
+          allResults,
           finishEvent,
           argsMap,
         )) {
@@ -1432,7 +1475,7 @@ class TextEngine<
     }
 
     const toolResultChunks = this.buildToolResultChunks(
-      executionResult.results,
+      allResults,
       finishEvent,
       argsMap,
     )
@@ -1446,6 +1489,8 @@ class TextEngine<
 
   private async *processToolCalls(): AsyncGenerator<StreamChunk, void, void> {
     if (!this.shouldExecuteToolPhase()) {
+      // Text-only turn — clear per-turn count so strategies see 0 tools.
+      this.lastTurnToolCallCount = 0
       this.setToolPhase('stop')
       return
     }
@@ -1454,15 +1499,20 @@ class TextEngine<
     const finishEvent = this.finishedEvent
 
     if (!finishEvent || toolCalls.length === 0) {
+      this.lastTurnToolCallCount = 0
       this.setToolPhase('stop')
       return
     }
 
+    // Count every model-emitted tool call (including ones we may skip).
+    const { toExecute: budgetedToolCalls, skippedResults } =
+      this.applyToolCallBudget(toolCalls)
+
     this.addAssistantToolCallMessage(toolCalls)
 
     // Handle undiscovered lazy tool calls with self-correcting error messages
     const undiscoveredLazyResults: Array<ToolResult> = []
-    const executableToolCalls = toolCalls.filter((tc) => {
+    const executableToolCalls = budgetedToolCalls.filter((tc) => {
       if (this.lazyToolManager.isUndiscoveredLazyTool(tc.function.name)) {
         undiscoveredLazyResults.push({
           toolCallId: tc.id,
@@ -1479,17 +1529,21 @@ class TextEngine<
       return true
     })
 
-    if (undiscoveredLazyResults.length > 0 && this.finishedEvent) {
-      for (const chunk of this.buildToolResultChunks(
-        undiscoveredLazyResults,
-        this.finishedEvent,
-      )) {
-        yield* this.pipeThroughMiddleware(chunk)
-      }
-    }
+    // Non-executed outcomes (undiscovered lazy + per-turn fan-out skips).
+    // Emitted after executed results so the stream prefers real results first.
+    const deferredErrorResults = [...undiscoveredLazyResults, ...skippedResults]
 
     if (executableToolCalls.length === 0) {
-      // All tool calls were undiscovered lazy tools — errors emitted, continue loop
+      // All tool calls were undiscovered lazy tools and/or skipped by the
+      // per-turn fan-out cap — errors emitted, continue loop (strategy may stop).
+      if (deferredErrorResults.length > 0) {
+        for (const chunk of this.buildToolResultChunks(
+          deferredErrorResults,
+          finishEvent,
+        )) {
+          yield* this.pipeThroughMiddleware(chunk)
+        }
+      }
       this.toolCallManager.clear()
       this.setToolPhase('continue')
       return
@@ -1548,10 +1602,13 @@ class TextEngine<
       return
     }
 
+    // Executed results first, then deferred errors (fan-out skips / undiscovered)
+    const allResults = [...executionResult.results, ...deferredErrorResults]
+
     // Notify middleware of tool phase completion (devtools emits aggregate events here)
     await this.middlewareRunner.runOnToolPhaseComplete(this.middlewareCtx, {
       toolCalls,
-      results: executionResult.results,
+      results: allResults,
       needsApproval: executionResult.needsApproval,
       needsClientExecution: executionResult.needsClientExecution,
     })
@@ -1560,9 +1617,9 @@ class TextEngine<
       executionResult.needsApproval.length > 0 ||
       executionResult.needsClientExecution.length > 0
     ) {
-      if (executionResult.results.length > 0) {
+      if (allResults.length > 0) {
         for (const chunk of this.buildToolResultChunks(
-          executionResult.results,
+          allResults,
           finishEvent,
         )) {
           yield* this.pipeThroughMiddleware(chunk)
@@ -1587,10 +1644,7 @@ class TextEngine<
       return
     }
 
-    const toolResultChunks = this.buildToolResultChunks(
-      executionResult.results,
-      finishEvent,
-    )
+    const toolResultChunks = this.buildToolResultChunks(allResults, finishEvent)
 
     for (const chunk of toolResultChunks) {
       yield* this.pipeThroughMiddleware(chunk)
@@ -1943,10 +1997,64 @@ class TextEngine<
         iterationCount: this.iterationCount,
         messages: this.messages,
         finishReason: this.lastFinishReason,
+        toolCallCount: this.toolCallCount,
+        lastTurnToolCallCount: this.lastTurnToolCallCount,
       }) && this.toolPhase === 'continue'
     )
   }
 
+  /**
+   * Record tool calls (deduped by id) and return the subset that should be
+   * executed after applying `maxToolCallsPerTurn`. Excess calls get synthetic
+   * error results so every tool_call still has a matching result.
+   *
+   * Used for both live model turns and pending/resume batches. IDs already
+   * counted in this run (e.g. wait→resume after a live turn) are not
+   * re-added to `toolCallCount`.
+   */
+  private applyToolCallBudget(toolCalls: Array<ToolCall>): {
+    toExecute: Array<ToolCall>
+    skippedResults: Array<ToolResult>
+  } {
+    this.lastTurnToolCallCount = toolCalls.length
+    let newlyCounted = 0
+    for (const tc of toolCalls) {
+      if (!this.countedToolCallIds.has(tc.id)) {
+        this.countedToolCallIds.add(tc.id)
+        newlyCounted++
+      }
+    }
+    this.toolCallCount += newlyCounted
+
+    const cap = this.maxToolCallsPerTurn
+    if (cap == null || toolCalls.length <= cap) {
+      return { toExecute: toolCalls, skippedResults: [] }
+    }
+
+    this.logger.agentLoop(
+      `maxToolCallsPerTurn=${cap} skipped=${toolCalls.length - cap}`,
+      {
+        maxToolCallsPerTurn: cap,
+        emitted: toolCalls.length,
+        skipped: toolCalls.length - cap,
+      },
+    )
+
+    const toExecute = toolCalls.slice(0, cap)
+    const skippedResults: Array<ToolResult> = toolCalls
+      .slice(cap)
+      .map((tc) => ({
+        toolCallId: tc.id,
+        toolName: tc.function.name,
+        result: {
+          error: `Skipped: exceeded maxToolCallsPerTurn (${cap})`,
+        },
+        state: 'output-error' as const,
+      }))
+
+    return { toExecute, skippedResults }
+  }
+
   private isAborted(): boolean {
     return !!this.effectiveSignal?.aborted
   }

package/src/index.ts

@@ -93,6 +93,7 @@ export { brandProviderTool } from './tools/provider-tool'
 // Agent loop strategies
 export {
   maxIterations,
+  maxToolCalls,
   untilFinishReason,
   combineStrategies,
 } from './activities/chat/agent-loop-strategies'

package/src/types.ts

@@ -831,12 +831,24 @@ export interface ResponseFormat<TData = any> {
  * State passed to agent loop strategy for determining whether to continue
  */
 export interface AgentLoopState {
-  /** Current iteration count (0-indexed) */
+  /** Current iteration count (0-indexed). One iteration = one model turn. */
   iterationCount: number
   /** Current messages array */
   messages: Array<ModelMessage>
   /** Finish reason from the last response */
   finishReason: string | null
+  /**
+   * Cumulative tool calls counted so far in this run (model-emitted during the
+   * agent loop, including ones skipped by `maxToolCallsPerTurn`, and pending
+   * tools from the inbound message list when resumed). Not a recount of full
+   * message history; not model turns.
+   */
+  toolCallCount: number
+  /**
+   * Tool calls in the most recent budgeted batch — a live model turn or a
+   * pending/resume batch (0 when the last phase produced no tool calls).
+   */
+  lastTurnToolCallCount: number
 }
 
 /**
@@ -847,8 +859,10 @@ export interface AgentLoopState {
  *
  * @example
  * ```typescript
- * // Continue for up to 5 iterations
+ * // Continue for up to 5 iterations (model turns, not tool calls)
  * const strategy: AgentLoopStrategy = ({ iterationCount }) => iterationCount < 5;
+ * // Cap total tool calls across the run
+ * const byTools: AgentLoopStrategy = ({ toolCallCount }) => toolCallCount < 20;
  * ```
  */
 export type AgentLoopStrategy = (state: AgentLoopState) => boolean
@@ -885,6 +899,24 @@ export interface TextOptions<
    */
   systemPrompts?: Array<SystemPrompt>
   agentLoopStrategy?: AgentLoopStrategy
+  /**
+   * Maximum number of tool calls to **execute** from a single model turn (or
+   * pending/resume batch). `0` skips all execution for that batch.
+   *
+   * Models can emit many parallel tool calls in one turn. `agentLoopStrategy`
+   * (including `maxIterations` / `maxToolCalls`) is only evaluated between
+   * turns, so without this cap a single runaway turn can still execute an
+   * unbounded fan-out.
+   *
+   * When set, only the first `maxToolCallsPerTurn` calls are executed; the
+   * remainder receive error tool results so the message history stays
+   * consistent. Unset means no per-turn execution cap. Must be a non-negative
+   * finite number when set.
+   *
+   * Pair with the `maxToolCalls(n)` strategy for a cumulative **emitted**-call
+   * budget across the run (skipped calls still count toward that budget).
+   */
+  maxToolCallsPerTurn?: number
   /**
    * Optional configuration for lazy-tool discovery (tools marked `lazy: true`).
    * Tunes how much of each lazy tool's description appears in the discovery