langchain 1.0.0-alpha.8 → 1.0.0-alpha.9

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

@@ -0,0 +1 @@
+{"version":3,"file":"hitl.d.ts","names":["z","ToolCall","InferInteropZodInput","AgentBuiltInState","Runtime","DescriptionFunctionSchema","Record","ZodTypeDef","ZodType","ZodUnknown","ZodTuple","ZodString","ZodPromise","ZodUnion","ZodFunction","DescriptionFactory","infer","DecisionType","ZodEnum","InterruptOnConfigSchema","ZodArray","ZodOptional","ZodAny","ZodRecord","ZodTypeAny","Promise","ZodObject","InterruptOnConfig","input","Action","ActionRequest","ReviewConfig","HITLRequest","ApproveDecision","EditDecision","RejectDecision","Decision","HITLResponse","contextSchema","ZodBoolean","ZodDefault","HumanInTheLoopMiddlewareConfig","humanInTheLoopMiddleware","NonNullable","__types_js4","AgentMiddleware"],"sources":["../../../src/agents/middleware/hitl.d.ts"],"sourcesContent":["/* eslint-disable @typescript-eslint/no-explicit-any */\nimport { z } from \"zod/v3\";\nimport { ToolCall } from \"@langchain/core/messages\";\nimport { InferInteropZodInput } from \"@langchain/core/utils/types\";\nimport type { AgentBuiltInState, Runtime } from \"../runtime.js\";\ndeclare const DescriptionFunctionSchema: z.ZodFunction<z.ZodTuple<[z.ZodType<ToolCall<string, Record<string, any>>, z.ZodTypeDef, ToolCall<string, Record<string, any>>>, z.ZodType<AgentBuiltInState, z.ZodTypeDef, AgentBuiltInState>, z.ZodType<Runtime<unknown>, z.ZodTypeDef, Runtime<unknown>>], z.ZodUnknown>, z.ZodUnion<[z.ZodString, z.ZodPromise<z.ZodString>]>>;\n/**\n * Function type that dynamically generates a description for a tool call approval request.\n *\n * @param toolCall - The tool call being reviewed\n * @param state - The current agent state\n * @param runtime - The agent runtime context\n * @returns A string description or Promise that resolves to a string description\n *\n * @example\n * ```typescript\n * import { type DescriptionFactory, type ToolCall } from \"langchain\";\n *\n * const descriptionFactory: DescriptionFactory = (toolCall, state, runtime) => {\n *   return `Please review: ${toolCall.name}(${JSON.stringify(toolCall.args)})`;\n * };\n * ```\n */\nexport type DescriptionFactory = z.infer<typeof DescriptionFunctionSchema>;\ndeclare const DecisionType: z.ZodEnum<[\"approve\", \"edit\", \"reject\"]>;\nexport type DecisionType = z.infer<typeof DecisionType>;\ndeclare const InterruptOnConfigSchema: z.ZodObject<{\n    /**\n     * The decisions that are allowed for this action.\n     */\n    allowedDecisions: z.ZodArray<z.ZodEnum<[\"approve\", \"edit\", \"reject\"]>, \"many\">;\n    /**\n     * The description attached to the request for human input.\n     * Can be either:\n     * - A static string describing the approval request\n     * - A callable that dynamically generates the description based on agent state,\n     *   runtime, and tool call information\n     *\n     * @example\n     * Static string description\n     * ```typescript\n     * import type { InterruptOnConfig } from \"langchain\";\n     *\n     * const config: InterruptOnConfig = {\n     *   allowedDecisions: [\"approve\", \"reject\"],\n     *   description: \"Please review this tool execution\"\n     * };\n     * ```\n     *\n     * @example\n     * Dynamic callable description\n     * ```typescript\n     * import type {\n     *   AgentBuiltInState,\n     *   Runtime,\n     *   DescriptionFactory,\n     *   ToolCall,\n     *   InterruptOnConfig\n     * } from \"langchain\";\n     *\n     * const formatToolDescription: DescriptionFactory = (\n     *   toolCall: ToolCall,\n     *   state: AgentBuiltInState,\n     *   runtime: Runtime<unknown>\n     * ) => {\n     *   return `Tool: ${toolCall.name}\\nArguments:\\n${JSON.stringify(toolCall.args, null, 2)}`;\n     * };\n     *\n     * const config: InterruptOnConfig = {\n     *   allowedDecisions: [\"approve\", \"edit\"],\n     *   description: formatToolDescription\n     * };\n     * ```\n     */\n    description: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodFunction<z.ZodTuple<[z.ZodType<ToolCall<string, Record<string, any>>, z.ZodTypeDef, ToolCall<string, Record<string, any>>>, z.ZodType<AgentBuiltInState, z.ZodTypeDef, AgentBuiltInState>, z.ZodType<Runtime<unknown>, z.ZodTypeDef, Runtime<unknown>>], z.ZodUnknown>, z.ZodUnion<[z.ZodString, z.ZodPromise<z.ZodString>]>>]>>;\n    /**\n     * JSON schema for the arguments associated with the action, if edits are allowed.\n     */\n    argumentsSchema: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;\n}, \"strip\", z.ZodTypeAny, {\n    allowedDecisions: (\"approve\" | \"edit\" | \"reject\")[];\n    description?: string | ((args_0: ToolCall<string, Record<string, any>>, args_1: AgentBuiltInState, args_2: Runtime<unknown>, ...args: unknown[]) => string | Promise<string>) | undefined;\n    argumentsSchema?: Record<string, any> | undefined;\n}, {\n    allowedDecisions: (\"approve\" | \"edit\" | \"reject\")[];\n    description?: string | ((args_0: ToolCall<string, Record<string, any>>, args_1: AgentBuiltInState, args_2: Runtime<unknown>, ...args: unknown[]) => string | Promise<string>) | undefined;\n    argumentsSchema?: Record<string, any> | undefined;\n}>;\nexport type InterruptOnConfig = z.input<typeof InterruptOnConfigSchema>;\n/**\n * Represents an action with a name and arguments.\n */\nexport interface Action {\n    /**\n     * The type or name of action being requested (e.g., \"add_numbers\").\n     */\n    name: string;\n    /**\n     * Key-value pairs of arguments needed for the action (e.g., {\"a\": 1, \"b\": 2}).\n     */\n    arguments: Record<string, any>;\n}\n/**\n * Represents an action request with a name, arguments, and description.\n */\nexport interface ActionRequest {\n    /**\n     * The name of the action being requested.\n     */\n    name: string;\n    /**\n     * Key-value pairs of arguments needed for the action (e.g., {\"a\": 1, \"b\": 2}).\n     */\n    arguments: Record<string, any>;\n    /**\n     * The description of the action to be reviewed.\n     */\n    description?: string;\n}\n/**\n * Policy for reviewing a HITL request.\n */\nexport interface ReviewConfig {\n    /**\n     * Name of the action associated with this review configuration.\n     */\n    actionName: string;\n    /**\n     * The decisions that are allowed for this request.\n     */\n    allowedDecisions: DecisionType[];\n    /**\n     * JSON schema for the arguments associated with the action, if edits are allowed.\n     */\n    argumentsSchema?: Record<string, any>;\n}\n/**\n * Request for human feedback on a sequence of actions requested by a model.\n *\n * @example\n * ```ts\n * const hitlRequest: HITLRequest = {\n *   actionRequests: [\n *     { name: \"send_email\", arguments: { to: \"user@example.com\", subject: \"Hello\" } }\n *   ],\n *   reviewConfigs: [\n *     {\n *       actionName: \"send_email\",\n *       allowedDecisions: [\"approve\", \"edit\", \"reject\"],\n *       description: \"Please review the email before sending\"\n *     }\n *   ]\n * };\n * const response = interrupt(hitlRequest);\n * ```\n */\nexport interface HITLRequest {\n    /**\n     * A list of agent actions for human review.\n     */\n    actionRequests: ActionRequest[];\n    /**\n     * Review configuration for all possible actions.\n     */\n    reviewConfigs: ReviewConfig[];\n}\n/**\n * Response when a human approves the action.\n */\nexport interface ApproveDecision {\n    type: \"approve\";\n}\n/**\n * Response when a human edits the action.\n */\nexport interface EditDecision {\n    type: \"edit\";\n    /**\n     * Edited action for the agent to perform.\n     * Ex: for a tool call, a human reviewer can edit the tool name and args.\n     */\n    editedAction: Action;\n}\n/**\n * Response when a human rejects the action.\n */\nexport interface RejectDecision {\n    type: \"reject\";\n    /**\n     * The message sent to the model explaining why the action was rejected.\n     */\n    message?: string;\n}\n/**\n * Union of all possible decision types.\n */\nexport type Decision = ApproveDecision | EditDecision | RejectDecision;\n/**\n * Response payload for a HITLRequest.\n */\nexport interface HITLResponse {\n    /**\n     * The decisions made by the human.\n     */\n    decisions: Decision[];\n}\ndeclare const contextSchema: z.ZodObject<{\n    /**\n     * Mapping of tool name to allowed reviewer responses.\n     * If a tool doesn't have an entry, it's auto-approved by default.\n     *\n     * - `true` -> pause for approval and allow approve/edit/reject decisions\n     * - `false` -> auto-approve (no human review)\n     * - `InterruptOnConfig` -> explicitly specify which decisions are allowed for this tool\n     */\n    interruptOn: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodBoolean, z.ZodObject<{\n        /**\n         * The decisions that are allowed for this action.\n         */\n        allowedDecisions: z.ZodArray<z.ZodEnum<[\"approve\", \"edit\", \"reject\"]>, \"many\">;\n        /**\n         * The description attached to the request for human input.\n         * Can be either:\n         * - A static string describing the approval request\n         * - A callable that dynamically generates the description based on agent state,\n         *   runtime, and tool call information\n         *\n         * @example\n         * Static string description\n         * ```typescript\n         * import type { InterruptOnConfig } from \"langchain\";\n         *\n         * const config: InterruptOnConfig = {\n         *   allowedDecisions: [\"approve\", \"reject\"],\n         *   description: \"Please review this tool execution\"\n         * };\n         * ```\n         *\n         * @example\n         * Dynamic callable description\n         * ```typescript\n         * import type {\n         *   AgentBuiltInState,\n         *   Runtime,\n         *   DescriptionFactory,\n         *   ToolCall,\n         *   InterruptOnConfig\n         * } from \"langchain\";\n         *\n         * const formatToolDescription: DescriptionFactory = (\n         *   toolCall: ToolCall,\n         *   state: AgentBuiltInState,\n         *   runtime: Runtime<unknown>\n         * ) => {\n         *   return `Tool: ${toolCall.name}\\nArguments:\\n${JSON.stringify(toolCall.args, null, 2)}`;\n         * };\n         *\n         * const config: InterruptOnConfig = {\n         *   allowedDecisions: [\"approve\", \"edit\"],\n         *   description: formatToolDescription\n         * };\n         * ```\n         */\n        description: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodFunction<z.ZodTuple<[z.ZodType<ToolCall<string, Record<string, any>>, z.ZodTypeDef, ToolCall<string, Record<string, any>>>, z.ZodType<AgentBuiltInState, z.ZodTypeDef, AgentBuiltInState>, z.ZodType<Runtime<unknown>, z.ZodTypeDef, Runtime<unknown>>], z.ZodUnknown>, z.ZodUnion<[z.ZodString, z.ZodPromise<z.ZodString>]>>]>>;\n        /**\n         * JSON schema for the arguments associated with the action, if edits are allowed.\n         */\n        argumentsSchema: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;\n    }, \"strip\", z.ZodTypeAny, {\n        allowedDecisions: (\"approve\" | \"edit\" | \"reject\")[];\n        description?: string | ((args_0: ToolCall<string, Record<string, any>>, args_1: AgentBuiltInState, args_2: Runtime<unknown>, ...args: unknown[]) => string | Promise<string>) | undefined;\n        argumentsSchema?: Record<string, any> | undefined;\n    }, {\n        allowedDecisions: (\"approve\" | \"edit\" | \"reject\")[];\n        description?: string | ((args_0: ToolCall<string, Record<string, any>>, args_1: AgentBuiltInState, args_2: Runtime<unknown>, ...args: unknown[]) => string | Promise<string>) | undefined;\n        argumentsSchema?: Record<string, any> | undefined;\n    }>]>>>;\n    /**\n     * Prefix used when constructing human-facing approval messages.\n     * Provides context about the tool call being reviewed; does not change the underlying action.\n     *\n     * Note: This prefix is only applied for tools that do not provide a custom\n     * `description` via their {@link InterruptOnConfig}. If a tool specifies a custom\n     * `description`, that per-tool text is used and this prefix is ignored.\n     */\n    descriptionPrefix: z.ZodDefault<z.ZodString>;\n}, \"strip\", z.ZodTypeAny, {\n    interruptOn?: Record<string, boolean | {\n        allowedDecisions: (\"approve\" | \"edit\" | \"reject\")[];\n        description?: string | ((args_0: ToolCall<string, Record<string, any>>, args_1: AgentBuiltInState, args_2: Runtime<unknown>, ...args: unknown[]) => string | Promise<string>) | undefined;\n        argumentsSchema?: Record<string, any> | undefined;\n    }> | undefined;\n    descriptionPrefix: string;\n}, {\n    interruptOn?: Record<string, boolean | {\n        allowedDecisions: (\"approve\" | \"edit\" | \"reject\")[];\n        description?: string | ((args_0: ToolCall<string, Record<string, any>>, args_1: AgentBuiltInState, args_2: Runtime<unknown>, ...args: unknown[]) => string | Promise<string>) | undefined;\n        argumentsSchema?: Record<string, any> | undefined;\n    }> | undefined;\n    descriptionPrefix?: string | undefined;\n}>;\nexport type HumanInTheLoopMiddlewareConfig = InferInteropZodInput<typeof contextSchema>;\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 * A invocation result that has been interrupted by the middleware will have a `__interrupt__`\n * property that contains the interrupt request.\n *\n * ```ts\n * import { type HITLRequest, type HITLResponse } from \"langchain\";\n * import { type Interrupt } from \"langchain\";\n *\n * const result = await agent.invoke(request);\n * const interruptRequest = result.__interrupt__?.[0] as Interrupt<HITLRequest>;\n *\n * // Examine the action requests and review configs\n * const actionRequests = interruptRequest.value.actionRequests;\n * const reviewConfigs = interruptRequest.value.reviewConfigs;\n *\n * // Create decisions for each action\n * const resume: HITLResponse = {\n *   decisions: actionRequests.map((action, i) => {\n *     if (action.name === \"calculator\") {\n *       return { type: \"approve\" };\n *     } else if (action.name === \"write_file\") {\n *       return {\n *         type: \"edit\",\n *         editedAction: { name: \"write_file\", arguments: { filename: \"safe.txt\", content: \"Safe content\" } }\n *       };\n *     }\n *     return { type: \"reject\", message: \"Action not allowed\" };\n *   })\n * };\n *\n * // Resume with decisions\n * await agent.invoke(new Command({ resume }), config);\n * ```\n *\n * ## Features\n *\n * - **Selective Tool Approval**: Configure which tools require human approval\n * - **Multiple Decision Types**: Approve, edit, or reject 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 * ## Decision Types\n *\n * When a tool requires approval, the human operator can respond with:\n * - `approve`: Execute the tool with original arguments\n * - `edit`: Modify the tool name and/or arguments before execution\n * - `reject`: Provide a manual response instead of executing the tool\n *\n * @param options - Configuration options for the middleware\n * @param options.interruptOn - Per-tool configuration mapping tool names to their settings\n * @param options.interruptOn[toolName].allowedDecisions - Array of decision types allowed for this tool (e.g., [\"approve\", \"edit\", \"reject\"])\n * @param options.interruptOn[toolName].description - Custom approval message for the tool. Can be either a static string or a callable that dynamically generates the description based on agent state, runtime, and tool call information\n * @param options.interruptOn[toolName].argumentsSchema - JSON schema for the arguments associated with the action, if edits are allowed\n * @param options.descriptionPrefix - Default prefix for approval messages (default: \"Tool execution requires approval\"). Only used for tools that do not define a custom `description` in their InterruptOnConfig.\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\";\n * import { createAgent } from \"langchain\";\n *\n * const hitlMiddleware = humanInTheLoopMiddleware({\n *   interruptOn: {\n *     // Interrupt write_file tool and allow edits or approvals\n *     \"write_file\": {\n *       allowedDecisions: [\"approve\", \"edit\"],\n *       description: \"⚠️ File write operation requires approval\"\n *     },\n *     // Auto-approve read_file tool\n *     \"read_file\": false\n *   }\n * });\n *\n * const agent = createAgent({\n *   model: \"openai:gpt-4\",\n *   tools: [writeFileTool, readFileTool],\n *   middleware: [hitlMiddleware]\n * });\n * ```\n *\n * @example\n * Handling approval requests\n * ```typescript\n * import { type HITLRequest, type HITLResponse, type Interrupt } from \"langchain\";\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 * if (result.__interrupt__) {\n *   const interruptRequest = result.__interrupt__?.[0] as Interrupt<HITLRequest>;\n *\n *   // Show tool call details to user\n *   console.log(\"Actions:\", interruptRequest.value.actionRequests);\n *   console.log(\"Review configs:\", interruptRequest.value.reviewConfigs);\n *\n *   // Resume with approval\n *   const resume: HITLResponse = {\n *     decisions: [{ type: \"approve\" }]\n *   };\n *   await agent.invoke(\n *     new Command({ resume }),\n *     config\n *   );\n * }\n * ```\n *\n * @example\n * Different decision types\n * ```typescript\n * import { type HITLResponse } from \"langchain\";\n *\n * // Approve the tool call as-is\n * const resume: HITLResponse = {\n *   decisions: [{ type: \"approve\" }]\n * };\n *\n * // Edit the tool arguments\n * const resume: HITLResponse = {\n *   decisions: [{\n *     type: \"edit\",\n *     editedAction: { name: \"write_file\", arguments: { filename: \"safe.txt\", content: \"Modified\" } }\n *   }]\n * };\n *\n * // Reject with feedback\n * const resume: HITLResponse = {\n *   decisions: [{\n *     type: \"reject\",\n *     message: \"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 *   interruptOn: {\n *     \"execute_sql\": {\n *       allowedDecisions: [\"approve\", \"edit\", \"reject\"],\n *       description: \"🚨 SQL query requires DBA approval\\nPlease review for safety and performance\"\n *     },\n *     \"read_schema\": false,  // Reading metadata is safe\n *     \"delete_records\": {\n *       allowedDecisions: [\"approve\", \"reject\"],\n *       description: \"⛔ DESTRUCTIVE OPERATION - Requires manager approval\"\n *     }\n *   },\n *   descriptionPrefix: \"Database operation pending approval\"\n * });\n * ```\n *\n * @example\n * Using dynamic callable descriptions\n * ```typescript\n * import { type DescriptionFactory, type ToolCall } from \"langchain\";\n * import type { AgentBuiltInState, Runtime } from \"langchain/agents\";\n *\n * // Define a dynamic description factory\n * const formatToolDescription: DescriptionFactory = (\n *   toolCall: ToolCall,\n *   state: AgentBuiltInState,\n *   runtime: Runtime<unknown>\n * ) => {\n *   return `Tool: ${toolCall.name}\\nArguments:\\n${JSON.stringify(toolCall.args, null, 2)}`;\n * };\n *\n * const hitlMiddleware = humanInTheLoopMiddleware({\n *   interruptOn: {\n *     \"write_file\": {\n *       allowedDecisions: [\"approve\", \"edit\"],\n *       // Use dynamic description that can access tool call, state, and runtime\n *       description: formatToolDescription\n *     },\n *     // Or use an inline function\n *     \"send_email\": {\n *       allowedDecisions: [\"approve\", \"reject\"],\n *       description: (toolCall, state, runtime) => {\n *         const { to, subject } = toolCall.args;\n *         return `Email to ${to}\\nSubject: ${subject}\\n\\nRequires approval before sending`;\n *       }\n *     }\n *   }\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 request\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: NonNullable<HumanInTheLoopMiddlewareConfig>): import(\"./types.js\").AgentMiddleware<undefined, z.ZodObject<{\n    /**\n     * Mapping of tool name to allowed reviewer responses.\n     * If a tool doesn't have an entry, it's auto-approved by default.\n     *\n     * - `true` -> pause for approval and allow approve/edit/reject decisions\n     * - `false` -> auto-approve (no human review)\n     * - `InterruptOnConfig` -> explicitly specify which decisions are allowed for this tool\n     */\n    interruptOn: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodBoolean, z.ZodObject<{\n        /**\n         * The decisions that are allowed for this action.\n         */\n        allowedDecisions: z.ZodArray<z.ZodEnum<[\"approve\", \"edit\", \"reject\"]>, \"many\">;\n        /**\n         * The description attached to the request for human input.\n         * Can be either:\n         * - A static string describing the approval request\n         * - A callable that dynamically generates the description based on agent state,\n         *   runtime, and tool call information\n         *\n         * @example\n         * Static string description\n         * ```typescript\n         * import type { InterruptOnConfig } from \"langchain\";\n         *\n         * const config: InterruptOnConfig = {\n         *   allowedDecisions: [\"approve\", \"reject\"],\n         *   description: \"Please review this tool execution\"\n         * };\n         * ```\n         *\n         * @example\n         * Dynamic callable description\n         * ```typescript\n         * import type {\n         *   AgentBuiltInState,\n         *   Runtime,\n         *   DescriptionFactory,\n         *   ToolCall,\n         *   InterruptOnConfig\n         * } from \"langchain\";\n         *\n         * const formatToolDescription: DescriptionFactory = (\n         *   toolCall: ToolCall,\n         *   state: AgentBuiltInState,\n         *   runtime: Runtime<unknown>\n         * ) => {\n         *   return `Tool: ${toolCall.name}\\nArguments:\\n${JSON.stringify(toolCall.args, null, 2)}`;\n         * };\n         *\n         * const config: InterruptOnConfig = {\n         *   allowedDecisions: [\"approve\", \"edit\"],\n         *   description: formatToolDescription\n         * };\n         * ```\n         */\n        description: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodFunction<z.ZodTuple<[z.ZodType<ToolCall<string, Record<string, any>>, z.ZodTypeDef, ToolCall<string, Record<string, any>>>, z.ZodType<AgentBuiltInState, z.ZodTypeDef, AgentBuiltInState>, z.ZodType<Runtime<unknown>, z.ZodTypeDef, Runtime<unknown>>], z.ZodUnknown>, z.ZodUnion<[z.ZodString, z.ZodPromise<z.ZodString>]>>]>>;\n        /**\n         * JSON schema for the arguments associated with the action, if edits are allowed.\n         */\n        argumentsSchema: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;\n    }, \"strip\", z.ZodTypeAny, {\n        allowedDecisions: (\"approve\" | \"edit\" | \"reject\")[];\n        description?: string | ((args_0: ToolCall<string, Record<string, any>>, args_1: AgentBuiltInState, args_2: Runtime<unknown>, ...args: unknown[]) => string | Promise<string>) | undefined;\n        argumentsSchema?: Record<string, any> | undefined;\n    }, {\n        allowedDecisions: (\"approve\" | \"edit\" | \"reject\")[];\n        description?: string | ((args_0: ToolCall<string, Record<string, any>>, args_1: AgentBuiltInState, args_2: Runtime<unknown>, ...args: unknown[]) => string | Promise<string>) | undefined;\n        argumentsSchema?: Record<string, any> | undefined;\n    }>]>>>;\n    /**\n     * Prefix used when constructing human-facing approval messages.\n     * Provides context about the tool call being reviewed; does not change the underlying action.\n     *\n     * Note: This prefix is only applied for tools that do not provide a custom\n     * `description` via their {@link InterruptOnConfig}. If a tool specifies a custom\n     * `description`, that per-tool text is used and this prefix is ignored.\n     */\n    descriptionPrefix: z.ZodDefault<z.ZodString>;\n}, \"strip\", z.ZodTypeAny, {\n    interruptOn?: Record<string, boolean | {\n        allowedDecisions: (\"approve\" | \"edit\" | \"reject\")[];\n        description?: string | ((args_0: ToolCall<string, Record<string, any>>, args_1: AgentBuiltInState, args_2: Runtime<unknown>, ...args: unknown[]) => string | Promise<string>) | undefined;\n        argumentsSchema?: Record<string, any> | undefined;\n    }> | undefined;\n    descriptionPrefix: string;\n}, {\n    interruptOn?: Record<string, boolean | {\n        allowedDecisions: (\"approve\" | \"edit\" | \"reject\")[];\n        description?: string | ((args_0: ToolCall<string, Record<string, any>>, args_1: AgentBuiltInState, args_2: Runtime<unknown>, ...args: unknown[]) => string | Promise<string>) | undefined;\n        argumentsSchema?: Record<string, any> | undefined;\n    }> | undefined;\n    descriptionPrefix?: string | undefined;\n}>, any>;\nexport {};\n"],"mappings":"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"}

package/dist/agents/middleware/hitl.js

@@ -0,0 +1,403 @@
+import { createMiddleware } from "../middleware.js";
+import { AIMessage, ToolMessage } from "@langchain/core/messages";
+import { interrupt } from "@langchain/langgraph";
+import { z } from "zod/v3";
+import { interopParse } from "@langchain/core/utils/types";
+
+//#region src/agents/middleware/hitl.ts
+const DescriptionFunctionSchema = z.function().args(z.custom(), z.custom(), z.custom()).returns(z.union([z.string(), z.promise(z.string())]));
+/**
+* The type of decision a human can make.
+*/
+const ALLOWED_DECISIONS = [
+	"approve",
+	"edit",
+	"reject"
+];
+const DecisionType = z.enum(ALLOWED_DECISIONS);
+const InterruptOnConfigSchema = z.object({
+	allowedDecisions: z.array(DecisionType),
+	description: z.union([z.string(), DescriptionFunctionSchema]).optional(),
+	argumentsSchema: z.record(z.any()).optional()
+});
+const contextSchema = z.object({
+	interruptOn: z.record(z.union([z.boolean(), InterruptOnConfigSchema])).optional(),
+	descriptionPrefix: 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.
+*
+* A invocation result that has been interrupted by the middleware will have a `__interrupt__`
+* property that contains the interrupt request.
+*
+* ```ts
+* import { type HITLRequest, type HITLResponse } from "langchain";
+* import { type Interrupt } from "langchain";
+*
+* const result = await agent.invoke(request);
+* const interruptRequest = result.__interrupt__?.[0] as Interrupt<HITLRequest>;
+*
+* // Examine the action requests and review configs
+* const actionRequests = interruptRequest.value.actionRequests;
+* const reviewConfigs = interruptRequest.value.reviewConfigs;
+*
+* // Create decisions for each action
+* const resume: HITLResponse = {
+*   decisions: actionRequests.map((action, i) => {
+*     if (action.name === "calculator") {
+*       return { type: "approve" };
+*     } else if (action.name === "write_file") {
+*       return {
+*         type: "edit",
+*         editedAction: { name: "write_file", arguments: { filename: "safe.txt", content: "Safe content" } }
+*       };
+*     }
+*     return { type: "reject", message: "Action not allowed" };
+*   })
+* };
+*
+* // Resume with decisions
+* await agent.invoke(new Command({ resume }), config);
+* ```
+*
+* ## Features
+*
+* - **Selective Tool Approval**: Configure which tools require human approval
+* - **Multiple Decision Types**: Approve, edit, or reject tool calls
+* - **Asynchronous Workflow**: Uses LangGraph's interrupt mechanism for non-blocking approval
+* - **Custom Approval Messages**: Provide context-specific descriptions for approval requests
+*
+* ## Decision Types
+*
+* When a tool requires approval, the human operator can respond with:
+* - `approve`: Execute the tool with original arguments
+* - `edit`: Modify the tool name and/or arguments before execution
+* - `reject`: Provide a manual response instead of executing the tool
+*
+* @param options - Configuration options for the middleware
+* @param options.interruptOn - Per-tool configuration mapping tool names to their settings
+* @param options.interruptOn[toolName].allowedDecisions - Array of decision types allowed for this tool (e.g., ["approve", "edit", "reject"])
+* @param options.interruptOn[toolName].description - Custom approval message for the tool. Can be either a static string or a callable that dynamically generates the description based on agent state, runtime, and tool call information
+* @param options.interruptOn[toolName].argumentsSchema - JSON schema for the arguments associated with the action, if edits are allowed
+* @param options.descriptionPrefix - Default prefix for approval messages (default: "Tool execution requires approval"). Only used for tools that do not define a custom `description` in their InterruptOnConfig.
+*
+* @returns A middleware instance that can be passed to `createAgent`
+*
+* @example
+* Basic usage with selective tool approval
+* ```typescript
+* import { humanInTheLoopMiddleware } from "langchain";
+* import { createAgent } from "langchain";
+*
+* const hitlMiddleware = humanInTheLoopMiddleware({
+*   interruptOn: {
+*     // Interrupt write_file tool and allow edits or approvals
+*     "write_file": {
+*       allowedDecisions: ["approve", "edit"],
+*       description: "⚠️ File write operation requires approval"
+*     },
+*     // Auto-approve read_file tool
+*     "read_file": false
+*   }
+* });
+*
+* const agent = createAgent({
+*   model: "openai:gpt-4",
+*   tools: [writeFileTool, readFileTool],
+*   middleware: [hitlMiddleware]
+* });
+* ```
+*
+* @example
+* Handling approval requests
+* ```typescript
+* import { type HITLRequest, type HITLResponse, type Interrupt } from "langchain";
+* 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
+* if (result.__interrupt__) {
+*   const interruptRequest = result.__interrupt__?.[0] as Interrupt<HITLRequest>;
+*
+*   // Show tool call details to user
+*   console.log("Actions:", interruptRequest.value.actionRequests);
+*   console.log("Review configs:", interruptRequest.value.reviewConfigs);
+*
+*   // Resume with approval
+*   const resume: HITLResponse = {
+*     decisions: [{ type: "approve" }]
+*   };
+*   await agent.invoke(
+*     new Command({ resume }),
+*     config
+*   );
+* }
+* ```
+*
+* @example
+* Different decision types
+* ```typescript
+* import { type HITLResponse } from "langchain";
+*
+* // Approve the tool call as-is
+* const resume: HITLResponse = {
+*   decisions: [{ type: "approve" }]
+* };
+*
+* // Edit the tool arguments
+* const resume: HITLResponse = {
+*   decisions: [{
+*     type: "edit",
+*     editedAction: { name: "write_file", arguments: { filename: "safe.txt", content: "Modified" } }
+*   }]
+* };
+*
+* // Reject with feedback
+* const resume: HITLResponse = {
+*   decisions: [{
+*     type: "reject",
+*     message: "File operation not allowed in demo mode"
+*   }]
+* };
+* ```
+*
+* @example
+* Production use case with database operations
+* ```typescript
+* const hitlMiddleware = humanInTheLoopMiddleware({
+*   interruptOn: {
+*     "execute_sql": {
+*       allowedDecisions: ["approve", "edit", "reject"],
+*       description: "🚨 SQL query requires DBA approval\nPlease review for safety and performance"
+*     },
+*     "read_schema": false,  // Reading metadata is safe
+*     "delete_records": {
+*       allowedDecisions: ["approve", "reject"],
+*       description: "⛔ DESTRUCTIVE OPERATION - Requires manager approval"
+*     }
+*   },
+*   descriptionPrefix: "Database operation pending approval"
+* });
+* ```
+*
+* @example
+* Using dynamic callable descriptions
+* ```typescript
+* import { type DescriptionFactory, type ToolCall } from "langchain";
+* import type { AgentBuiltInState, Runtime } from "langchain/agents";
+*
+* // Define a dynamic description factory
+* const formatToolDescription: DescriptionFactory = (
+*   toolCall: ToolCall,
+*   state: AgentBuiltInState,
+*   runtime: Runtime<unknown>
+* ) => {
+*   return `Tool: ${toolCall.name}\nArguments:\n${JSON.stringify(toolCall.args, null, 2)}`;
+* };
+*
+* const hitlMiddleware = humanInTheLoopMiddleware({
+*   interruptOn: {
+*     "write_file": {
+*       allowedDecisions: ["approve", "edit"],
+*       // Use dynamic description that can access tool call, state, and runtime
+*       description: formatToolDescription
+*     },
+*     // Or use an inline function
+*     "send_email": {
+*       allowedDecisions: ["approve", "reject"],
+*       description: (toolCall, state, runtime) => {
+*         const { to, subject } = toolCall.args;
+*         return `Email to ${to}\nSubject: ${subject}\n\nRequires approval before sending`;
+*       }
+*     }
+*   }
+* });
+* ```
+*
+* @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 request
+* - 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) {
+	const createActionAndConfig = async (toolCall, config, state, runtime) => {
+		const toolName = toolCall.name;
+		const toolArgs = toolCall.args;
+		const descriptionValue = config.description;
+		let description;
+		if (typeof descriptionValue === "function") description = await descriptionValue(toolCall, state, runtime);
+		else if (descriptionValue !== void 0) description = descriptionValue;
+		else description = `${options.descriptionPrefix ?? "Tool execution requires approval"}\n\nTool: ${toolName}\nArgs: ${JSON.stringify(toolArgs, null, 2)}`;
+		/**
+		* Create ActionRequest with description
+		*/
+		const actionRequest = {
+			name: toolName,
+			arguments: toolArgs,
+			description
+		};
+		/**
+		* Create ReviewConfig
+		*/
+		const reviewConfig = {
+			actionName: toolName,
+			allowedDecisions: config.allowedDecisions
+		};
+		if (config.argumentsSchema) reviewConfig.argumentsSchema = config.argumentsSchema;
+		return {
+			actionRequest,
+			reviewConfig
+		};
+	};
+	const processDecision = (decision, toolCall, config) => {
+		const allowedDecisions = config.allowedDecisions;
+		if (decision.type === "approve" && allowedDecisions.includes("approve")) return {
+			revisedToolCall: toolCall,
+			toolMessage: null
+		};
+		if (decision.type === "edit" && allowedDecisions.includes("edit")) {
+			const editedAction = decision.editedAction;
+			/**
+			* Validate edited action structure
+			*/
+			if (!editedAction || typeof editedAction.name !== "string") throw new Error(`Invalid edited action for tool "${toolCall.name}": name must be a string`);
+			if (!editedAction.arguments || typeof editedAction.arguments !== "object") throw new Error(`Invalid edited action for tool "${toolCall.name}": arguments must be an object`);
+			return {
+				revisedToolCall: {
+					type: "tool_call",
+					name: editedAction.name,
+					args: editedAction.arguments,
+					id: toolCall.id
+				},
+				toolMessage: null
+			};
+		}
+		if (decision.type === "reject" && allowedDecisions.includes("reject")) {
+			/**
+			* Validate that message is a string if provided
+			*/
+			if (decision.message !== void 0 && typeof decision.message !== "string") throw new Error(`Tool call response for "${toolCall.name}" must be a string, got ${typeof decision.message}`);
+			const content = decision.message ?? `User rejected the tool call for \`${toolCall.name}\` with id ${toolCall.id}`;
+			const toolMessage = new ToolMessage({
+				content,
+				name: toolCall.name,
+				tool_call_id: toolCall.id,
+				status: "error"
+			});
+			return {
+				revisedToolCall: toolCall,
+				toolMessage
+			};
+		}
+		const msg = `Unexpected human decision: ${JSON.stringify(decision)}. Decision type '${decision.type}' is not allowed for tool '${toolCall.name}'. Expected one of ${JSON.stringify(allowedDecisions)} based on the tool's configuration.`;
+		throw new Error(msg);
+	};
+	return createMiddleware({
+		name: "HumanInTheLoopMiddleware",
+		contextSchema,
+		afterModelJumpTo: ["model"],
+		afterModel: async (state, runtime) => {
+			const config = interopParse(contextSchema, {
+				...options,
+				...runtime.context || {}
+			});
+			if (!config) return;
+			const { messages } = state;
+			if (!messages.length) return;
+			/**
+			* Don't do anything if the last message isn't an AI message with tool calls.
+			*/
+			const lastMessage = [...messages].reverse().find((msg) => AIMessage.isInstance(msg));
+			if (!lastMessage || !lastMessage.tool_calls?.length) return;
+			/**
+			* If the user omits the interruptOn config, we don't do anything.
+			*/
+			if (!config.interruptOn) return;
+			/**
+			* Resolve per-tool configs (boolean true -> all decisions allowed; false -> auto-approve)
+			*/
+			const resolvedConfigs = {};
+			for (const [toolName, toolConfig] of Object.entries(config.interruptOn)) if (typeof toolConfig === "boolean") {
+				if (toolConfig === true) resolvedConfigs[toolName] = { allowedDecisions: [...ALLOWED_DECISIONS] };
+			} else if (toolConfig.allowedDecisions) resolvedConfigs[toolName] = toolConfig;
+			const interruptToolCalls = [];
+			const autoApprovedToolCalls = [];
+			for (const toolCall of lastMessage.tool_calls) if (toolCall.name in resolvedConfigs) interruptToolCalls.push(toolCall);
+			else autoApprovedToolCalls.push(toolCall);
+			/**
+			* No interrupt tool calls, so we can just return.
+			*/
+			if (!interruptToolCalls.length) return;
+			/**
+			* Create action requests and review configs for all tools that need approval
+			*/
+			const actionRequests = [];
+			const reviewConfigs = [];
+			for (const toolCall of interruptToolCalls) {
+				const interruptConfig = resolvedConfigs[toolCall.name];
+				/**
+				* Create ActionRequest and ReviewConfig using helper method
+				*/
+				const { actionRequest, reviewConfig } = await createActionAndConfig(toolCall, interruptConfig, state, runtime);
+				actionRequests.push(actionRequest);
+				reviewConfigs.push(reviewConfig);
+			}
+			/**
+			* Create single HITLRequest with all actions and configs
+			*/
+			const hitlRequest = {
+				actionRequests,
+				reviewConfigs
+			};
+			/**
+			* Send interrupt and get response
+			*/
+			const hitlResponse = await interrupt(hitlRequest);
+			const decisions = hitlResponse.decisions;
+			/**
+			* Validate that decisions is a valid array before checking length
+			*/
+			if (!decisions || !Array.isArray(decisions)) throw new Error("Invalid HITLResponse: decisions must be a non-empty array");
+			/**
+			* Validate that the number of decisions matches the number of interrupt tool calls
+			*/
+			if (decisions.length !== interruptToolCalls.length) throw new Error(`Number of human decisions (${decisions.length}) does not match number of hanging tool calls (${interruptToolCalls.length}).`);
+			const revisedToolCalls = [...autoApprovedToolCalls];
+			const artificialToolMessages = [];
+			/**
+			* Process each decision using helper method
+			*/
+			for (let i = 0; i < decisions.length; i++) {
+				const decision = decisions[i];
+				const toolCall = interruptToolCalls[i];
+				const interruptConfig = resolvedConfigs[toolCall.name];
+				const { revisedToolCall, toolMessage } = processDecision(decision, toolCall, interruptConfig);
+				if (revisedToolCall) revisedToolCalls.push(revisedToolCall);
+				if (toolMessage) artificialToolMessages.push(toolMessage);
+			}
+			/**
+			* Update the AI message to only include approved tool calls
+			*/
+			if (AIMessage.isInstance(lastMessage)) lastMessage.tool_calls = revisedToolCalls;
+			return { messages: [lastMessage, ...artificialToolMessages] };
+		}
+	});
+}
+
+//#endregion
+export { humanInTheLoopMiddleware };
+//# sourceMappingURL=hitl.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"hitl.js","names":["options: NonNullable<HumanInTheLoopMiddlewareConfig>","toolCall: ToolCall","config: InterruptOnConfig","state: AgentBuiltInState","runtime: Runtime<unknown>","description: string","actionRequest: ActionRequest","reviewConfig: ReviewConfig","decision: Decision","resolvedConfigs: Record<string, InterruptOnConfig>","interruptToolCalls: ToolCall[]","autoApprovedToolCalls: ToolCall[]","actionRequests: ActionRequest[]","reviewConfigs: ReviewConfig[]","hitlRequest: HITLRequest","revisedToolCalls: ToolCall[]","artificialToolMessages: ToolMessage[]"],"sources":["../../../src/agents/middleware/hitl.ts"],"sourcesContent":["/* eslint-disable @typescript-eslint/no-explicit-any */\nimport { z } from \"zod/v3\";\nimport { AIMessage, ToolMessage, ToolCall } from \"@langchain/core/messages\";\nimport {\n  InferInteropZodInput,\n  interopParse,\n} from \"@langchain/core/utils/types\";\nimport { interrupt } from \"@langchain/langgraph\";\n\nimport { createMiddleware } from \"../middleware.js\";\nimport type { AgentBuiltInState, Runtime } from \"../runtime.js\";\n\nconst DescriptionFunctionSchema = z\n  .function()\n  .args(\n    z.custom<ToolCall>(), // toolCall\n    z.custom<AgentBuiltInState>(), // state\n    z.custom<Runtime<unknown>>() // runtime\n  )\n  .returns(z.union([z.string(), z.promise(z.string())]));\n\n/**\n * Function type that dynamically generates a description for a tool call approval request.\n *\n * @param toolCall - The tool call being reviewed\n * @param state - The current agent state\n * @param runtime - The agent runtime context\n * @returns A string description or Promise that resolves to a string description\n *\n * @example\n * ```typescript\n * import { type DescriptionFactory, type ToolCall } from \"langchain\";\n *\n * const descriptionFactory: DescriptionFactory = (toolCall, state, runtime) => {\n *   return `Please review: ${toolCall.name}(${JSON.stringify(toolCall.args)})`;\n * };\n * ```\n */\nexport type DescriptionFactory = z.infer<typeof DescriptionFunctionSchema>;\n\n/**\n * The type of decision a human can make.\n */\nconst ALLOWED_DECISIONS = [\"approve\", \"edit\", \"reject\"] as const;\nconst DecisionType = z.enum(ALLOWED_DECISIONS);\nexport type DecisionType = z.infer<typeof DecisionType>;\n\nconst InterruptOnConfigSchema = z.object({\n  /**\n   * The decisions that are allowed for this action.\n   */\n  allowedDecisions: z.array(DecisionType),\n  /**\n   * The description attached to the request for human input.\n   * Can be either:\n   * - A static string describing the approval request\n   * - A callable that dynamically generates the description based on agent state,\n   *   runtime, and tool call information\n   *\n   * @example\n   * Static string description\n   * ```typescript\n   * import type { InterruptOnConfig } from \"langchain\";\n   *\n   * const config: InterruptOnConfig = {\n   *   allowedDecisions: [\"approve\", \"reject\"],\n   *   description: \"Please review this tool execution\"\n   * };\n   * ```\n   *\n   * @example\n   * Dynamic callable description\n   * ```typescript\n   * import type {\n   *   AgentBuiltInState,\n   *   Runtime,\n   *   DescriptionFactory,\n   *   ToolCall,\n   *   InterruptOnConfig\n   * } from \"langchain\";\n   *\n   * const formatToolDescription: DescriptionFactory = (\n   *   toolCall: ToolCall,\n   *   state: AgentBuiltInState,\n   *   runtime: Runtime<unknown>\n   * ) => {\n   *   return `Tool: ${toolCall.name}\\nArguments:\\n${JSON.stringify(toolCall.args, null, 2)}`;\n   * };\n   *\n   * const config: InterruptOnConfig = {\n   *   allowedDecisions: [\"approve\", \"edit\"],\n   *   description: formatToolDescription\n   * };\n   * ```\n   */\n  description: z.union([z.string(), DescriptionFunctionSchema]).optional(),\n  /**\n   * JSON schema for the arguments associated with the action, if edits are allowed.\n   */\n  argumentsSchema: z.record(z.any()).optional(),\n});\nexport type InterruptOnConfig = z.input<typeof InterruptOnConfigSchema>;\n\n/**\n * Represents an action with a name and arguments.\n */\nexport interface Action {\n  /**\n   * The type or name of action being requested (e.g., \"add_numbers\").\n   */\n  name: string;\n  /**\n   * Key-value pairs of arguments needed for the action (e.g., {\"a\": 1, \"b\": 2}).\n   */\n  arguments: Record<string, any>;\n}\n\n/**\n * Represents an action request with a name, arguments, and description.\n */\nexport interface ActionRequest {\n  /**\n   * The name of the action being requested.\n   */\n  name: string;\n  /**\n   * Key-value pairs of arguments needed for the action (e.g., {\"a\": 1, \"b\": 2}).\n   */\n  arguments: Record<string, any>;\n  /**\n   * The description of the action to be reviewed.\n   */\n  description?: string;\n}\n\n/**\n * Policy for reviewing a HITL request.\n */\nexport interface ReviewConfig {\n  /**\n   * Name of the action associated with this review configuration.\n   */\n  actionName: string;\n  /**\n   * The decisions that are allowed for this request.\n   */\n  allowedDecisions: DecisionType[];\n  /**\n   * JSON schema for the arguments associated with the action, if edits are allowed.\n   */\n  argumentsSchema?: Record<string, any>;\n}\n\n/**\n * Request for human feedback on a sequence of actions requested by a model.\n *\n * @example\n * ```ts\n * const hitlRequest: HITLRequest = {\n *   actionRequests: [\n *     { name: \"send_email\", arguments: { to: \"user@example.com\", subject: \"Hello\" } }\n *   ],\n *   reviewConfigs: [\n *     {\n *       actionName: \"send_email\",\n *       allowedDecisions: [\"approve\", \"edit\", \"reject\"],\n *       description: \"Please review the email before sending\"\n *     }\n *   ]\n * };\n * const response = interrupt(hitlRequest);\n * ```\n */\nexport interface HITLRequest {\n  /**\n   * A list of agent actions for human review.\n   */\n  actionRequests: ActionRequest[];\n  /**\n   * Review configuration for all possible actions.\n   */\n  reviewConfigs: ReviewConfig[];\n}\n\n/**\n * Response when a human approves the action.\n */\nexport interface ApproveDecision {\n  type: \"approve\";\n}\n\n/**\n * Response when a human edits the action.\n */\nexport interface EditDecision {\n  type: \"edit\";\n  /**\n   * Edited action for the agent to perform.\n   * Ex: for a tool call, a human reviewer can edit the tool name and args.\n   */\n  editedAction: Action;\n}\n\n/**\n * Response when a human rejects the action.\n */\nexport interface RejectDecision {\n  type: \"reject\";\n  /**\n   * The message sent to the model explaining why the action was rejected.\n   */\n  message?: string;\n}\n\n/**\n * Union of all possible decision types.\n */\nexport type Decision = ApproveDecision | EditDecision | RejectDecision;\n\n/**\n * Response payload for a HITLRequest.\n */\nexport interface HITLResponse {\n  /**\n   * The decisions made by the human.\n   */\n  decisions: Decision[];\n}\n\nconst contextSchema = z.object({\n  /**\n   * Mapping of tool name to allowed reviewer responses.\n   * If a tool doesn't have an entry, it's auto-approved by default.\n   *\n   * - `true` -> pause for approval and allow approve/edit/reject decisions\n   * - `false` -> auto-approve (no human review)\n   * - `InterruptOnConfig` -> explicitly specify which decisions are allowed for this tool\n   */\n  interruptOn: z\n    .record(z.union([z.boolean(), InterruptOnConfigSchema]))\n    .optional(),\n  /**\n   * Prefix used when constructing human-facing approval messages.\n   * Provides context about the tool call being reviewed; does not change the underlying action.\n   *\n   * Note: This prefix is only applied for tools that do not provide a custom\n   * `description` via their {@link InterruptOnConfig}. If a tool specifies a custom\n   * `description`, that per-tool text is used and this prefix is ignored.\n   */\n  descriptionPrefix: z.string().default(\"Tool execution requires approval\"),\n});\nexport type HumanInTheLoopMiddlewareConfig = InferInteropZodInput<\n  typeof contextSchema\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 * A invocation result that has been interrupted by the middleware will have a `__interrupt__`\n * property that contains the interrupt request.\n *\n * ```ts\n * import { type HITLRequest, type HITLResponse } from \"langchain\";\n * import { type Interrupt } from \"langchain\";\n *\n * const result = await agent.invoke(request);\n * const interruptRequest = result.__interrupt__?.[0] as Interrupt<HITLRequest>;\n *\n * // Examine the action requests and review configs\n * const actionRequests = interruptRequest.value.actionRequests;\n * const reviewConfigs = interruptRequest.value.reviewConfigs;\n *\n * // Create decisions for each action\n * const resume: HITLResponse = {\n *   decisions: actionRequests.map((action, i) => {\n *     if (action.name === \"calculator\") {\n *       return { type: \"approve\" };\n *     } else if (action.name === \"write_file\") {\n *       return {\n *         type: \"edit\",\n *         editedAction: { name: \"write_file\", arguments: { filename: \"safe.txt\", content: \"Safe content\" } }\n *       };\n *     }\n *     return { type: \"reject\", message: \"Action not allowed\" };\n *   })\n * };\n *\n * // Resume with decisions\n * await agent.invoke(new Command({ resume }), config);\n * ```\n *\n * ## Features\n *\n * - **Selective Tool Approval**: Configure which tools require human approval\n * - **Multiple Decision Types**: Approve, edit, or reject 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 * ## Decision Types\n *\n * When a tool requires approval, the human operator can respond with:\n * - `approve`: Execute the tool with original arguments\n * - `edit`: Modify the tool name and/or arguments before execution\n * - `reject`: Provide a manual response instead of executing the tool\n *\n * @param options - Configuration options for the middleware\n * @param options.interruptOn - Per-tool configuration mapping tool names to their settings\n * @param options.interruptOn[toolName].allowedDecisions - Array of decision types allowed for this tool (e.g., [\"approve\", \"edit\", \"reject\"])\n * @param options.interruptOn[toolName].description - Custom approval message for the tool. Can be either a static string or a callable that dynamically generates the description based on agent state, runtime, and tool call information\n * @param options.interruptOn[toolName].argumentsSchema - JSON schema for the arguments associated with the action, if edits are allowed\n * @param options.descriptionPrefix - Default prefix for approval messages (default: \"Tool execution requires approval\"). Only used for tools that do not define a custom `description` in their InterruptOnConfig.\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\";\n * import { createAgent } from \"langchain\";\n *\n * const hitlMiddleware = humanInTheLoopMiddleware({\n *   interruptOn: {\n *     // Interrupt write_file tool and allow edits or approvals\n *     \"write_file\": {\n *       allowedDecisions: [\"approve\", \"edit\"],\n *       description: \"⚠️ File write operation requires approval\"\n *     },\n *     // Auto-approve read_file tool\n *     \"read_file\": false\n *   }\n * });\n *\n * const agent = createAgent({\n *   model: \"openai:gpt-4\",\n *   tools: [writeFileTool, readFileTool],\n *   middleware: [hitlMiddleware]\n * });\n * ```\n *\n * @example\n * Handling approval requests\n * ```typescript\n * import { type HITLRequest, type HITLResponse, type Interrupt } from \"langchain\";\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 * if (result.__interrupt__) {\n *   const interruptRequest = result.__interrupt__?.[0] as Interrupt<HITLRequest>;\n *\n *   // Show tool call details to user\n *   console.log(\"Actions:\", interruptRequest.value.actionRequests);\n *   console.log(\"Review configs:\", interruptRequest.value.reviewConfigs);\n *\n *   // Resume with approval\n *   const resume: HITLResponse = {\n *     decisions: [{ type: \"approve\" }]\n *   };\n *   await agent.invoke(\n *     new Command({ resume }),\n *     config\n *   );\n * }\n * ```\n *\n * @example\n * Different decision types\n * ```typescript\n * import { type HITLResponse } from \"langchain\";\n *\n * // Approve the tool call as-is\n * const resume: HITLResponse = {\n *   decisions: [{ type: \"approve\" }]\n * };\n *\n * // Edit the tool arguments\n * const resume: HITLResponse = {\n *   decisions: [{\n *     type: \"edit\",\n *     editedAction: { name: \"write_file\", arguments: { filename: \"safe.txt\", content: \"Modified\" } }\n *   }]\n * };\n *\n * // Reject with feedback\n * const resume: HITLResponse = {\n *   decisions: [{\n *     type: \"reject\",\n *     message: \"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 *   interruptOn: {\n *     \"execute_sql\": {\n *       allowedDecisions: [\"approve\", \"edit\", \"reject\"],\n *       description: \"🚨 SQL query requires DBA approval\\nPlease review for safety and performance\"\n *     },\n *     \"read_schema\": false,  // Reading metadata is safe\n *     \"delete_records\": {\n *       allowedDecisions: [\"approve\", \"reject\"],\n *       description: \"⛔ DESTRUCTIVE OPERATION - Requires manager approval\"\n *     }\n *   },\n *   descriptionPrefix: \"Database operation pending approval\"\n * });\n * ```\n *\n * @example\n * Using dynamic callable descriptions\n * ```typescript\n * import { type DescriptionFactory, type ToolCall } from \"langchain\";\n * import type { AgentBuiltInState, Runtime } from \"langchain/agents\";\n *\n * // Define a dynamic description factory\n * const formatToolDescription: DescriptionFactory = (\n *   toolCall: ToolCall,\n *   state: AgentBuiltInState,\n *   runtime: Runtime<unknown>\n * ) => {\n *   return `Tool: ${toolCall.name}\\nArguments:\\n${JSON.stringify(toolCall.args, null, 2)}`;\n * };\n *\n * const hitlMiddleware = humanInTheLoopMiddleware({\n *   interruptOn: {\n *     \"write_file\": {\n *       allowedDecisions: [\"approve\", \"edit\"],\n *       // Use dynamic description that can access tool call, state, and runtime\n *       description: formatToolDescription\n *     },\n *     // Or use an inline function\n *     \"send_email\": {\n *       allowedDecisions: [\"approve\", \"reject\"],\n *       description: (toolCall, state, runtime) => {\n *         const { to, subject } = toolCall.args;\n *         return `Email to ${to}\\nSubject: ${subject}\\n\\nRequires approval before sending`;\n *       }\n *     }\n *   }\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 request\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: NonNullable<HumanInTheLoopMiddlewareConfig>\n) {\n  const createActionAndConfig = async (\n    toolCall: ToolCall,\n    config: InterruptOnConfig,\n    state: AgentBuiltInState,\n    runtime: Runtime<unknown>\n  ): Promise<{\n    actionRequest: ActionRequest;\n    reviewConfig: ReviewConfig;\n  }> => {\n    const toolName = toolCall.name;\n    const toolArgs = toolCall.args;\n\n    // Generate description using the description field (str or callable)\n    const descriptionValue = config.description;\n    let description: string;\n    if (typeof descriptionValue === \"function\") {\n      description = await descriptionValue(toolCall, state, runtime);\n    } else if (descriptionValue !== undefined) {\n      description = descriptionValue;\n    } else {\n      description = `${\n        options.descriptionPrefix ?? \"Tool execution requires approval\"\n      }\\n\\nTool: ${toolName}\\nArgs: ${JSON.stringify(toolArgs, null, 2)}`;\n    }\n\n    /**\n     * Create ActionRequest with description\n     */\n    const actionRequest: ActionRequest = {\n      name: toolName,\n      arguments: toolArgs,\n      description,\n    };\n\n    /**\n     * Create ReviewConfig\n     */\n    const reviewConfig: ReviewConfig = {\n      actionName: toolName,\n      allowedDecisions: config.allowedDecisions,\n    };\n\n    if (config.argumentsSchema) {\n      reviewConfig.argumentsSchema = config.argumentsSchema;\n    }\n\n    return { actionRequest, reviewConfig };\n  };\n\n  const processDecision = (\n    decision: Decision,\n    toolCall: ToolCall,\n    config: InterruptOnConfig\n  ): { revisedToolCall: ToolCall | null; toolMessage: ToolMessage | null } => {\n    const allowedDecisions = config.allowedDecisions;\n    if (decision.type === \"approve\" && allowedDecisions.includes(\"approve\")) {\n      return { revisedToolCall: toolCall, toolMessage: null };\n    }\n\n    if (decision.type === \"edit\" && allowedDecisions.includes(\"edit\")) {\n      const editedAction = decision.editedAction;\n\n      /**\n       * Validate edited action structure\n       */\n      if (!editedAction || typeof editedAction.name !== \"string\") {\n        throw new Error(\n          `Invalid edited action for tool \"${toolCall.name}\": name must be a string`\n        );\n      }\n      if (\n        !editedAction.arguments ||\n        typeof editedAction.arguments !== \"object\"\n      ) {\n        throw new Error(\n          `Invalid edited action for tool \"${toolCall.name}\": arguments must be an object`\n        );\n      }\n\n      return {\n        revisedToolCall: {\n          type: \"tool_call\",\n          name: editedAction.name,\n          args: editedAction.arguments,\n          id: toolCall.id,\n        },\n        toolMessage: null,\n      };\n    }\n\n    if (decision.type === \"reject\" && allowedDecisions.includes(\"reject\")) {\n      /**\n       * Validate that message is a string if provided\n       */\n      if (\n        decision.message !== undefined &&\n        typeof decision.message !== \"string\"\n      ) {\n        throw new Error(\n          `Tool call response for \"${\n            toolCall.name\n          }\" must be a string, got ${typeof decision.message}`\n        );\n      }\n\n      // Create a tool message with the human's text response\n      const content =\n        decision.message ??\n        `User rejected the tool call for \\`${toolCall.name}\\` with id ${toolCall.id}`;\n\n      const toolMessage = new ToolMessage({\n        content,\n        name: toolCall.name,\n        tool_call_id: toolCall.id!,\n        status: \"error\",\n      });\n\n      return { revisedToolCall: toolCall, toolMessage };\n    }\n\n    const msg = `Unexpected human decision: ${JSON.stringify(\n      decision\n    )}. Decision type '${decision.type}' is not allowed for tool '${\n      toolCall.name\n    }'. Expected one of ${JSON.stringify(\n      allowedDecisions\n    )} based on the tool's configuration.`;\n    throw new Error(msg);\n  };\n\n  return createMiddleware({\n    name: \"HumanInTheLoopMiddleware\",\n    contextSchema,\n    afterModelJumpTo: [\"model\"],\n    afterModel: async (state, runtime) => {\n      const config = interopParse(contextSchema, {\n        ...options,\n        ...(runtime.context || {}),\n      });\n      if (!config) {\n        return;\n      }\n\n      const { messages } = state;\n      if (!messages.length) {\n        return;\n      }\n\n      /**\n       * Don't do anything if the last message isn't an AI message with tool calls.\n       */\n      const lastMessage = [...messages]\n        .reverse()\n        .find((msg) => AIMessage.isInstance(msg)) as AIMessage;\n      if (!lastMessage || !lastMessage.tool_calls?.length) {\n        return;\n      }\n\n      /**\n       * If the user omits the interruptOn config, we don't do anything.\n       */\n      if (!config.interruptOn) {\n        return;\n      }\n\n      /**\n       * Resolve per-tool configs (boolean true -> all decisions allowed; false -> auto-approve)\n       */\n      const resolvedConfigs: Record<string, InterruptOnConfig> = {};\n      for (const [toolName, toolConfig] of Object.entries(config.interruptOn)) {\n        if (typeof toolConfig === \"boolean\") {\n          if (toolConfig === true) {\n            resolvedConfigs[toolName] = {\n              allowedDecisions: [...ALLOWED_DECISIONS],\n            };\n          }\n        } else if (toolConfig.allowedDecisions) {\n          resolvedConfigs[toolName] = toolConfig as InterruptOnConfig;\n        }\n      }\n\n      const interruptToolCalls: ToolCall[] = [];\n      const autoApprovedToolCalls: ToolCall[] = [];\n\n      for (const toolCall of lastMessage.tool_calls) {\n        if (toolCall.name in resolvedConfigs) {\n          interruptToolCalls.push(toolCall);\n        } else {\n          autoApprovedToolCalls.push(toolCall);\n        }\n      }\n\n      /**\n       * No interrupt tool calls, so we can just return.\n       */\n      if (!interruptToolCalls.length) {\n        return;\n      }\n\n      /**\n       * Create action requests and review configs for all tools that need approval\n       */\n      const actionRequests: ActionRequest[] = [];\n      const reviewConfigs: ReviewConfig[] = [];\n\n      for (const toolCall of interruptToolCalls) {\n        const interruptConfig = resolvedConfigs[toolCall.name]!;\n\n        /**\n         * Create ActionRequest and ReviewConfig using helper method\n         */\n        const { actionRequest, reviewConfig } = await createActionAndConfig(\n          toolCall,\n          interruptConfig,\n          state,\n          runtime\n        );\n        actionRequests.push(actionRequest);\n        reviewConfigs.push(reviewConfig);\n      }\n\n      /**\n       * Create single HITLRequest with all actions and configs\n       */\n      const hitlRequest: HITLRequest = {\n        actionRequests,\n        reviewConfigs,\n      };\n\n      /**\n       * Send interrupt and get response\n       */\n      const hitlResponse = (await interrupt(hitlRequest)) as HITLResponse;\n      const decisions = hitlResponse.decisions;\n\n      /**\n       * Validate that decisions is a valid array before checking length\n       */\n      if (!decisions || !Array.isArray(decisions)) {\n        throw new Error(\n          \"Invalid HITLResponse: decisions must be a non-empty array\"\n        );\n      }\n\n      /**\n       * Validate that the number of decisions matches the number of interrupt tool calls\n       */\n      if (decisions.length !== interruptToolCalls.length) {\n        throw new Error(\n          `Number of human decisions (${decisions.length}) does not match number of hanging tool calls (${interruptToolCalls.length}).`\n        );\n      }\n\n      const revisedToolCalls: ToolCall[] = [...autoApprovedToolCalls];\n      const artificialToolMessages: ToolMessage[] = [];\n\n      /**\n       * Process each decision using helper method\n       */\n      for (let i = 0; i < decisions.length; i++) {\n        const decision = decisions[i]!;\n        const toolCall = interruptToolCalls[i]!;\n        const interruptConfig = resolvedConfigs[toolCall.name]!;\n\n        const { revisedToolCall, toolMessage } = processDecision(\n          decision,\n          toolCall,\n          interruptConfig\n        );\n\n        if (revisedToolCall) {\n          revisedToolCalls.push(revisedToolCall);\n        }\n        if (toolMessage) {\n          artificialToolMessages.push(toolMessage);\n        }\n      }\n\n      /**\n       * Update the AI message to only include approved tool calls\n       */\n      if (AIMessage.isInstance(lastMessage)) {\n        lastMessage.tool_calls = revisedToolCalls;\n      }\n\n      return { messages: [lastMessage, ...artificialToolMessages] };\n    },\n  });\n}\n"],"mappings":"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"}

package/dist/agents/middleware/index.cjs

@@ -0,0 +1,12 @@
+const require_utils = require('./utils.cjs');
+const require_summarization = require('./summarization.cjs');
+const require_hitl = require('./hitl.cjs');
+const require_promptCaching = require('./promptCaching.cjs');
+const require_dynamicSystemPrompt = require('./dynamicSystemPrompt.cjs');
+const require_llmToolSelector = require('./llmToolSelector.cjs');
+const require_piiRedaction = require('./piiRedaction.cjs');
+const require_contextEditing = require('./contextEditing.cjs');
+const require_toolCallLimit = require('./toolCallLimit.cjs');
+const require_todoListMiddleware = require('./todoListMiddleware.cjs');
+const require_callLimit = require('./callLimit.cjs');
+const require_modelFallback = require('./modelFallback.cjs');

package/dist/agents/middleware/index.js

@@ -0,0 +1,12 @@
+import { countTokensApproximately } from "./utils.js";
+import { summarizationMiddleware } from "./summarization.js";
+import { humanInTheLoopMiddleware } from "./hitl.js";
+import { anthropicPromptCachingMiddleware } from "./promptCaching.js";
+import { dynamicSystemPromptMiddleware } from "./dynamicSystemPrompt.js";
+import { llmToolSelectorMiddleware } from "./llmToolSelector.js";
+import { piiRedactionMiddleware } from "./piiRedaction.js";
+import { ClearToolUsesEdit, contextEditingMiddleware } from "./contextEditing.js";
+import { ToolCallLimitExceededError, toolCallLimitMiddleware } from "./toolCallLimit.js";
+import { TODO_LIST_MIDDLEWARE_SYSTEM_PROMPT, todoListMiddleware } from "./todoListMiddleware.js";
+import { modelCallLimitMiddleware } from "./callLimit.js";
+import { modelFallbackMiddleware } from "./modelFallback.js";

package/dist/agents/{middlewareAgent/middleware → middleware}/llmToolSelector.cjs

@@ -1,11 +1,11 @@
-const require_rolldown_runtime = require('../../../_virtual/rolldown_runtime.cjs');
-const require_chat_models_universal = require('../../../chat_models/universal.cjs');
+const require_rolldown_runtime = require('../../_virtual/rolldown_runtime.cjs');
+const require_chat_models_universal = require('../../chat_models/universal.cjs');
 const require_middleware = require('../middleware.cjs');
 const __langchain_core_messages = require_rolldown_runtime.__toESM(require("@langchain/core/messages"));
 const zod_v3 = require_rolldown_runtime.__toESM(require("zod/v3"));
 const __langchain_core_language_models_base = require_rolldown_runtime.__toESM(require("@langchain/core/language_models/base"));
 
-//#region src/agents/middlewareAgent/middleware/llmToolSelector.ts
+//#region src/agents/middleware/llmToolSelector.ts
 const DEFAULT_SYSTEM_PROMPT = "Your goal is to select the most relevant tools for answering the user's query.";
 /**
 * Create a structured output schema for tool selection.
@@ -70,9 +70,9 @@ function llmToolSelectorMiddleware(options) {
 	return require_middleware.createMiddleware({
 		name: "LLMToolSelector",
 		contextSchema: LLMToolSelectorOptionsSchema,
-		async modifyModelRequest(request, _, runtime) {
-			const selectionRequest = await prepareSelectionRequest(request, options, runtime);
-			if (!selectionRequest) return request;
+		async wrapModelCall(request, handler) {
+			const selectionRequest = await prepareSelectionRequest(request, options, request.runtime);
+			if (!selectionRequest) return handler(request);
 			const toolSelectionSchema = createToolSelectionResponse(selectionRequest.availableTools);
 			const structuredModel = await selectionRequest.model.withStructuredOutput?.(toolSelectionSchema);
 			const response = await structuredModel?.invoke([{
@@ -80,7 +80,7 @@ function llmToolSelectorMiddleware(options) {
 				content: selectionRequest.systemMessage
 			}, selectionRequest.lastUserMessage]);
 			if (!response || typeof response !== "object" || !("tools" in response)) throw new Error(`Expected object response with tools array, got ${typeof response}`);
-			return processSelectionResponse(response, selectionRequest.availableTools, selectionRequest.validToolNames, request, options);
+			return handler(processSelectionResponse(response, selectionRequest.availableTools, selectionRequest.validToolNames, request, options));
 		}
 	});
 }