langchain 1.0.2 → 1.0.4

package/dist/agents/middleware/toolRetry.d.ts

@@ -0,0 +1,179 @@
+import { AgentMiddleware } from "./types.js";
+import { ClientTool, ServerTool } from "@langchain/core/tools";
+import { z } from "zod/v3";
+
+//#region src/agents/middleware/toolRetry.d.ts
+
+/**
+ * Configuration options for the Tool Retry Middleware.
+ */
+declare const ToolRetryMiddlewareOptionsSchema: z.ZodObject<{
+  /**
+   * Maximum number of retry attempts after the initial call.
+   * Default is 2 retries (3 total attempts). Must be >= 0.
+   */
+  maxRetries: z.ZodDefault<z.ZodNumber>;
+  /**
+   * Optional list of tools or tool names to apply retry logic to.
+   * Can be a list of `BaseTool` instances or tool name strings.
+   * If `undefined`, applies to all tools. Default is `undefined`.
+   */
+  tools: z.ZodOptional<z.ZodArray<z.ZodUnion<[z.ZodType<ClientTool, z.ZodTypeDef, ClientTool>, z.ZodType<ServerTool, z.ZodTypeDef, ServerTool>, z.ZodString]>, "many">>;
+  /**
+   * Either an array of error constructors to retry on, or a function
+   * that takes an error and returns `true` if it should be retried.
+   * Default is to retry on all errors.
+   */
+  retryOn: z.ZodDefault<z.ZodUnion<[z.ZodFunction<z.ZodTuple<[z.ZodType<Error, z.ZodTypeDef, Error>], z.ZodUnknown>, z.ZodBoolean>, z.ZodArray<z.ZodType<new (...args: any[]) => Error, z.ZodTypeDef, new (...args: any[]) => Error>, "many">]>>;
+  /**
+   * Behavior when all retries are exhausted. Options:
+   * - `"return_message"` (default): Return a ToolMessage with error details,
+   *   allowing the LLM to handle the failure and potentially recover.
+   * - `"raise"`: Re-raise the exception, stopping agent execution.
+   * - Custom function: Function that takes the exception and returns a string
+   *   for the ToolMessage content, allowing custom error formatting.
+   */
+  onFailure: z.ZodDefault<z.ZodUnion<[z.ZodLiteral<"raise">, z.ZodLiteral<"return_message">, z.ZodFunction<z.ZodTuple<[z.ZodType<Error, z.ZodTypeDef, Error>], z.ZodUnknown>, z.ZodString>]>>;
+  /**
+   * Multiplier for exponential backoff. Each retry waits
+   * `initialDelayMs * (backoffFactor ** retryNumber)` milliseconds.
+   * Set to 0.0 for constant delay. Default is 2.0.
+   */
+  backoffFactor: z.ZodDefault<z.ZodNumber>;
+  /**
+   * Initial delay in milliseconds before first retry. Default is 1000 (1 second).
+   */
+  initialDelayMs: z.ZodDefault<z.ZodNumber>;
+  /**
+   * Maximum delay in milliseconds between retries. Caps exponential
+   * backoff growth. Default is 60000 (60 seconds).
+   */
+  maxDelayMs: z.ZodDefault<z.ZodNumber>;
+  /**
+   * Whether to add random jitter (±25%) to delay to avoid thundering herd.
+   * Default is `true`.
+   */
+  jitter: z.ZodDefault<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+  maxRetries: number;
+  tools?: (string | ServerTool | ClientTool)[] | undefined;
+  retryOn: (new (...args: any[]) => Error)[] | ((args_0: Error, ...args: unknown[]) => boolean);
+  onFailure: "raise" | "return_message" | ((args_0: Error, ...args: unknown[]) => string);
+  backoffFactor: number;
+  initialDelayMs: number;
+  maxDelayMs: number;
+  jitter: boolean;
+}, {
+  maxRetries?: number | undefined;
+  tools?: (string | ServerTool | ClientTool)[] | undefined;
+  retryOn?: (new (...args: any[]) => Error)[] | ((args_0: Error, ...args: unknown[]) => boolean) | undefined;
+  onFailure?: "raise" | "return_message" | ((args_0: Error, ...args: unknown[]) => string) | undefined;
+  backoffFactor?: number | undefined;
+  initialDelayMs?: number | undefined;
+  maxDelayMs?: number | undefined;
+  jitter?: boolean | undefined;
+}>;
+type ToolRetryMiddlewareConfig = z.input<typeof ToolRetryMiddlewareOptionsSchema>;
+/**
+ * Middleware that automatically retries failed tool calls with configurable backoff.
+ *
+ * Supports retrying on specific exceptions and exponential backoff.
+ *
+ * @example Basic usage with default settings (2 retries, exponential backoff)
+ * ```ts
+ * import { createAgent, toolRetryMiddleware } from "langchain";
+ *
+ * const agent = createAgent({
+ *   model: "openai:gpt-4o",
+ *   tools: [searchTool],
+ *   middleware: [toolRetryMiddleware()],
+ * });
+ * ```
+ *
+ * @example Retry specific exceptions only
+ * ```ts
+ * import { toolRetryMiddleware } from "langchain";
+ *
+ * const retry = toolRetryMiddleware({
+ *   maxRetries: 4,
+ *   retryOn: [TimeoutError, NetworkError],
+ *   backoffFactor: 1.5,
+ * });
+ * ```
+ *
+ * @example Custom exception filtering
+ * ```ts
+ * function shouldRetry(error: Error): boolean {
+ *   // Only retry on 5xx errors
+ *   if (error.name === "HTTPError" && "statusCode" in error) {
+ *     const statusCode = (error as any).statusCode;
+ *     return 500 <= statusCode && statusCode < 600;
+ *   }
+ *   return false;
+ * }
+ *
+ * const retry = toolRetryMiddleware({
+ *   maxRetries: 3,
+ *   retryOn: shouldRetry,
+ * });
+ * ```
+ *
+ * @example Apply to specific tools with custom error handling
+ * ```ts
+ * const formatError = (error: Error) =>
+ *   "Database temporarily unavailable. Please try again later.";
+ *
+ * const retry = toolRetryMiddleware({
+ *   maxRetries: 4,
+ *   tools: ["search_database"],
+ *   onFailure: formatError,
+ * });
+ * ```
+ *
+ * @example Apply to specific tools using BaseTool instances
+ * ```ts
+ * import { tool } from "@langchain/core/tools";
+ * import { z } from "zod";
+ *
+ * const searchDatabase = tool(
+ *   async ({ query }) => {
+ *     // Search implementation
+ *     return results;
+ *   },
+ *   {
+ *     name: "search_database",
+ *     description: "Search the database",
+ *     schema: z.object({ query: z.string() }),
+ *   }
+ * );
+ *
+ * const retry = toolRetryMiddleware({
+ *   maxRetries: 4,
+ *   tools: [searchDatabase], // Pass BaseTool instance
+ * });
+ * ```
+ *
+ * @example Constant backoff (no exponential growth)
+ * ```ts
+ * const retry = toolRetryMiddleware({
+ *   maxRetries: 5,
+ *   backoffFactor: 0.0, // No exponential growth
+ *   initialDelayMs: 2000, // Always wait 2 seconds
+ * });
+ * ```
+ *
+ * @example Raise exception on failure
+ * ```ts
+ * const retry = toolRetryMiddleware({
+ *   maxRetries: 2,
+ *   onFailure: "raise", // Re-raise exception instead of returning message
+ * });
+ * ```
+ *
+ * @param config - Configuration options for the retry middleware
+ * @returns A middleware instance that handles tool failures with retries
+ */
+declare function toolRetryMiddleware(config?: ToolRetryMiddlewareConfig): AgentMiddleware;
+//#endregion
+export { ToolRetryMiddlewareConfig, toolRetryMiddleware };
+//# sourceMappingURL=toolRetry.d.ts.map

package/dist/agents/middleware/toolRetry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"toolRetry.d.ts","names":["z","ClientTool","ServerTool","AgentMiddleware","calculateRetryDelay","ToolRetryMiddlewareOptionsSchema","ZodNumber","ZodDefault","ZodTypeDef","ZodType","ZodString","ZodUnion","ZodArray","ZodOptional","Error","ZodUnknown","ZodTuple","ZodBoolean","ZodFunction","ZodLiteral","ZodTypeAny","ZodObject","ToolRetryMiddlewareConfig","input","toolRetryMiddleware"],"sources":["../../../src/agents/middleware/toolRetry.d.ts"],"sourcesContent":["/**\n * Tool retry middleware for agents.\n */\nimport { z } from \"zod/v3\";\nimport type { ClientTool, ServerTool } from \"@langchain/core/tools\";\nimport type { AgentMiddleware } from \"./types.js\";\n/**\n * Calculate delay for a retry attempt with exponential backoff and jitter.\n *\n * @param retryNumber - The retry attempt number (0-indexed)\n * @param config - Configuration for backoff calculation\n * @returns Delay in milliseconds before next retry\n *\n * @internal Exported for testing purposes\n */\nexport declare function calculateRetryDelay(config: {\n    backoffFactor: number;\n    initialDelayMs: number;\n    maxDelayMs: number;\n    jitter: boolean;\n}, retryNumber: number): number;\n/**\n * Configuration options for the Tool Retry Middleware.\n */\nexport declare const ToolRetryMiddlewareOptionsSchema: z.ZodObject<{\n    /**\n     * Maximum number of retry attempts after the initial call.\n     * Default is 2 retries (3 total attempts). Must be >= 0.\n     */\n    maxRetries: z.ZodDefault<z.ZodNumber>;\n    /**\n     * Optional list of tools or tool names to apply retry logic to.\n     * Can be a list of `BaseTool` instances or tool name strings.\n     * If `undefined`, applies to all tools. Default is `undefined`.\n     */\n    tools: z.ZodOptional<z.ZodArray<z.ZodUnion<[z.ZodType<ClientTool, z.ZodTypeDef, ClientTool>, z.ZodType<ServerTool, z.ZodTypeDef, ServerTool>, z.ZodString]>, \"many\">>;\n    /**\n     * Either an array of error constructors to retry on, or a function\n     * that takes an error and returns `true` if it should be retried.\n     * Default is to retry on all errors.\n     */\n    retryOn: z.ZodDefault<z.ZodUnion<[z.ZodFunction<z.ZodTuple<[z.ZodType<Error, z.ZodTypeDef, Error>], z.ZodUnknown>, z.ZodBoolean>, z.ZodArray<z.ZodType<new (...args: any[]) => Error, z.ZodTypeDef, new (...args: any[]) => Error>, \"many\">]>>;\n    /**\n     * Behavior when all retries are exhausted. Options:\n     * - `\"return_message\"` (default): Return a ToolMessage with error details,\n     *   allowing the LLM to handle the failure and potentially recover.\n     * - `\"raise\"`: Re-raise the exception, stopping agent execution.\n     * - Custom function: Function that takes the exception and returns a string\n     *   for the ToolMessage content, allowing custom error formatting.\n     */\n    onFailure: z.ZodDefault<z.ZodUnion<[z.ZodLiteral<\"raise\">, z.ZodLiteral<\"return_message\">, z.ZodFunction<z.ZodTuple<[z.ZodType<Error, z.ZodTypeDef, Error>], z.ZodUnknown>, z.ZodString>]>>;\n    /**\n     * Multiplier for exponential backoff. Each retry waits\n     * `initialDelayMs * (backoffFactor ** retryNumber)` milliseconds.\n     * Set to 0.0 for constant delay. Default is 2.0.\n     */\n    backoffFactor: z.ZodDefault<z.ZodNumber>;\n    /**\n     * Initial delay in milliseconds before first retry. Default is 1000 (1 second).\n     */\n    initialDelayMs: z.ZodDefault<z.ZodNumber>;\n    /**\n     * Maximum delay in milliseconds between retries. Caps exponential\n     * backoff growth. Default is 60000 (60 seconds).\n     */\n    maxDelayMs: z.ZodDefault<z.ZodNumber>;\n    /**\n     * Whether to add random jitter (±25%) to delay to avoid thundering herd.\n     * Default is `true`.\n     */\n    jitter: z.ZodDefault<z.ZodBoolean>;\n}, \"strip\", z.ZodTypeAny, {\n    maxRetries: number;\n    tools?: (string | ServerTool | ClientTool)[] | undefined;\n    retryOn: (new (...args: any[]) => Error)[] | ((args_0: Error, ...args: unknown[]) => boolean);\n    onFailure: \"raise\" | \"return_message\" | ((args_0: Error, ...args: unknown[]) => string);\n    backoffFactor: number;\n    initialDelayMs: number;\n    maxDelayMs: number;\n    jitter: boolean;\n}, {\n    maxRetries?: number | undefined;\n    tools?: (string | ServerTool | ClientTool)[] | undefined;\n    retryOn?: (new (...args: any[]) => Error)[] | ((args_0: Error, ...args: unknown[]) => boolean) | undefined;\n    onFailure?: \"raise\" | \"return_message\" | ((args_0: Error, ...args: unknown[]) => string) | undefined;\n    backoffFactor?: number | undefined;\n    initialDelayMs?: number | undefined;\n    maxDelayMs?: number | undefined;\n    jitter?: boolean | undefined;\n}>;\nexport type ToolRetryMiddlewareConfig = z.input<typeof ToolRetryMiddlewareOptionsSchema>;\n/**\n * Middleware that automatically retries failed tool calls with configurable backoff.\n *\n * Supports retrying on specific exceptions and exponential backoff.\n *\n * @example Basic usage with default settings (2 retries, exponential backoff)\n * ```ts\n * import { createAgent, toolRetryMiddleware } from \"langchain\";\n *\n * const agent = createAgent({\n *   model: \"openai:gpt-4o\",\n *   tools: [searchTool],\n *   middleware: [toolRetryMiddleware()],\n * });\n * ```\n *\n * @example Retry specific exceptions only\n * ```ts\n * import { toolRetryMiddleware } from \"langchain\";\n *\n * const retry = toolRetryMiddleware({\n *   maxRetries: 4,\n *   retryOn: [TimeoutError, NetworkError],\n *   backoffFactor: 1.5,\n * });\n * ```\n *\n * @example Custom exception filtering\n * ```ts\n * function shouldRetry(error: Error): boolean {\n *   // Only retry on 5xx errors\n *   if (error.name === \"HTTPError\" && \"statusCode\" in error) {\n *     const statusCode = (error as any).statusCode;\n *     return 500 <= statusCode && statusCode < 600;\n *   }\n *   return false;\n * }\n *\n * const retry = toolRetryMiddleware({\n *   maxRetries: 3,\n *   retryOn: shouldRetry,\n * });\n * ```\n *\n * @example Apply to specific tools with custom error handling\n * ```ts\n * const formatError = (error: Error) =>\n *   \"Database temporarily unavailable. Please try again later.\";\n *\n * const retry = toolRetryMiddleware({\n *   maxRetries: 4,\n *   tools: [\"search_database\"],\n *   onFailure: formatError,\n * });\n * ```\n *\n * @example Apply to specific tools using BaseTool instances\n * ```ts\n * import { tool } from \"@langchain/core/tools\";\n * import { z } from \"zod\";\n *\n * const searchDatabase = tool(\n *   async ({ query }) => {\n *     // Search implementation\n *     return results;\n *   },\n *   {\n *     name: \"search_database\",\n *     description: \"Search the database\",\n *     schema: z.object({ query: z.string() }),\n *   }\n * );\n *\n * const retry = toolRetryMiddleware({\n *   maxRetries: 4,\n *   tools: [searchDatabase], // Pass BaseTool instance\n * });\n * ```\n *\n * @example Constant backoff (no exponential growth)\n * ```ts\n * const retry = toolRetryMiddleware({\n *   maxRetries: 5,\n *   backoffFactor: 0.0, // No exponential growth\n *   initialDelayMs: 2000, // Always wait 2 seconds\n * });\n * ```\n *\n * @example Raise exception on failure\n * ```ts\n * const retry = toolRetryMiddleware({\n *   maxRetries: 2,\n *   onFailure: \"raise\", // Re-raise exception instead of returning message\n * });\n * ```\n *\n * @param config - Configuration options for the retry middleware\n * @returns A middleware instance that handles tool failures with retries\n */\nexport declare function toolRetryMiddleware(config?: ToolRetryMiddlewareConfig): AgentMiddleware;\n"],"mappings":"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"}

package/dist/agents/middleware/toolRetry.js

@@ -0,0 +1,223 @@
+import { sleep } from "./utils.js";
+import { createMiddleware } from "../middleware.js";
+import { ToolMessage } from "@langchain/core/messages";
+import { z } from "zod/v3";
+
+//#region src/agents/middleware/toolRetry.ts
+/**
+* Calculate delay for a retry attempt with exponential backoff and jitter.
+*
+* @param retryNumber - The retry attempt number (0-indexed)
+* @param config - Configuration for backoff calculation
+* @returns Delay in milliseconds before next retry
+*
+* @internal Exported for testing purposes
+*/
+function calculateRetryDelay(config, retryNumber) {
+	const { backoffFactor, initialDelayMs, maxDelayMs, jitter } = config;
+	let delay;
+	if (backoffFactor === 0) delay = initialDelayMs;
+	else delay = initialDelayMs * backoffFactor ** retryNumber;
+	delay = Math.min(delay, maxDelayMs);
+	if (jitter && delay > 0) {
+		const jitterAmount = delay * .25;
+		delay = delay + (Math.random() * 2 - 1) * jitterAmount;
+		delay = Math.max(0, delay);
+	}
+	return delay;
+}
+/**
+* Configuration options for the Tool Retry Middleware.
+*/
+const ToolRetryMiddlewareOptionsSchema = z.object({
+	maxRetries: z.number().min(0).default(2),
+	tools: z.array(z.union([
+		z.custom(),
+		z.custom(),
+		z.string()
+	])).optional(),
+	retryOn: z.union([z.function().args(z.instanceof(Error)).returns(z.boolean()), z.array(z.custom())]).default(() => () => true),
+	onFailure: z.union([
+		z.literal("raise"),
+		z.literal("return_message"),
+		z.function().args(z.instanceof(Error)).returns(z.string())
+	]).default("return_message"),
+	backoffFactor: z.number().min(0).default(2),
+	initialDelayMs: z.number().min(0).default(1e3),
+	maxDelayMs: z.number().min(0).default(6e4),
+	jitter: z.boolean().default(true)
+});
+/**
+* Middleware that automatically retries failed tool calls with configurable backoff.
+*
+* Supports retrying on specific exceptions and exponential backoff.
+*
+* @example Basic usage with default settings (2 retries, exponential backoff)
+* ```ts
+* import { createAgent, toolRetryMiddleware } from "langchain";
+*
+* const agent = createAgent({
+*   model: "openai:gpt-4o",
+*   tools: [searchTool],
+*   middleware: [toolRetryMiddleware()],
+* });
+* ```
+*
+* @example Retry specific exceptions only
+* ```ts
+* import { toolRetryMiddleware } from "langchain";
+*
+* const retry = toolRetryMiddleware({
+*   maxRetries: 4,
+*   retryOn: [TimeoutError, NetworkError],
+*   backoffFactor: 1.5,
+* });
+* ```
+*
+* @example Custom exception filtering
+* ```ts
+* function shouldRetry(error: Error): boolean {
+*   // Only retry on 5xx errors
+*   if (error.name === "HTTPError" && "statusCode" in error) {
+*     const statusCode = (error as any).statusCode;
+*     return 500 <= statusCode && statusCode < 600;
+*   }
+*   return false;
+* }
+*
+* const retry = toolRetryMiddleware({
+*   maxRetries: 3,
+*   retryOn: shouldRetry,
+* });
+* ```
+*
+* @example Apply to specific tools with custom error handling
+* ```ts
+* const formatError = (error: Error) =>
+*   "Database temporarily unavailable. Please try again later.";
+*
+* const retry = toolRetryMiddleware({
+*   maxRetries: 4,
+*   tools: ["search_database"],
+*   onFailure: formatError,
+* });
+* ```
+*
+* @example Apply to specific tools using BaseTool instances
+* ```ts
+* import { tool } from "@langchain/core/tools";
+* import { z } from "zod";
+*
+* const searchDatabase = tool(
+*   async ({ query }) => {
+*     // Search implementation
+*     return results;
+*   },
+*   {
+*     name: "search_database",
+*     description: "Search the database",
+*     schema: z.object({ query: z.string() }),
+*   }
+* );
+*
+* const retry = toolRetryMiddleware({
+*   maxRetries: 4,
+*   tools: [searchDatabase], // Pass BaseTool instance
+* });
+* ```
+*
+* @example Constant backoff (no exponential growth)
+* ```ts
+* const retry = toolRetryMiddleware({
+*   maxRetries: 5,
+*   backoffFactor: 0.0, // No exponential growth
+*   initialDelayMs: 2000, // Always wait 2 seconds
+* });
+* ```
+*
+* @example Raise exception on failure
+* ```ts
+* const retry = toolRetryMiddleware({
+*   maxRetries: 2,
+*   onFailure: "raise", // Re-raise exception instead of returning message
+* });
+* ```
+*
+* @param config - Configuration options for the retry middleware
+* @returns A middleware instance that handles tool failures with retries
+*/
+function toolRetryMiddleware(config = {}) {
+	const { maxRetries, tools, retryOn, onFailure, backoffFactor, initialDelayMs, maxDelayMs, jitter } = ToolRetryMiddlewareOptionsSchema.parse(config);
+	const toolFilter = [];
+	for (const tool of tools ?? []) if (typeof tool === "string") toolFilter.push(tool);
+	else if ("name" in tool && typeof tool.name === "string") toolFilter.push(tool.name);
+	else throw new TypeError("Expected a tool name string or tool instance to be passed to toolRetryMiddleware");
+	/**
+	* Check if retry logic should apply to this tool.
+	*/
+	const shouldRetryTool = (toolName) => {
+		if (toolFilter.length === 0) return true;
+		return toolFilter.includes(toolName);
+	};
+	/**
+	* Check if the exception should trigger a retry.
+	*/
+	const shouldRetryException = (error) => {
+		if (typeof retryOn === "function") return retryOn(error);
+		return retryOn.some((ErrorConstructor) => error.constructor === ErrorConstructor);
+	};
+	const delayConfig = {
+		backoffFactor,
+		initialDelayMs,
+		maxDelayMs,
+		jitter
+	};
+	/**
+	* Format the failure message when retries are exhausted.
+	*/
+	const formatFailureMessage = (toolName, error, attemptsMade) => {
+		const errorType = error.constructor.name;
+		const attemptWord = attemptsMade === 1 ? "attempt" : "attempts";
+		return `Tool '${toolName}' failed after ${attemptsMade} ${attemptWord} with ${errorType}`;
+	};
+	/**
+	* Handle failure when all retries are exhausted.
+	*/
+	const handleFailure = (toolName, toolCallId, error, attemptsMade) => {
+		if (onFailure === "raise") throw error;
+		let content;
+		if (typeof onFailure === "function") content = onFailure(error);
+		else content = formatFailureMessage(toolName, error, attemptsMade);
+		return new ToolMessage({
+			content,
+			tool_call_id: toolCallId,
+			name: toolName,
+			status: "error"
+		});
+	};
+	return createMiddleware({
+		name: "toolRetryMiddleware",
+		contextSchema: ToolRetryMiddlewareOptionsSchema,
+		wrapToolCall: async (request, handler) => {
+			const toolName = request.tool.name;
+			if (!shouldRetryTool(toolName)) return handler(request);
+			const toolCallId = request.toolCall.id ?? "";
+			for (let attempt = 0; attempt <= maxRetries; attempt++) try {
+				return await handler(request);
+			} catch (error) {
+				const attemptsMade = attempt + 1;
+				const err = error && typeof error === "object" && "message" in error ? error : new Error(String(error));
+				if (!shouldRetryException(err)) return handleFailure(toolName, toolCallId, err, attemptsMade);
+				if (attempt < maxRetries) {
+					const delay = calculateRetryDelay(delayConfig, attempt);
+					if (delay > 0) await sleep(delay);
+				} else return handleFailure(toolName, toolCallId, err, attemptsMade);
+			}
+			throw new Error("Unexpected: retry loop completed without returning");
+		}
+	});
+}
+
+//#endregion
+export { toolRetryMiddleware };
+//# sourceMappingURL=toolRetry.js.map

package/dist/agents/middleware/toolRetry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"toolRetry.js","names":["config: {\n    backoffFactor: number;\n    initialDelayMs: number;\n    maxDelayMs: number;\n    jitter: boolean;\n  }","retryNumber: number","delay: number","config: ToolRetryMiddlewareConfig","toolFilter: string[]","toolName: string","error: Error","attemptsMade: number","toolCallId: string","content: string"],"sources":["../../../src/agents/middleware/toolRetry.ts"],"sourcesContent":["/**\n * Tool retry middleware for agents.\n */\nimport { z } from \"zod/v3\";\nimport { ToolMessage } from \"@langchain/core/messages\";\nimport type { ClientTool, ServerTool } from \"@langchain/core/tools\";\n\nimport { createMiddleware } from \"../middleware.js\";\nimport type { AgentMiddleware } from \"./types.js\";\nimport { sleep } from \"./utils.js\";\n\n/**\n * Calculate delay for a retry attempt with exponential backoff and jitter.\n *\n * @param retryNumber - The retry attempt number (0-indexed)\n * @param config - Configuration for backoff calculation\n * @returns Delay in milliseconds before next retry\n *\n * @internal Exported for testing purposes\n */\nexport function calculateRetryDelay(\n  config: {\n    backoffFactor: number;\n    initialDelayMs: number;\n    maxDelayMs: number;\n    jitter: boolean;\n  },\n  retryNumber: number\n): number {\n  const { backoffFactor, initialDelayMs, maxDelayMs, jitter } = config;\n\n  let delay: number;\n  if (backoffFactor === 0.0) {\n    delay = initialDelayMs;\n  } else {\n    delay = initialDelayMs * backoffFactor ** retryNumber;\n  }\n\n  // Cap at maxDelayMs\n  delay = Math.min(delay, maxDelayMs);\n\n  if (jitter && delay > 0) {\n    const jitterAmount = delay * 0.25;\n    delay = delay + (Math.random() * 2 - 1) * jitterAmount;\n    // Ensure delay is not negative after jitter\n    delay = Math.max(0, delay);\n  }\n\n  return delay;\n}\n\n/**\n * Configuration options for the Tool Retry Middleware.\n */\nexport const ToolRetryMiddlewareOptionsSchema = z.object({\n  /**\n   * Maximum number of retry attempts after the initial call.\n   * Default is 2 retries (3 total attempts). Must be >= 0.\n   */\n  maxRetries: z.number().min(0).default(2),\n\n  /**\n   * Optional list of tools or tool names to apply retry logic to.\n   * Can be a list of `BaseTool` instances or tool name strings.\n   * If `undefined`, applies to all tools. Default is `undefined`.\n   */\n  tools: z\n    .array(\n      z.union([z.custom<ClientTool>(), z.custom<ServerTool>(), z.string()])\n    )\n    .optional(),\n\n  /**\n   * Either an array of error constructors to retry on, or a function\n   * that takes an error and returns `true` if it should be retried.\n   * Default is to retry on all errors.\n   */\n  retryOn: z\n    .union([\n      z.function().args(z.instanceof(Error)).returns(z.boolean()),\n      // eslint-disable-next-line @typescript-eslint/no-explicit-any\n      z.array(z.custom<new (...args: any[]) => Error>()),\n    ])\n    .default(() => () => true),\n\n  /**\n   * Behavior when all retries are exhausted. Options:\n   * - `\"return_message\"` (default): Return a ToolMessage with error details,\n   *   allowing the LLM to handle the failure and potentially recover.\n   * - `\"raise\"`: Re-raise the exception, stopping agent execution.\n   * - Custom function: Function that takes the exception and returns a string\n   *   for the ToolMessage content, allowing custom error formatting.\n   */\n  onFailure: z\n    .union([\n      z.literal(\"raise\"),\n      z.literal(\"return_message\"),\n      z.function().args(z.instanceof(Error)).returns(z.string()),\n    ])\n    .default(\"return_message\"),\n\n  /**\n   * Multiplier for exponential backoff. Each retry waits\n   * `initialDelayMs * (backoffFactor ** retryNumber)` milliseconds.\n   * Set to 0.0 for constant delay. Default is 2.0.\n   */\n  backoffFactor: z.number().min(0).default(2.0),\n\n  /**\n   * Initial delay in milliseconds before first retry. Default is 1000 (1 second).\n   */\n  initialDelayMs: z.number().min(0).default(1000),\n\n  /**\n   * Maximum delay in milliseconds between retries. Caps exponential\n   * backoff growth. Default is 60000 (60 seconds).\n   */\n  maxDelayMs: z.number().min(0).default(60000),\n\n  /**\n   * Whether to add random jitter (±25%) to delay to avoid thundering herd.\n   * Default is `true`.\n   */\n  jitter: z.boolean().default(true),\n});\n\nexport type ToolRetryMiddlewareConfig = z.input<\n  typeof ToolRetryMiddlewareOptionsSchema\n>;\n\n/**\n * Middleware that automatically retries failed tool calls with configurable backoff.\n *\n * Supports retrying on specific exceptions and exponential backoff.\n *\n * @example Basic usage with default settings (2 retries, exponential backoff)\n * ```ts\n * import { createAgent, toolRetryMiddleware } from \"langchain\";\n *\n * const agent = createAgent({\n *   model: \"openai:gpt-4o\",\n *   tools: [searchTool],\n *   middleware: [toolRetryMiddleware()],\n * });\n * ```\n *\n * @example Retry specific exceptions only\n * ```ts\n * import { toolRetryMiddleware } from \"langchain\";\n *\n * const retry = toolRetryMiddleware({\n *   maxRetries: 4,\n *   retryOn: [TimeoutError, NetworkError],\n *   backoffFactor: 1.5,\n * });\n * ```\n *\n * @example Custom exception filtering\n * ```ts\n * function shouldRetry(error: Error): boolean {\n *   // Only retry on 5xx errors\n *   if (error.name === \"HTTPError\" && \"statusCode\" in error) {\n *     const statusCode = (error as any).statusCode;\n *     return 500 <= statusCode && statusCode < 600;\n *   }\n *   return false;\n * }\n *\n * const retry = toolRetryMiddleware({\n *   maxRetries: 3,\n *   retryOn: shouldRetry,\n * });\n * ```\n *\n * @example Apply to specific tools with custom error handling\n * ```ts\n * const formatError = (error: Error) =>\n *   \"Database temporarily unavailable. Please try again later.\";\n *\n * const retry = toolRetryMiddleware({\n *   maxRetries: 4,\n *   tools: [\"search_database\"],\n *   onFailure: formatError,\n * });\n * ```\n *\n * @example Apply to specific tools using BaseTool instances\n * ```ts\n * import { tool } from \"@langchain/core/tools\";\n * import { z } from \"zod\";\n *\n * const searchDatabase = tool(\n *   async ({ query }) => {\n *     // Search implementation\n *     return results;\n *   },\n *   {\n *     name: \"search_database\",\n *     description: \"Search the database\",\n *     schema: z.object({ query: z.string() }),\n *   }\n * );\n *\n * const retry = toolRetryMiddleware({\n *   maxRetries: 4,\n *   tools: [searchDatabase], // Pass BaseTool instance\n * });\n * ```\n *\n * @example Constant backoff (no exponential growth)\n * ```ts\n * const retry = toolRetryMiddleware({\n *   maxRetries: 5,\n *   backoffFactor: 0.0, // No exponential growth\n *   initialDelayMs: 2000, // Always wait 2 seconds\n * });\n * ```\n *\n * @example Raise exception on failure\n * ```ts\n * const retry = toolRetryMiddleware({\n *   maxRetries: 2,\n *   onFailure: \"raise\", // Re-raise exception instead of returning message\n * });\n * ```\n *\n * @param config - Configuration options for the retry middleware\n * @returns A middleware instance that handles tool failures with retries\n */\nexport function toolRetryMiddleware(\n  config: ToolRetryMiddlewareConfig = {}\n): AgentMiddleware {\n  const {\n    maxRetries,\n    tools,\n    retryOn,\n    onFailure,\n    backoffFactor,\n    initialDelayMs,\n    maxDelayMs,\n    jitter,\n  } = ToolRetryMiddlewareOptionsSchema.parse(config);\n\n  // Extract tool names from BaseTool instances or strings\n  const toolFilter: string[] = [];\n  for (const tool of tools ?? []) {\n    if (typeof tool === \"string\") {\n      toolFilter.push(tool);\n    } else if (\"name\" in tool && typeof tool.name === \"string\") {\n      toolFilter.push(tool.name);\n    } else {\n      throw new TypeError(\n        \"Expected a tool name string or tool instance to be passed to toolRetryMiddleware\"\n      );\n    }\n  }\n\n  /**\n   * Check if retry logic should apply to this tool.\n   */\n  const shouldRetryTool = (toolName: string): boolean => {\n    if (toolFilter.length === 0) {\n      return true;\n    }\n    return toolFilter.includes(toolName);\n  };\n\n  /**\n   * Check if the exception should trigger a retry.\n   */\n  const shouldRetryException = (error: Error): boolean => {\n    if (typeof retryOn === \"function\") {\n      return retryOn(error);\n    }\n    // retryOn is an array of error constructors\n    return retryOn.some(\n      (ErrorConstructor) => error.constructor === ErrorConstructor\n    );\n  };\n\n  // Use the exported calculateRetryDelay function with our config\n  const delayConfig = { backoffFactor, initialDelayMs, maxDelayMs, jitter };\n\n  /**\n   * Format the failure message when retries are exhausted.\n   */\n  const formatFailureMessage = (\n    toolName: string,\n    error: Error,\n    attemptsMade: number\n  ): string => {\n    const errorType = error.constructor.name;\n    const attemptWord = attemptsMade === 1 ? \"attempt\" : \"attempts\";\n    return `Tool '${toolName}' failed after ${attemptsMade} ${attemptWord} with ${errorType}`;\n  };\n\n  /**\n   * Handle failure when all retries are exhausted.\n   */\n  const handleFailure = (\n    toolName: string,\n    toolCallId: string,\n    error: Error,\n    attemptsMade: number\n  ): ToolMessage => {\n    if (onFailure === \"raise\") {\n      throw error;\n    }\n\n    let content: string;\n    if (typeof onFailure === \"function\") {\n      content = onFailure(error);\n    } else {\n      content = formatFailureMessage(toolName, error, attemptsMade);\n    }\n\n    return new ToolMessage({\n      content,\n      tool_call_id: toolCallId,\n      name: toolName,\n      status: \"error\",\n    });\n  };\n\n  return createMiddleware({\n    name: \"toolRetryMiddleware\",\n    contextSchema: ToolRetryMiddlewareOptionsSchema,\n    wrapToolCall: async (request, handler) => {\n      const toolName = request.tool.name as string;\n\n      // Check if retry should apply to this tool\n      if (!shouldRetryTool(toolName)) {\n        return handler(request);\n      }\n\n      const toolCallId = request.toolCall.id ?? \"\";\n\n      // Initial attempt + retries\n      for (let attempt = 0; attempt <= maxRetries; attempt++) {\n        try {\n          return await handler(request);\n        } catch (error) {\n          const attemptsMade = attempt + 1; // attempt is 0-indexed\n\n          // Ensure error is an Error instance\n          const err =\n            error && typeof error === \"object\" && \"message\" in error\n              ? (error as Error)\n              : new Error(String(error));\n\n          // Check if we should retry this exception\n          if (!shouldRetryException(err)) {\n            // Exception is not retryable, handle failure immediately\n            return handleFailure(toolName, toolCallId, err, attemptsMade);\n          }\n\n          // Check if we have more retries left\n          if (attempt < maxRetries) {\n            // Calculate and apply backoff delay\n            const delay = calculateRetryDelay(delayConfig, attempt);\n            if (delay > 0) {\n              await sleep(delay);\n            }\n            // Continue to next retry\n          } else {\n            // No more retries, handle failure\n            return handleFailure(toolName, toolCallId, err, attemptsMade);\n          }\n        }\n      }\n\n      // Unreachable: loop always returns via handler success or handleFailure\n      throw new Error(\"Unexpected: retry loop completed without returning\");\n    },\n  });\n}\n"],"mappings":"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"}

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

@@ -1,8 +1,8 @@
 import { JumpToTarget } from "../constants.cjs";
-import { ClientTool, ServerTool } from "../tools.cjs";
 import { AgentBuiltInState, Runtime } from "../runtime.cjs";
 import { ModelRequest } from "../nodes/types.cjs";
 import { AIMessage, ToolMessage } from "@langchain/core/messages";
+import { ClientTool, ServerTool } from "@langchain/core/tools";
 import { InferInteropZodInput, InferInteropZodOutput, InteropZodDefault, InteropZodObject, InteropZodOptional } from "@langchain/core/utils/types";
 import { ToolCall as ToolCall$1 } from "@langchain/core/messages/tool";
 import { AnnotationRoot, Command } from "@langchain/langgraph";
@@ -11,11 +11,13 @@ import { InteropZodToStateDefinition } from "@langchain/langgraph/zod";
 //#region src/agents/middleware/types.d.ts
 type PromiseOrValue<T> = T | Promise<T>;
 type AnyAnnotationRoot = AnnotationRoot<any>;
-type NormalizedSchemaInput<TSchema extends InteropZodObject | undefined = any> = TSchema extends InteropZodObject ? InferInteropZodInput<TSchema> : {};
+type NormalizedSchemaInput<TSchema extends InteropZodObject | undefined | never = any> = [TSchema] extends [never] ? AgentBuiltInState : TSchema extends InteropZodObject ? InferInteropZodOutput<TSchema> & AgentBuiltInState : TSchema extends Record<string, unknown> ? TSchema & AgentBuiltInState : AgentBuiltInState;
 /**
  * Result type for middleware functions.
  */
-type MiddlewareResult<TState> = TState | void;
+type MiddlewareResult<TState> = (TState & {
+  jumpTo?: JumpToTarget;
+}) | void;
 /**
  * Represents a tool call request for the wrapToolCall hook.
  * Contains the tool call information along with the agent's current state and runtime.
@@ -43,12 +45,12 @@ interface ToolCallRequest<TState extends Record<string, unknown> = Record<string
  * Handler function type for wrapping tool calls.
  * Takes a tool call request and returns the tool result or a command.
  */
-type ToolCallHandler<TSchema extends InteropZodObject | undefined = any, TContext = unknown> = (request: ToolCallRequest<NormalizedSchemaInput<TSchema> & AgentBuiltInState, TContext>) => PromiseOrValue<ToolMessage | Command>;
+type ToolCallHandler<TSchema extends Record<string, unknown> = AgentBuiltInState, TContext = unknown> = (request: ToolCallRequest<TSchema, TContext>) => PromiseOrValue<ToolMessage | Command>;
 /**
  * Wrapper function type for the wrapToolCall hook.
  * Allows middleware to intercept and modify tool execution.
  */
-type WrapToolCallHook<TSchema extends InteropZodObject | undefined = any, TContext = unknown> = (request: ToolCallRequest<NormalizedSchemaInput<TSchema> & AgentBuiltInState, TContext>, handler: ToolCallHandler<TSchema, TContext>) => PromiseOrValue<ToolMessage | Command>;
+type WrapToolCallHook<TSchema extends InteropZodObject | undefined = undefined, TContext = unknown> = (request: ToolCallRequest<NormalizedSchemaInput<TSchema>, TContext>, handler: ToolCallHandler<NormalizedSchemaInput<TSchema>, TContext>) => PromiseOrValue<ToolMessage | Command>;
 /**
  * Handler function type for wrapping model calls.
  * Takes a model request and returns the AI message response.
@@ -56,7 +58,7 @@ type WrapToolCallHook<TSchema extends InteropZodObject | undefined = any, TConte
  * @param request - The model request containing model, messages, systemPrompt, tools, state, and runtime
  * @returns The AI message response from the model
  */
-type WrapModelCallHandler<TSchema extends InteropZodObject | undefined = any, TContext = unknown> = (request: ModelRequest<NormalizedSchemaInput<TSchema> & AgentBuiltInState, TContext>) => PromiseOrValue<AIMessage>;
+type WrapModelCallHandler<TSchema extends InteropZodObject | undefined = undefined, TContext = unknown> = (request: ModelRequest<NormalizedSchemaInput<TSchema>, TContext>) => PromiseOrValue<AIMessage>;
 /**
  * Wrapper function type for the wrapModelCall hook.
  * Allows middleware to intercept and modify model execution.
@@ -70,7 +72,7 @@ type WrapModelCallHandler<TSchema extends InteropZodObject | undefined = any, TC
  * @param handler - The function that invokes the model. Call this with a ModelRequest to get the response
  * @returns The AI message response from the model (or a modified version)
  */
-type WrapModelCallHook<TSchema extends InteropZodObject | undefined = any, TContext = unknown> = (request: ModelRequest<NormalizedSchemaInput<TSchema> & AgentBuiltInState, TContext>, handler: WrapModelCallHandler<TSchema, TContext>) => PromiseOrValue<AIMessage>;
+type WrapModelCallHook<TSchema extends InteropZodObject | undefined = undefined, TContext = unknown> = (request: ModelRequest<NormalizedSchemaInput<TSchema>, TContext>, handler: WrapModelCallHandler<TSchema, TContext>) => PromiseOrValue<AIMessage>;
 /**
  * Handler function type for the beforeAgent hook.
  * Called once at the start of agent invocation before any model calls or tool executions.
@@ -79,14 +81,14 @@ type WrapModelCallHook<TSchema extends InteropZodObject | undefined = any, TCont
  * @param runtime - The runtime context containing metadata, signal, writer, interrupt, etc.
  * @returns A middleware result containing partial state updates or undefined to pass through
  */
-type BeforeAgentHandler<TSchema extends InteropZodObject | undefined = any, TContext = unknown> = (state: NormalizedSchemaInput<TSchema> & AgentBuiltInState, runtime: Runtime<TContext>) => PromiseOrValue<MiddlewareResult<Partial<NormalizedSchemaInput<TSchema>>>>;
+type BeforeAgentHandler<TSchema, TContext> = (state: TSchema, runtime: Runtime<TContext>) => PromiseOrValue<MiddlewareResult<Partial<TSchema>>>;
 /**
  * Hook type for the beforeAgent lifecycle event.
  * Can be either a handler function or an object with a handler and optional jump targets.
  * This hook is called once at the start of the agent invocation.
  */
-type BeforeAgentHook<TSchema extends InteropZodObject | undefined = any, TContext = unknown> = BeforeAgentHandler<TSchema, TContext> | {
-  hook: BeforeAgentHandler<TSchema, TContext>;
+type BeforeAgentHook<TSchema extends InteropZodObject | undefined = undefined, TContext = unknown> = BeforeAgentHandler<NormalizedSchemaInput<TSchema>, TContext> | {
+  hook: BeforeAgentHandler<NormalizedSchemaInput<TSchema>, TContext>;
   canJumpTo?: JumpToTarget[];
 };
 /**
@@ -97,14 +99,14 @@ type BeforeAgentHook<TSchema extends InteropZodObject | undefined = any, TContex
  * @param runtime - The runtime context containing metadata, signal, writer, interrupt, etc.
  * @returns A middleware result containing partial state updates or undefined to pass through
  */
-type BeforeModelHandler<TSchema extends InteropZodObject | undefined = any, TContext = unknown> = (state: NormalizedSchemaInput<TSchema> & AgentBuiltInState, runtime: Runtime<TContext>) => PromiseOrValue<MiddlewareResult<Partial<NormalizedSchemaInput<TSchema>>>>;
+type BeforeModelHandler<TSchema, TContext> = (state: TSchema, runtime: Runtime<TContext>) => PromiseOrValue<MiddlewareResult<Partial<TSchema>>>;
 /**
  * Hook type for the beforeModel lifecycle event.
  * Can be either a handler function or an object with a handler and optional jump targets.
  * This hook is called before each model invocation.
  */
-type BeforeModelHook<TSchema extends InteropZodObject | undefined = any, TContext = unknown> = BeforeModelHandler<TSchema, TContext> | {
-  hook: BeforeModelHandler<TSchema, TContext>;
+type BeforeModelHook<TSchema extends InteropZodObject | undefined = undefined, TContext = unknown> = BeforeModelHandler<NormalizedSchemaInput<TSchema>, TContext> | {
+  hook: BeforeModelHandler<NormalizedSchemaInput<TSchema>, TContext>;
   canJumpTo?: JumpToTarget[];
 };
 /**
@@ -116,14 +118,14 @@ type BeforeModelHook<TSchema extends InteropZodObject | undefined = any, TContex
  * @param runtime - The runtime context containing metadata, signal, writer, interrupt, etc.
  * @returns A middleware result containing partial state updates or undefined to pass through
  */
-type AfterModelHandler<TSchema extends InteropZodObject | undefined = any, TContext = unknown> = (state: NormalizedSchemaInput<TSchema> & AgentBuiltInState, runtime: Runtime<TContext>) => PromiseOrValue<MiddlewareResult<Partial<NormalizedSchemaInput<TSchema>>>>;
+type AfterModelHandler<TSchema, TContext> = (state: TSchema, runtime: Runtime<TContext>) => PromiseOrValue<MiddlewareResult<Partial<TSchema>>>;
 /**
  * Hook type for the afterModel lifecycle event.
  * Can be either a handler function or an object with a handler and optional jump targets.
  * This hook is called after each model invocation.
  */
-type AfterModelHook<TSchema extends InteropZodObject | undefined = any, TContext = unknown> = AfterModelHandler<TSchema, TContext> | {
-  hook: AfterModelHandler<TSchema, TContext>;
+type AfterModelHook<TSchema extends InteropZodObject | undefined = undefined, TContext = unknown> = AfterModelHandler<NormalizedSchemaInput<TSchema>, TContext> | {
+  hook: AfterModelHandler<NormalizedSchemaInput<TSchema>, TContext>;
   canJumpTo?: JumpToTarget[];
 };
 /**
@@ -134,14 +136,14 @@ type AfterModelHook<TSchema extends InteropZodObject | undefined = any, TContext
  * @param runtime - The runtime context containing metadata, signal, writer, interrupt, etc.
  * @returns A middleware result containing partial state updates or undefined to pass through
  */
-type AfterAgentHandler<TSchema extends InteropZodObject | undefined = any, TContext = unknown> = (state: NormalizedSchemaInput<TSchema> & AgentBuiltInState, runtime: Runtime<TContext>) => PromiseOrValue<MiddlewareResult<Partial<NormalizedSchemaInput<TSchema>>>>;
+type AfterAgentHandler<TSchema, TContext> = (state: TSchema, runtime: Runtime<TContext>) => PromiseOrValue<MiddlewareResult<Partial<TSchema>>>;
 /**
  * Hook type for the afterAgent lifecycle event.
  * Can be either a handler function or an object with a handler and optional jump targets.
  * This hook is called once at the end of the agent invocation.
  */
-type AfterAgentHook<TSchema extends InteropZodObject | undefined = any, TContext = unknown> = AfterAgentHandler<TSchema, TContext> | {
-  hook: AfterAgentHandler<TSchema, TContext>;
+type AfterAgentHook<TSchema extends InteropZodObject | undefined = undefined, TContext = unknown> = AfterAgentHandler<NormalizedSchemaInput<TSchema>, TContext> | {
+  hook: AfterAgentHandler<NormalizedSchemaInput<TSchema>, TContext>;
   canJumpTo?: JumpToTarget[];
 };
 /**