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

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

@@ -1,524 +0,0 @@
-import { AgentMiddleware } from "../types.js";
-import { AIMessage } from "@langchain/core/messages";
-import { InferInteropZodInput } from "@langchain/core/utils/types";
-import { z } from "zod/v3";
-
-//#region src/agents/middlewareAgent/middleware/hitl.d.ts
-declare const ToolConfigSchema: z.ZodObject<{
-  /**
-   * Whether the human can approve the current action without changes
-   */
-  allowAccept: z.ZodOptional<z.ZodBoolean>;
-  /**
-   * Whether the human can reject the current action with feedback
-   */
-  allowEdit: z.ZodOptional<z.ZodBoolean>;
-  /**
-   * Whether the human can approve the current action with edited content
-   */
-  allowRespond: z.ZodOptional<z.ZodBoolean>;
-  /**
-   * The description attached to the request for human input.
-   * Can be either:
-   * - A static string describing the approval request
-   * - A callable that dynamically generates the description based on agent state,
-   *   runtime, and tool call information
-   *
-   * @example
-   * Static string description
-   * ```typescript
-   * const config: ToolConfig = {
-   *   allowAccept: true,
-   *   description: "Please review this tool execution"
-   * };
-   * ```
-   *
-   * @example
-   * Dynamic callable description
-   * ```typescript
-   * const formatToolDescription: DescriptionFactory = (toolCall, state, runtime) => {
-   *   return `Tool: ${toolCall.name}\nArguments:\n${JSON.stringify(toolCall.args, null, 2)}`;
-   * };
-   *
-   * const config: ToolConfig = {
-   *   allowAccept: true,
-   *   description: formatToolDescription
-   * };
-   * ```
-   */
-  description: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodUnknown>]>>;
-}, "strip", z.ZodTypeAny, {
-  allowAccept?: boolean | undefined;
-  allowEdit?: boolean | undefined;
-  allowRespond?: boolean | undefined;
-  description?: string | ((...args: unknown[]) => unknown) | undefined;
-}, {
-  allowAccept?: boolean | undefined;
-  allowEdit?: boolean | undefined;
-  allowRespond?: boolean | undefined;
-  description?: string | ((...args: unknown[]) => unknown) | undefined;
-}>;
-type ToolConfigSchema = z.input<typeof ToolConfigSchema>;
-/**
- * Configuration that defines which reviewer response types are permitted during a human interrupt.
- * These flags control what the human reviewer may do (e.g., accept/edit/respond),
- * not the tool action the agent has requested.
- */
-interface HumanInTheLoopConfig extends Omit<ToolConfigSchema, "description"> {}
-/**
- * Describes the agent-requested tool action (name and arguments).
- * This is what the AI intends to execute, subject to human review.
- */
-interface ActionRequest {
-  /**
-   * The tool/action name requested by the agent (e.g., "send_email").
-   */
-  action: string;
-  /**
-   * Arguments for the requested tool call (e.g., {"a": 1, "b": 2}).
-   */
-  args: Record<string, any>;
-}
-/**
- * Represents an interrupt triggered by the graph that requires human intervention
- * to approve, edit, or respond to an agent-requested tool action.
- *
- * @example
- * ```ts
- * const hitlRequest: HumanInTheLoopRequest = {
- *   actionRequest: { action: "Approve XYZ action", args: { ... } },
- *   config: { allowAccept: true, allowEdit: true, allowRespond: true },
- *   description: "Please review the command before execution"
- * };
- * response = interrupt([request])[0]
- * ```
- */
-interface HumanInTheLoopRequest {
-  /**
-   * The agent-requested tool action to be reviewed.
-   */
-  actionRequest: ActionRequest;
-  /**
-   * Which reviewer responses are allowed (accept/edit/respond).
-   */
-  config: HumanInTheLoopConfig;
-  /**
-   * Optional human-facing description shown in the approval prompt.
-   */
-  description?: string;
-}
-/**
- * Response when a human approves the agent-requested action.
- */
-interface AcceptPayload {
-  type: "accept";
-}
-/**
- * Response when a human provides a manual response instead of executing
- * the agent-requested action.
- */
-interface ResponsePayload {
-  type: "response";
-  args?: string;
-}
-/**
- * Response when a human edits the agent-requested action (tool name and/or args).
- */
-interface EditPayload {
-  type: "edit";
-  args: ActionRequest;
-}
-type HumanInTheLoopMiddlewareHumanResponse = AcceptPayload | ResponsePayload | EditPayload;
-/**
- * Configuration for a tool requiring human in the loop.
- */
-
-declare const contextSchema: z.ZodObject<{
-  /**
-   * Mapping of tool name to allowed reviewer responses.
-   * If a tool doesn't have an entry, it's auto-approved by default.
-   *
-   * - `true` -> pause for approval and allow accept/edit/respond
-   * - `false` -> auto-approve (no human review)
-   * - `ToolConfig` -> explicitly specify which reviewer responses are allowed for this tool
-   */
-  interruptOn: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodBoolean, z.ZodObject<{
-    /**
-     * Whether the human can approve the current action without changes
-     */
-    allowAccept: z.ZodOptional<z.ZodBoolean>;
-    /**
-     * Whether the human can reject the current action with feedback
-     */
-    allowEdit: z.ZodOptional<z.ZodBoolean>;
-    /**
-     * Whether the human can approve the current action with edited content
-     */
-    allowRespond: z.ZodOptional<z.ZodBoolean>;
-    /**
-     * The description attached to the request for human input.
-     * Can be either:
-     * - A static string describing the approval request
-     * - A callable that dynamically generates the description based on agent state,
-     *   runtime, and tool call information
-     *
-     * @example
-     * Static string description
-     * ```typescript
-     * const config: ToolConfig = {
-     *   allowAccept: true,
-     *   description: "Please review this tool execution"
-     * };
-     * ```
-     *
-     * @example
-     * Dynamic callable description
-     * ```typescript
-     * const formatToolDescription: DescriptionFactory = (toolCall, state, runtime) => {
-     *   return `Tool: ${toolCall.name}\nArguments:\n${JSON.stringify(toolCall.args, null, 2)}`;
-     * };
-     *
-     * const config: ToolConfig = {
-     *   allowAccept: true,
-     *   description: formatToolDescription
-     * };
-     * ```
-     */
-    description: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodUnknown>]>>;
-  }, "strip", z.ZodTypeAny, {
-    allowAccept?: boolean | undefined;
-    allowEdit?: boolean | undefined;
-    allowRespond?: boolean | undefined;
-    description?: string | ((...args: unknown[]) => unknown) | undefined;
-  }, {
-    allowAccept?: boolean | undefined;
-    allowEdit?: boolean | undefined;
-    allowRespond?: boolean | undefined;
-    description?: string | ((...args: unknown[]) => unknown) | undefined;
-  }>]>>>;
-  /**
-   * Prefix used when constructing human-facing approval messages.
-   * Provides context about the tool call being reviewed; does not change the underlying action.
-   *
-   * Note: This prefix is only applied for tools that do not provide a custom
-   * `description` via their {@link ToolConfig}. If a tool specifies a custom
-   * `description`, that per-tool text is used and this prefix is ignored.
-   */
-  descriptionPrefix: z.ZodDefault<z.ZodString>;
-}, "strip", z.ZodTypeAny, {
-  interruptOn?: Record<string, boolean | {
-    allowAccept?: boolean | undefined;
-    allowEdit?: boolean | undefined;
-    allowRespond?: boolean | undefined;
-    description?: string | ((...args: unknown[]) => unknown) | undefined;
-  }> | undefined;
-  descriptionPrefix: string;
-}, {
-  interruptOn?: Record<string, boolean | {
-    allowAccept?: boolean | undefined;
-    allowEdit?: boolean | undefined;
-    allowRespond?: boolean | undefined;
-    description?: string | ((...args: unknown[]) => unknown) | undefined;
-  }> | undefined;
-  descriptionPrefix?: string | undefined;
-}>;
-type HumanInTheLoopMiddlewareConfig = InferInteropZodInput<typeof contextSchema>;
-/**
- * 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. You can loop over the request to determine
- * which tools were interrupted, and how to handle them separately.
- *
- * ```ts
- * import { type ToolApprovalRequest, type HumanInTheLoopMiddlewareHumanResponse } from "langchain";
- * import { type Interrupt } from "langchain";
- *
- * const result = await agent.invoke(request);
- * const interruptRequest = initialResult.__interrupt__?.[0] as Interrupt<
- *   ToolApprovalRequest[]
- * >;
- * const resume: HumanInTheLoopMiddlewareHumanResponse[] =
- *   interruptRequest.value.map((request) => {
- *     if (request.action === "calculator") {
- *       return { id: request.toolCallId, type: "accept" };
- *     } else if (request.action === "write_file") {
- *       return {
- *         id: request.toolCallId,
- *         type: "edit",
- *         args: { filename: "safe.txt", content: "Safe content" },
- *       };
- *     }
- *
- *     throw new Error(`Unknown action: ${request.action}`);
- *   });
- *
- * // Resume with approval
- * await agent.invoke(new Command({ resume }), config);
- * ```
- *
- * ## 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.interruptOn - Per-tool configuration mapping tool names to their settings
- * @param options.interruptOn[toolName].allowAccept - Whether the human can approve the current action without changes
- * @param options.interruptOn[toolName].allowEdit - Whether the human can reject the current action with feedback
- * @param options.interruptOn[toolName].allowRespond - Whether the human can approve the current action with edited content
- * @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.messagePrefix - Default prefix for approval messages (default: "Tool execution requires approval"). Only used for tools that do not define a custom `description` in their ToolConfig.
- *
- * @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 accepts
- *     "write_file": {
- *       allowEdit: true,
- *       allowAccept: true,
- *       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 HumanInTheLoopRequest, 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 = initialResult.__interrupt__?.[0] as Interrupt<
- *     HumanInTheLoopRequest[]
- *   >;
- *
- *   // Show tool call details to user
- *   console.log("Tool:", interruptRequest.value[0].actionRequest);
- *   console.log("Allowed actions:", interruptRequest.value[0].config);
- *
- *   // 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: "response" }] })
- *
- * // Provide manual response
- * new Command({
- *   resume: [{
- *     type: "response",
- *     // this must be a string
- *     args: "File operation not allowed in demo mode"
- *   }]
- * })
- * ```
- *
- * @example
- * Production use case with database operations
- * ```typescript
- * const hitlMiddleware = humanInTheLoopMiddleware({
- *   interruptOn: {
- *     "execute_sql": {
- *       allowAccept: true,
- *       allowEdit: true,
- *       allowRespond: true,
- *       description: "🚨 SQL query requires DBA approval\nPlease review for safety and performance"
- *     },
- *     "read_schema": false  // Reading metadata is safe
- *     "delete_records": {
- *       allowAccept: true,
- *       description: "⛔ DESTRUCTIVE OPERATION - Requires manager approval"
- *     }
- *   },
- *   messagePrefix: "Database operation pending approval"
- * });
- * ```
- *
- * @example
- * Using dynamic callable descriptions
- * ```typescript
- * import { type DescriptionFactory } from "langchain";
- *
- * // Define a dynamic description factory
- * const formatToolDescription: DescriptionFactory = (toolCall, state, runtime) => {
- *   return `Tool: ${toolCall.name}\nArguments:\n${JSON.stringify(toolCall.args, null, 2)}`;
- * };
- *
- * const hitlMiddleware = humanInTheLoopMiddleware({
- *   interruptOn: {
- *     "write_file": {
- *       allowAccept: true,
- *       allowEdit: true,
- *       // Use dynamic description that can access tool call, state, and runtime
- *       description: formatToolDescription
- *     },
- *     // Or use an inline function
- *     "send_email": {
- *       allowAccept: true,
- *       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
- * - 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: NonNullable<HumanInTheLoopMiddlewareConfig>): AgentMiddleware<undefined, z.ZodObject<{
-  /**
-   * Mapping of tool name to allowed reviewer responses.
-   * If a tool doesn't have an entry, it's auto-approved by default.
-   *
-   * - `true` -> pause for approval and allow accept/edit/respond
-   * - `false` -> auto-approve (no human review)
-   * - `ToolConfig` -> explicitly specify which reviewer responses are allowed for this tool
-   */
-  interruptOn: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodBoolean, z.ZodObject<{
-    /**
-     * Whether the human can approve the current action without changes
-     */
-    allowAccept: z.ZodOptional<z.ZodBoolean>;
-    /**
-     * Whether the human can reject the current action with feedback
-     */
-    allowEdit: z.ZodOptional<z.ZodBoolean>;
-    /**
-     * Whether the human can approve the current action with edited content
-     */
-    allowRespond: z.ZodOptional<z.ZodBoolean>;
-    /**
-     * The description attached to the request for human input.
-     * Can be either:
-     * - A static string describing the approval request
-     * - A callable that dynamically generates the description based on agent state,
-     *   runtime, and tool call information
-     *
-     * @example
-     * Static string description
-     * ```typescript
-     * const config: ToolConfig = {
-     *   allowAccept: true,
-     *   description: "Please review this tool execution"
-     * };
-     * ```
-     *
-     * @example
-     * Dynamic callable description
-     * ```typescript
-     * const formatToolDescription: DescriptionFactory = (toolCall, state, runtime) => {
-     *   return `Tool: ${toolCall.name}\nArguments:\n${JSON.stringify(toolCall.args, null, 2)}`;
-     * };
-     *
-     * const config: ToolConfig = {
-     *   allowAccept: true,
-     *   description: formatToolDescription
-     * };
-     * ```
-     */
-    description: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodUnknown>]>>;
-  }, "strip", z.ZodTypeAny, {
-    allowAccept?: boolean | undefined;
-    allowEdit?: boolean | undefined;
-    allowRespond?: boolean | undefined;
-    description?: string | ((...args: unknown[]) => unknown) | undefined;
-  }, {
-    allowAccept?: boolean | undefined;
-    allowEdit?: boolean | undefined;
-    allowRespond?: boolean | undefined;
-    description?: string | ((...args: unknown[]) => unknown) | undefined;
-  }>]>>>;
-  /**
-   * Prefix used when constructing human-facing approval messages.
-   * Provides context about the tool call being reviewed; does not change the underlying action.
-   *
-   * Note: This prefix is only applied for tools that do not provide a custom
-   * `description` via their {@link ToolConfig}. If a tool specifies a custom
-   * `description`, that per-tool text is used and this prefix is ignored.
-   */
-  descriptionPrefix: z.ZodDefault<z.ZodString>;
-}, "strip", z.ZodTypeAny, {
-  interruptOn?: Record<string, boolean | {
-    allowAccept?: boolean | undefined;
-    allowEdit?: boolean | undefined;
-    allowRespond?: boolean | undefined;
-    description?: string | ((...args: unknown[]) => unknown) | undefined;
-  }> | undefined;
-  descriptionPrefix: string;
-}, {
-  interruptOn?: Record<string, boolean | {
-    allowAccept?: boolean | undefined;
-    allowEdit?: boolean | undefined;
-    allowRespond?: boolean | undefined;
-    description?: string | ((...args: unknown[]) => unknown) | undefined;
-  }> | undefined;
-  descriptionPrefix?: string | undefined;
-}>, any>;
-//#endregion
-export { ActionRequest, HumanInTheLoopMiddlewareConfig, HumanInTheLoopMiddlewareHumanResponse, HumanInTheLoopRequest, humanInTheLoopMiddleware };
-//# sourceMappingURL=hitl.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"hitl.d.ts","names":["z","AIMessage","InferInteropZodInput","AgentBuiltInState","Runtime","ToolConfigSchema","ZodBoolean","ZodOptional","ZodString","ZodUnknown","ZodTuple","ZodFunction","ZodUnion","ZodTypeAny","ZodObject","input","ToolCall","NonNullable","DescriptionFactory","State","Promise","HumanInTheLoopConfig","Omit","ActionRequest","Record","HumanInTheLoopRequest","AcceptPayload","ResponsePayload","EditPayload","HumanInTheLoopMiddlewareHumanResponse","ToolConfig","contextSchema","ZodRecord","ZodDefault","HumanInTheLoopMiddlewareConfig","humanInTheLoopMiddleware","__index_js2","AgentMiddleware"],"sources":["../../../../src/agents/middlewareAgent/middleware/hitl.d.ts"],"sourcesContent":["/* eslint-disable @typescript-eslint/no-explicit-any */\nimport { z } from \"zod/v3\";\nimport { AIMessage } from \"@langchain/core/messages\";\nimport { InferInteropZodInput } from \"@langchain/core/utils/types\";\nimport type { AgentBuiltInState, Runtime } from \"../types.js\";\ndeclare const ToolConfigSchema: z.ZodObject<{\n    /**\n     * Whether the human can approve the current action without changes\n     */\n    allowAccept: z.ZodOptional<z.ZodBoolean>;\n    /**\n     * Whether the human can reject the current action with feedback\n     */\n    allowEdit: z.ZodOptional<z.ZodBoolean>;\n    /**\n     * Whether the human can approve the current action with edited content\n     */\n    allowRespond: z.ZodOptional<z.ZodBoolean>;\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     * const config: ToolConfig = {\n     *   allowAccept: true,\n     *   description: \"Please review this tool execution\"\n     * };\n     * ```\n     *\n     * @example\n     * Dynamic callable description\n     * ```typescript\n     * const formatToolDescription: DescriptionFactory = (toolCall, state, runtime) => {\n     *   return `Tool: ${toolCall.name}\\nArguments:\\n${JSON.stringify(toolCall.args, null, 2)}`;\n     * };\n     *\n     * const config: ToolConfig = {\n     *   allowAccept: true,\n     *   description: formatToolDescription\n     * };\n     * ```\n     */\n    description: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodUnknown>]>>;\n}, \"strip\", z.ZodTypeAny, {\n    allowAccept?: boolean | undefined;\n    allowEdit?: boolean | undefined;\n    allowRespond?: boolean | undefined;\n    description?: string | ((...args: unknown[]) => unknown) | undefined;\n}, {\n    allowAccept?: boolean | undefined;\n    allowEdit?: boolean | undefined;\n    allowRespond?: boolean | undefined;\n    description?: string | ((...args: unknown[]) => unknown) | undefined;\n}>;\ntype ToolConfigSchema = z.input<typeof ToolConfigSchema>;\ntype ToolCall = NonNullable<AIMessage[\"tool_calls\"]>[number];\n/**\n * Function type that dynamically generates a description based on agent state,\n * runtime, and tool call information.\n */\nexport type DescriptionFactory<State extends AgentBuiltInState = AgentBuiltInState> = (toolCall: ToolCall, state: State, runtime: Runtime<unknown>) => string | Promise<string>;\n/**\n * Configuration that defines which reviewer response types are permitted during a human interrupt.\n * These flags control what the human reviewer may do (e.g., accept/edit/respond),\n * not the tool action the agent has requested.\n */\nexport interface HumanInTheLoopConfig extends Omit<ToolConfigSchema, \"description\"> {\n}\n/**\n * Describes the agent-requested tool action (name and arguments).\n * This is what the AI intends to execute, subject to human review.\n */\nexport interface ActionRequest {\n    /**\n     * The tool/action name requested by the agent (e.g., \"send_email\").\n     */\n    action: string;\n    /**\n     * Arguments for the requested tool call (e.g., {\"a\": 1, \"b\": 2}).\n     */\n    args: Record<string, any>;\n}\n/**\n * Represents an interrupt triggered by the graph that requires human intervention\n * to approve, edit, or respond to an agent-requested tool action.\n *\n * @example\n * ```ts\n * const hitlRequest: HumanInTheLoopRequest = {\n *   actionRequest: { action: \"Approve XYZ action\", args: { ... } },\n *   config: { allowAccept: true, allowEdit: true, allowRespond: true },\n *   description: \"Please review the command before execution\"\n * };\n * response = interrupt([request])[0]\n * ```\n */\nexport interface HumanInTheLoopRequest {\n    /**\n     * The agent-requested tool action to be reviewed.\n     */\n    actionRequest: ActionRequest;\n    /**\n     * Which reviewer responses are allowed (accept/edit/respond).\n     */\n    config: HumanInTheLoopConfig;\n    /**\n     * Optional human-facing description shown in the approval prompt.\n     */\n    description?: string;\n}\n/**\n * Response when a human approves the agent-requested action.\n */\nexport interface AcceptPayload {\n    type: \"accept\";\n}\n/**\n * Response when a human provides a manual response instead of executing\n * the agent-requested action.\n */\nexport interface ResponsePayload {\n    type: \"response\";\n    args?: string;\n}\n/**\n * Response when a human edits the agent-requested action (tool name and/or args).\n */\nexport interface EditPayload {\n    type: \"edit\";\n    args: ActionRequest;\n}\nexport type HumanInTheLoopMiddlewareHumanResponse = AcceptPayload | ResponsePayload | EditPayload;\n/**\n * Configuration for a tool requiring human in the loop.\n */\nexport interface ToolConfig extends HumanInTheLoopConfig {\n    /**\n     * Human-facing description shown in the approval request.\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    description?: string | DescriptionFactory;\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 accept/edit/respond\n     * - `false` -> auto-approve (no human review)\n     * - `ToolConfig` -> explicitly specify which reviewer responses are allowed for this tool\n     */\n    interruptOn: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodBoolean, z.ZodObject<{\n        /**\n         * Whether the human can approve the current action without changes\n         */\n        allowAccept: z.ZodOptional<z.ZodBoolean>;\n        /**\n         * Whether the human can reject the current action with feedback\n         */\n        allowEdit: z.ZodOptional<z.ZodBoolean>;\n        /**\n         * Whether the human can approve the current action with edited content\n         */\n        allowRespond: z.ZodOptional<z.ZodBoolean>;\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         * const config: ToolConfig = {\n         *   allowAccept: true,\n         *   description: \"Please review this tool execution\"\n         * };\n         * ```\n         *\n         * @example\n         * Dynamic callable description\n         * ```typescript\n         * const formatToolDescription: DescriptionFactory = (toolCall, state, runtime) => {\n         *   return `Tool: ${toolCall.name}\\nArguments:\\n${JSON.stringify(toolCall.args, null, 2)}`;\n         * };\n         *\n         * const config: ToolConfig = {\n         *   allowAccept: true,\n         *   description: formatToolDescription\n         * };\n         * ```\n         */\n        description: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodUnknown>]>>;\n    }, \"strip\", z.ZodTypeAny, {\n        allowAccept?: boolean | undefined;\n        allowEdit?: boolean | undefined;\n        allowRespond?: boolean | undefined;\n        description?: string | ((...args: unknown[]) => unknown) | undefined;\n    }, {\n        allowAccept?: boolean | undefined;\n        allowEdit?: boolean | undefined;\n        allowRespond?: boolean | undefined;\n        description?: string | ((...args: unknown[]) => unknown) | 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 ToolConfig}. 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        allowAccept?: boolean | undefined;\n        allowEdit?: boolean | undefined;\n        allowRespond?: boolean | undefined;\n        description?: string | ((...args: unknown[]) => unknown) | undefined;\n    }> | undefined;\n    descriptionPrefix: string;\n}, {\n    interruptOn?: Record<string, boolean | {\n        allowAccept?: boolean | undefined;\n        allowEdit?: boolean | undefined;\n        allowRespond?: boolean | undefined;\n        description?: string | ((...args: unknown[]) => unknown) | 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. You can loop over the request to determine\n * which tools were interrupted, and how to handle them separately.\n *\n * ```ts\n * import { type ToolApprovalRequest, type HumanInTheLoopMiddlewareHumanResponse } from \"langchain\";\n * import { type Interrupt } from \"langchain\";\n *\n * const result = await agent.invoke(request);\n * const interruptRequest = initialResult.__interrupt__?.[0] as Interrupt<\n *   ToolApprovalRequest[]\n * >;\n * const resume: HumanInTheLoopMiddlewareHumanResponse[] =\n *   interruptRequest.value.map((request) => {\n *     if (request.action === \"calculator\") {\n *       return { id: request.toolCallId, type: \"accept\" };\n *     } else if (request.action === \"write_file\") {\n *       return {\n *         id: request.toolCallId,\n *         type: \"edit\",\n *         args: { filename: \"safe.txt\", content: \"Safe content\" },\n *       };\n *     }\n *\n *     throw new Error(`Unknown action: ${request.action}`);\n *   });\n *\n * // Resume with approval\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 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.interruptOn - Per-tool configuration mapping tool names to their settings\n * @param options.interruptOn[toolName].allowAccept - Whether the human can approve the current action without changes\n * @param options.interruptOn[toolName].allowEdit - Whether the human can reject the current action with feedback\n * @param options.interruptOn[toolName].allowRespond - Whether the human can approve the current action with edited content\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.messagePrefix - Default prefix for approval messages (default: \"Tool execution requires approval\"). Only used for tools that do not define a custom `description` in their ToolConfig.\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 accepts\n *     \"write_file\": {\n *       allowEdit: true,\n *       allowAccept: true,\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 HumanInTheLoopRequest, 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 = initialResult.__interrupt__?.[0] as Interrupt<\n *     HumanInTheLoopRequest[]\n *   >;\n *\n *   // Show tool call details to user\n *   console.log(\"Tool:\", interruptRequest.value[0].actionRequest);\n *   console.log(\"Allowed actions:\", interruptRequest.value[0].config);\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: \"response\" }] })\n *\n * // Provide manual response\n * new Command({\n *   resume: [{\n *     type: \"response\",\n *     // this must be a string\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 *   interruptOn: {\n *     \"execute_sql\": {\n *       allowAccept: true,\n *       allowEdit: true,\n *       allowRespond: true,\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 *       allowAccept: true,\n *       description: \"⛔ DESTRUCTIVE OPERATION - Requires manager approval\"\n *     }\n *   },\n *   messagePrefix: \"Database operation pending approval\"\n * });\n * ```\n *\n * @example\n * Using dynamic callable descriptions\n * ```typescript\n * import { type DescriptionFactory } from \"langchain\";\n *\n * // Define a dynamic description factory\n * const formatToolDescription: DescriptionFactory = (toolCall, state, runtime) => {\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 *       allowAccept: true,\n *       allowEdit: true,\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 *       allowAccept: true,\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\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(\"./index.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 accept/edit/respond\n     * - `false` -> auto-approve (no human review)\n     * - `ToolConfig` -> explicitly specify which reviewer responses are allowed for this tool\n     */\n    interruptOn: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodBoolean, z.ZodObject<{\n        /**\n         * Whether the human can approve the current action without changes\n         */\n        allowAccept: z.ZodOptional<z.ZodBoolean>;\n        /**\n         * Whether the human can reject the current action with feedback\n         */\n        allowEdit: z.ZodOptional<z.ZodBoolean>;\n        /**\n         * Whether the human can approve the current action with edited content\n         */\n        allowRespond: z.ZodOptional<z.ZodBoolean>;\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         * const config: ToolConfig = {\n         *   allowAccept: true,\n         *   description: \"Please review this tool execution\"\n         * };\n         * ```\n         *\n         * @example\n         * Dynamic callable description\n         * ```typescript\n         * const formatToolDescription: DescriptionFactory = (toolCall, state, runtime) => {\n         *   return `Tool: ${toolCall.name}\\nArguments:\\n${JSON.stringify(toolCall.args, null, 2)}`;\n         * };\n         *\n         * const config: ToolConfig = {\n         *   allowAccept: true,\n         *   description: formatToolDescription\n         * };\n         * ```\n         */\n        description: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodUnknown>]>>;\n    }, \"strip\", z.ZodTypeAny, {\n        allowAccept?: boolean | undefined;\n        allowEdit?: boolean | undefined;\n        allowRespond?: boolean | undefined;\n        description?: string | ((...args: unknown[]) => unknown) | undefined;\n    }, {\n        allowAccept?: boolean | undefined;\n        allowEdit?: boolean | undefined;\n        allowRespond?: boolean | undefined;\n        description?: string | ((...args: unknown[]) => unknown) | 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 ToolConfig}. 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        allowAccept?: boolean | undefined;\n        allowEdit?: boolean | undefined;\n        allowRespond?: boolean | undefined;\n        description?: string | ((...args: unknown[]) => unknown) | undefined;\n    }> | undefined;\n    descriptionPrefix: string;\n}, {\n    interruptOn?: Record<string, boolean | {\n        allowAccept?: boolean | undefined;\n        allowEdit?: boolean | undefined;\n        allowRespond?: boolean | undefined;\n        description?: string | ((...args: unknown[]) => unknown) | undefined;\n    }> | undefined;\n    descriptionPrefix?: string | undefined;\n}>, any>;\nexport {};\n"],"mappings":"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"}