langchain 1.0.0-alpha.3 → 1.0.0-alpha.5

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

@@ -0,0 +1,46 @@
+import { AgentBuiltInState, AgentMiddleware, Controls, MiddlewareResult, ModelRequest, Runtime } from "./types.js";
+import { z } from "zod";
+
+//#region src/agents/middlewareAgent/middleware.d.ts
+
+/**
+ * Creates a middleware instance with automatic schema inference.
+ *
+ * @param config - Middleware configuration
+ * @param config.name - The name of the middleware
+ * @param config.stateSchema - The schema of the middleware state
+ * @param config.contextSchema - The schema of the middleware context
+ * @param config.prepareModelRequest - The function to prepare the model request
+ * @param config.beforeModel - The function to run before the model call
+ * @param config.afterModel - The function to run after the model call
+ * @returns A middleware instance
+ *
+ * @example
+ * ```ts
+ * const authMiddleware = createMiddleware({
+ *   name: "AuthMiddleware",
+ *   stateSchema: z.object({
+ *     isAuthenticated: z.boolean().default(false),
+ *   }),
+ *   contextSchema: z.object({
+ *     userId: z.string(),
+ *   }),
+ *   beforeModel: async (state, runtime, controls) => {
+ *     if (!state.isAuthenticated) {
+ *       return controls.terminate(new Error("Not authenticated"));
+ *     }
+ *   },
+ * });
+ * ```
+ */
+declare function createMiddleware<TSchema extends z.ZodObject<any> | undefined = undefined, TContextSchema extends z.ZodObject<any> | undefined = undefined>(config: {
+  name: string;
+  stateSchema?: TSchema;
+  contextSchema?: TContextSchema;
+  prepareModelRequest?: (options: ModelRequest, state: (TSchema extends z.ZodObject<any> ? z.infer<TSchema> : {}) & AgentBuiltInState, runtime: Runtime<TContextSchema extends z.ZodObject<any> ? z.infer<TContextSchema> : {}>) => Promise<ModelRequest | void> | ModelRequest | void;
+  beforeModel?: (state: (TSchema extends z.ZodObject<any> ? z.infer<TSchema> : {}) & AgentBuiltInState, runtime: Runtime<TContextSchema extends z.ZodObject<any> ? z.infer<TContextSchema> : {}>, controls: Controls<(TSchema extends z.ZodObject<any> ? z.infer<TSchema> : {}) & AgentBuiltInState>) => Promise<MiddlewareResult<Partial<TSchema extends z.ZodObject<any> ? z.infer<TSchema> : {}>>> | MiddlewareResult<Partial<TSchema extends z.ZodObject<any> ? z.infer<TSchema> : {}>>;
+  afterModel?: (state: (TSchema extends z.ZodObject<any> ? z.infer<TSchema> : {}) & AgentBuiltInState, runtime: Runtime<TContextSchema extends z.ZodObject<any> ? z.infer<TContextSchema> : {}>, controls: Controls<(TSchema extends z.ZodObject<any> ? z.infer<TSchema> : {}) & AgentBuiltInState>) => Promise<MiddlewareResult<Partial<TSchema extends z.ZodObject<any> ? z.infer<TSchema> : {}>>> | MiddlewareResult<Partial<TSchema extends z.ZodObject<any> ? z.infer<TSchema> : {}>>;
+}): AgentMiddleware<TSchema, TContextSchema, any>;
+//#endregion
+export { createMiddleware };
+//# sourceMappingURL=middleware.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"middleware.d.ts","names":["z","AgentMiddleware","Runtime","Controls","MiddlewareResult","AgentBuiltInState","ModelRequest","createMiddleware","ZodObject","TSchema","TContextSchema","infer","Promise","Partial"],"sources":["../../../src/agents/middlewareAgent/middleware.d.ts"],"sourcesContent":["/* eslint-disable @typescript-eslint/ban-types */\nimport { z } from \"zod\";\nimport type { AgentMiddleware, Runtime, Controls, MiddlewareResult, AgentBuiltInState, ModelRequest } from \"./types.js\";\n/**\n * Creates a middleware instance with automatic schema inference.\n *\n * @param config - Middleware configuration\n * @param config.name - The name of the middleware\n * @param config.stateSchema - The schema of the middleware state\n * @param config.contextSchema - The schema of the middleware context\n * @param config.prepareModelRequest - The function to prepare the model request\n * @param config.beforeModel - The function to run before the model call\n * @param config.afterModel - The function to run after the model call\n * @returns A middleware instance\n *\n * @example\n * ```ts\n * const authMiddleware = createMiddleware({\n *   name: \"AuthMiddleware\",\n *   stateSchema: z.object({\n *     isAuthenticated: z.boolean().default(false),\n *   }),\n *   contextSchema: z.object({\n *     userId: z.string(),\n *   }),\n *   beforeModel: async (state, runtime, controls) => {\n *     if (!state.isAuthenticated) {\n *       return controls.terminate(new Error(\"Not authenticated\"));\n *     }\n *   },\n * });\n * ```\n */\nexport declare function createMiddleware<TSchema extends z.ZodObject<any> | undefined = undefined, TContextSchema extends z.ZodObject<any> | undefined = undefined>(config: {\n    name: string;\n    stateSchema?: TSchema;\n    contextSchema?: TContextSchema;\n    prepareModelRequest?: (options: ModelRequest, state: (TSchema extends z.ZodObject<any> ? z.infer<TSchema> : {}) & AgentBuiltInState, runtime: Runtime<TContextSchema extends z.ZodObject<any> ? z.infer<TContextSchema> : {}>) => Promise<ModelRequest | void> | ModelRequest | void;\n    beforeModel?: (state: (TSchema extends z.ZodObject<any> ? z.infer<TSchema> : {}) & AgentBuiltInState, runtime: Runtime<TContextSchema extends z.ZodObject<any> ? z.infer<TContextSchema> : {}>, controls: Controls<(TSchema extends z.ZodObject<any> ? z.infer<TSchema> : {}) & AgentBuiltInState>) => Promise<MiddlewareResult<Partial<TSchema extends z.ZodObject<any> ? z.infer<TSchema> : {}>>> | MiddlewareResult<Partial<TSchema extends z.ZodObject<any> ? z.infer<TSchema> : {}>>;\n    afterModel?: (state: (TSchema extends z.ZodObject<any> ? z.infer<TSchema> : {}) & AgentBuiltInState, runtime: Runtime<TContextSchema extends z.ZodObject<any> ? z.infer<TContextSchema> : {}>, controls: Controls<(TSchema extends z.ZodObject<any> ? z.infer<TSchema> : {}) & AgentBuiltInState>) => Promise<MiddlewareResult<Partial<TSchema extends z.ZodObject<any> ? z.infer<TSchema> : {}>>> | MiddlewareResult<Partial<TSchema extends z.ZodObject<any> ? z.infer<TSchema> : {}>>;\n}): AgentMiddleware<TSchema, TContextSchema, any>;\n"],"mappings":";;;;;;AAiCA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAKmHE,iBAL3FK,gBAK2FL,CAAAA,gBAL1DF,CAAAA,CAAEQ,SAKwDN,CAAAA,GAAAA,CAAAA,GAAAA,SAAAA,GAAAA,SAAAA,EAAAA,uBALOF,CAAAA,CAAEQ,SAKTN,CAAAA,GAAAA,CAAAA,GAAAA,SAAAA,GAAAA,SAAAA,CAAAA,CAAAA,MAAAA,EAAAA;EAAO,IAA8FO,EAAAA,MAAAA;EAAO,WAAWD,CAAAA,EAHxNC,OAGwND;EAAS,aAAgBC,CAAAA,EAF/OC,cAE+OD;EAAO,mBAAbE,CAAAA,EAAAA,CAAAA,OAAAA,EADzNL,YACyNK,EAAAA,KAAAA,EAAAA,CADnMF,OACmME,SADnLX,CAAAA,CAAEQ,SACiLG,CAAAA,GAAAA,CAAAA,GADhKX,CAAAA,CAAEW,KAC8JA,CADxJF,OACwJE,CAAAA,GAAAA,CAAAA,CAAAA,CAAAA,GADvIN,iBACuIM,EAAAA,OAAAA,EAD3GT,OAC2GS,CADnGD,cACmGC,SAD5EX,CAAAA,CAAEQ,SAC0EG,CAAAA,GAAAA,CAAAA,GADzDX,CAAAA,CAAEW,KACuDA,CADjDD,cACiDC,CAAAA,GAAAA,CAAAA,CAAAA,CAAAA,EAAAA,GADvBC,OACuBD,CADfL,YACeK,GAAAA,IAAAA,CAAAA,GADQL,YACRK,GAAAA,IAAAA;EAAK,WAAkBN,CAAAA,EAAAA,CAAAA,KAAAA,EAAAA,CAAzPI,OAAyPJ,SAAzOL,CAAAA,CAAEQ,SAAuOH,CAAAA,GAAAA,CAAAA,GAAtNL,CAAAA,CAAEW,KAAoNN,CAA9MI,OAA8MJ,CAAAA,GAAAA,CAAAA,CAAAA,CAAAA,GAA7LA,iBAA6LA,EAAAA,OAAAA,EAAjKH,OAAiKG,CAAzJK,cAAyJL,SAAlIL,CAAAA,CAAEQ,SAAgIH,CAAAA,GAAAA,CAAAA,GAA/GL,CAAAA,CAAEW,KAA6GN,CAAvGK,cAAuGL,CAAAA,GAAAA,CAAAA,CAAAA,CAAAA,EAAAA,QAAAA,EAAtEF,QAAsEE,CAAAA,CAA5DI,OAA4DJ,SAA5CL,CAAAA,CAAEQ,SAA0CH,CAAAA,GAAAA,CAAAA,GAAzBL,CAAAA,CAAEW,KAAuBN,CAAjBI,OAAiBJ,CAAAA,GAAAA,CAAAA,CAAAA,CAAAA,GAAAA,iBAAAA,CAAAA,EAAAA,GAAuBO,OAAvBP,CAA+BD,gBAA/BC,CAAgDQ,OAAhDR,CAAwDI,OAAxDJ,SAAwEL,CAAAA,CAAEQ,SAA1EH,CAAAA,GAAAA,CAAAA,GAA2FL,CAAAA,CAAEW,KAA7FN,CAAmGI,OAAnGJ,CAAAA,GAAAA,CAAAA,CAAAA,CAAAA,CAAAA,CAAAA,GAAsHD,gBAAtHC,CAAuIQ,OAAvIR,CAA+II,OAA/IJ,SAA+JL,CAAAA,CAAEQ,SAAjKH,CAAAA,GAAAA,CAAAA,GAAkLL,CAAAA,CAAEW,KAApLN,CAA0LI,OAA1LJ,CAAAA,GAAAA,CAAAA,CAAAA,CAAAA,CAAAA;EAAiB,UAAvFF,CAAAA,EAAAA,CAAAA,KAAAA,EAAAA,CACpLM,OADoLN,SACpKH,CAAAA,CAAEQ,SADkKL,CAAAA,GAAAA,CAAAA,GACjJH,CAAAA,CAAEW,KAD+IR,CACzIM,OADyIN,CAAAA,GAAAA,CAAAA,CAAAA,CAAAA,GACxHE,iBADwHF,EAAAA,OAAAA,EAC5FD,OAD4FC,CACpFO,cADoFP,SAC7DH,CAAAA,CAAEQ,SAD2DL,CAAAA,GAAAA,CAAAA,GAC1CH,CAAAA,CAAEW,KADwCR,CAClCO,cADkCP,CAAAA,GAAAA,CAAAA,CAAAA,CAAAA,EAAAA,QAAAA,EACDA,QADCA,CAAAA,CACSM,OADTN,SACyBH,CAAAA,CAAEQ,SAD3BL,CAAAA,GAAAA,CAAAA,GAC4CH,CAAAA,CAAEW,KAD9CR,CACoDM,OADpDN,CAAAA,GAAAA,CAAAA,CAAAA,CAAAA,GACqEE,iBADrEF,CAAAA,EAAAA,GAC4FS,OAD5FT,CACoGC,gBADpGD,CACqHU,OADrHV,CAC6HM,OAD7HN,SAC6IH,CAAAA,CAAEQ,SAD/IL,CAAAA,GAAAA,CAAAA,GACgKH,CAAAA,CAAEW,KADlKR,CACwKM,OADxKN,CAAAA,GAAAA,CAAAA,CAAAA,CAAAA,CAAAA,CAAAA,GAC2LC,gBAD3LD,CAC4MU,OAD5MV,CACoNM,OADpNN,SACoOH,CAAAA,CAAEQ,SADtOL,CAAAA,GAAAA,CAAAA,GACuPH,CAAAA,CAAEW,KADzPR,CAC+PM,OAD/PN,CAAAA,GAAAA,CAAAA,CAAAA,CAAAA,CAAAA;CAAQ,CAAA,EAElNF,eAFwUQ,CAExTA,OAFwTA,EAE/SC,cAF+SD,EAAAA,GAAAA,CAAAA"}

package/dist/agents/middlewareAgent/middleware.js

@@ -0,0 +1,46 @@
+//#region src/agents/middlewareAgent/middleware.ts
+/**
+* Creates a middleware instance with automatic schema inference.
+*
+* @param config - Middleware configuration
+* @param config.name - The name of the middleware
+* @param config.stateSchema - The schema of the middleware state
+* @param config.contextSchema - The schema of the middleware context
+* @param config.prepareModelRequest - The function to prepare the model request
+* @param config.beforeModel - The function to run before the model call
+* @param config.afterModel - The function to run after the model call
+* @returns A middleware instance
+*
+* @example
+* ```ts
+* const authMiddleware = createMiddleware({
+*   name: "AuthMiddleware",
+*   stateSchema: z.object({
+*     isAuthenticated: z.boolean().default(false),
+*   }),
+*   contextSchema: z.object({
+*     userId: z.string(),
+*   }),
+*   beforeModel: async (state, runtime, controls) => {
+*     if (!state.isAuthenticated) {
+*       return controls.terminate(new Error("Not authenticated"));
+*     }
+*   },
+* });
+* ```
+*/
+function createMiddleware(config) {
+	const middleware = {
+		name: config.name,
+		stateSchema: config.stateSchema,
+		contextSchema: config.contextSchema
+	};
+	if (config.prepareModelRequest) middleware.prepareModelRequest = async (options, state, runtime) => Promise.resolve(config.prepareModelRequest(options, state, runtime));
+	if (config.beforeModel) middleware.beforeModel = async (state, runtime, controls) => Promise.resolve(config.beforeModel(state, runtime, controls));
+	if (config.afterModel) middleware.afterModel = async (state, runtime, controls) => Promise.resolve(config.afterModel(state, runtime, controls));
+	return middleware;
+}
+
+//#endregion
+export { createMiddleware };
+//# sourceMappingURL=middleware.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"middleware.js","names":["config: {\n  name: string;\n  stateSchema?: TSchema;\n  contextSchema?: TContextSchema;\n  prepareModelRequest?: (\n    options: ModelRequest,\n    state: (TSchema extends z.ZodObject<any> ? z.infer<TSchema> : {}) &\n      AgentBuiltInState,\n    runtime: Runtime<\n      TContextSchema extends z.ZodObject<any> ? z.infer<TContextSchema> : {}\n    >\n  ) => Promise<ModelRequest | void> | ModelRequest | void;\n  beforeModel?: (\n    state: (TSchema extends z.ZodObject<any> ? z.infer<TSchema> : {}) &\n      AgentBuiltInState,\n    runtime: Runtime<\n      TContextSchema extends z.ZodObject<any> ? z.infer<TContextSchema> : {}\n    >,\n    controls: Controls<\n      (TSchema extends z.ZodObject<any> ? z.infer<TSchema> : {}) &\n        AgentBuiltInState\n    >\n  ) =>\n    | Promise<\n        MiddlewareResult<\n          Partial<TSchema extends z.ZodObject<any> ? z.infer<TSchema> : {}>\n        >\n      >\n    | MiddlewareResult<\n        Partial<TSchema extends z.ZodObject<any> ? z.infer<TSchema> : {}>\n      >;\n  afterModel?: (\n    state: (TSchema extends z.ZodObject<any> ? z.infer<TSchema> : {}) &\n      AgentBuiltInState,\n    runtime: Runtime<\n      TContextSchema extends z.ZodObject<any> ? z.infer<TContextSchema> : {}\n    >,\n    controls: Controls<\n      (TSchema extends z.ZodObject<any> ? z.infer<TSchema> : {}) &\n        AgentBuiltInState\n    >\n  ) =>\n    | Promise<\n        MiddlewareResult<\n          Partial<TSchema extends z.ZodObject<any> ? z.infer<TSchema> : {}>\n        >\n      >\n    | MiddlewareResult<\n        Partial<TSchema extends z.ZodObject<any> ? z.infer<TSchema> : {}>\n      >;\n}","middleware: AgentMiddleware<TSchema, TContextSchema, any>"],"sources":["../../../src/agents/middlewareAgent/middleware.ts"],"sourcesContent":["/* eslint-disable @typescript-eslint/ban-types */\nimport { z } from \"zod\";\nimport type {\n  AgentMiddleware,\n  Runtime,\n  Controls,\n  MiddlewareResult,\n  AgentBuiltInState,\n  ModelRequest,\n} from \"./types.js\";\n\n/**\n * Creates a middleware instance with automatic schema inference.\n *\n * @param config - Middleware configuration\n * @param config.name - The name of the middleware\n * @param config.stateSchema - The schema of the middleware state\n * @param config.contextSchema - The schema of the middleware context\n * @param config.prepareModelRequest - The function to prepare the model request\n * @param config.beforeModel - The function to run before the model call\n * @param config.afterModel - The function to run after the model call\n * @returns A middleware instance\n *\n * @example\n * ```ts\n * const authMiddleware = createMiddleware({\n *   name: \"AuthMiddleware\",\n *   stateSchema: z.object({\n *     isAuthenticated: z.boolean().default(false),\n *   }),\n *   contextSchema: z.object({\n *     userId: z.string(),\n *   }),\n *   beforeModel: async (state, runtime, controls) => {\n *     if (!state.isAuthenticated) {\n *       return controls.terminate(new Error(\"Not authenticated\"));\n *     }\n *   },\n * });\n * ```\n */\nexport function createMiddleware<\n  TSchema extends z.ZodObject<any> | undefined = undefined,\n  TContextSchema extends z.ZodObject<any> | undefined = undefined\n>(config: {\n  name: string;\n  stateSchema?: TSchema;\n  contextSchema?: TContextSchema;\n  prepareModelRequest?: (\n    options: ModelRequest,\n    state: (TSchema extends z.ZodObject<any> ? z.infer<TSchema> : {}) &\n      AgentBuiltInState,\n    runtime: Runtime<\n      TContextSchema extends z.ZodObject<any> ? z.infer<TContextSchema> : {}\n    >\n  ) => Promise<ModelRequest | void> | ModelRequest | void;\n  beforeModel?: (\n    state: (TSchema extends z.ZodObject<any> ? z.infer<TSchema> : {}) &\n      AgentBuiltInState,\n    runtime: Runtime<\n      TContextSchema extends z.ZodObject<any> ? z.infer<TContextSchema> : {}\n    >,\n    controls: Controls<\n      (TSchema extends z.ZodObject<any> ? z.infer<TSchema> : {}) &\n        AgentBuiltInState\n    >\n  ) =>\n    | Promise<\n        MiddlewareResult<\n          Partial<TSchema extends z.ZodObject<any> ? z.infer<TSchema> : {}>\n        >\n      >\n    | MiddlewareResult<\n        Partial<TSchema extends z.ZodObject<any> ? z.infer<TSchema> : {}>\n      >;\n  afterModel?: (\n    state: (TSchema extends z.ZodObject<any> ? z.infer<TSchema> : {}) &\n      AgentBuiltInState,\n    runtime: Runtime<\n      TContextSchema extends z.ZodObject<any> ? z.infer<TContextSchema> : {}\n    >,\n    controls: Controls<\n      (TSchema extends z.ZodObject<any> ? z.infer<TSchema> : {}) &\n        AgentBuiltInState\n    >\n  ) =>\n    | Promise<\n        MiddlewareResult<\n          Partial<TSchema extends z.ZodObject<any> ? z.infer<TSchema> : {}>\n        >\n      >\n    | MiddlewareResult<\n        Partial<TSchema extends z.ZodObject<any> ? z.infer<TSchema> : {}>\n      >;\n}): AgentMiddleware<TSchema, TContextSchema, any> {\n  const middleware: AgentMiddleware<TSchema, TContextSchema, any> = {\n    name: config.name,\n    stateSchema: config.stateSchema,\n    contextSchema: config.contextSchema,\n  };\n\n  if (config.prepareModelRequest) {\n    middleware.prepareModelRequest = async (options, state, runtime) =>\n      Promise.resolve(config.prepareModelRequest!(options, state, runtime));\n  }\n\n  if (config.beforeModel) {\n    middleware.beforeModel = async (state, runtime, controls) =>\n      Promise.resolve(config.beforeModel!(state, runtime, controls));\n  }\n\n  if (config.afterModel) {\n    middleware.afterModel = async (state, runtime, controls) =>\n      Promise.resolve(config.afterModel!(state, runtime, controls));\n  }\n\n  return middleware;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAyCA,SAAgB,iBAGdA,QAkDgD;CAChD,MAAMC,aAA4D;EAChE,MAAM,OAAO;EACb,aAAa,OAAO;EACpB,eAAe,OAAO;CACvB;AAED,KAAI,OAAO,qBACT,WAAW,sBAAsB,OAAO,SAAS,OAAO,YACtD,QAAQ,QAAQ,OAAO,oBAAqB,SAAS,OAAO,QAAQ,CAAC;AAGzE,KAAI,OAAO,aACT,WAAW,cAAc,OAAO,OAAO,SAAS,aAC9C,QAAQ,QAAQ,OAAO,YAAa,OAAO,SAAS,SAAS,CAAC;AAGlE,KAAI,OAAO,YACT,WAAW,aAAa,OAAO,OAAO,SAAS,aAC7C,QAAQ,QAAQ,OAAO,WAAY,OAAO,SAAS,SAAS,CAAC;AAGjE,QAAO;AACR"}

package/dist/agents/middlewareAgent/middlewares/hitl.cjs

@@ -0,0 +1,235 @@
+const require_rolldown_runtime = require('../../../_virtual/rolldown_runtime.cjs');
+const require_middleware = require('../middleware.cjs');
+const __langchain_core_messages = require_rolldown_runtime.__toESM(require("@langchain/core/messages"));
+const __langchain_langgraph = require_rolldown_runtime.__toESM(require("@langchain/langgraph"));
+const zod = require_rolldown_runtime.__toESM(require("zod"));
+const uuid = require_rolldown_runtime.__toESM(require("uuid"));
+
+//#region src/agents/middlewareAgent/middlewares/hitl.ts
+const contextSchema = zod.z.object({
+	toolConfigs: zod.z.record(zod.z.object({
+		requireApproval: zod.z.boolean().optional(),
+		description: zod.z.string().optional()
+	})).default({}),
+	messagePrefix: zod.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 require_middleware.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 (!(0, __langchain_core_messages.isAIMessage)(lastMessage) || !lastMessage.tool_calls?.length) return;
+			const interruptToolCalls = [];
+			const autoApprovedToolCalls = [];
+			for (const toolCall of lastMessage.tool_calls) {
+				const normalizedToolCall = {
+					id: toolCall.id || (0, uuid.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 (0, __langchain_langgraph.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 __langchain_core_messages.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 __langchain_core_messages.AIMessage({
+				content: lastMessage.content,
+				tool_calls: approvedToolCalls,
+				id: lastMessage.id
+			});
+			return { messages: [...state.messages.slice(0, -1), updatedMessage] };
+		}
+	});
+}
+
+//#endregion
+exports.humanInTheLoopMiddleware = humanInTheLoopMiddleware;
+//# sourceMappingURL=hitl.cjs.map

package/dist/agents/middlewareAgent/middlewares/hitl.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"hitl.cjs","names":["z","options: z.input<typeof contextSchema>","createMiddleware","interruptToolCalls: ToolCall[]","autoApprovedToolCalls: ToolCall[]","normalizedToolCall: ToolCall","requests: ToolApprovalRequest[]","ToolMessage","AIMessage"],"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,gBAAgBA,MAAE,OAAO;CAC7B,aAAaA,MACV,OACCA,MAAE,OAAO;EACP,iBAAiBA,MAAE,SAAS,CAAC,UAAU;EACvC,aAAaA,MAAE,QAAQ,CAAC,UAAU;CACnC,EAAC,CACH,CACA,QAAQ,CAAE,EAAC;CACd,eAAeA,MAAE,QAAQ,CAAC,QAAQ,mCAAmC;AACtE,EAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgJF,SAAgB,yBACdC,UAAyC,CAAE,GAC3C;AACA,QAAOC,oCAAiB;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,4CAAa,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,oBAAY;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,2CAAgB,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,IAAIC,sCAAY;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,IAAIC,oCAAU;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/hitl.d.cts

@@ -0,0 +1,199 @@
+import { AgentMiddleware } from "../types.cjs";
+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.cts.map

package/dist/agents/middlewareAgent/middlewares/hitl.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hitl.d.cts","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"}