langchain 1.0.0-alpha.4 → 1.0.0-alpha.6

package/dist/agents/middlewareAgent/middleware/hitl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hitl.d.ts","names":["z","contextSchema","ZodString","ZodBoolean","ZodOptional","ZodTypeAny","ZodObject","ZodRecord","ZodDefault","Record","humanInTheLoopMiddleware","input","___types_js0","AgentMiddleware"],"sources":["../../../../src/agents/middlewareAgent/middleware/hitl.d.ts"],"sourcesContent":["/* eslint-disable @typescript-eslint/no-explicit-any */\nimport { z } from \"zod/v3\";\ndeclare const contextSchema: z.ZodObject<{\n    toolConfigs: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{\n        requireApproval: z.ZodOptional<z.ZodBoolean>;\n        description: z.ZodOptional<z.ZodString>;\n    }, \"strip\", z.ZodTypeAny, {\n        requireApproval?: boolean | undefined;\n        description?: string | undefined;\n    }, {\n        requireApproval?: boolean | undefined;\n        description?: string | undefined;\n    }>>>;\n    messagePrefix: z.ZodDefault<z.ZodString>;\n}, \"strip\", z.ZodTypeAny, {\n    toolConfigs: Record<string, {\n        requireApproval?: boolean | undefined;\n        description?: string | undefined;\n    }>;\n    messagePrefix: string;\n}, {\n    toolConfigs?: Record<string, {\n        requireApproval?: boolean | undefined;\n        description?: string | undefined;\n    }> | undefined;\n    messagePrefix?: string | undefined;\n}>;\n/**\n * Creates a Human-in-the-Loop (HITL) middleware for tool approval and oversight.\n *\n * This middleware intercepts tool calls made by an AI agent and provides human oversight\n * capabilities before execution. It enables selective approval workflows where certain tools\n * require human intervention while others can execute automatically.\n *\n * ## Features\n *\n * - **Selective Tool Approval**: Configure which tools require human approval\n * - **Multiple Response Types**: Accept, edit, ignore, or manually respond to tool calls\n * - **Asynchronous Workflow**: Uses LangGraph's interrupt mechanism for non-blocking approval\n * - **Custom Approval Messages**: Provide context-specific descriptions for approval requests\n *\n * ## Response Types\n *\n * When a tool requires approval, the human operator can respond with:\n * - `accept`: Execute the tool with original arguments\n * - `edit`: Modify the tool arguments before execution\n * - `ignore`: Skip the tool and terminate the agent\n * - `response`: Provide a manual response instead of executing the tool\n *\n * @param options - Configuration options for the middleware\n * @param options.toolConfigs - Per-tool configuration mapping tool names to their settings\n * @param options.toolConfigs[toolName].requireApproval - Whether the tool requires human approval\n * @param options.toolConfigs[toolName].description - Custom approval message for the tool\n * @param options.messagePrefix - Default prefix for approval messages (default: \"Tool execution requires approval\")\n *\n * @returns A middleware instance that can be passed to `createAgent`\n *\n * @example\n * Basic usage with selective tool approval\n * ```typescript\n * import { humanInTheLoopMiddleware } from \"langchain/middleware\";\n * import { createAgent } from \"langchain\";\n *\n * const hitlMiddleware = humanInTheLoopMiddleware({\n *   toolConfigs: {\n *     \"write_file\": {\n *       requireApproval: true,\n *       description: \"⚠️ File write operation requires approval\"\n *     },\n *     \"read_file\": {\n *       requireApproval: false  // Safe operation, no approval needed\n *     }\n *   }\n * });\n *\n * const agent = createAgent({\n *   model: \"openai:gpt-4\",\n *   tools: [writeFileTool, readFileTool],\n *   middleware: [hitlMiddleware]\n * });\n * ```\n *\n * @example\n * Handling approval requests\n * ```typescript\n * import { Command } from \"@langchain/langgraph\";\n *\n * // Initial agent invocation\n * const result = await agent.invoke({\n *   messages: [new HumanMessage(\"Write 'Hello' to output.txt\")]\n * }, config);\n *\n * // Check if agent is paused for approval\n * const state = await agent.graph.getState(config);\n * if (state.next?.length > 0) {\n *   // Get interrupt details\n *   const task = state.tasks?.[0];\n *   const requests = task?.interrupts?.[0]?.value;\n *\n *   // Show tool call details to user\n *   console.log(\"Tool:\", requests[0].action);\n *   console.log(\"Args:\", requests[0].args);\n *\n *   // Resume with approval\n *   await agent.invoke(\n *     new Command({ resume: [{ type: \"accept\" }] }),\n *     config\n *   );\n * }\n * ```\n *\n * @example\n * Different response types\n * ```typescript\n * // Accept the tool call as-is\n * new Command({ resume: [{ type: \"accept\" }] })\n *\n * // Edit the tool arguments\n * new Command({\n *   resume: [{\n *     type: \"edit\",\n *     args: { action: \"write_file\", args: { filename: \"safe.txt\", content: \"Modified\" } }\n *   }]\n * })\n *\n * // Skip tool and terminate agent\n * new Command({ resume: [{ type: \"ignore\" }] })\n *\n * // Provide manual response\n * new Command({\n *   resume: [{\n *     type: \"response\",\n *     args: \"File operation not allowed in demo mode\"\n *   }]\n * })\n * ```\n *\n * @example\n * Production use case with database operations\n * ```typescript\n * const hitlMiddleware = humanInTheLoopMiddleware({\n *   toolConfigs: {\n *     \"execute_sql\": {\n *       requireApproval: true,\n *       description: \"🚨 SQL query requires DBA approval\\nPlease review for safety and performance\"\n *     },\n *     \"read_schema\": {\n *       requireApproval: false  // Reading metadata is safe\n *     },\n *     \"delete_records\": {\n *       requireApproval: true,\n *       description: \"⛔ DESTRUCTIVE OPERATION - Requires manager approval\"\n *     }\n *   },\n *   messagePrefix: \"Database operation pending approval\"\n * });\n * ```\n *\n * @remarks\n * - Tool calls are processed in the order they appear in the AI message\n * - Auto-approved tools execute immediately without interruption\n * - Multiple tools requiring approval are bundled into a single interrupt\n * - The middleware operates in the `afterModel` phase, intercepting before tool execution\n * - Requires a checkpointer to maintain state across interruptions\n *\n * @see {@link createAgent} for agent creation\n * @see {@link Command} for resuming interrupted execution\n * @public\n */\nexport declare function humanInTheLoopMiddleware(options?: z.input<typeof contextSchema>): import(\"../types.js\").AgentMiddleware<undefined, z.ZodObject<{\n    toolConfigs: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{\n        requireApproval: z.ZodOptional<z.ZodBoolean>;\n        description: z.ZodOptional<z.ZodString>;\n    }, \"strip\", z.ZodTypeAny, {\n        requireApproval?: boolean | undefined;\n        description?: string | undefined;\n    }, {\n        requireApproval?: boolean | undefined;\n        description?: string | undefined;\n    }>>>;\n    messagePrefix: z.ZodDefault<z.ZodString>;\n}, \"strip\", z.ZodTypeAny, {\n    toolConfigs: Record<string, {\n        requireApproval?: boolean | undefined;\n        description?: string | undefined;\n    }>;\n    messagePrefix: string;\n}, {\n    toolConfigs?: Record<string, {\n        requireApproval?: boolean | undefined;\n        description?: string | undefined;\n    }> | undefined;\n    messagePrefix?: string | undefined;\n}>, any>;\nexport {};\n"],"mappings":";;;;cAEcC,eAAeD,CAAAA,CAAEM;eACdN,CAAAA,CAAEQ,WAAWR,CAAAA,CAAEO,UAAUP,CAAAA,CAAEE,WAAWF,CAAAA,CAAEM;IAD3CL,eAwBZ,EAtBuBD,CAAAA,CAAEI,WAsBzB,CAtBqCJ,CAAAA,CAAEG,UAsBvC,CAAA;IAAA,WAAA,EArBmBH,CAAAA,CAAEI,WAqBrB,CArBiCJ,CAAAA,CAAEE,SAqBnC,CAAA;EAAA,CAAA,EAvBwCF,OAAEE,EAG5BF,CAAAA,CAAEK,UAH0BH,EAAAA;IACLF,eAAEG,CAAAA,EAAAA,OAAAA,GAAAA,SAAAA;IAAhBH,WAAEI,CAAAA,EAAAA,MAAAA,GAAAA,SAAAA;EAAW,CAAA,EACHJ;IAAdA,eAAEI,CAAAA,EAAAA,OAAAA,GAAAA,SAAAA;IACPJ,WAAEK,CAAAA,EAAAA,MAAAA,GAAAA,SAAAA;EAAU,CAAA,CAAA,CAH2BL,CAAAA;EAAW,aAAlCO,EAUbP,CAAAA,CAAEQ,UAVWD,CAUAP,CAAAA,CAAEE,SAVFK,CAAAA;CAAS,EAAA,OAAtBC,EAWPR,CAAAA,CAAEK,UAXKG,EAAAA;EAAU,WAUKN,EAEjBO,MAFiBP,CAAAA,MAAAA,EAAAA;IAAfF,eAAEQ,CAAAA,EAAAA,OAAAA,GAAAA,SAAAA;IACTR,WAAEK,CAAAA,EAAAA,MAAAA,GAAAA,SAAAA;EAAU,CAAA,CAAA;EACD,aAMLI,EAAAA,MAAAA;CAAM,EAAA;EAnBgB,WAAA,CAAA,EAmBtBA,MAnBsB,CAAA,MAAA,EAAA;IAuKhBC,eAAAA,CAAAA,EAAAA,OAAwB,GAAA,SAAA;IAAA,WAAA,CAAA,EAAA,MAAA,GAAA,SAAA;EAAA,CAAA,CAAA,GAA0BT,SAAAA;EAAa,aAA1BU,CAAAA,EAAAA,MAAAA,GAAAA,SAAAA;CAAK,CAAA;;;;;;;;;;;;;;;;AAA8D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAAxGD,wBAAAA,WAAmCV,CAAAA,CAAEW,aAAaV,iBAA6E,2BAAXD,CAAAA,CAAEM;eAC7HN,CAAAA,CAAEQ,WAAWR,CAAAA,CAAEO,UAAUP,CAAAA,CAAEE,WAAWF,CAAAA,CAAEM;qBAChCN,CAAAA,CAAEI,YAAYJ,CAAAA,CAAEG;iBACpBH,CAAAA,CAAEI,YAAYJ,CAAAA,CAAEE;cACrBF,CAAAA,CAAEK;;;;;;;iBAOCL,CAAAA,CAAEQ,WAAWR,CAAAA,CAAEE;YACtBF,CAAAA,CAAEK;eACGI;;;;;;gBAMCA"}

package/dist/agents/middlewareAgent/middleware/hitl.js

@@ -0,0 +1,234 @@
+import { createMiddleware } from "../middleware.js";
+import { AIMessage, ToolMessage, isAIMessage } from "@langchain/core/messages";
+import { interrupt } from "@langchain/langgraph";
+import { z } from "zod/v3";
+import { v4 } from "uuid";
+
+//#region src/agents/middlewareAgent/middleware/hitl.ts
+const contextSchema = z.object({
+	toolConfigs: z.record(z.object({
+		requireApproval: z.boolean().optional(),
+		description: z.string().optional()
+	})).default({}),
+	messagePrefix: z.string().default("Tool execution requires approval")
+});
+/**
+* Creates a Human-in-the-Loop (HITL) middleware for tool approval and oversight.
+*
+* This middleware intercepts tool calls made by an AI agent and provides human oversight
+* capabilities before execution. It enables selective approval workflows where certain tools
+* require human intervention while others can execute automatically.
+*
+* ## Features
+*
+* - **Selective Tool Approval**: Configure which tools require human approval
+* - **Multiple Response Types**: Accept, edit, ignore, or manually respond to tool calls
+* - **Asynchronous Workflow**: Uses LangGraph's interrupt mechanism for non-blocking approval
+* - **Custom Approval Messages**: Provide context-specific descriptions for approval requests
+*
+* ## Response Types
+*
+* When a tool requires approval, the human operator can respond with:
+* - `accept`: Execute the tool with original arguments
+* - `edit`: Modify the tool arguments before execution
+* - `ignore`: Skip the tool and terminate the agent
+* - `response`: Provide a manual response instead of executing the tool
+*
+* @param options - Configuration options for the middleware
+* @param options.toolConfigs - Per-tool configuration mapping tool names to their settings
+* @param options.toolConfigs[toolName].requireApproval - Whether the tool requires human approval
+* @param options.toolConfigs[toolName].description - Custom approval message for the tool
+* @param options.messagePrefix - Default prefix for approval messages (default: "Tool execution requires approval")
+*
+* @returns A middleware instance that can be passed to `createAgent`
+*
+* @example
+* Basic usage with selective tool approval
+* ```typescript
+* import { humanInTheLoopMiddleware } from "langchain/middleware";
+* import { createAgent } from "langchain";
+*
+* const hitlMiddleware = humanInTheLoopMiddleware({
+*   toolConfigs: {
+*     "write_file": {
+*       requireApproval: true,
+*       description: "⚠️ File write operation requires approval"
+*     },
+*     "read_file": {
+*       requireApproval: false  // Safe operation, no approval needed
+*     }
+*   }
+* });
+*
+* const agent = createAgent({
+*   model: "openai:gpt-4",
+*   tools: [writeFileTool, readFileTool],
+*   middleware: [hitlMiddleware]
+* });
+* ```
+*
+* @example
+* Handling approval requests
+* ```typescript
+* import { Command } from "@langchain/langgraph";
+*
+* // Initial agent invocation
+* const result = await agent.invoke({
+*   messages: [new HumanMessage("Write 'Hello' to output.txt")]
+* }, config);
+*
+* // Check if agent is paused for approval
+* const state = await agent.graph.getState(config);
+* if (state.next?.length > 0) {
+*   // Get interrupt details
+*   const task = state.tasks?.[0];
+*   const requests = task?.interrupts?.[0]?.value;
+*
+*   // Show tool call details to user
+*   console.log("Tool:", requests[0].action);
+*   console.log("Args:", requests[0].args);
+*
+*   // Resume with approval
+*   await agent.invoke(
+*     new Command({ resume: [{ type: "accept" }] }),
+*     config
+*   );
+* }
+* ```
+*
+* @example
+* Different response types
+* ```typescript
+* // Accept the tool call as-is
+* new Command({ resume: [{ type: "accept" }] })
+*
+* // Edit the tool arguments
+* new Command({
+*   resume: [{
+*     type: "edit",
+*     args: { action: "write_file", args: { filename: "safe.txt", content: "Modified" } }
+*   }]
+* })
+*
+* // Skip tool and terminate agent
+* new Command({ resume: [{ type: "ignore" }] })
+*
+* // Provide manual response
+* new Command({
+*   resume: [{
+*     type: "response",
+*     args: "File operation not allowed in demo mode"
+*   }]
+* })
+* ```
+*
+* @example
+* Production use case with database operations
+* ```typescript
+* const hitlMiddleware = humanInTheLoopMiddleware({
+*   toolConfigs: {
+*     "execute_sql": {
+*       requireApproval: true,
+*       description: "🚨 SQL query requires DBA approval\nPlease review for safety and performance"
+*     },
+*     "read_schema": {
+*       requireApproval: false  // Reading metadata is safe
+*     },
+*     "delete_records": {
+*       requireApproval: true,
+*       description: "⛔ DESTRUCTIVE OPERATION - Requires manager approval"
+*     }
+*   },
+*   messagePrefix: "Database operation pending approval"
+* });
+* ```
+*
+* @remarks
+* - Tool calls are processed in the order they appear in the AI message
+* - Auto-approved tools execute immediately without interruption
+* - Multiple tools requiring approval are bundled into a single interrupt
+* - The middleware operates in the `afterModel` phase, intercepting before tool execution
+* - Requires a checkpointer to maintain state across interruptions
+*
+* @see {@link createAgent} for agent creation
+* @see {@link Command} for resuming interrupted execution
+* @public
+*/
+function humanInTheLoopMiddleware(options = {}) {
+	return createMiddleware({
+		name: "HumanInTheLoopMiddleware",
+		contextSchema,
+		afterModel: async (state, runtime, controls) => {
+			const config = {
+				...contextSchema.parse(options),
+				...runtime.context
+			};
+			const { messages } = state;
+			if (!messages.length) return;
+			const lastMessage = messages[messages.length - 1];
+			if (!isAIMessage(lastMessage) || !lastMessage.tool_calls?.length) return;
+			const interruptToolCalls = [];
+			const autoApprovedToolCalls = [];
+			for (const toolCall of lastMessage.tool_calls) {
+				const normalizedToolCall = {
+					id: toolCall.id || v4(),
+					name: toolCall.name,
+					args: toolCall.args
+				};
+				const toolConfig = config.toolConfigs[normalizedToolCall.name];
+				if (toolConfig?.requireApproval) interruptToolCalls.push(normalizedToolCall);
+				else autoApprovedToolCalls.push(normalizedToolCall);
+			}
+			if (!interruptToolCalls.length) return;
+			const approvedToolCalls = [...autoApprovedToolCalls];
+			const requests = interruptToolCalls.map((toolCall) => {
+				const toolConfig = config.toolConfigs[toolCall.name];
+				const description = toolConfig?.description || `${config.messagePrefix}\n\nTool: ${toolCall.name}\nArgs: ${JSON.stringify(toolCall.args, null, 2)}`;
+				return {
+					action: toolCall.name,
+					args: toolCall.args,
+					toolCallId: toolCall.id,
+					description
+				};
+			});
+			const responses = await interrupt(requests);
+			for (let i = 0; i < responses.length; i++) {
+				const response = responses[i];
+				const toolCall = interruptToolCalls[i];
+				switch (response.type) {
+					case "accept":
+						approvedToolCalls.push(toolCall);
+						break;
+					case "edit":
+						if (response.args && typeof response.args === "object" && "args" in response.args) approvedToolCalls.push({
+							...toolCall,
+							args: response.args.args
+						});
+						break;
+					case "ignore": return controls.terminate();
+					case "response": {
+						const toolMessage = new ToolMessage({
+							content: typeof response.args === "string" ? response.args : "",
+							tool_call_id: toolCall.id
+						});
+						return {
+							messages: [...state.messages, toolMessage],
+							jump_to: "model"
+						};
+					}
+					default: throw new Error(`Unknown response type: ${response.type}`);
+				}
+			}
+			const updatedMessage = new AIMessage({
+				content: lastMessage.content,
+				tool_calls: approvedToolCalls,
+				id: lastMessage.id
+			});
+			return { messages: [...state.messages.slice(0, -1), updatedMessage] };
+		}
+	});
+}
+
+//#endregion
+export { humanInTheLoopMiddleware };
+//# sourceMappingURL=hitl.js.map

package/dist/agents/middlewareAgent/middleware/hitl.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hitl.js","names":["options: z.input<typeof contextSchema>","interruptToolCalls: ToolCall[]","autoApprovedToolCalls: ToolCall[]","normalizedToolCall: ToolCall","uuid","requests: ToolApprovalRequest[]"],"sources":["../../../../src/agents/middlewareAgent/middleware/hitl.ts"],"sourcesContent":["/* eslint-disable @typescript-eslint/no-explicit-any */\nimport { z } from \"zod/v3\";\nimport { v4 as uuid } from \"uuid\";\nimport { AIMessage, ToolMessage, isAIMessage } from \"@langchain/core/messages\";\nimport { interrupt } from \"@langchain/langgraph\";\n\nimport { createMiddleware } from \"../middleware.js\";\nimport type { ToolCall } from \"../types.js\";\nimport { HumanResponse } from \"../../interrupt.js\";\n\n/**\n * Interrupt request for tool approval\n */\ninterface ToolApprovalRequest {\n  action: string;\n  args: Record<string, any>;\n  toolCallId: string;\n  description?: string;\n}\n\nconst contextSchema = z.object({\n  toolConfigs: z\n    .record(\n      z.object({\n        requireApproval: z.boolean().optional(),\n        description: z.string().optional(),\n      })\n    )\n    .default({}),\n  messagePrefix: z.string().default(\"Tool execution requires approval\"),\n});\n\n/**\n * Creates a Human-in-the-Loop (HITL) middleware for tool approval and oversight.\n *\n * This middleware intercepts tool calls made by an AI agent and provides human oversight\n * capabilities before execution. It enables selective approval workflows where certain tools\n * require human intervention while others can execute automatically.\n *\n * ## Features\n *\n * - **Selective Tool Approval**: Configure which tools require human approval\n * - **Multiple Response Types**: Accept, edit, ignore, or manually respond to tool calls\n * - **Asynchronous Workflow**: Uses LangGraph's interrupt mechanism for non-blocking approval\n * - **Custom Approval Messages**: Provide context-specific descriptions for approval requests\n *\n * ## Response Types\n *\n * When a tool requires approval, the human operator can respond with:\n * - `accept`: Execute the tool with original arguments\n * - `edit`: Modify the tool arguments before execution\n * - `ignore`: Skip the tool and terminate the agent\n * - `response`: Provide a manual response instead of executing the tool\n *\n * @param options - Configuration options for the middleware\n * @param options.toolConfigs - Per-tool configuration mapping tool names to their settings\n * @param options.toolConfigs[toolName].requireApproval - Whether the tool requires human approval\n * @param options.toolConfigs[toolName].description - Custom approval message for the tool\n * @param options.messagePrefix - Default prefix for approval messages (default: \"Tool execution requires approval\")\n *\n * @returns A middleware instance that can be passed to `createAgent`\n *\n * @example\n * Basic usage with selective tool approval\n * ```typescript\n * import { humanInTheLoopMiddleware } from \"langchain/middleware\";\n * import { createAgent } from \"langchain\";\n *\n * const hitlMiddleware = humanInTheLoopMiddleware({\n *   toolConfigs: {\n *     \"write_file\": {\n *       requireApproval: true,\n *       description: \"⚠️ File write operation requires approval\"\n *     },\n *     \"read_file\": {\n *       requireApproval: false  // Safe operation, no approval needed\n *     }\n *   }\n * });\n *\n * const agent = createAgent({\n *   model: \"openai:gpt-4\",\n *   tools: [writeFileTool, readFileTool],\n *   middleware: [hitlMiddleware]\n * });\n * ```\n *\n * @example\n * Handling approval requests\n * ```typescript\n * import { Command } from \"@langchain/langgraph\";\n *\n * // Initial agent invocation\n * const result = await agent.invoke({\n *   messages: [new HumanMessage(\"Write 'Hello' to output.txt\")]\n * }, config);\n *\n * // Check if agent is paused for approval\n * const state = await agent.graph.getState(config);\n * if (state.next?.length > 0) {\n *   // Get interrupt details\n *   const task = state.tasks?.[0];\n *   const requests = task?.interrupts?.[0]?.value;\n *\n *   // Show tool call details to user\n *   console.log(\"Tool:\", requests[0].action);\n *   console.log(\"Args:\", requests[0].args);\n *\n *   // Resume with approval\n *   await agent.invoke(\n *     new Command({ resume: [{ type: \"accept\" }] }),\n *     config\n *   );\n * }\n * ```\n *\n * @example\n * Different response types\n * ```typescript\n * // Accept the tool call as-is\n * new Command({ resume: [{ type: \"accept\" }] })\n *\n * // Edit the tool arguments\n * new Command({\n *   resume: [{\n *     type: \"edit\",\n *     args: { action: \"write_file\", args: { filename: \"safe.txt\", content: \"Modified\" } }\n *   }]\n * })\n *\n * // Skip tool and terminate agent\n * new Command({ resume: [{ type: \"ignore\" }] })\n *\n * // Provide manual response\n * new Command({\n *   resume: [{\n *     type: \"response\",\n *     args: \"File operation not allowed in demo mode\"\n *   }]\n * })\n * ```\n *\n * @example\n * Production use case with database operations\n * ```typescript\n * const hitlMiddleware = humanInTheLoopMiddleware({\n *   toolConfigs: {\n *     \"execute_sql\": {\n *       requireApproval: true,\n *       description: \"🚨 SQL query requires DBA approval\\nPlease review for safety and performance\"\n *     },\n *     \"read_schema\": {\n *       requireApproval: false  // Reading metadata is safe\n *     },\n *     \"delete_records\": {\n *       requireApproval: true,\n *       description: \"⛔ DESTRUCTIVE OPERATION - Requires manager approval\"\n *     }\n *   },\n *   messagePrefix: \"Database operation pending approval\"\n * });\n * ```\n *\n * @remarks\n * - Tool calls are processed in the order they appear in the AI message\n * - Auto-approved tools execute immediately without interruption\n * - Multiple tools requiring approval are bundled into a single interrupt\n * - The middleware operates in the `afterModel` phase, intercepting before tool execution\n * - Requires a checkpointer to maintain state across interruptions\n *\n * @see {@link createAgent} for agent creation\n * @see {@link Command} for resuming interrupted execution\n * @public\n */\nexport function humanInTheLoopMiddleware(\n  options: z.input<typeof contextSchema> = {}\n) {\n  return createMiddleware({\n    name: \"HumanInTheLoopMiddleware\",\n    contextSchema,\n    afterModel: async (state, runtime, controls) => {\n      const config = { ...contextSchema.parse(options), ...runtime.context };\n      const { messages } = state;\n\n      if (!messages.length) {\n        return;\n      }\n\n      const lastMessage = messages[messages.length - 1];\n\n      // Check if it's an AI message with tool calls\n      if (!isAIMessage(lastMessage) || !lastMessage.tool_calls?.length) {\n        return;\n      }\n\n      // Separate tool calls that need interrupts from those that don't\n      const interruptToolCalls: ToolCall[] = [];\n      const autoApprovedToolCalls: ToolCall[] = [];\n\n      for (const toolCall of lastMessage.tool_calls) {\n        // Ensure tool call has an ID\n        const normalizedToolCall: ToolCall = {\n          id: toolCall.id || uuid(),\n          name: toolCall.name,\n          args: toolCall.args,\n        };\n\n        const toolConfig = config.toolConfigs[normalizedToolCall.name];\n\n        if (toolConfig?.requireApproval) {\n          interruptToolCalls.push(normalizedToolCall);\n        } else {\n          autoApprovedToolCalls.push(normalizedToolCall);\n        }\n      }\n\n      // If no interrupts needed, return early\n      if (!interruptToolCalls.length) {\n        return;\n      }\n\n      const approvedToolCalls = [...autoApprovedToolCalls];\n\n      // Process tool calls that need interrupts\n      const requests: ToolApprovalRequest[] = interruptToolCalls.map(\n        (toolCall) => {\n          const toolConfig = config.toolConfigs[toolCall.name];\n          const description =\n            toolConfig?.description ||\n            `${config.messagePrefix}\\n\\nTool: ${\n              toolCall.name\n            }\\nArgs: ${JSON.stringify(toolCall.args, null, 2)}`;\n\n          return {\n            action: toolCall.name,\n            args: toolCall.args,\n            toolCallId: toolCall.id,\n            description,\n          };\n        }\n      );\n\n      // Interrupt and wait for human responses\n      const responses = (await interrupt(requests)) as HumanResponse[];\n\n      // Process responses\n      for (let i = 0; i < responses.length; i++) {\n        const response = responses[i];\n        const toolCall = interruptToolCalls[i];\n\n        switch (response.type) {\n          case \"accept\":\n            approvedToolCalls.push(toolCall);\n            break;\n\n          case \"edit\":\n            // For edit, args is an ActionRequest with updated args\n            if (\n              response.args &&\n              typeof response.args === \"object\" &&\n              \"args\" in response.args\n            ) {\n              approvedToolCalls.push({\n                ...toolCall,\n                args: (\n                  response.args as { action: string; args: Record<string, any> }\n                ).args,\n              });\n            }\n            break;\n\n          case \"ignore\":\n            // Skip to end - terminate the agent\n            return controls.terminate();\n\n          case \"response\": {\n            // Return manual tool response and jump back to model\n            // For response, args is a string\n            const toolMessage = new ToolMessage({\n              content: typeof response.args === \"string\" ? response.args : \"\",\n              tool_call_id: toolCall.id,\n            });\n            return {\n              messages: [...state.messages, toolMessage],\n              jump_to: \"model\",\n            };\n          }\n          default:\n            throw new Error(`Unknown response type: ${(response as any).type}`);\n        }\n      }\n\n      // Update the last message with approved tool calls\n      const updatedMessage = new AIMessage({\n        content: lastMessage.content,\n        tool_calls: approvedToolCalls,\n        id: lastMessage.id,\n      });\n\n      // Replace the last message with the updated one\n      return {\n        messages: [...state.messages.slice(0, -1), updatedMessage],\n      };\n    },\n  });\n}\n"],"mappings":";;;;;;;AAoBA,MAAM,gBAAgB,EAAE,OAAO;CAC7B,aAAa,EACV,OACC,EAAE,OAAO;EACP,iBAAiB,EAAE,SAAS,CAAC,UAAU;EACvC,aAAa,EAAE,QAAQ,CAAC,UAAU;CACnC,EAAC,CACH,CACA,QAAQ,CAAE,EAAC;CACd,eAAe,EAAE,QAAQ,CAAC,QAAQ,mCAAmC;AACtE,EAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgJF,SAAgB,yBACdA,UAAyC,CAAE,GAC3C;AACA,QAAO,iBAAiB;EACtB,MAAM;EACN;EACA,YAAY,OAAO,OAAO,SAAS,aAAa;GAC9C,MAAM,SAAS;IAAE,GAAG,cAAc,MAAM,QAAQ;IAAE,GAAG,QAAQ;GAAS;GACtE,MAAM,EAAE,UAAU,GAAG;AAErB,OAAI,CAAC,SAAS,OACZ;GAGF,MAAM,cAAc,SAAS,SAAS,SAAS;AAG/C,OAAI,CAAC,YAAY,YAAY,IAAI,CAAC,YAAY,YAAY,OACxD;GAIF,MAAMC,qBAAiC,CAAE;GACzC,MAAMC,wBAAoC,CAAE;AAE5C,QAAK,MAAM,YAAY,YAAY,YAAY;IAE7C,MAAMC,qBAA+B;KACnC,IAAI,SAAS,MAAMC,IAAM;KACzB,MAAM,SAAS;KACf,MAAM,SAAS;IAChB;IAED,MAAM,aAAa,OAAO,YAAY,mBAAmB;AAEzD,QAAI,YAAY,iBACd,mBAAmB,KAAK,mBAAmB;SAE3C,sBAAsB,KAAK,mBAAmB;GAEjD;AAGD,OAAI,CAAC,mBAAmB,OACtB;GAGF,MAAM,oBAAoB,CAAC,GAAG,qBAAsB;GAGpD,MAAMC,WAAkC,mBAAmB,IACzD,CAAC,aAAa;IACZ,MAAM,aAAa,OAAO,YAAY,SAAS;IAC/C,MAAM,cACJ,YAAY,eACZ,GAAG,OAAO,cAAc,UAAU,EAChC,SAAS,KACV,QAAQ,EAAE,KAAK,UAAU,SAAS,MAAM,MAAM,EAAE,EAAE;AAErD,WAAO;KACL,QAAQ,SAAS;KACjB,MAAM,SAAS;KACf,YAAY,SAAS;KACrB;IACD;GACF,EACF;GAGD,MAAM,YAAa,MAAM,UAAU,SAAS;AAG5C,QAAK,IAAI,IAAI,GAAG,IAAI,UAAU,QAAQ,KAAK;IACzC,MAAM,WAAW,UAAU;IAC3B,MAAM,WAAW,mBAAmB;AAEpC,YAAQ,SAAS,MAAjB;KACE,KAAK;MACH,kBAAkB,KAAK,SAAS;AAChC;KAEF,KAAK;AAEH,UACE,SAAS,QACT,OAAO,SAAS,SAAS,YACzB,UAAU,SAAS,MAEnB,kBAAkB,KAAK;OACrB,GAAG;OACH,MACE,SAAS,KACT;MACH,EAAC;AAEJ;KAEF,KAAK,SAEH,QAAO,SAAS,WAAW;KAE7B,KAAK,YAAY;MAGf,MAAM,cAAc,IAAI,YAAY;OAClC,SAAS,OAAO,SAAS,SAAS,WAAW,SAAS,OAAO;OAC7D,cAAc,SAAS;MACxB;AACD,aAAO;OACL,UAAU,CAAC,GAAG,MAAM,UAAU,WAAY;OAC1C,SAAS;MACV;KACF;KACD,QACE,OAAM,IAAI,MAAM,CAAC,uBAAuB,EAAG,SAAiB,MAAM;IACrE;GACF;GAGD,MAAM,iBAAiB,IAAI,UAAU;IACnC,SAAS,YAAY;IACrB,YAAY;IACZ,IAAI,YAAY;GACjB;AAGD,UAAO,EACL,UAAU,CAAC,GAAG,MAAM,SAAS,MAAM,GAAG,GAAG,EAAE,cAAe,EAC3D;EACF;CACF,EAAC;AACH"}

package/dist/agents/middlewareAgent/middleware/index.cjs

@@ -0,0 +1,26 @@
+const require_rolldown_runtime = require('../../../_virtual/rolldown_runtime.cjs');
+const require_summarization = require('./summarization.cjs');
+const require_hitl = require('./hitl.cjs');
+const require_promptCaching = require('./promptCaching.cjs');
+
+//#region src/agents/middlewareAgent/middleware/index.ts
+var middleware_exports = {};
+require_rolldown_runtime.__export(middleware_exports, {
+	anthropicPromptCachingMiddleware: () => require_promptCaching.anthropicPromptCachingMiddleware,
+	countTokensApproximately: () => require_summarization.countTokensApproximately,
+	humanInTheLoopMiddleware: () => require_hitl.humanInTheLoopMiddleware,
+	summarizationMiddleware: () => require_summarization.summarizationMiddleware
+});
+
+//#endregion
+exports.anthropicPromptCachingMiddleware = require_promptCaching.anthropicPromptCachingMiddleware;
+exports.countTokensApproximately = require_summarization.countTokensApproximately;
+exports.humanInTheLoopMiddleware = require_hitl.humanInTheLoopMiddleware;
+Object.defineProperty(exports, 'middleware_exports', {
+  enumerable: true,
+  get: function () {
+    return middleware_exports;
+  }
+});
+exports.summarizationMiddleware = require_summarization.summarizationMiddleware;
+//# sourceMappingURL=index.cjs.map

package/dist/agents/middlewareAgent/middleware/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs","names":[],"sources":["../../../../src/agents/middlewareAgent/middleware/index.ts"],"sourcesContent":["export {\n  summarizationMiddleware,\n  countTokensApproximately,\n} from \"./summarization.js\";\nexport { humanInTheLoopMiddleware } from \"./hitl.js\";\nexport { anthropicPromptCachingMiddleware } from \"./promptCaching.js\";\n"],"mappings":""}

package/dist/agents/middlewareAgent/middleware/index.d.cts

@@ -0,0 +1,4 @@
+import { countTokensApproximately, summarizationMiddleware } from "./summarization.cjs";
+import { humanInTheLoopMiddleware } from "./hitl.cjs";
+import { anthropicPromptCachingMiddleware } from "./promptCaching.cjs";
+export { anthropicPromptCachingMiddleware, countTokensApproximately, humanInTheLoopMiddleware, summarizationMiddleware };

package/dist/agents/middlewareAgent/middleware/index.d.ts

@@ -0,0 +1,4 @@
+import { countTokensApproximately, summarizationMiddleware } from "./summarization.js";
+import { humanInTheLoopMiddleware } from "./hitl.js";
+import { anthropicPromptCachingMiddleware } from "./promptCaching.js";
+export { anthropicPromptCachingMiddleware, countTokensApproximately, humanInTheLoopMiddleware, summarizationMiddleware };

package/dist/agents/middlewareAgent/middleware/index.js

@@ -0,0 +1,17 @@
+import { __export } from "../../../_virtual/rolldown_runtime.js";
+import { countTokensApproximately, summarizationMiddleware } from "./summarization.js";
+import { humanInTheLoopMiddleware } from "./hitl.js";
+import { anthropicPromptCachingMiddleware } from "./promptCaching.js";
+
+//#region src/agents/middlewareAgent/middleware/index.ts
+var middleware_exports = {};
+__export(middleware_exports, {
+	anthropicPromptCachingMiddleware: () => anthropicPromptCachingMiddleware,
+	countTokensApproximately: () => countTokensApproximately,
+	humanInTheLoopMiddleware: () => humanInTheLoopMiddleware,
+	summarizationMiddleware: () => summarizationMiddleware
+});
+
+//#endregion
+export { anthropicPromptCachingMiddleware, countTokensApproximately, humanInTheLoopMiddleware, middleware_exports, summarizationMiddleware };
+//# sourceMappingURL=index.js.map

package/dist/agents/middlewareAgent/middleware/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../../../../src/agents/middlewareAgent/middleware/index.ts"],"sourcesContent":["export {\n  summarizationMiddleware,\n  countTokensApproximately,\n} from \"./summarization.js\";\nexport { humanInTheLoopMiddleware } from \"./hitl.js\";\nexport { anthropicPromptCachingMiddleware } from \"./promptCaching.js\";\n"],"mappings":""}

package/dist/agents/middlewareAgent/middleware/promptCaching.cjs

@@ -0,0 +1,182 @@
+const require_rolldown_runtime = require('../../../_virtual/rolldown_runtime.cjs');
+const require_middleware = require('../middleware.cjs');
+const zod_v3 = require_rolldown_runtime.__toESM(require("zod/v3"));
+
+//#region src/agents/middlewareAgent/middleware/promptCaching.ts
+const DEFAULT_ENABLE_CACHING = true;
+const DEFAULT_TTL = "5m";
+const DEFAULT_MIN_MESSAGES_TO_CACHE = 3;
+const contextSchema = zod_v3.z.object({
+	enableCaching: zod_v3.z.boolean().default(DEFAULT_ENABLE_CACHING),
+	ttl: zod_v3.z.enum(["5m", "1h"]).default(DEFAULT_TTL),
+	minMessagesToCache: zod_v3.z.number().default(DEFAULT_MIN_MESSAGES_TO_CACHE)
+});
+var PromptCachingMiddlewareError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "PromptCachingMiddlewareError";
+	}
+};
+/**
+* Creates a prompt caching middleware for Anthropic models to optimize API usage.
+*
+* This middleware automatically adds cache control headers to the last messages when using Anthropic models,
+* enabling their prompt caching feature. This can significantly reduce costs for applications with repetitive
+* prompts, long system messages, or extensive conversation histories.
+*
+* ## How It Works
+*
+* The middleware intercepts model requests and adds cache control metadata that tells Anthropic's
+* API to cache processed prompt prefixes. On subsequent requests with matching prefixes, the
+* cached representations are reused, skipping redundant token processing.
+*
+* ## Benefits
+*
+* - **Cost Reduction**: Avoid reprocessing the same tokens repeatedly (up to 90% savings on cached portions)
+* - **Lower Latency**: Cached prompts are processed faster as embeddings are pre-computed
+* - **Better Scalability**: Reduced computational load enables handling more requests
+* - **Consistent Performance**: Stable response times for repetitive queries
+*
+* @param middlewareOptions - Configuration options for the caching behavior
+* @param middlewareOptions.enableCaching - Whether to enable prompt caching (default: `true`)
+* @param middlewareOptions.ttl - Cache time-to-live: `"5m"` for 5 minutes or `"1h"` for 1 hour (default: `"5m"`)
+* @param middlewareOptions.minMessagesToCache - Minimum number of messages required before caching is applied (default: `3`)
+*
+* @returns A middleware instance that can be passed to `createAgent`
+*
+* @throws {Error} If used with non-Anthropic models
+*
+* @example
+* Basic usage with default settings
+* ```typescript
+* import { createAgent } from "langchain";
+* import { anthropicPromptCachingMiddleware } from "langchain/middleware";
+*
+* const agent = createAgent({
+*   model: "anthropic:claude-3-5-sonnet",
+*   middleware: [
+*     anthropicPromptCachingMiddleware()
+*   ]
+* });
+* ```
+*
+* @example
+* Custom configuration for longer conversations
+* ```typescript
+* const cachingMiddleware = anthropicPromptCachingMiddleware({
+*   ttl: "1h",  // Cache for 1 hour instead of default 5 minutes
+*   minMessagesToCache: 5  // Only cache after 5 messages
+* });
+*
+* const agent = createAgent({
+*   model: "anthropic:claude-3-5-sonnet",
+*   systemMessage: "You are a helpful assistant with deep knowledge of...", // Long system prompt
+*   middleware: [cachingMiddleware]
+* });
+* ```
+*
+* @example
+* Conditional caching based on runtime context
+* ```typescript
+* const agent = createAgent({
+*   model: "anthropic:claude-3-5-sonnet",
+*   middleware: [
+*     anthropicPromptCachingMiddleware({
+*       enableCaching: true,
+*       ttl: "5m"
+*     })
+*   ]
+* });
+*
+* // Disable caching for specific requests
+* await agent.invoke(
+*   { messages: [new HumanMessage("Process this without caching")] },
+*   {
+*     configurable: {
+*       middleware_context: { enableCaching: false }
+*     }
+*   }
+* );
+* ```
+*
+* @example
+* Optimal setup for customer support chatbot
+* ```typescript
+* const supportAgent = createAgent({
+*   model: "anthropic:claude-3-5-sonnet",
+*   systemMessage: `You are a customer support agent for ACME Corp.
+*
+*     Company policies:
+*     - Always be polite and professional
+*     - Refer to knowledge base for product information
+*     - Escalate billing issues to human agents
+*     ... (extensive policies and guidelines)
+*   `,
+*   tools: [searchKnowledgeBase, createTicket, checkOrderStatus],
+*   middleware: [
+*     anthropicPromptCachingMiddleware({
+*       ttl: "1h",  // Long TTL for stable system prompt
+*       minMessagesToCache: 1  // Cache immediately due to large system prompt
+*     })
+*   ]
+* });
+* ```
+*
+* @remarks
+* - **Anthropic Only**: This middleware only works with Anthropic models and will throw an error if used with other providers
+* - **Automatic Application**: Caching is applied automatically when message count exceeds `minMessagesToCache`
+* - **Cache Scope**: Caches are isolated per API key and cannot be shared across different keys
+* - **TTL Options**: Only supports "5m" (5 minutes) and "1h" (1 hour) as TTL values per Anthropic's API
+* - **Best Use Cases**: Long system prompts, multi-turn conversations, repetitive queries, RAG applications
+* - **Cost Impact**: Cached tokens are billed at 10% of the base input token price, cache writes are billed at 25% of the base
+*
+* @see {@link createAgent} for agent creation
+* @see {@link https://docs.anthropic.com/en/docs/build-with-claude/prompt-caching} Anthropic's prompt caching documentation
+* @public
+*/
+function anthropicPromptCachingMiddleware(middlewareOptions) {
+	return require_middleware.createMiddleware({
+		name: "PromptCachingMiddleware",
+		contextSchema,
+		prepareModelRequest: (options, state, runtime) => {
+			/**
+			* If the runtime values match the schema default values, use the middleware option
+			* values otherwise use the runtime values. This allows to apply general configurations
+			* for all invocations, and override them for specific invocations.
+			*/
+			const enableCaching = runtime.context.enableCaching === DEFAULT_ENABLE_CACHING ? middlewareOptions?.enableCaching ?? runtime.context.enableCaching : runtime.context.enableCaching ?? middlewareOptions?.enableCaching;
+			const ttl = runtime.context.ttl === DEFAULT_TTL ? middlewareOptions?.ttl ?? runtime.context.ttl : runtime.context.ttl ?? middlewareOptions?.ttl;
+			const minMessagesToCache = runtime.context.minMessagesToCache === DEFAULT_MIN_MESSAGES_TO_CACHE ? middlewareOptions?.minMessagesToCache ?? runtime.context.minMessagesToCache : runtime.context.minMessagesToCache ?? middlewareOptions?.minMessagesToCache;
+			if (!enableCaching) return void 0;
+			if (options.model?.getName() !== "ChatAnthropic") throw new Error("Prompt caching is only supported for Anthropic models");
+			const messagesCount = state.messages.length + (options.systemMessage ? 1 : 0);
+			if (messagesCount < minMessagesToCache) return options;
+			/**
+			* Add cache_control to the last message
+			*/
+			const lastMessage = options.messages.at(-1);
+			if (!lastMessage) return options;
+			if (Array.isArray(lastMessage.content)) lastMessage.content = [...lastMessage.content.slice(0, -1), {
+				...lastMessage.content.at(-1),
+				cache_control: {
+					type: "ephemeral",
+					ttl
+				}
+			}];
+			else if (typeof lastMessage.content === "string") lastMessage.content = [{
+				type: "text",
+				text: lastMessage.content,
+				cache_control: {
+					type: "ephemeral",
+					ttl
+				}
+			}];
+			else throw new PromptCachingMiddlewareError("Last message content is not a string or array");
+			return options;
+		}
+	});
+}
+
+//#endregion
+exports.anthropicPromptCachingMiddleware = anthropicPromptCachingMiddleware;
+//# sourceMappingURL=promptCaching.cjs.map

package/dist/agents/middlewareAgent/middleware/promptCaching.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"promptCaching.cjs","names":["z","message: string","middlewareOptions?: Partial<z.infer<typeof contextSchema>>","createMiddleware"],"sources":["../../../../src/agents/middlewareAgent/middleware/promptCaching.ts"],"sourcesContent":["import { z } from \"zod/v3\";\nimport { ContentBlock } from \"@langchain/core/messages\";\nimport { createMiddleware } from \"../middleware.js\";\n\nconst DEFAULT_ENABLE_CACHING = true;\nconst DEFAULT_TTL = \"5m\";\nconst DEFAULT_MIN_MESSAGES_TO_CACHE = 3;\n\nconst contextSchema = z.object({\n  // Configuration options\n  enableCaching: z.boolean().default(DEFAULT_ENABLE_CACHING),\n  ttl: z.enum([\"5m\", \"1h\"]).default(DEFAULT_TTL),\n  minMessagesToCache: z.number().default(DEFAULT_MIN_MESSAGES_TO_CACHE),\n});\n\nclass PromptCachingMiddlewareError extends Error {\n  constructor(message: string) {\n    super(message);\n    this.name = \"PromptCachingMiddlewareError\";\n  }\n}\n\n/**\n * Creates a prompt caching middleware for Anthropic models to optimize API usage.\n *\n * This middleware automatically adds cache control headers to the last messages when using Anthropic models,\n * enabling their prompt caching feature. This can significantly reduce costs for applications with repetitive\n * prompts, long system messages, or extensive conversation histories.\n *\n * ## How It Works\n *\n * The middleware intercepts model requests and adds cache control metadata that tells Anthropic's\n * API to cache processed prompt prefixes. On subsequent requests with matching prefixes, the\n * cached representations are reused, skipping redundant token processing.\n *\n * ## Benefits\n *\n * - **Cost Reduction**: Avoid reprocessing the same tokens repeatedly (up to 90% savings on cached portions)\n * - **Lower Latency**: Cached prompts are processed faster as embeddings are pre-computed\n * - **Better Scalability**: Reduced computational load enables handling more requests\n * - **Consistent Performance**: Stable response times for repetitive queries\n *\n * @param middlewareOptions - Configuration options for the caching behavior\n * @param middlewareOptions.enableCaching - Whether to enable prompt caching (default: `true`)\n * @param middlewareOptions.ttl - Cache time-to-live: `\"5m\"` for 5 minutes or `\"1h\"` for 1 hour (default: `\"5m\"`)\n * @param middlewareOptions.minMessagesToCache - Minimum number of messages required before caching is applied (default: `3`)\n *\n * @returns A middleware instance that can be passed to `createAgent`\n *\n * @throws {Error} If used with non-Anthropic models\n *\n * @example\n * Basic usage with default settings\n * ```typescript\n * import { createAgent } from \"langchain\";\n * import { anthropicPromptCachingMiddleware } from \"langchain/middleware\";\n *\n * const agent = createAgent({\n *   model: \"anthropic:claude-3-5-sonnet\",\n *   middleware: [\n *     anthropicPromptCachingMiddleware()\n *   ]\n * });\n * ```\n *\n * @example\n * Custom configuration for longer conversations\n * ```typescript\n * const cachingMiddleware = anthropicPromptCachingMiddleware({\n *   ttl: \"1h\",  // Cache for 1 hour instead of default 5 minutes\n *   minMessagesToCache: 5  // Only cache after 5 messages\n * });\n *\n * const agent = createAgent({\n *   model: \"anthropic:claude-3-5-sonnet\",\n *   systemMessage: \"You are a helpful assistant with deep knowledge of...\", // Long system prompt\n *   middleware: [cachingMiddleware]\n * });\n * ```\n *\n * @example\n * Conditional caching based on runtime context\n * ```typescript\n * const agent = createAgent({\n *   model: \"anthropic:claude-3-5-sonnet\",\n *   middleware: [\n *     anthropicPromptCachingMiddleware({\n *       enableCaching: true,\n *       ttl: \"5m\"\n *     })\n *   ]\n * });\n *\n * // Disable caching for specific requests\n * await agent.invoke(\n *   { messages: [new HumanMessage(\"Process this without caching\")] },\n *   {\n *     configurable: {\n *       middleware_context: { enableCaching: false }\n *     }\n *   }\n * );\n * ```\n *\n * @example\n * Optimal setup for customer support chatbot\n * ```typescript\n * const supportAgent = createAgent({\n *   model: \"anthropic:claude-3-5-sonnet\",\n *   systemMessage: `You are a customer support agent for ACME Corp.\n *\n *     Company policies:\n *     - Always be polite and professional\n *     - Refer to knowledge base for product information\n *     - Escalate billing issues to human agents\n *     ... (extensive policies and guidelines)\n *   `,\n *   tools: [searchKnowledgeBase, createTicket, checkOrderStatus],\n *   middleware: [\n *     anthropicPromptCachingMiddleware({\n *       ttl: \"1h\",  // Long TTL for stable system prompt\n *       minMessagesToCache: 1  // Cache immediately due to large system prompt\n *     })\n *   ]\n * });\n * ```\n *\n * @remarks\n * - **Anthropic Only**: This middleware only works with Anthropic models and will throw an error if used with other providers\n * - **Automatic Application**: Caching is applied automatically when message count exceeds `minMessagesToCache`\n * - **Cache Scope**: Caches are isolated per API key and cannot be shared across different keys\n * - **TTL Options**: Only supports \"5m\" (5 minutes) and \"1h\" (1 hour) as TTL values per Anthropic's API\n * - **Best Use Cases**: Long system prompts, multi-turn conversations, repetitive queries, RAG applications\n * - **Cost Impact**: Cached tokens are billed at 10% of the base input token price, cache writes are billed at 25% of the base\n *\n * @see {@link createAgent} for agent creation\n * @see {@link https://docs.anthropic.com/en/docs/build-with-claude/prompt-caching} Anthropic's prompt caching documentation\n * @public\n */\nexport function anthropicPromptCachingMiddleware(\n  middlewareOptions?: Partial<z.infer<typeof contextSchema>>\n) {\n  return createMiddleware({\n    name: \"PromptCachingMiddleware\",\n    contextSchema,\n    prepareModelRequest: (options, state, runtime) => {\n      /**\n       * If the runtime values match the schema default values, use the middleware option\n       * values otherwise use the runtime values. This allows to apply general configurations\n       * for all invocations, and override them for specific invocations.\n       */\n      const enableCaching =\n        runtime.context.enableCaching === DEFAULT_ENABLE_CACHING\n          ? middlewareOptions?.enableCaching ?? runtime.context.enableCaching\n          : runtime.context.enableCaching ?? middlewareOptions?.enableCaching;\n      const ttl =\n        runtime.context.ttl === DEFAULT_TTL\n          ? middlewareOptions?.ttl ?? runtime.context.ttl\n          : runtime.context.ttl ?? middlewareOptions?.ttl;\n      const minMessagesToCache =\n        runtime.context.minMessagesToCache === DEFAULT_MIN_MESSAGES_TO_CACHE\n          ? middlewareOptions?.minMessagesToCache ??\n            runtime.context.minMessagesToCache\n          : runtime.context.minMessagesToCache ??\n            middlewareOptions?.minMessagesToCache;\n\n      // Skip if caching is disabled\n      if (!enableCaching) {\n        return undefined;\n      }\n\n      if (options.model?.getName() !== \"ChatAnthropic\") {\n        throw new Error(\n          \"Prompt caching is only supported for Anthropic models\"\n        );\n      }\n\n      const messagesCount =\n        state.messages.length + (options.systemMessage ? 1 : 0);\n\n      if (messagesCount < minMessagesToCache) {\n        return options;\n      }\n\n      /**\n       * Add cache_control to the last message\n       */\n      const lastMessage = options.messages.at(-1);\n      if (!lastMessage) {\n        return options;\n      }\n\n      if (Array.isArray(lastMessage.content)) {\n        lastMessage.content = [\n          ...lastMessage.content.slice(0, -1),\n          {\n            ...lastMessage.content.at(-1),\n            cache_control: {\n              type: \"ephemeral\",\n              ttl,\n            },\n          } as ContentBlock,\n        ];\n      } else if (typeof lastMessage.content === \"string\") {\n        lastMessage.content = [\n          {\n            type: \"text\",\n            text: lastMessage.content,\n            cache_control: {\n              type: \"ephemeral\",\n              ttl,\n            },\n          },\n        ];\n      } else {\n        throw new PromptCachingMiddlewareError(\n          \"Last message content is not a string or array\"\n        );\n      }\n\n      return options;\n    },\n  });\n}\n"],"mappings":";;;;;AAIA,MAAM,yBAAyB;AAC/B,MAAM,cAAc;AACpB,MAAM,gCAAgC;AAEtC,MAAM,gBAAgBA,SAAE,OAAO;CAE7B,eAAeA,SAAE,SAAS,CAAC,QAAQ,uBAAuB;CAC1D,KAAKA,SAAE,KAAK,CAAC,MAAM,IAAK,EAAC,CAAC,QAAQ,YAAY;CAC9C,oBAAoBA,SAAE,QAAQ,CAAC,QAAQ,8BAA8B;AACtE,EAAC;AAEF,IAAM,+BAAN,cAA2C,MAAM;CAC/C,YAAYC,SAAiB;EAC3B,MAAM,QAAQ;EACd,KAAK,OAAO;CACb;AACF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAuHD,SAAgB,iCACdC,mBACA;AACA,QAAOC,oCAAiB;EACtB,MAAM;EACN;EACA,qBAAqB,CAAC,SAAS,OAAO,YAAY;;;;;;GAMhD,MAAM,gBACJ,QAAQ,QAAQ,kBAAkB,yBAC9B,mBAAmB,iBAAiB,QAAQ,QAAQ,gBACpD,QAAQ,QAAQ,iBAAiB,mBAAmB;GAC1D,MAAM,MACJ,QAAQ,QAAQ,QAAQ,cACpB,mBAAmB,OAAO,QAAQ,QAAQ,MAC1C,QAAQ,QAAQ,OAAO,mBAAmB;GAChD,MAAM,qBACJ,QAAQ,QAAQ,uBAAuB,gCACnC,mBAAmB,sBACnB,QAAQ,QAAQ,qBAChB,QAAQ,QAAQ,sBAChB,mBAAmB;AAGzB,OAAI,CAAC,cACH,QAAO;AAGT,OAAI,QAAQ,OAAO,SAAS,KAAK,gBAC/B,OAAM,IAAI,MACR;GAIJ,MAAM,gBACJ,MAAM,SAAS,UAAU,QAAQ,gBAAgB,IAAI;AAEvD,OAAI,gBAAgB,mBAClB,QAAO;;;;GAMT,MAAM,cAAc,QAAQ,SAAS,GAAG,GAAG;AAC3C,OAAI,CAAC,YACH,QAAO;AAGT,OAAI,MAAM,QAAQ,YAAY,QAAQ,EACpC,YAAY,UAAU,CACpB,GAAG,YAAY,QAAQ,MAAM,GAAG,GAAG,EACnC;IACE,GAAG,YAAY,QAAQ,GAAG,GAAG;IAC7B,eAAe;KACb,MAAM;KACN;IACD;GACF,CACF;YACQ,OAAO,YAAY,YAAY,UACxC,YAAY,UAAU,CACpB;IACE,MAAM;IACN,MAAM,YAAY;IAClB,eAAe;KACb,MAAM;KACN;IACD;GACF,CACF;OAED,OAAM,IAAI,6BACR;AAIJ,UAAO;EACR;CACF,EAAC;AACH"}