@tanstack/ai 0.41.0 → 0.42.0

package/dist/esm/activities/chat/agent-loop-strategies.d.ts

@@ -1,8 +1,13 @@
 import { AgentLoopStrategy } from '../../types.js';
 /**
- * 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
@@ -12,11 +17,42 @@ import { AgentLoopStrategy } from '../../types.js';
  *   model: "gpt-4o",
  *   messages: [...],
  *   tools: [weatherTool],
- *   agentLoopStrategy: maxIterations(3), // Max 3 iterations
+ *   agentLoopStrategy: maxIterations(3), // Max 3 model turns
  * });
  * ```
  */
 export declare function maxIterations(max: number): AgentLoopStrategy;
+/**
+ * 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 declare function maxToolCalls(max: number): AgentLoopStrategy;
 /**
  * Creates a strategy that continues until a specific finish reason is encountered
  *
@@ -51,6 +87,7 @@ export declare function untilFinishReason(stopReasons: Array<string>): AgentLoop
  *   tools: [weatherTool],
  *   agentLoopStrategy: combineStrategies([
  *     maxIterations(10),
+ *     maxToolCalls(20),
  *     ({ messages }) => messages.length < 100,
  *   ]),
  * });

package/dist/esm/activities/chat/agent-loop-strategies.js

@@ -1,6 +1,9 @@
 function maxIterations(max) {
   return ({ iterationCount }) => iterationCount < max;
 }
+function maxToolCalls(max) {
+  return ({ toolCallCount }) => toolCallCount < max;
+}
 function untilFinishReason(stopReasons) {
   return ({ finishReason, iterationCount }) => {
     if (iterationCount === 0) return true;
@@ -18,6 +21,7 @@ function combineStrategies(strategies) {
 export {
   combineStrategies,
   maxIterations,
+  maxToolCalls,
   untilFinishReason
 };
 //# sourceMappingURL=agent-loop-strategies.js.map

package/dist/esm/activities/chat/agent-loop-strategies.js.map

@@ -1 +1 @@
-{"version":3,"file":"agent-loop-strategies.js","sources":["../../../../src/activities/chat/agent-loop-strategies.ts"],"sourcesContent":["import type { AgentLoopStrategy } from '../../types'\n\n/**\n * Creates a strategy that continues for a maximum number of iterations\n *\n * @param max - Maximum number of iterations to allow\n * @returns AgentLoopStrategy that stops after max iterations\n *\n * @example\n * ```typescript\n * const stream = chat({\n *   adapter: openaiText(),\n *   model: \"gpt-4o\",\n *   messages: [...],\n *   tools: [weatherTool],\n *   agentLoopStrategy: maxIterations(3), // Max 3 iterations\n * });\n * ```\n */\nexport function maxIterations(max: number): AgentLoopStrategy {\n  return ({ iterationCount }) => iterationCount < max\n}\n\n/**\n * Creates a strategy that continues until a specific finish reason is encountered\n *\n * @param stopReasons - Finish reasons that should stop the loop\n * @returns AgentLoopStrategy that stops on specific finish reasons\n *\n * @example\n * ```typescript\n * const stream = chat({\n *   adapter: openaiText(),\n *   model: \"gpt-4o\",\n *   messages: [...],\n *   tools: [weatherTool],\n *   agentLoopStrategy: untilFinishReason([\"stop\", \"length\"]),\n * });\n * ```\n */\nexport function untilFinishReason(\n  stopReasons: Array<string>,\n): AgentLoopStrategy {\n  return ({ finishReason, iterationCount }) => {\n    // Always allow at least one iteration\n    if (iterationCount === 0) return true\n\n    // Stop if we hit a stop reason\n    if (finishReason && stopReasons.includes(finishReason)) {\n      return false\n    }\n\n    // Otherwise continue\n    return true\n  }\n}\n\n/**\n * Creates a strategy that combines multiple strategies with AND logic\n * All strategies must return true to continue\n *\n * @param strategies - Array of strategies to combine\n * @returns AgentLoopStrategy that continues only if all strategies return true\n *\n * @example\n * ```typescript\n * const stream = chat({\n *   adapter: openaiText(),\n *   model: \"gpt-4o\",\n *   messages: [...],\n *   tools: [weatherTool],\n *   agentLoopStrategy: combineStrategies([\n *     maxIterations(10),\n *     ({ messages }) => messages.length < 100,\n *   ]),\n * });\n * ```\n */\nexport function combineStrategies(\n  strategies: Array<AgentLoopStrategy>,\n): AgentLoopStrategy {\n  return (state) => {\n    return strategies.every((strategy) => strategy(state))\n  }\n}\n"],"names":[],"mappings":"AAmBO,SAAS,cAAc,KAAgC;AAC5D,SAAO,CAAC,EAAE,qBAAqB,iBAAiB;AAClD;AAmBO,SAAS,kBACd,aACmB;AACnB,SAAO,CAAC,EAAE,cAAc,qBAAqB;AAE3C,QAAI,mBAAmB,EAAG,QAAO;AAGjC,QAAI,gBAAgB,YAAY,SAAS,YAAY,GAAG;AACtD,aAAO;AAAA,IACT;AAGA,WAAO;AAAA,EACT;AACF;AAuBO,SAAS,kBACd,YACmB;AACnB,SAAO,CAAC,UAAU;AAChB,WAAO,WAAW,MAAM,CAAC,aAAa,SAAS,KAAK,CAAC;AAAA,EACvD;AACF;"}
+{"version":3,"file":"agent-loop-strategies.js","sources":["../../../../src/activities/chat/agent-loop-strategies.ts"],"sourcesContent":["import type { AgentLoopStrategy } from '../../types'\n\n/**\n * Creates a strategy that continues for a maximum number of **model turns**\n * (iterations), not tool calls.\n *\n * One iteration can still emit many parallel tool calls. Prefer\n * {@link maxToolCalls} (and optionally `maxToolCallsPerTurn` on `chat()`)\n * when you need a tool-call budget.\n *\n * @param max - Maximum number of model turns to allow\n * @returns AgentLoopStrategy that stops after max iterations\n *\n * @example\n * ```typescript\n * const stream = chat({\n *   adapter: openaiText(),\n *   model: \"gpt-4o\",\n *   messages: [...],\n *   tools: [weatherTool],\n *   agentLoopStrategy: maxIterations(3), // Max 3 model turns\n * });\n * ```\n */\nexport function maxIterations(max: number): AgentLoopStrategy {\n  return ({ iterationCount }) => iterationCount < max\n}\n\n/**\n * Creates a strategy that continues while `toolCallCount < max`.\n *\n * Unlike {@link maxIterations} (which counts model turns), this bounds\n * **emitted** tool calls counted during the run (including ones skipped by\n * `maxToolCallsPerTurn`). Strategies only run between turns, so the turn that\n * crosses `max` is not truncated — the final count (and executions, unless\n * `maxToolCallsPerTurn` is set) may exceed `max`. Pair with\n * `chat({ maxToolCallsPerTurn })` to also cap parallel fan-out inside a single\n * turn.\n *\n * @param max - Maximum cumulative emitted tool calls before stopping further turns\n * @returns AgentLoopStrategy that returns true while `toolCallCount < max`\n *\n * @example\n * ```typescript\n * import { chat, combineStrategies, maxIterations, maxToolCalls } from '@tanstack/ai'\n *\n * const stream = chat({\n *   adapter: openaiText('gpt-4o'),\n *   messages: [...],\n *   tools: [weatherTool],\n *   maxToolCallsPerTurn: 10,\n *   agentLoopStrategy: combineStrategies([\n *     maxIterations(20),\n *     maxToolCalls(20),\n *   ]),\n * })\n * ```\n */\nexport function maxToolCalls(max: number): AgentLoopStrategy {\n  return ({ toolCallCount }) => toolCallCount < max\n}\n\n/**\n * Creates a strategy that continues until a specific finish reason is encountered\n *\n * @param stopReasons - Finish reasons that should stop the loop\n * @returns AgentLoopStrategy that stops on specific finish reasons\n *\n * @example\n * ```typescript\n * const stream = chat({\n *   adapter: openaiText(),\n *   model: \"gpt-4o\",\n *   messages: [...],\n *   tools: [weatherTool],\n *   agentLoopStrategy: untilFinishReason([\"stop\", \"length\"]),\n * });\n * ```\n */\nexport function untilFinishReason(\n  stopReasons: Array<string>,\n): AgentLoopStrategy {\n  return ({ finishReason, iterationCount }) => {\n    // Always allow at least one iteration\n    if (iterationCount === 0) return true\n\n    // Stop if we hit a stop reason\n    if (finishReason && stopReasons.includes(finishReason)) {\n      return false\n    }\n\n    // Otherwise continue\n    return true\n  }\n}\n\n/**\n * Creates a strategy that combines multiple strategies with AND logic\n * All strategies must return true to continue\n *\n * @param strategies - Array of strategies to combine\n * @returns AgentLoopStrategy that continues only if all strategies return true\n *\n * @example\n * ```typescript\n * const stream = chat({\n *   adapter: openaiText(),\n *   model: \"gpt-4o\",\n *   messages: [...],\n *   tools: [weatherTool],\n *   agentLoopStrategy: combineStrategies([\n *     maxIterations(10),\n *     maxToolCalls(20),\n *     ({ messages }) => messages.length < 100,\n *   ]),\n * });\n * ```\n */\nexport function combineStrategies(\n  strategies: Array<AgentLoopStrategy>,\n): AgentLoopStrategy {\n  return (state) => {\n    return strategies.every((strategy) => strategy(state))\n  }\n}\n"],"names":[],"mappings":"AAwBO,SAAS,cAAc,KAAgC;AAC5D,SAAO,CAAC,EAAE,qBAAqB,iBAAiB;AAClD;AAgCO,SAAS,aAAa,KAAgC;AAC3D,SAAO,CAAC,EAAE,oBAAoB,gBAAgB;AAChD;AAmBO,SAAS,kBACd,aACmB;AACnB,SAAO,CAAC,EAAE,cAAc,qBAAqB;AAE3C,QAAI,mBAAmB,EAAG,QAAO;AAGjC,QAAI,gBAAgB,YAAY,SAAS,YAAY,GAAG;AACtD,aAAO;AAAA,IACT;AAGA,WAAO;AAAA,EACT;AACF;AAwBO,SAAS,kBACd,YACmB;AACnB,SAAO,CAAC,UAAU;AAChB,WAAO,WAAW,MAAM,CAAC,aAAa,SAAS,KAAK,CAAC;AAAA,EACvD;AACF;"}

package/dist/esm/activities/chat/index.d.ts

@@ -93,6 +93,11 @@ export interface TextActivityOptions<TAdapter extends AnyTextAdapter, TSchema ex
     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

package/dist/esm/activities/chat/index.js

@@ -20,6 +20,15 @@ const kind = "text";
 function createChatOptions(options) {
   return options;
 }
+function resolveMaxToolCallsPerTurn(cap) {
+  if (cap == null) return void 0;
+  if (!Number.isFinite(cap) || cap < 0) {
+    throw new Error(
+      `maxToolCallsPerTurn must be a non-negative finite number, got ${cap}`
+    );
+  }
+  return Math.floor(cap);
+}
 function combineAbortSignals(a, b) {
   if (!a) return b;
   if (!b) return a;
@@ -48,6 +57,12 @@ class TextEngine {
   effectiveSignal;
   messages;
   iterationCount = 0;
+  /** Cumulative tool calls counted in this run (emitted + pending resume). */
+  toolCallCount = 0;
+  /** Tool calls in the most recent budgeted batch (0 when none). */
+  lastTurnToolCallCount = 0;
+  /** Tool call IDs already counted toward `toolCallCount` (avoids double-count on resume). */
+  countedToolCallIds = /* @__PURE__ */ new Set();
   lastFinishReason = null;
   streamStartTime = 0;
   totalChunkCount = 0;
@@ -62,6 +77,7 @@ class TextEngine {
   earlyTermination = false;
   toolPhase = "continue";
   cyclePhase = "processText";
+  maxToolCallsPerTurn;
   // Client state extracted from initial messages (before conversion to ModelMessage)
   initialApprovals;
   initialClientToolResults;
@@ -107,6 +123,9 @@ class TextEngine {
     this.params = config.params;
     this.systemPrompts = config.params.systemPrompts || [];
     this.loopStrategy = config.params.agentLoopStrategy || maxIterations(5);
+    this.maxToolCallsPerTurn = resolveMaxToolCallsPerTurn(
+      config.params.maxToolCallsPerTurn
+    );
     this.initialMessageCount = config.params.messages.length;
     const { approvals, clientToolResults } = this.extractClientStateFromOriginalMessages(
       config.params.messages
@@ -584,8 +603,9 @@ class TextEngine {
       return "continue";
     }
     const finishEvent = this.createSyntheticFinishedEvent();
+    const { toExecute: budgetedToolCalls, skippedResults } = this.applyToolCallBudget(pendingToolCalls);
     const undiscoveredLazyResults = [];
-    const executablePendingCalls = pendingToolCalls.filter((tc) => {
+    const executablePendingCalls = budgetedToolCalls.filter((tc) => {
       if (this.lazyToolManager.isUndiscoveredLazyTool(tc.function.name)) {
         undiscoveredLazyResults.push({
           toolCallId: tc.id,
@@ -601,15 +621,21 @@ class TextEngine {
       }
       return true;
     });
-    if (undiscoveredLazyResults.length > 0) {
-      for (const chunk of this.buildToolResultChunks(
-        undiscoveredLazyResults,
-        finishEvent
-      )) {
-        yield* this.pipeThroughMiddleware(chunk);
-      }
+    const deferredErrorResults = [...undiscoveredLazyResults, ...skippedResults];
+    const argsMap = /* @__PURE__ */ new Map();
+    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";
     }
     const { approvals, clientToolResults } = this.collectClientState();
@@ -656,20 +682,17 @@ class TextEngine {
       this.setToolPhase("stop");
       return "stop";
     }
+    const allResults = [...executionResult.results, ...deferredErrorResults];
     await this.middlewareRunner.runOnToolPhaseComplete(this.middlewareCtx, {
       toolCalls: pendingToolCalls,
-      results: executionResult.results,
+      results: allResults,
       needsApproval: executionResult.needsApproval,
       needsClientExecution: executionResult.needsClientExecution
     });
-    const argsMap = /* @__PURE__ */ new Map();
-    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
         )) {
@@ -692,7 +715,7 @@ class TextEngine {
       return "wait";
     }
     const toolResultChunks = this.buildToolResultChunks(
-      executionResult.results,
+      allResults,
       finishEvent,
       argsMap
     );
@@ -703,18 +726,21 @@ class TextEngine {
   }
   async *processToolCalls() {
     if (!this.shouldExecuteToolPhase()) {
+      this.lastTurnToolCallCount = 0;
       this.setToolPhase("stop");
       return;
     }
     const toolCalls = this.toolCallManager.getToolCalls();
     const finishEvent = this.finishedEvent;
     if (!finishEvent || toolCalls.length === 0) {
+      this.lastTurnToolCallCount = 0;
       this.setToolPhase("stop");
       return;
     }
+    const { toExecute: budgetedToolCalls, skippedResults } = this.applyToolCallBudget(toolCalls);
     this.addAssistantToolCallMessage(toolCalls);
     const undiscoveredLazyResults = [];
-    const executableToolCalls = toolCalls.filter((tc) => {
+    const executableToolCalls = budgetedToolCalls.filter((tc) => {
       if (this.lazyToolManager.isUndiscoveredLazyTool(tc.function.name)) {
         undiscoveredLazyResults.push({
           toolCallId: tc.id,
@@ -730,15 +756,16 @@ class TextEngine {
       }
       return true;
     });
-    if (undiscoveredLazyResults.length > 0 && this.finishedEvent) {
-      for (const chunk of this.buildToolResultChunks(
-        undiscoveredLazyResults,
-        this.finishedEvent
-      )) {
-        yield* this.pipeThroughMiddleware(chunk);
-      }
-    }
+    const deferredErrorResults = [...undiscoveredLazyResults, ...skippedResults];
     if (executableToolCalls.length === 0) {
+      if (deferredErrorResults.length > 0) {
+        for (const chunk of this.buildToolResultChunks(
+          deferredErrorResults,
+          finishEvent
+        )) {
+          yield* this.pipeThroughMiddleware(chunk);
+        }
+      }
       this.toolCallManager.clear();
       this.setToolPhase("continue");
       return;
@@ -789,16 +816,17 @@ class TextEngine {
       this.setToolPhase("stop");
       return;
     }
+    const allResults = [...executionResult.results, ...deferredErrorResults];
     await this.middlewareRunner.runOnToolPhaseComplete(this.middlewareCtx, {
       toolCalls,
-      results: executionResult.results,
+      results: allResults,
       needsApproval: executionResult.needsApproval,
       needsClientExecution: executionResult.needsClientExecution
     });
     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
         )) {
           yield* this.pipeThroughMiddleware(chunk);
@@ -819,10 +847,7 @@ class TextEngine {
       this.setToolPhase("wait");
       return;
     }
-    const toolResultChunks = this.buildToolResultChunks(
-      executionResult.results,
-      finishEvent
-    );
+    const toolResultChunks = this.buildToolResultChunks(allResults, finishEvent);
     for (const chunk of toolResultChunks) {
       yield* this.pipeThroughMiddleware(chunk);
     }
@@ -1060,9 +1085,53 @@ class TextEngine {
     return this.loopStrategy({
       iterationCount: this.iterationCount,
       messages: this.messages,
-      finishReason: this.lastFinishReason
+      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`.
+   */
+  applyToolCallBudget(toolCalls) {
+    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 = toolCalls.slice(cap).map((tc) => ({
+      toolCallId: tc.id,
+      toolName: tc.function.name,
+      result: {
+        error: `Skipped: exceeded maxToolCallsPerTurn (${cap})`
+      },
+      state: "output-error"
+    }));
+    return { toExecute, skippedResults };
+  }
   isAborted() {
     return !!this.effectiveSignal?.aborted;
   }