langchain 1.0.2 → 1.0.4

package/dist/agents/middleware/toolCallLimit.cjs

@@ -2,64 +2,54 @@ const require_rolldown_runtime = require('../../_virtual/rolldown_runtime.cjs');
 const require_middleware = require('../middleware.cjs');
 const __langchain_core_messages = require_rolldown_runtime.__toESM(require("@langchain/core/messages"));
 const zod_v3 = require_rolldown_runtime.__toESM(require("zod/v3"));
+const zod_v4 = require_rolldown_runtime.__toESM(require("zod/v4"));
 
 //#region src/agents/middleware/toolCallLimit.ts
 /**
-* Count tool calls in a list of messages.
+* Build the error message content for ToolMessage when limit is exceeded.
 *
-* @param messages - List of messages to count tool calls in.
-* @param toolName - If specified, only count calls to this specific tool.
-*   If undefined, count all tool calls.
-* @returns The total number of tool calls (optionally filtered by toolName).
-*/
-function countToolCallsInMessages(messages, toolName) {
-	let count = 0;
-	for (const message of messages) if (__langchain_core_messages.AIMessage.isInstance(message) && message.tool_calls) if (toolName === void 0) count += message.tool_calls.length;
-	else count += message.tool_calls.filter((tc) => tc.name === toolName).length;
-	return count;
-}
-/**
-* Get messages from the current run (after the last HumanMessage).
+* This message is sent to the model, so it should not reference thread/run concepts
+* that the model has no notion of.
 *
-* @param messages - Full list of messages.
-* @returns Messages from the current run (after last HumanMessage).
+* @param toolName - Tool name being limited (if specific tool), or undefined for all tools.
+* @returns A concise message instructing the model not to call the tool again.
 */
-function getRunMessages(messages) {
-	/**
-	* Find the last HumanMessage
-	*/
-	let lastHumanIndex = -1;
-	for (let i = messages.length - 1; i >= 0; i--) if (__langchain_core_messages.HumanMessage.isInstance(messages[i])) {
-		lastHumanIndex = i;
-		break;
-	}
-	/**
-	* If no HumanMessage found, return all messages
-	*/
-	if (lastHumanIndex === -1) return messages;
-	/**
-	* Return messages after the last HumanMessage
-	*/
-	return messages.slice(lastHumanIndex + 1);
+function buildToolMessageContent(toolName) {
+	if (toolName) return `Tool call limit exceeded. Do not call '${toolName}' again.`;
+	return "Tool call limit exceeded. Do not make additional tool calls.";
 }
+const VALID_EXIT_BEHAVIORS = [
+	"continue",
+	"error",
+	"end"
+];
+const DEFAULT_EXIT_BEHAVIOR = "continue";
 /**
-* Build a message indicating which tool call limits were reached.
+* Build the final AI message content for 'end' behavior.
+*
+* This message is displayed to the user, so it should include detailed information
+* about which limits were exceeded.
 *
 * @param threadCount - Current thread tool call count.
 * @param runCount - Current run tool call count.
 * @param threadLimit - Thread tool call limit (if set).
 * @param runLimit - Run tool call limit (if set).
 * @param toolName - Tool name being limited (if specific tool), or undefined for all tools.
-* @returns A formatted message describing which limits were reached.
+* @returns A formatted message describing which limits were exceeded.
 */
-function buildToolLimitExceededMessage(threadCount, runCount, threadLimit, runLimit, toolName) {
-	const toolDesc = toolName ? `'${toolName}' tool call` : "Tool call";
+function buildFinalAIMessageContent(threadCount, runCount, threadLimit, runLimit, toolName) {
+	const toolDesc = toolName ? `'${toolName}' tool` : "Tool";
 	const exceededLimits = [];
-	if (threadLimit !== void 0 && threadCount >= threadLimit) exceededLimits.push(`thread limit reached (${threadCount}/${threadLimit})`);
-	if (runLimit !== void 0 && runCount >= runLimit) exceededLimits.push(`run limit reached (${runCount}/${runLimit})`);
-	return `${toolDesc} limit${exceededLimits.length > 1 ? "s" : ""}: ${exceededLimits.join(", ")}. Stopping to prevent further tool calls.`;
+	if (threadLimit !== void 0 && threadCount > threadLimit) exceededLimits.push(`thread limit exceeded (${threadCount}/${threadLimit} calls)`);
+	if (runLimit !== void 0 && runCount > runLimit) exceededLimits.push(`run limit exceeded (${runCount}/${runLimit} calls)`);
+	const limitsText = exceededLimits.join(" and ");
+	return `${toolDesc} call limit reached: ${limitsText}.`;
 }
 /**
+* Schema for the exit behavior.
+*/
+const exitBehaviorSchema = zod_v3.z.enum(VALID_EXIT_BEHAVIORS).default(DEFAULT_EXIT_BEHAVIOR);
+/**
 * Exception raised when tool call limits are exceeded.
 *
 * This exception is raised when the configured exit behavior is 'error'
@@ -87,7 +77,7 @@ var ToolCallLimitExceededError = class extends Error {
 	*/
 	toolName;
 	constructor(threadCount, runCount, threadLimit, runLimit, toolName = void 0) {
-		const message = buildToolLimitExceededMessage(threadCount, runCount, threadLimit, runLimit, toolName);
+		const message = buildFinalAIMessageContent(threadCount, runCount, threadLimit, runLimit, toolName);
 		super(message);
 		this.name = "ToolCallLimitExceededError";
 		this.threadCount = threadCount;
@@ -104,9 +94,17 @@ const ToolCallLimitOptionsSchema = zod_v3.z.object({
 	toolName: zod_v3.z.string().optional(),
 	threadLimit: zod_v3.z.number().optional(),
 	runLimit: zod_v3.z.number().optional(),
-	exitBehavior: zod_v3.z.enum(["end", "error"]).default("end")
+	exitBehavior: exitBehaviorSchema
 });
 /**
+* Middleware state schema to track the number of model calls made at the thread and run level.
+*/
+const stateSchema = zod_v3.z.object({
+	threadToolCallCount: zod_v3.z.record(zod_v3.z.string(), zod_v3.z.number()).default({}),
+	runToolCallCount: zod_v3.z.record(zod_v3.z.string(), zod_v3.z.number()).default({})
+});
+const DEFAULT_TOOL_COUNT_KEY = "__all__";
+/**
 * Middleware that tracks tool call counts and enforces limits.
 *
 * This middleware monitors the number of tool calls made during agent execution
@@ -124,68 +122,66 @@ const ToolCallLimitOptionsSchema = zod_v3.z.object({
 * @param options.threadLimit - Maximum number of tool calls allowed per thread. undefined means no limit.
 * @param options.runLimit - Maximum number of tool calls allowed per run. undefined means no limit.
 * @param options.exitBehavior - What to do when limits are exceeded.
-*   - "end": Jump to the end of the agent execution and inject an artificial AI message indicating that the limit was exceeded.
-*   - "error": throws a ToolCallLimitExceededError
+*   - "continue": Block exceeded tools with error messages, let other tools continue. Model decides when to end. (default)
+*   - "error": Raise a ToolCallLimitExceededError exception
+*   - "end": Stop execution immediately with a ToolMessage + AI message for the single tool call that exceeded the limit. Raises NotImplementedError if there are multiple tool calls.
 *
-* @throws {Error} If both limits are undefined or if exitBehavior is invalid.
+* @throws {Error} If both limits are undefined, if exitBehavior is invalid, or if runLimit exceeds threadLimit.
+* @throws {NotImplementedError} If exitBehavior is "end" and there are multiple tool calls.
 *
-* @example Limit all tool calls globally
+* @example Continue execution with blocked tools (default)
 * ```ts
 * import { toolCallLimitMiddleware } from "@langchain/langchain/agents/middleware";
 * import { createAgent } from "@langchain/langchain/agents";
 *
-* const globalLimiter = toolCallLimitMiddleware({
+* // Block exceeded tools but let other tools and model continue
+* const limiter = toolCallLimitMiddleware({
 *   threadLimit: 20,
 *   runLimit: 10,
-*   exitBehavior: "end"
+*   exitBehavior: "continue", // default
 * });
 *
 * const agent = createAgent({
 *   model: "openai:gpt-4o",
-*   middleware: [globalLimiter]
+*   middleware: [limiter]
 * });
 * ```
 *
-* @example Limit a specific tool
+* @example Stop immediately when limit exceeded
 * ```ts
-* import { toolCallLimitMiddleware } from "@langchain/langchain/agents/middleware";
-* import { createAgent } from "@langchain/langchain/agents";
-*
-* const searchLimiter = toolCallLimitMiddleware({
-*   toolName: "search",
-*   threadLimit: 5,
-*   runLimit: 3,
+* // End execution immediately with an AI message
+* const limiter = toolCallLimitMiddleware({
+*   runLimit: 5,
 *   exitBehavior: "end"
 * });
 *
 * const agent = createAgent({
 *   model: "openai:gpt-4o",
-*   middleware: [searchLimiter]
+*   middleware: [limiter]
 * });
 * ```
 *
-* @example Use both in the same agent
+* @example Raise exception on limit
 * ```ts
-* import { toolCallLimitMiddleware } from "@langchain/langchain/agents/middleware";
-* import { createAgent } from "@langchain/langchain/agents";
-*
-* const globalLimiter = toolCallLimitMiddleware({
-*   threadLimit: 20,
-*   runLimit: 10,
-*   exitBehavior: "end"
-* });
-*
-* const searchLimiter = toolCallLimitMiddleware({
+* // Strict limit with exception handling
+* const limiter = toolCallLimitMiddleware({
 *   toolName: "search",
 *   threadLimit: 5,
-*   runLimit: 3,
-*   exitBehavior: "end"
+*   exitBehavior: "error"
 * });
 *
 * const agent = createAgent({
 *   model: "openai:gpt-4o",
-*   middleware: [globalLimiter, searchLimiter]
+*   middleware: [limiter]
 * });
+*
+* try {
+*   const result = await agent.invoke({ messages: [new HumanMessage("Task")] });
+* } catch (error) {
+*   if (error instanceof ToolCallLimitExceededError) {
+*     console.log(`Search limit exceeded: ${error}`);
+*   }
+* }
 * ```
 */
 function toolCallLimitMiddleware(options) {
@@ -194,47 +190,173 @@ function toolCallLimitMiddleware(options) {
 	*/
 	if (options.threadLimit === void 0 && options.runLimit === void 0) throw new Error("At least one limit must be specified (threadLimit or runLimit)");
 	/**
-	* Apply default for exitBehavior and validate
+	* Validate exitBehavior (Zod schema already validates, but provide helpful error)
+	*/
+	const exitBehavior = options.exitBehavior ?? DEFAULT_EXIT_BEHAVIOR;
+	const parseResult = exitBehaviorSchema.safeParse(exitBehavior);
+	if (!parseResult.success) throw new Error(zod_v4.z.prettifyError(parseResult.error).slice(2));
+	/**
+	* Validate that runLimit does not exceed threadLimit
 	*/
-	const exitBehavior = options.exitBehavior ?? "end";
-	if (exitBehavior !== "end" && exitBehavior !== "error") throw new Error(`Invalid exit behavior: ${exitBehavior}. Must be 'end' or 'error'`);
+	if (options.threadLimit !== void 0 && options.runLimit !== void 0 && options.runLimit > options.threadLimit) throw new Error(`runLimit (${options.runLimit}) cannot exceed threadLimit (${options.threadLimit}). The run limit should be less than or equal to the thread limit.`);
 	/**
 	* Generate the middleware name based on the tool name
 	*/
 	const middlewareName = options.toolName ? `ToolCallLimitMiddleware[${options.toolName}]` : "ToolCallLimitMiddleware";
 	return require_middleware.createMiddleware({
 		name: middlewareName,
-		beforeModel: {
+		stateSchema,
+		afterModel: {
 			canJumpTo: ["end"],
 			hook: (state) => {
-				const messages = state.messages;
 				/**
-				* Count tool calls in entire thread
+				* Get the last AI message to check for tool calls
+				*/
+				const lastAIMessage = [...state.messages].reverse().find(__langchain_core_messages.AIMessage.isInstance);
+				if (!lastAIMessage || !lastAIMessage.tool_calls) return void 0;
+				/**
+				* Helper to check if limit would be exceeded by one more call
+				*/
+				const wouldExceedLimit = (threadCount, runCount) => {
+					return options.threadLimit !== void 0 && threadCount + 1 > options.threadLimit || options.runLimit !== void 0 && runCount + 1 > options.runLimit;
+				};
+				/**
+				* Helper to check if a tool call matches our filter
+				*/
+				const matchesToolFilter = (toolCall) => {
+					return options.toolName === void 0 || toolCall.name === options.toolName;
+				};
+				/**
+				* Separate tool calls into allowed and blocked based on limits
+				*/
+				const separateToolCalls = (toolCalls, threadCount, runCount) => {
+					const allowed$1 = [];
+					const blocked$1 = [];
+					let tempThreadCount = threadCount;
+					let tempRunCount = runCount;
+					for (const toolCall of toolCalls) {
+						if (!matchesToolFilter(toolCall)) continue;
+						if (wouldExceedLimit(tempThreadCount, tempRunCount)) blocked$1.push(toolCall);
+						else {
+							allowed$1.push(toolCall);
+							tempThreadCount += 1;
+							tempRunCount += 1;
+						}
+					}
+					return {
+						allowed: allowed$1,
+						blocked: blocked$1,
+						finalThreadCount: tempThreadCount,
+						finalRunCount: tempRunCount + blocked$1.length
+					};
+				};
+				/**
+				* Get the count key for this middleware instance
+				*/
+				const countKey = options.toolName ?? DEFAULT_TOOL_COUNT_KEY;
+				/**
+				* Get current counts
+				*/
+				const threadCounts = { ...state.threadToolCallCount ?? {} };
+				const runCounts = { ...state.runToolCallCount ?? {} };
+				const currentThreadCount = threadCounts[countKey] ?? 0;
+				const currentRunCount = runCounts[countKey] ?? 0;
+				/**
+				* Separate tool calls into allowed and blocked
+				*/
+				const { allowed, blocked, finalThreadCount, finalRunCount } = separateToolCalls(lastAIMessage.tool_calls, currentThreadCount, currentRunCount);
+				/**
+				* Update counts:
+				* - Thread count includes only allowed calls (blocked calls don't count towards thread-level tracking)
+				* - Run count includes blocked calls since they were attempted in this run
+				*/
+				threadCounts[countKey] = finalThreadCount;
+				runCounts[countKey] = finalRunCount;
+				/**
+				* If no tool calls are blocked, just update counts
+				*/
+				if (blocked.length === 0) {
+					if (allowed.length > 0) return {
+						threadToolCallCount: threadCounts,
+						runToolCallCount: runCounts
+					};
+					return void 0;
+				}
+				/**
+				* Handle different exit behaviors
 				*/
-				const threadCount = countToolCallsInMessages(messages, options.toolName);
+				if (exitBehavior === "error") {
+					const hypotheticalThreadCount = finalThreadCount + blocked.length;
+					throw new ToolCallLimitExceededError(hypotheticalThreadCount, finalRunCount, options.threadLimit, options.runLimit, options.toolName);
+				}
 				/**
-				* Count tool calls in current run (after last HumanMessage)
+				* Build tool message content (sent to model - no thread/run details)
 				*/
-				const runMessages = getRunMessages(messages);
-				const runCount = countToolCallsInMessages(runMessages, options.toolName);
+				const toolMsgContent = buildToolMessageContent(options.toolName);
 				/**
-				* Check if any limits are exceeded
+				* Inject artificial error ToolMessages for blocked tool calls
 				*/
-				const threadLimitExceeded = options.threadLimit !== void 0 && threadCount >= options.threadLimit;
-				const runLimitExceeded = options.runLimit !== void 0 && runCount >= options.runLimit;
-				if (!threadLimitExceeded && !runLimitExceeded) return void 0;
-				if (exitBehavior === "error") throw new ToolCallLimitExceededError(threadCount, runCount, options.threadLimit, options.runLimit, options.toolName);
+				const artificialMessages = blocked.map((toolCall) => new __langchain_core_messages.ToolMessage({
+					content: toolMsgContent,
+					tool_call_id: toolCall.id,
+					name: toolCall.name,
+					status: "error"
+				}));
+				if (exitBehavior === "end") {
+					/**
+					* Check if there are tool calls to other tools that would continue executing
+					* For tool-specific limiters: check for calls to other tools
+					* For global limiters: check if there are multiple different tool types
+					*/
+					let otherTools = [];
+					if (options.toolName !== void 0)
+ /**
+					* Tool-specific limiter: check for calls to other tools
+					*/
+					otherTools = lastAIMessage.tool_calls.filter((tc) => tc.name !== options.toolName);
+					else {
+						/**
+						* Global limiter: check if there are multiple different tool types
+						* If there are allowed calls, those would execute
+						* But even if all are blocked, we can't handle multiple tool types with "end"
+						*/
+						const uniqueToolNames = new Set(lastAIMessage.tool_calls.map((tc) => tc.name).filter(Boolean));
+						if (uniqueToolNames.size > 1)
+ /**
+						* Multiple different tool types - use allowed calls to show which ones
+						*/
+						otherTools = allowed.length > 0 ? allowed : lastAIMessage.tool_calls;
+					}
+					if (otherTools.length > 0) {
+						const toolNames = Array.from(new Set(otherTools.map((tc) => tc.name).filter(Boolean))).join(", ");
+						throw new Error(`Cannot end execution with other tool calls pending. Found calls to: ${toolNames}. Use 'continue' or 'error' behavior instead.`);
+					}
+					/**
+					* Build final AI message content (displayed to user - includes thread/run details)
+					* Use hypothetical thread count (what it would have been if call wasn't blocked)
+					* to show which limit was actually exceeded
+					*/
+					const hypotheticalThreadCount = finalThreadCount + blocked.length;
+					const finalMsgContent = buildFinalAIMessageContent(hypotheticalThreadCount, finalRunCount, options.threadLimit, options.runLimit, options.toolName);
+					artificialMessages.push(new __langchain_core_messages.AIMessage(finalMsgContent));
+					return {
+						threadToolCallCount: threadCounts,
+						runToolCallCount: runCounts,
+						jumpTo: "end",
+						messages: artificialMessages
+					};
+				}
 				/**
-				* Create a message indicating the limit was exceeded
+				* For exit_behavior="continue", return error messages to block exceeded tools
 				*/
-				const limitMessage = buildToolLimitExceededMessage(threadCount, runCount, options.threadLimit, options.runLimit, options.toolName);
-				const limitAiMessage = new __langchain_core_messages.AIMessage(limitMessage);
 				return {
-					jumpTo: "end",
-					messages: [limitAiMessage]
+					threadToolCallCount: threadCounts,
+					runToolCallCount: runCounts,
+					messages: artificialMessages
 				};
 			}
-		}
+		},
+		afterAgent: () => ({ runToolCallCount: {} })
 	});
 }
 

package/dist/agents/middleware/toolCallLimit.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"toolCallLimit.cjs","names":["messages: BaseMessage[]","toolName?: string","AIMessage","HumanMessage","threadCount: number","runCount: number","threadLimit: number | undefined","runLimit: number | undefined","toolName: string | undefined","exceededLimits: string[]","z","options: ToolCallLimitConfig","createMiddleware"],"sources":["../../../src/agents/middleware/toolCallLimit.ts"],"sourcesContent":["/**\n * Tool call limit middleware for agents.\n */\n\nimport { AIMessage, BaseMessage, HumanMessage } from \"@langchain/core/messages\";\nimport { z } from \"zod/v3\";\nimport type { InferInteropZodInput } from \"@langchain/core/utils/types\";\n\nimport { createMiddleware } from \"../middleware.js\";\n\n/**\n * Count tool calls in a list of messages.\n *\n * @param messages - List of messages to count tool calls in.\n * @param toolName - If specified, only count calls to this specific tool.\n *   If undefined, count all tool calls.\n * @returns The total number of tool calls (optionally filtered by toolName).\n */\nfunction countToolCallsInMessages(\n  messages: BaseMessage[],\n  toolName?: string\n): number {\n  let count = 0;\n  for (const message of messages) {\n    if (AIMessage.isInstance(message) && message.tool_calls) {\n      if (toolName === undefined) {\n        // Count all tool calls\n        count += message.tool_calls.length;\n      } else {\n        // Count only calls to the specified tool\n        count += message.tool_calls.filter((tc) => tc.name === toolName).length;\n      }\n    }\n  }\n  return count;\n}\n\n/**\n * Get messages from the current run (after the last HumanMessage).\n *\n * @param messages - Full list of messages.\n * @returns Messages from the current run (after last HumanMessage).\n */\nfunction getRunMessages(messages: BaseMessage[]): BaseMessage[] {\n  /**\n   * Find the last HumanMessage\n   */\n  let lastHumanIndex = -1;\n  for (let i = messages.length - 1; i >= 0; i--) {\n    if (HumanMessage.isInstance(messages[i])) {\n      lastHumanIndex = i;\n      break;\n    }\n  }\n\n  /**\n   * If no HumanMessage found, return all messages\n   */\n  if (lastHumanIndex === -1) {\n    return messages;\n  }\n\n  /**\n   * Return messages after the last HumanMessage\n   */\n  return messages.slice(lastHumanIndex + 1);\n}\n\n/**\n * Build a message indicating which tool call limits were reached.\n *\n * @param threadCount - Current thread tool call count.\n * @param runCount - Current run tool call count.\n * @param threadLimit - Thread tool call limit (if set).\n * @param runLimit - Run tool call limit (if set).\n * @param toolName - Tool name being limited (if specific tool), or undefined for all tools.\n * @returns A formatted message describing which limits were reached.\n */\nfunction buildToolLimitExceededMessage(\n  threadCount: number,\n  runCount: number,\n  threadLimit: number | undefined,\n  runLimit: number | undefined,\n  toolName: string | undefined\n): string {\n  const toolDesc = toolName ? `'${toolName}' tool call` : \"Tool call\";\n  const exceededLimits: string[] = [];\n\n  if (threadLimit !== undefined && threadCount >= threadLimit) {\n    exceededLimits.push(`thread limit reached (${threadCount}/${threadLimit})`);\n  }\n  if (runLimit !== undefined && runCount >= runLimit) {\n    exceededLimits.push(`run limit reached (${runCount}/${runLimit})`);\n  }\n\n  return `${toolDesc} limit${\n    exceededLimits.length > 1 ? \"s\" : \"\"\n  }: ${exceededLimits.join(\", \")}. Stopping to prevent further tool calls.`;\n}\n\n/**\n * Exception raised when tool call limits are exceeded.\n *\n * This exception is raised when the configured exit behavior is 'error'\n * and either the thread or run tool call limit has been exceeded.\n */\nexport class ToolCallLimitExceededError extends Error {\n  /**\n   * Current thread tool call count.\n   */\n  threadCount: number;\n  /**\n   * Current run tool call count.\n   */\n  runCount: number;\n  /**\n   * Thread tool call limit (if set).\n   */\n  threadLimit: number | undefined;\n  /**\n   * Run tool call limit (if set).\n   */\n  runLimit: number | undefined;\n  /**\n   * Tool name being limited (if specific tool), or undefined for all tools.\n   */\n  toolName: string | undefined;\n\n  constructor(\n    threadCount: number,\n    runCount: number,\n    threadLimit: number | undefined,\n    runLimit: number | undefined,\n    toolName: string | undefined = undefined\n  ) {\n    const message = buildToolLimitExceededMessage(\n      threadCount,\n      runCount,\n      threadLimit,\n      runLimit,\n      toolName\n    );\n    super(message);\n\n    this.name = \"ToolCallLimitExceededError\";\n    this.threadCount = threadCount;\n    this.runCount = runCount;\n    this.threadLimit = threadLimit;\n    this.runLimit = runLimit;\n    this.toolName = toolName;\n  }\n}\n\n/**\n * Options for configuring the Tool Call Limit middleware.\n */\nexport const ToolCallLimitOptionsSchema = z.object({\n  /**\n   * Name of the specific tool to limit. If undefined, limits apply to all tools.\n   */\n  toolName: z.string().optional(),\n  /**\n   * Maximum number of tool calls allowed per thread.\n   * undefined means no limit.\n   */\n  threadLimit: z.number().optional(),\n  /**\n   * Maximum number of tool calls allowed per run.\n   * undefined means no limit.\n   */\n  runLimit: z.number().optional(),\n  /**\n   * What to do when limits are exceeded.\n   * - \"end\": Jump to the end of the agent execution and inject an artificial\n   *   AI message indicating that the limit was exceeded.\n   * - \"error\": throws a ToolCallLimitExceededError\n   */\n  exitBehavior: z.enum([\"end\", \"error\"]).default(\"end\"),\n});\n\nexport type ToolCallLimitConfig = InferInteropZodInput<\n  typeof ToolCallLimitOptionsSchema\n>;\n\n/**\n * Middleware that tracks tool call counts and enforces limits.\n *\n * This middleware monitors the number of tool calls made during agent execution\n * and can terminate the agent when specified limits are reached. It supports\n * both thread-level and run-level call counting with configurable exit behaviors.\n *\n * Thread-level: The middleware counts all tool calls in the entire message history\n * and persists this count across multiple runs (invocations) of the agent.\n *\n * Run-level: The middleware counts tool calls made after the last HumanMessage,\n * representing the current run (invocation) of the agent.\n *\n * @param options - Configuration options for the middleware\n * @param options.toolName - Name of the specific tool to limit. If undefined, limits apply to all tools.\n * @param options.threadLimit - Maximum number of tool calls allowed per thread. undefined means no limit.\n * @param options.runLimit - Maximum number of tool calls allowed per run. undefined means no limit.\n * @param options.exitBehavior - What to do when limits are exceeded.\n *   - \"end\": Jump to the end of the agent execution and inject an artificial AI message indicating that the limit was exceeded.\n *   - \"error\": throws a ToolCallLimitExceededError\n *\n * @throws {Error} If both limits are undefined or if exitBehavior is invalid.\n *\n * @example Limit all tool calls globally\n * ```ts\n * import { toolCallLimitMiddleware } from \"@langchain/langchain/agents/middleware\";\n * import { createAgent } from \"@langchain/langchain/agents\";\n *\n * const globalLimiter = toolCallLimitMiddleware({\n *   threadLimit: 20,\n *   runLimit: 10,\n *   exitBehavior: \"end\"\n * });\n *\n * const agent = createAgent({\n *   model: \"openai:gpt-4o\",\n *   middleware: [globalLimiter]\n * });\n * ```\n *\n * @example Limit a specific tool\n * ```ts\n * import { toolCallLimitMiddleware } from \"@langchain/langchain/agents/middleware\";\n * import { createAgent } from \"@langchain/langchain/agents\";\n *\n * const searchLimiter = toolCallLimitMiddleware({\n *   toolName: \"search\",\n *   threadLimit: 5,\n *   runLimit: 3,\n *   exitBehavior: \"end\"\n * });\n *\n * const agent = createAgent({\n *   model: \"openai:gpt-4o\",\n *   middleware: [searchLimiter]\n * });\n * ```\n *\n * @example Use both in the same agent\n * ```ts\n * import { toolCallLimitMiddleware } from \"@langchain/langchain/agents/middleware\";\n * import { createAgent } from \"@langchain/langchain/agents\";\n *\n * const globalLimiter = toolCallLimitMiddleware({\n *   threadLimit: 20,\n *   runLimit: 10,\n *   exitBehavior: \"end\"\n * });\n *\n * const searchLimiter = toolCallLimitMiddleware({\n *   toolName: \"search\",\n *   threadLimit: 5,\n *   runLimit: 3,\n *   exitBehavior: \"end\"\n * });\n *\n * const agent = createAgent({\n *   model: \"openai:gpt-4o\",\n *   middleware: [globalLimiter, searchLimiter]\n * });\n * ```\n */\nexport function toolCallLimitMiddleware(options: ToolCallLimitConfig) {\n  /**\n   * Validate that at least one limit is specified\n   */\n  if (options.threadLimit === undefined && options.runLimit === undefined) {\n    throw new Error(\n      \"At least one limit must be specified (threadLimit or runLimit)\"\n    );\n  }\n\n  /**\n   * Apply default for exitBehavior and validate\n   */\n  const exitBehavior = options.exitBehavior ?? \"end\";\n  if (exitBehavior !== \"end\" && exitBehavior !== \"error\") {\n    throw new Error(\n      `Invalid exit behavior: ${exitBehavior}. Must be 'end' or 'error'`\n    );\n  }\n\n  /**\n   * Generate the middleware name based on the tool name\n   */\n  const middlewareName = options.toolName\n    ? `ToolCallLimitMiddleware[${options.toolName}]`\n    : \"ToolCallLimitMiddleware\";\n\n  return createMiddleware({\n    name: middlewareName,\n    beforeModel: {\n      canJumpTo: [\"end\"],\n      hook: (state) => {\n        const messages = state.messages;\n\n        /**\n         * Count tool calls in entire thread\n         */\n        const threadCount = countToolCallsInMessages(\n          messages,\n          options.toolName\n        );\n\n        /**\n         * Count tool calls in current run (after last HumanMessage)\n         */\n        const runMessages = getRunMessages(messages);\n        const runCount = countToolCallsInMessages(\n          runMessages,\n          options.toolName\n        );\n\n        /**\n         * Check if any limits are exceeded\n         */\n        const threadLimitExceeded =\n          options.threadLimit !== undefined &&\n          threadCount >= options.threadLimit;\n        const runLimitExceeded =\n          options.runLimit !== undefined && runCount >= options.runLimit;\n\n        if (!threadLimitExceeded && !runLimitExceeded) {\n          return undefined;\n        }\n\n        if (exitBehavior === \"error\") {\n          throw new ToolCallLimitExceededError(\n            threadCount,\n            runCount,\n            options.threadLimit,\n            options.runLimit,\n            options.toolName\n          );\n        }\n\n        /**\n         * Create a message indicating the limit was exceeded\n         */\n        const limitMessage = buildToolLimitExceededMessage(\n          threadCount,\n          runCount,\n          options.threadLimit,\n          options.runLimit,\n          options.toolName\n        );\n        const limitAiMessage = new AIMessage(limitMessage);\n\n        return {\n          jumpTo: \"end\",\n          messages: [limitAiMessage],\n        };\n      },\n    },\n  });\n}\n"],"mappings":"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"}
+{"version":3,"file":"toolCallLimit.cjs","names":["toolName: string | undefined","threadCount: number","runCount: number","threadLimit: number | undefined","runLimit: number | undefined","exceededLimits: string[]","z","options: ToolCallLimitConfig","z4","createMiddleware","AIMessage","toolCall: { name?: string }","toolCalls: ToolCall[]","allowed: ToolCall[]","blocked: ToolCall[]","blocked","allowed","artificialMessages: Array<ToolMessage | AIMessage>","ToolMessage","otherTools: ToolCall[]"],"sources":["../../../src/agents/middleware/toolCallLimit.ts"],"sourcesContent":["import { AIMessage, ToolMessage } from \"@langchain/core/messages\";\nimport { z as z4 } from \"zod/v4\";\nimport { z } from \"zod/v3\";\nimport type { InferInteropZodInput } from \"@langchain/core/utils/types\";\nimport type { ToolCall } from \"@langchain/core/messages/tool\";\n\nimport { createMiddleware } from \"../middleware.js\";\n\n/**\n * Build the error message content for ToolMessage when limit is exceeded.\n *\n * This message is sent to the model, so it should not reference thread/run concepts\n * that the model has no notion of.\n *\n * @param toolName - Tool name being limited (if specific tool), or undefined for all tools.\n * @returns A concise message instructing the model not to call the tool again.\n */\nfunction buildToolMessageContent(toolName: string | undefined): string {\n  // Always instruct the model not to call again, regardless of which limit was hit\n  if (toolName) {\n    return `Tool call limit exceeded. Do not call '${toolName}' again.`;\n  }\n  return \"Tool call limit exceeded. Do not make additional tool calls.\";\n}\n\nconst VALID_EXIT_BEHAVIORS = [\"continue\", \"error\", \"end\"] as const;\nconst DEFAULT_EXIT_BEHAVIOR = \"continue\";\n\n/**\n * Build the final AI message content for 'end' behavior.\n *\n * This message is displayed to the user, so it should include detailed information\n * about which limits were exceeded.\n *\n * @param threadCount - Current thread tool call count.\n * @param runCount - Current run tool call count.\n * @param threadLimit - Thread tool call limit (if set).\n * @param runLimit - Run tool call limit (if set).\n * @param toolName - Tool name being limited (if specific tool), or undefined for all tools.\n * @returns A formatted message describing which limits were exceeded.\n */\nfunction buildFinalAIMessageContent(\n  threadCount: number,\n  runCount: number,\n  threadLimit: number | undefined,\n  runLimit: number | undefined,\n  toolName: string | undefined\n): string {\n  const toolDesc = toolName ? `'${toolName}' tool` : \"Tool\";\n  const exceededLimits: string[] = [];\n\n  if (threadLimit !== undefined && threadCount > threadLimit) {\n    exceededLimits.push(\n      `thread limit exceeded (${threadCount}/${threadLimit} calls)`\n    );\n  }\n  if (runLimit !== undefined && runCount > runLimit) {\n    exceededLimits.push(`run limit exceeded (${runCount}/${runLimit} calls)`);\n  }\n\n  const limitsText = exceededLimits.join(\" and \");\n  return `${toolDesc} call limit reached: ${limitsText}.`;\n}\n\n/**\n * Schema for the exit behavior.\n */\nconst exitBehaviorSchema = z\n  .enum(VALID_EXIT_BEHAVIORS)\n  .default(DEFAULT_EXIT_BEHAVIOR);\n\n/**\n * Exception raised when tool call limits are exceeded.\n *\n * This exception is raised when the configured exit behavior is 'error'\n * and either the thread or run tool call limit has been exceeded.\n */\nexport class ToolCallLimitExceededError extends Error {\n  /**\n   * Current thread tool call count.\n   */\n  threadCount: number;\n  /**\n   * Current run tool call count.\n   */\n  runCount: number;\n  /**\n   * Thread tool call limit (if set).\n   */\n  threadLimit: number | undefined;\n  /**\n   * Run tool call limit (if set).\n   */\n  runLimit: number | undefined;\n  /**\n   * Tool name being limited (if specific tool), or undefined for all tools.\n   */\n  toolName: string | undefined;\n\n  constructor(\n    threadCount: number,\n    runCount: number,\n    threadLimit: number | undefined,\n    runLimit: number | undefined,\n    toolName: string | undefined = undefined\n  ) {\n    const message = buildFinalAIMessageContent(\n      threadCount,\n      runCount,\n      threadLimit,\n      runLimit,\n      toolName\n    );\n    super(message);\n\n    this.name = \"ToolCallLimitExceededError\";\n    this.threadCount = threadCount;\n    this.runCount = runCount;\n    this.threadLimit = threadLimit;\n    this.runLimit = runLimit;\n    this.toolName = toolName;\n  }\n}\n\n/**\n * Options for configuring the Tool Call Limit middleware.\n */\nexport const ToolCallLimitOptionsSchema = z.object({\n  /**\n   * Name of the specific tool to limit. If undefined, limits apply to all tools.\n   */\n  toolName: z.string().optional(),\n  /**\n   * Maximum number of tool calls allowed per thread.\n   * undefined means no limit.\n   */\n  threadLimit: z.number().optional(),\n  /**\n   * Maximum number of tool calls allowed per run.\n   * undefined means no limit.\n   */\n  runLimit: z.number().optional(),\n  /**\n   * What to do when limits are exceeded.\n   * - \"continue\": Block exceeded tools with error messages, let other tools continue (default)\n   * - \"error\": Raise a ToolCallLimitExceededError exception\n   * - \"end\": Stop execution immediately, injecting a ToolMessage and an AI message\n   *   for the single tool call that exceeded the limit. Raises NotImplementedError\n   *   if there are multiple tool calls.\n   *\n   * @default \"continue\"\n   */\n  exitBehavior: exitBehaviorSchema,\n});\n\nexport type ToolCallLimitConfig = InferInteropZodInput<\n  typeof ToolCallLimitOptionsSchema\n>;\n\n/**\n * Middleware state schema to track the number of model calls made at the thread and run level.\n */\nconst stateSchema = z.object({\n  threadToolCallCount: z.record(z.string(), z.number()).default({}),\n  runToolCallCount: z.record(z.string(), z.number()).default({}),\n});\n\nconst DEFAULT_TOOL_COUNT_KEY = \"__all__\";\n\n/**\n * Middleware that tracks tool call counts and enforces limits.\n *\n * This middleware monitors the number of tool calls made during agent execution\n * and can terminate the agent when specified limits are reached. It supports\n * both thread-level and run-level call counting with configurable exit behaviors.\n *\n * Thread-level: The middleware counts all tool calls in the entire message history\n * and persists this count across multiple runs (invocations) of the agent.\n *\n * Run-level: The middleware counts tool calls made after the last HumanMessage,\n * representing the current run (invocation) of the agent.\n *\n * @param options - Configuration options for the middleware\n * @param options.toolName - Name of the specific tool to limit. If undefined, limits apply to all tools.\n * @param options.threadLimit - Maximum number of tool calls allowed per thread. undefined means no limit.\n * @param options.runLimit - Maximum number of tool calls allowed per run. undefined means no limit.\n * @param options.exitBehavior - What to do when limits are exceeded.\n *   - \"continue\": Block exceeded tools with error messages, let other tools continue. Model decides when to end. (default)\n *   - \"error\": Raise a ToolCallLimitExceededError exception\n *   - \"end\": Stop execution immediately with a ToolMessage + AI message for the single tool call that exceeded the limit. Raises NotImplementedError if there are multiple tool calls.\n *\n * @throws {Error} If both limits are undefined, if exitBehavior is invalid, or if runLimit exceeds threadLimit.\n * @throws {NotImplementedError} If exitBehavior is \"end\" and there are multiple tool calls.\n *\n * @example Continue execution with blocked tools (default)\n * ```ts\n * import { toolCallLimitMiddleware } from \"@langchain/langchain/agents/middleware\";\n * import { createAgent } from \"@langchain/langchain/agents\";\n *\n * // Block exceeded tools but let other tools and model continue\n * const limiter = toolCallLimitMiddleware({\n *   threadLimit: 20,\n *   runLimit: 10,\n *   exitBehavior: \"continue\", // default\n * });\n *\n * const agent = createAgent({\n *   model: \"openai:gpt-4o\",\n *   middleware: [limiter]\n * });\n * ```\n *\n * @example Stop immediately when limit exceeded\n * ```ts\n * // End execution immediately with an AI message\n * const limiter = toolCallLimitMiddleware({\n *   runLimit: 5,\n *   exitBehavior: \"end\"\n * });\n *\n * const agent = createAgent({\n *   model: \"openai:gpt-4o\",\n *   middleware: [limiter]\n * });\n * ```\n *\n * @example Raise exception on limit\n * ```ts\n * // Strict limit with exception handling\n * const limiter = toolCallLimitMiddleware({\n *   toolName: \"search\",\n *   threadLimit: 5,\n *   exitBehavior: \"error\"\n * });\n *\n * const agent = createAgent({\n *   model: \"openai:gpt-4o\",\n *   middleware: [limiter]\n * });\n *\n * try {\n *   const result = await agent.invoke({ messages: [new HumanMessage(\"Task\")] });\n * } catch (error) {\n *   if (error instanceof ToolCallLimitExceededError) {\n *     console.log(`Search limit exceeded: ${error}`);\n *   }\n * }\n * ```\n */\nexport function toolCallLimitMiddleware(options: ToolCallLimitConfig) {\n  /**\n   * Validate that at least one limit is specified\n   */\n  if (options.threadLimit === undefined && options.runLimit === undefined) {\n    throw new Error(\n      \"At least one limit must be specified (threadLimit or runLimit)\"\n    );\n  }\n\n  /**\n   * Validate exitBehavior (Zod schema already validates, but provide helpful error)\n   */\n  const exitBehavior = options.exitBehavior ?? DEFAULT_EXIT_BEHAVIOR;\n  const parseResult = exitBehaviorSchema.safeParse(exitBehavior);\n  if (!parseResult.success) {\n    throw new Error(z4.prettifyError(parseResult.error).slice(2));\n  }\n\n  /**\n   * Validate that runLimit does not exceed threadLimit\n   */\n  if (\n    options.threadLimit !== undefined &&\n    options.runLimit !== undefined &&\n    options.runLimit > options.threadLimit\n  ) {\n    throw new Error(\n      `runLimit (${options.runLimit}) cannot exceed threadLimit (${options.threadLimit}). ` +\n        \"The run limit should be less than or equal to the thread limit.\"\n    );\n  }\n\n  /**\n   * Generate the middleware name based on the tool name\n   */\n  const middlewareName = options.toolName\n    ? `ToolCallLimitMiddleware[${options.toolName}]`\n    : \"ToolCallLimitMiddleware\";\n\n  return createMiddleware({\n    name: middlewareName,\n    stateSchema,\n    afterModel: {\n      canJumpTo: [\"end\"],\n      hook: (state) => {\n        /**\n         * Get the last AI message to check for tool calls\n         */\n        const lastAIMessage = [...state.messages]\n          .reverse()\n          .find(AIMessage.isInstance);\n\n        if (!lastAIMessage || !lastAIMessage.tool_calls) {\n          return undefined;\n        }\n\n        /**\n         * Helper to check if limit would be exceeded by one more call\n         */\n        const wouldExceedLimit = (\n          threadCount: number,\n          runCount: number\n        ): boolean => {\n          return (\n            (options.threadLimit !== undefined &&\n              threadCount + 1 > options.threadLimit) ||\n            (options.runLimit !== undefined && runCount + 1 > options.runLimit)\n          );\n        };\n\n        /**\n         * Helper to check if a tool call matches our filter\n         */\n        const matchesToolFilter = (toolCall: { name?: string }): boolean => {\n          return (\n            options.toolName === undefined || toolCall.name === options.toolName\n          );\n        };\n\n        /**\n         * Separate tool calls into allowed and blocked based on limits\n         */\n        const separateToolCalls = (\n          toolCalls: ToolCall[],\n          threadCount: number,\n          runCount: number\n        ): {\n          allowed: ToolCall[];\n          blocked: ToolCall[];\n          finalThreadCount: number;\n          finalRunCount: number;\n        } => {\n          const allowed: ToolCall[] = [];\n          const blocked: ToolCall[] = [];\n          let tempThreadCount = threadCount;\n          let tempRunCount = runCount;\n\n          for (const toolCall of toolCalls) {\n            if (!matchesToolFilter(toolCall)) {\n              // Tool call doesn't match our filter, skip it\n              continue;\n            }\n\n            if (wouldExceedLimit(tempThreadCount, tempRunCount)) {\n              blocked.push(toolCall);\n            } else {\n              allowed.push(toolCall);\n              tempThreadCount += 1;\n              tempRunCount += 1;\n            }\n          }\n\n          return {\n            allowed,\n            blocked,\n            finalThreadCount: tempThreadCount,\n            finalRunCount: tempRunCount + blocked.length,\n          };\n        };\n\n        /**\n         * Get the count key for this middleware instance\n         */\n        const countKey = options.toolName ?? DEFAULT_TOOL_COUNT_KEY;\n\n        /**\n         * Get current counts\n         */\n        const threadCounts = { ...(state.threadToolCallCount ?? {}) };\n        const runCounts = { ...(state.runToolCallCount ?? {}) };\n        const currentThreadCount = threadCounts[countKey] ?? 0;\n        const currentRunCount = runCounts[countKey] ?? 0;\n\n        /**\n         * Separate tool calls into allowed and blocked\n         */\n        const { allowed, blocked, finalThreadCount, finalRunCount } =\n          separateToolCalls(\n            lastAIMessage.tool_calls,\n            currentThreadCount,\n            currentRunCount\n          );\n\n        /**\n         * Update counts:\n         * - Thread count includes only allowed calls (blocked calls don't count towards thread-level tracking)\n         * - Run count includes blocked calls since they were attempted in this run\n         */\n        threadCounts[countKey] = finalThreadCount;\n        runCounts[countKey] = finalRunCount;\n\n        /**\n         * If no tool calls are blocked, just update counts\n         */\n        if (blocked.length === 0) {\n          if (allowed.length > 0) {\n            return {\n              threadToolCallCount: threadCounts,\n              runToolCallCount: runCounts,\n            };\n          }\n          return undefined;\n        }\n\n        /**\n         * Handle different exit behaviors\n         */\n        if (exitBehavior === \"error\") {\n          // Use hypothetical thread count to show which limit was exceeded\n          const hypotheticalThreadCount = finalThreadCount + blocked.length;\n          throw new ToolCallLimitExceededError(\n            hypotheticalThreadCount,\n            finalRunCount,\n            options.threadLimit,\n            options.runLimit,\n            options.toolName\n          );\n        }\n\n        /**\n         * Build tool message content (sent to model - no thread/run details)\n         */\n        const toolMsgContent = buildToolMessageContent(options.toolName);\n\n        /**\n         * Inject artificial error ToolMessages for blocked tool calls\n         */\n        const artificialMessages: Array<ToolMessage | AIMessage> = blocked.map(\n          (toolCall) =>\n            new ToolMessage({\n              content: toolMsgContent,\n              tool_call_id: toolCall.id!,\n              name: toolCall.name,\n              status: \"error\",\n            })\n        );\n\n        if (exitBehavior === \"end\") {\n          /**\n           * Check if there are tool calls to other tools that would continue executing\n           * For tool-specific limiters: check for calls to other tools\n           * For global limiters: check if there are multiple different tool types\n           */\n          let otherTools: ToolCall[] = [];\n          if (options.toolName !== undefined) {\n            /**\n             * Tool-specific limiter: check for calls to other tools\n             */\n            otherTools = lastAIMessage.tool_calls.filter(\n              (tc) => tc.name !== options.toolName\n            );\n          } else {\n            /**\n             * Global limiter: check if there are multiple different tool types\n             * If there are allowed calls, those would execute\n             * But even if all are blocked, we can't handle multiple tool types with \"end\"\n             */\n            const uniqueToolNames = new Set(\n              lastAIMessage.tool_calls.map((tc) => tc.name).filter(Boolean)\n            );\n            if (uniqueToolNames.size > 1) {\n              /**\n               * Multiple different tool types - use allowed calls to show which ones\n               */\n              otherTools =\n                allowed.length > 0 ? allowed : lastAIMessage.tool_calls;\n            }\n          }\n\n          if (otherTools.length > 0) {\n            const toolNames = Array.from(\n              new Set(otherTools.map((tc) => tc.name).filter(Boolean))\n            ).join(\", \");\n            throw new Error(\n              `Cannot end execution with other tool calls pending. Found calls to: ${toolNames}. Use 'continue' or 'error' behavior instead.`\n            );\n          }\n\n          /**\n           * Build final AI message content (displayed to user - includes thread/run details)\n           * Use hypothetical thread count (what it would have been if call wasn't blocked)\n           * to show which limit was actually exceeded\n           */\n          const hypotheticalThreadCount = finalThreadCount + blocked.length;\n          const finalMsgContent = buildFinalAIMessageContent(\n            hypotheticalThreadCount,\n            finalRunCount,\n            options.threadLimit,\n            options.runLimit,\n            options.toolName\n          );\n          artificialMessages.push(new AIMessage(finalMsgContent));\n\n          return {\n            threadToolCallCount: threadCounts,\n            runToolCallCount: runCounts,\n            jumpTo: \"end\" as const,\n            messages: artificialMessages,\n          };\n        }\n\n        /**\n         * For exit_behavior=\"continue\", return error messages to block exceeded tools\n         */\n        return {\n          threadToolCallCount: threadCounts,\n          runToolCallCount: runCounts,\n          messages: artificialMessages,\n        };\n      },\n    },\n    /**\n     * reset the run tool call count after the agent execution completes\n     */\n    afterAgent: () => ({\n      runToolCallCount: {},\n    }),\n  });\n}\n"],"mappings":"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"}

package/dist/agents/middleware/toolCallLimit.d.cts

@@ -53,21 +53,25 @@ declare const ToolCallLimitOptionsSchema: z.ZodObject<{
   runLimit: z.ZodOptional<z.ZodNumber>;
   /**
    * What to do when limits are exceeded.
-   * - "end": Jump to the end of the agent execution and inject an artificial
-   *   AI message indicating that the limit was exceeded.
-   * - "error": throws a ToolCallLimitExceededError
+   * - "continue": Block exceeded tools with error messages, let other tools continue (default)
+   * - "error": Raise a ToolCallLimitExceededError exception
+   * - "end": Stop execution immediately, injecting a ToolMessage and an AI message
+   *   for the single tool call that exceeded the limit. Raises NotImplementedError
+   *   if there are multiple tool calls.
+   *
+   * @default "continue"
    */
-  exitBehavior: z.ZodDefault<z.ZodEnum<["end", "error"]>>;
+  exitBehavior: z.ZodDefault<z.ZodEnum<["continue", "error", "end"]>>;
 }, "strip", z.ZodTypeAny, {
   toolName?: string | undefined;
   threadLimit?: number | undefined;
   runLimit?: number | undefined;
-  exitBehavior: "end" | "error";
+  exitBehavior: "continue" | "end" | "error";
 }, {
   toolName?: string | undefined;
   threadLimit?: number | undefined;
   runLimit?: number | undefined;
-  exitBehavior?: "end" | "error" | undefined;
+  exitBehavior?: "continue" | "end" | "error" | undefined;
 }>;
 type ToolCallLimitConfig = InferInteropZodInput<typeof ToolCallLimitOptionsSchema>;
 /**
@@ -88,71 +92,78 @@ type ToolCallLimitConfig = InferInteropZodInput<typeof ToolCallLimitOptionsSchem
  * @param options.threadLimit - Maximum number of tool calls allowed per thread. undefined means no limit.
  * @param options.runLimit - Maximum number of tool calls allowed per run. undefined means no limit.
  * @param options.exitBehavior - What to do when limits are exceeded.
- *   - "end": Jump to the end of the agent execution and inject an artificial AI message indicating that the limit was exceeded.
- *   - "error": throws a ToolCallLimitExceededError
+ *   - "continue": Block exceeded tools with error messages, let other tools continue. Model decides when to end. (default)
+ *   - "error": Raise a ToolCallLimitExceededError exception
+ *   - "end": Stop execution immediately with a ToolMessage + AI message for the single tool call that exceeded the limit. Raises NotImplementedError if there are multiple tool calls.
  *
- * @throws {Error} If both limits are undefined or if exitBehavior is invalid.
+ * @throws {Error} If both limits are undefined, if exitBehavior is invalid, or if runLimit exceeds threadLimit.
+ * @throws {NotImplementedError} If exitBehavior is "end" and there are multiple tool calls.
  *
- * @example Limit all tool calls globally
+ * @example Continue execution with blocked tools (default)
  * ```ts
  * import { toolCallLimitMiddleware } from "@langchain/langchain/agents/middleware";
  * import { createAgent } from "@langchain/langchain/agents";
  *
- * const globalLimiter = toolCallLimitMiddleware({
+ * // Block exceeded tools but let other tools and model continue
+ * const limiter = toolCallLimitMiddleware({
  *   threadLimit: 20,
  *   runLimit: 10,
- *   exitBehavior: "end"
+ *   exitBehavior: "continue", // default
  * });
  *
  * const agent = createAgent({
  *   model: "openai:gpt-4o",
- *   middleware: [globalLimiter]
+ *   middleware: [limiter]
  * });
  * ```
  *
- * @example Limit a specific tool
+ * @example Stop immediately when limit exceeded
  * ```ts
- * import { toolCallLimitMiddleware } from "@langchain/langchain/agents/middleware";
- * import { createAgent } from "@langchain/langchain/agents";
- *
- * const searchLimiter = toolCallLimitMiddleware({
- *   toolName: "search",
- *   threadLimit: 5,
- *   runLimit: 3,
+ * // End execution immediately with an AI message
+ * const limiter = toolCallLimitMiddleware({
+ *   runLimit: 5,
  *   exitBehavior: "end"
  * });
  *
  * const agent = createAgent({
  *   model: "openai:gpt-4o",
- *   middleware: [searchLimiter]
+ *   middleware: [limiter]
  * });
  * ```
  *
- * @example Use both in the same agent
+ * @example Raise exception on limit
  * ```ts
- * import { toolCallLimitMiddleware } from "@langchain/langchain/agents/middleware";
- * import { createAgent } from "@langchain/langchain/agents";
- *
- * const globalLimiter = toolCallLimitMiddleware({
- *   threadLimit: 20,
- *   runLimit: 10,
- *   exitBehavior: "end"
- * });
- *
- * const searchLimiter = toolCallLimitMiddleware({
+ * // Strict limit with exception handling
+ * const limiter = toolCallLimitMiddleware({
  *   toolName: "search",
  *   threadLimit: 5,
- *   runLimit: 3,
- *   exitBehavior: "end"
+ *   exitBehavior: "error"
  * });
  *
  * const agent = createAgent({
  *   model: "openai:gpt-4o",
- *   middleware: [globalLimiter, searchLimiter]
+ *   middleware: [limiter]
  * });
+ *
+ * try {
+ *   const result = await agent.invoke({ messages: [new HumanMessage("Task")] });
+ * } catch (error) {
+ *   if (error instanceof ToolCallLimitExceededError) {
+ *     console.log(`Search limit exceeded: ${error}`);
+ *   }
+ * }
  * ```
  */
-declare function toolCallLimitMiddleware(options: ToolCallLimitConfig): AgentMiddleware<undefined, undefined, any>;
+declare function toolCallLimitMiddleware(options: ToolCallLimitConfig): AgentMiddleware<z.ZodObject<{
+  threadToolCallCount: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodNumber>>;
+  runToolCallCount: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodNumber>>;
+}, "strip", z.ZodTypeAny, {
+  threadToolCallCount: Record<string, number>;
+  runToolCallCount: Record<string, number>;
+}, {
+  threadToolCallCount?: Record<string, number> | undefined;
+  runToolCallCount?: Record<string, number> | undefined;
+}>, undefined, any>;
 //#endregion
 export { ToolCallLimitConfig, ToolCallLimitExceededError, toolCallLimitMiddleware };
 //# sourceMappingURL=toolCallLimit.d.cts.map