langchain 1.0.0-alpha.4 → 1.0.0-alpha.5

package/dist/agents/middlewareAgent/middlewares/hitl.d.ts

@@ -0,0 +1,199 @@
+import { AgentMiddleware } from "../types.js";
+import { z } from "zod";
+
+//#region src/agents/middlewareAgent/middlewares/hitl.d.ts
+declare const contextSchema: z.ZodObject<{
+  toolConfigs: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
+    requireApproval: z.ZodOptional<z.ZodBoolean>;
+    description: z.ZodOptional<z.ZodString>;
+  }, "strip", z.ZodTypeAny, {
+    requireApproval?: boolean | undefined;
+    description?: string | undefined;
+  }, {
+    requireApproval?: boolean | undefined;
+    description?: string | undefined;
+  }>>>;
+  messagePrefix: z.ZodDefault<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+  toolConfigs: Record<string, {
+    requireApproval?: boolean | undefined;
+    description?: string | undefined;
+  }>;
+  messagePrefix: string;
+}, {
+  toolConfigs?: Record<string, {
+    requireApproval?: boolean | undefined;
+    description?: string | undefined;
+  }> | undefined;
+  messagePrefix?: string | undefined;
+}>;
+/**
+ * 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],
+ *   middlewares: [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
+ */
+declare function humanInTheLoopMiddleware(options?: z.input<typeof contextSchema>): AgentMiddleware<undefined, z.ZodObject<{
+  toolConfigs: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
+    requireApproval: z.ZodOptional<z.ZodBoolean>;
+    description: z.ZodOptional<z.ZodString>;
+  }, "strip", z.ZodTypeAny, {
+    requireApproval?: boolean | undefined;
+    description?: string | undefined;
+  }, {
+    requireApproval?: boolean | undefined;
+    description?: string | undefined;
+  }>>>;
+  messagePrefix: z.ZodDefault<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+  toolConfigs: Record<string, {
+    requireApproval?: boolean | undefined;
+    description?: string | undefined;
+  }>;
+  messagePrefix: string;
+}, {
+  toolConfigs?: Record<string, {
+    requireApproval?: boolean | undefined;
+    description?: string | undefined;
+  }> | undefined;
+  messagePrefix?: string | undefined;
+}>, any>;
+//#endregion
+export { humanInTheLoopMiddleware };
+//# sourceMappingURL=hitl.d.ts.map

package/dist/agents/middlewareAgent/middlewares/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_js1","AgentMiddleware"],"sources":["../../../../src/agents/middlewareAgent/middlewares/hitl.d.ts"],"sourcesContent":["import { z } from \"zod\";\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 *   middlewares: [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":";;;;cACcC,eAAeD,CAAAA,CAAEM;eACdN,CAAAA,CAAEQ,WAAWR,CAAAA,CAAEO,UAAUP,CAAAA,CAAEE,WAAWF,CAAAA,CAAEM;qBAChCN,CAAAA,CAAEI,YAAYJ,CAAAA,CAAEG;IAF3BF,WAAAA,EAGOD,CAAAA,CAAEI,WAqBrB,CArBiCJ,CAAAA,CAAEE,SAqBnC,CAAA;EAAA,CAAA,EAAA,OAAA,EApBcF,CAAAA,CAAEK,UAoBhB,EAAA;IAvBwCL,eAAEE,CAAAA,EAAAA,OAAAA,GAAAA,SAAAA;IACLF,WAAEG,CAAAA,EAAAA,MAAAA,GAAAA,SAAAA;EAAU,CAAA,EAA1BH;IACUA,eAAEE,CAAAA,EAAAA,OAAAA,GAAAA,SAAAA;IAAhBF,WAAEI,CAAAA,EAAAA,MAAAA,GAAAA,SAAAA;EAAW,CAAA,CAAA,CAClBJ,CAAAA;EAAY,aAH6BM,EAUtCN,CAAAA,CAAEQ,UAVoCF,CAUzBN,CAAAA,CAAEE,SAVuBI,CAAAA;CAAS,EAAA,OAAlCC,EAWpBP,CAAAA,CAAEK,UAXkBE,EAAAA;EAAS,WAAtBC,EAYFC,MAZED,CAAAA,MAAAA,EAAAA;IAUaR,eAAEE,CAAAA,EAAAA,OAAAA,GAAAA,SAAAA;IAAfF,WAAEQ,CAAAA,EAAAA,MAAAA,GAAAA,SAAAA;EAAU,CAAA,CAAA;EACP,aACPC,EAAAA,MAAAA;CAAM,EAAA;EAMC,WAnBOH,CAAAA,EAmBbG,MAnBaH,CAAAA,MAAAA,EAAAA;IAAS,eAAA,CAAA,EAAA,OAAA,GAAA,SAAA;IAuKhBI,WAAAA,CAAAA,EAAAA,MAAAA,GAAwB,SAAA;EAAA,CAAA,CAAA,GAAA,SAAA;EAAA,aAA0BT,CAAAA,EAAAA,MAAAA,GAAAA,SAAAA;CAAa,CAAA;;;;;;;;;;;;;;;;;AAAyC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAAxGS,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/middlewares/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";
+import { v4 } from "uuid";
+
+//#region src/agents/middlewareAgent/middlewares/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],
+*   middlewares: [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/middlewares/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/middlewares/hitl.ts"],"sourcesContent":["import { z } from \"zod\";\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 *   middlewares: [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":";;;;;;;AAmBA,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/middlewares/index.cjs

@@ -0,0 +1,8 @@
+const require_summarization = require('./summarization.cjs');
+const require_hitl = require('./hitl.cjs');
+const require_promptCaching = require('./promptCaching.cjs');
+
+exports.anthropicPromptCachingMiddleware = require_promptCaching.anthropicPromptCachingMiddleware;
+exports.countTokensApproximately = require_summarization.countTokensApproximately;
+exports.humanInTheLoopMiddleware = require_hitl.humanInTheLoopMiddleware;
+exports.summarizationMiddleware = require_summarization.summarizationMiddleware;

package/dist/agents/middlewareAgent/middlewares/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/middlewares/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/middlewares/index.js

@@ -0,0 +1,5 @@
+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/middlewares/promptCaching.cjs

@@ -0,0 +1,153 @@
+const require_rolldown_runtime = require('../../../_virtual/rolldown_runtime.cjs');
+const require_middleware = require('../middleware.cjs');
+const zod = require_rolldown_runtime.__toESM(require("zod"));
+
+//#region src/agents/middlewareAgent/middlewares/promptCaching.ts
+const contextSchema = zod.z.object({
+	enableCaching: zod.z.boolean().default(true),
+	ttl: zod.z.enum(["5m", "1h"]).default("5m"),
+	minMessagesToCache: zod.z.number().default(3)
+});
+/**
+* Creates a prompt caching middleware for Anthropic models to optimize API usage.
+*
+* This middleware automatically adds cache control headers to messages when using Anthropic models,
+* enabling their prompt caching feature. This can significantly reduce costs and latency 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",
+*   middlewares: [
+*     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
+*   middlewares: [cachingMiddleware]
+* });
+* ```
+*
+* @example
+* Conditional caching based on runtime context
+* ```typescript
+* const agent = createAgent({
+*   model: "anthropic:claude-3-5-sonnet",
+*   middlewares: [
+*     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],
+*   middlewares: [
+*     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) => {
+			const enableCaching = runtime.context.enableCaching ?? middlewareOptions?.enableCaching;
+			const ttl = runtime.context.ttl ?? middlewareOptions?.ttl;
+			const minMessagesToCache = runtime.context.minMessagesToCache ?? middlewareOptions?.minMessagesToCache;
+			if (!enableCaching) return void 0;
+			if (options.model?.getName() !== "anthropic") 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;
+			return {
+				...options,
+				modelSettings: { cache_control: {
+					type: "ephemeral",
+					ttl
+				} }
+			};
+		}
+	});
+}
+
+//#endregion
+exports.anthropicPromptCachingMiddleware = anthropicPromptCachingMiddleware;
+//# sourceMappingURL=promptCaching.cjs.map