@illuma-ai/agents 1.1.19 → 1.1.21

package/dist/esm/common/enum.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"enum.mjs","sources":["../../../src/common/enum.ts"],"sourcesContent":["/**\n * Enum representing the various event types emitted during the execution of runnables.\n * These events provide real-time information about the progress and state of different components.\n *\n * @enum {string}\n */\nexport enum GraphEvents {\n  /* Custom Events */\n\n  /** [Custom] Agent update event in multi-agent graph/workflow */\n  ON_AGENT_UPDATE = 'on_agent_update',\n  /** [Custom] Delta event for run steps (message creation and tool calls) */\n  ON_RUN_STEP = 'on_run_step',\n  /** [Custom] Delta event for run steps (tool calls) */\n  ON_RUN_STEP_DELTA = 'on_run_step_delta',\n  /** [Custom] Completed event for run steps (tool calls) */\n  ON_RUN_STEP_COMPLETED = 'on_run_step_completed',\n  /** [Custom] Delta events for messages */\n  ON_MESSAGE_DELTA = 'on_message_delta',\n  /** [Custom] Reasoning Delta events for messages */\n  ON_REASONING_DELTA = 'on_reasoning_delta',\n  /** [Custom] Context analytics event for traces */\n  ON_CONTEXT_ANALYTICS = 'on_context_analytics',\n  /** [Custom] Structured output event - emitted when agent returns structured JSON */\n  ON_STRUCTURED_OUTPUT = 'on_structured_output',\n  /** [Custom] Request to execute tools - dispatched by ToolNode, handled by host */\n  ON_TOOL_EXECUTE = 'on_tool_execute',\n  /** [Custom] Context pressure event for monitoring compaction triggers */\n  ON_CONTEXT_PRESSURE = 'on_context_pressure',\n  /** [Custom] Tool requires human approval before execution - dispatched by ToolNode HITL */\n  ON_TOOL_APPROVAL_REQUIRED = 'on_tool_approval_required',\n  /** [Custom] Agent transition event — dispatched when control passes between agents */\n  ON_AGENT_TRANSITION = 'on_agent_transition',\n\n  /* Official Events */\n\n  /** Custom event, emitted by system */\n  ON_CUSTOM_EVENT = 'on_custom_event',\n  /** Emitted when a chat model starts processing. */\n  CHAT_MODEL_START = 'on_chat_model_start',\n\n  /** Emitted when a chat model streams a chunk of its response. */\n  CHAT_MODEL_STREAM = 'on_chat_model_stream',\n\n  /** Emitted when a chat model completes its processing. */\n  CHAT_MODEL_END = 'on_chat_model_end',\n\n  /** Emitted when a language model starts processing. */\n  LLM_START = 'on_llm_start',\n\n  /** Emitted when a language model streams a chunk of its response. */\n  LLM_STREAM = 'on_llm_stream',\n\n  /** Emitted when a language model completes its processing. */\n  LLM_END = 'on_llm_end',\n\n  /** Emitted when a chain starts processing. */\n  CHAIN_START = 'on_chain_start',\n\n  /** Emitted when a chain streams a chunk of its output. */\n  CHAIN_STREAM = 'on_chain_stream',\n\n  /** Emitted when a chain completes its processing. */\n  CHAIN_END = 'on_chain_end',\n\n  /** Emitted when a tool starts its operation. */\n  TOOL_START = 'on_tool_start',\n\n  /** Emitted when a tool completes its operation. */\n  TOOL_END = 'on_tool_end',\n\n  /** Emitted when a retriever starts its operation. */\n  RETRIEVER_START = 'on_retriever_start',\n\n  /** Emitted when a retriever completes its operation. */\n  RETRIEVER_END = 'on_retriever_end',\n\n  /** Emitted when a prompt starts processing. */\n  PROMPT_START = 'on_prompt_start',\n\n  /** Emitted when a prompt completes its processing. */\n  PROMPT_END = 'on_prompt_end',\n}\n\nexport enum Providers {\n  OPENAI = 'openAI',\n  VERTEXAI = 'vertexai',\n  BEDROCK = 'bedrock',\n  ANTHROPIC = 'anthropic',\n  MISTRALAI = 'mistralai',\n  MISTRAL = 'mistral',\n  GOOGLE = 'google',\n  AZURE = 'azureOpenAI',\n  DEEPSEEK = 'deepseek',\n  OPENROUTER = 'openrouter',\n  XAI = 'xai',\n  MOONSHOT = 'moonshot',\n}\n\nexport enum EdgeType {\n  /** True agent handoff — parent calls child agent inline, gets result back, continues orchestrating */\n  HANDOFF = 'handoff',\n  /** One-way transfer — parent exits, child takes over and responds directly to user */\n  TRANSFER = 'transfer',\n  /** Fixed graph edges for automatic sequential/parallel transitions */\n  SEQUENCE = 'sequence',\n}\n\nexport enum GraphNodeKeys {\n  TOOLS = 'tools=',\n  AGENT = 'agent=',\n  ROUTER = 'router',\n  PRE_TOOLS = 'pre_tools',\n  POST_TOOLS = 'post_tools',\n}\n\nexport enum GraphNodeActions {\n  TOOL_NODE = 'tool_node',\n  CALL_MODEL = 'call_model',\n  ROUTE_MESSAGE = 'route_message',\n}\n\nexport enum CommonEvents {\n  LANGGRAPH = 'LangGraph',\n}\n\nexport enum StepTypes {\n  TOOL_CALLS = 'tool_calls',\n  MESSAGE_CREATION = 'message_creation',\n}\n\nexport enum ContentTypes {\n  TEXT = 'text',\n  ERROR = 'error',\n  THINK = 'think',\n  TOOL_CALL = 'tool_call',\n  IMAGE_URL = 'image_url',\n  IMAGE_FILE = 'image_file',\n  /** Anthropic */\n  THINKING = 'thinking',\n  /** Vertex AI / Google Common */\n  REASONING = 'reasoning',\n  /** Multi-Agent Switch */\n  AGENT_UPDATE = 'agent_update',\n  /** Bedrock */\n  REASONING_CONTENT = 'reasoning_content',\n}\n\nexport enum ToolCallTypes {\n  FUNCTION = 'function',\n  RETRIEVAL = 'retrieval',\n  FILE_SEARCH = 'file_search',\n  CODE_INTERPRETER = 'code_interpreter',\n  /* Agents Tool Call */\n  TOOL_CALL = 'tool_call',\n}\n\nexport enum Callback {\n  TOOL_ERROR = 'handleToolError',\n  TOOL_START = 'handleToolStart',\n  TOOL_END = 'handleToolEnd',\n  CUSTOM_EVENT = 'handleCustomEvent',\n  /*\n  LLM_START = 'handleLLMStart',\n  LLM_NEW_TOKEN = 'handleLLMNewToken',\n  LLM_ERROR = 'handleLLMError',\n  LLM_END = 'handleLLMEnd',\n  CHAT_MODEL_START = 'handleChatModelStart',\n  CHAIN_START = 'handleChainStart',\n  CHAIN_ERROR = 'handleChainError',\n  CHAIN_END = 'handleChainEnd',\n  TEXT = 'handleText',\n  AGENT_ACTION = 'handleAgentAction',\n  AGENT_END = 'handleAgentEnd',\n  RETRIEVER_START = 'handleRetrieverStart',\n  RETRIEVER_END = 'handleRetrieverEnd',\n  RETRIEVER_ERROR = 'handleRetrieverError',\n  */\n}\n\nexport enum Constants {\n  OFFICIAL_CODE_BASEURL = 'https://api.illuma.ai/v1',\n  EXECUTE_CODE = 'execute_code',\n  TOOL_SEARCH = 'tool_search',\n  PROGRAMMATIC_TOOL_CALLING = 'run_tools_with_code',\n  WEB_SEARCH = 'web_search',\n  CONTENT_AND_ARTIFACT = 'content_and_artifact',\n  LC_TRANSFER_TO_ = 'lc_transfer_to_',\n  /** Prefix for handoff tool names: lc_handoff_to_{agentId} */\n  LC_HANDOFF_TO_ = 'lc_handoff_to_',\n  /** Tool name for the AskUser structured question tool */\n  ASK_USER = 'ask_user',\n  /** Delimiter for MCP tools: toolName_mcp_serverName */\n  MCP_DELIMITER = '_mcp_',\n}\n\nexport enum TitleMethod {\n  STRUCTURED = 'structured',\n  FUNCTIONS = 'functions',\n  COMPLETION = 'completion',\n}\n\nexport enum EnvVar {\n  CODE_API_KEY = 'CODE_EXECUTOR_API_KEY',\n  CODE_BASEURL = 'CODE_EXECUTOR_BASEURL',\n}\n\n/**\n * Normalized LLM finish/stop reasons across providers.\n * Used by toolCallContinuation to detect max_tokens truncation.\n */\nexport enum FinishReasons {\n  /** Anthropic / Bedrock stop reason for token limit */\n  MAX_TOKENS = 'max_tokens',\n  /** OpenAI / Azure finish reason for token limit */\n  LENGTH = 'length',\n  /** Normal completion */\n  STOP = 'stop',\n  /** Anthropic / Bedrock stop reason for normal completion */\n  END_TURN = 'end_turn',\n  /** Model chose to call tools */\n  TOOL_USE = 'tool_use',\n  /** OpenAI finish reason for tool calls */\n  TOOL_CALLS = 'tool_calls',\n}\n\n/**\n * Message type identifiers used by LangChain's BaseMessage.getType().\n * Use these constants instead of instanceof checks to avoid module mismatch issues\n * when different copies of @langchain/core/messages are loaded.\n */\nexport enum MessageTypes {\n  HUMAN = 'human',\n  AI = 'ai',\n  SYSTEM = 'system',\n  TOOL = 'tool',\n  FUNCTION = 'function',\n  GENERIC = 'generic',\n  DEVELOPER = 'developer',\n  REMOVE = 'remove',\n}\n\n/** Default max characters for handoff results returned to parent (~8192 tokens at ~4 chars/token) */\nexport const DEFAULT_HANDOFF_MAX_RESULT_CHARS = 32768;\n\n/** Default timeout for handoff sub-agent execution in milliseconds (5 minutes) */\nexport const HANDOFF_TIMEOUT_MS = 300_000;\n"],"names":[],"mappings":"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"}
+{"version":3,"file":"enum.mjs","sources":["../../../src/common/enum.ts"],"sourcesContent":["/**\n * Enum representing the various event types emitted during the execution of runnables.\n * These events provide real-time information about the progress and state of different components.\n *\n * @enum {string}\n */\nexport enum GraphEvents {\n  /* Custom Events */\n\n  /** [Custom] Agent update event in multi-agent graph/workflow */\n  ON_AGENT_UPDATE = 'on_agent_update',\n  /** [Custom] Delta event for run steps (message creation and tool calls) */\n  ON_RUN_STEP = 'on_run_step',\n  /** [Custom] Delta event for run steps (tool calls) */\n  ON_RUN_STEP_DELTA = 'on_run_step_delta',\n  /** [Custom] Completed event for run steps (tool calls) */\n  ON_RUN_STEP_COMPLETED = 'on_run_step_completed',\n  /** [Custom] Delta events for messages */\n  ON_MESSAGE_DELTA = 'on_message_delta',\n  /** [Custom] Reasoning Delta events for messages */\n  ON_REASONING_DELTA = 'on_reasoning_delta',\n  /** [Custom] Context analytics event for traces */\n  ON_CONTEXT_ANALYTICS = 'on_context_analytics',\n  /** [Custom] Structured output event - emitted when agent returns structured JSON */\n  ON_STRUCTURED_OUTPUT = 'on_structured_output',\n  /** [Custom] Request to execute tools - dispatched by ToolNode, handled by host */\n  ON_TOOL_EXECUTE = 'on_tool_execute',\n  /** [Custom] Context pressure event for monitoring compaction triggers */\n  ON_CONTEXT_PRESSURE = 'on_context_pressure',\n  /** [Custom] Tool requires human approval before execution - dispatched by ToolNode HITL */\n  ON_TOOL_APPROVAL_REQUIRED = 'on_tool_approval_required',\n  /** [Custom] Agent transition event — dispatched when control passes between agents */\n  ON_AGENT_TRANSITION = 'on_agent_transition',\n  /** [Custom] Approval gate interrupt — dispatched by ApprovalGateNode before interrupt() */\n  ON_APPROVAL_GATE = 'on_approval_gate',\n\n  /* Official Events */\n\n  /** Custom event, emitted by system */\n  ON_CUSTOM_EVENT = 'on_custom_event',\n  /** Emitted when a chat model starts processing. */\n  CHAT_MODEL_START = 'on_chat_model_start',\n\n  /** Emitted when a chat model streams a chunk of its response. */\n  CHAT_MODEL_STREAM = 'on_chat_model_stream',\n\n  /** Emitted when a chat model completes its processing. */\n  CHAT_MODEL_END = 'on_chat_model_end',\n\n  /** Emitted when a language model starts processing. */\n  LLM_START = 'on_llm_start',\n\n  /** Emitted when a language model streams a chunk of its response. */\n  LLM_STREAM = 'on_llm_stream',\n\n  /** Emitted when a language model completes its processing. */\n  LLM_END = 'on_llm_end',\n\n  /** Emitted when a chain starts processing. */\n  CHAIN_START = 'on_chain_start',\n\n  /** Emitted when a chain streams a chunk of its output. */\n  CHAIN_STREAM = 'on_chain_stream',\n\n  /** Emitted when a chain completes its processing. */\n  CHAIN_END = 'on_chain_end',\n\n  /** Emitted when a tool starts its operation. */\n  TOOL_START = 'on_tool_start',\n\n  /** Emitted when a tool completes its operation. */\n  TOOL_END = 'on_tool_end',\n\n  /** Emitted when a retriever starts its operation. */\n  RETRIEVER_START = 'on_retriever_start',\n\n  /** Emitted when a retriever completes its operation. */\n  RETRIEVER_END = 'on_retriever_end',\n\n  /** Emitted when a prompt starts processing. */\n  PROMPT_START = 'on_prompt_start',\n\n  /** Emitted when a prompt completes its processing. */\n  PROMPT_END = 'on_prompt_end',\n}\n\nexport enum Providers {\n  OPENAI = 'openAI',\n  VERTEXAI = 'vertexai',\n  BEDROCK = 'bedrock',\n  ANTHROPIC = 'anthropic',\n  MISTRALAI = 'mistralai',\n  MISTRAL = 'mistral',\n  GOOGLE = 'google',\n  AZURE = 'azureOpenAI',\n  DEEPSEEK = 'deepseek',\n  OPENROUTER = 'openrouter',\n  XAI = 'xai',\n  MOONSHOT = 'moonshot',\n}\n\nexport enum EdgeType {\n  /** True agent handoff — parent calls child agent inline, gets result back, continues orchestrating */\n  HANDOFF = 'handoff',\n  /** One-way transfer — parent exits, child takes over and responds directly to user */\n  TRANSFER = 'transfer',\n  /** Fixed graph edges for automatic sequential/parallel transitions */\n  SEQUENCE = 'sequence',\n}\n\nexport enum GraphNodeKeys {\n  TOOLS = 'tools=',\n  AGENT = 'agent=',\n  ROUTER = 'router',\n  PRE_TOOLS = 'pre_tools',\n  POST_TOOLS = 'post_tools',\n}\n\nexport enum GraphNodeActions {\n  TOOL_NODE = 'tool_node',\n  CALL_MODEL = 'call_model',\n  ROUTE_MESSAGE = 'route_message',\n}\n\nexport enum CommonEvents {\n  LANGGRAPH = 'LangGraph',\n}\n\nexport enum StepTypes {\n  TOOL_CALLS = 'tool_calls',\n  MESSAGE_CREATION = 'message_creation',\n}\n\nexport enum ContentTypes {\n  TEXT = 'text',\n  ERROR = 'error',\n  THINK = 'think',\n  TOOL_CALL = 'tool_call',\n  IMAGE_URL = 'image_url',\n  IMAGE_FILE = 'image_file',\n  /** Anthropic */\n  THINKING = 'thinking',\n  /** Vertex AI / Google Common */\n  REASONING = 'reasoning',\n  /** Multi-Agent Switch */\n  AGENT_UPDATE = 'agent_update',\n  /** Bedrock */\n  REASONING_CONTENT = 'reasoning_content',\n}\n\nexport enum ToolCallTypes {\n  FUNCTION = 'function',\n  RETRIEVAL = 'retrieval',\n  FILE_SEARCH = 'file_search',\n  CODE_INTERPRETER = 'code_interpreter',\n  /* Agents Tool Call */\n  TOOL_CALL = 'tool_call',\n}\n\nexport enum Callback {\n  TOOL_ERROR = 'handleToolError',\n  TOOL_START = 'handleToolStart',\n  TOOL_END = 'handleToolEnd',\n  CUSTOM_EVENT = 'handleCustomEvent',\n  /*\n  LLM_START = 'handleLLMStart',\n  LLM_NEW_TOKEN = 'handleLLMNewToken',\n  LLM_ERROR = 'handleLLMError',\n  LLM_END = 'handleLLMEnd',\n  CHAT_MODEL_START = 'handleChatModelStart',\n  CHAIN_START = 'handleChainStart',\n  CHAIN_ERROR = 'handleChainError',\n  CHAIN_END = 'handleChainEnd',\n  TEXT = 'handleText',\n  AGENT_ACTION = 'handleAgentAction',\n  AGENT_END = 'handleAgentEnd',\n  RETRIEVER_START = 'handleRetrieverStart',\n  RETRIEVER_END = 'handleRetrieverEnd',\n  RETRIEVER_ERROR = 'handleRetrieverError',\n  */\n}\n\nexport enum Constants {\n  OFFICIAL_CODE_BASEURL = 'https://api.illuma.ai/v1',\n  EXECUTE_CODE = 'execute_code',\n  TOOL_SEARCH = 'tool_search',\n  PROGRAMMATIC_TOOL_CALLING = 'run_tools_with_code',\n  WEB_SEARCH = 'web_search',\n  CONTENT_AND_ARTIFACT = 'content_and_artifact',\n  LC_TRANSFER_TO_ = 'lc_transfer_to_',\n  /** Prefix for handoff tool names: lc_handoff_to_{agentId} */\n  LC_HANDOFF_TO_ = 'lc_handoff_to_',\n  /** Tool name for the AskUser structured question tool */\n  ASK_USER = 'ask_user',\n  /** Delimiter for MCP tools: toolName_mcp_serverName */\n  MCP_DELIMITER = '_mcp_',\n}\n\nexport enum TitleMethod {\n  STRUCTURED = 'structured',\n  FUNCTIONS = 'functions',\n  COMPLETION = 'completion',\n}\n\nexport enum EnvVar {\n  CODE_API_KEY = 'CODE_EXECUTOR_API_KEY',\n  CODE_BASEURL = 'CODE_EXECUTOR_BASEURL',\n}\n\n/**\n * Normalized LLM finish/stop reasons across providers.\n * Used by toolCallContinuation to detect max_tokens truncation.\n */\nexport enum FinishReasons {\n  /** Anthropic / Bedrock stop reason for token limit */\n  MAX_TOKENS = 'max_tokens',\n  /** OpenAI / Azure finish reason for token limit */\n  LENGTH = 'length',\n  /** Normal completion */\n  STOP = 'stop',\n  /** Anthropic / Bedrock stop reason for normal completion */\n  END_TURN = 'end_turn',\n  /** Model chose to call tools */\n  TOOL_USE = 'tool_use',\n  /** OpenAI finish reason for tool calls */\n  TOOL_CALLS = 'tool_calls',\n}\n\n/**\n * Message type identifiers used by LangChain's BaseMessage.getType().\n * Use these constants instead of instanceof checks to avoid module mismatch issues\n * when different copies of @langchain/core/messages are loaded.\n */\nexport enum MessageTypes {\n  HUMAN = 'human',\n  AI = 'ai',\n  SYSTEM = 'system',\n  TOOL = 'tool',\n  FUNCTION = 'function',\n  GENERIC = 'generic',\n  DEVELOPER = 'developer',\n  REMOVE = 'remove',\n}\n\n/** Default max characters for handoff results returned to parent (~8192 tokens at ~4 chars/token) */\nexport const DEFAULT_HANDOFF_MAX_RESULT_CHARS = 32768;\n\n/** Default timeout for handoff sub-agent execution in milliseconds (5 minutes) */\nexport const HANDOFF_TIMEOUT_MS = 300_000;\n"],"names":[],"mappings":"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"}

package/dist/esm/graphs/MultiAgentGraph.mjs

@@ -10,6 +10,7 @@ import '../utils/toonFormat.mjs';
 import { summarize, createEmergencySummary } from '../messages/summarize.mjs';
 import { StandardGraph } from './Graph.mjs';
 import { safeDispatchCustomEvent } from '../utils/events.mjs';
+import { getApprovalGateNodeId, createApprovalGateNode } from '../nodes/ApprovalGateNode.mjs';
 
 /** Pattern to extract instructions from transfer ToolMessage content */
 const TRANSFER_INSTRUCTIONS_PATTERN = /(?:Instructions?|Context):\s*(.+)/is;
@@ -928,7 +929,34 @@ class MultiAgentGraph extends StandardGraph {
             }),
         });
         const builder = new StateGraph(StateAnnotation);
-        // Add all agents as complete subgraphs
+        /**
+         * Identify agents that are ONLY handoff destinations (not transfer/sequence
+         * destinations and not starting nodes). These agents are invoked inline via
+         * subgraph.invoke() inside handoff tools — they must NOT be added as
+         * top-level nodes in the parent graph because LangGraph validates that all
+         * nodes are reachable from START via edges.
+         */
+        const handoffOnlyDestinations = new Set();
+        const transferOrSequenceDestinations = new Set();
+        for (const edge of this.handoffEdges) {
+            const dests = Array.isArray(edge.to) ? edge.to : [edge.to];
+            dests.forEach((d) => handoffOnlyDestinations.add(d));
+        }
+        for (const edge of [...this.transferEdges, ...this.sequenceEdges]) {
+            const dests = Array.isArray(edge.to) ? edge.to : [edge.to];
+            dests.forEach((d) => transferOrSequenceDestinations.add(d));
+        }
+        // Remove agents that are also transfer/sequence destinations or starting nodes
+        for (const d of transferOrSequenceDestinations) {
+            handoffOnlyDestinations.delete(d);
+        }
+        for (const startNode of this.startingNodes) {
+            handoffOnlyDestinations.delete(startNode);
+        }
+        if (handoffOnlyDestinations.size > 0) {
+            console.debug(`[MultiAgentGraph] Handoff-only children (subgraph only, no top-level node): [${Array.from(handoffOnlyDestinations).join(', ')}]`);
+        }
+        // Add agents as nodes — skip handoff-only children (they exist as subgraphs only)
         for (const [agentId] of this.agentContexts) {
             // Get all possible destinations for this agent
             const transferDestinations = new Set();
@@ -965,6 +993,14 @@ class MultiAgentGraph extends StandardGraph {
             const agentSubgraph = this.createAgentSubgraph(agentId);
             /** Register subgraph for handoff tools (lazy reference resolution) */
             this.subgraphRegistry.set(agentId, agentSubgraph);
+            /**
+             * Handoff-only children are invoked inline via subgraph.invoke() — they
+             * don't need a top-level node. Adding them would cause LangGraph to reject
+             * the graph because no edge routes to them (UNREACHABLE_NODE).
+             */
+            if (handoffOnlyDestinations.has(agentId)) {
+                continue;
+            }
             /** Wrapper function that handles agentMessages channel, handoff reception, and conditional routing */
             const agentWrapper = async (state, config) => {
                 console.debug(`[MultiAgentGraph] Agent "${agentId}" wrapper ENTRY (messages: ${state.messages.length}, needsCommandRouting: ${needsCommandRouting})`);
@@ -1273,12 +1309,62 @@ class MultiAgentGraph extends StandardGraph {
                 builder.addEdge(START, startNode);
             }
         }
+        /**
+         * Add approval gate nodes for sequence edges with approvalGate config.
+         * Gates are inserted between source and destination agents.
+         * They ALWAYS fire regardless of ExecutionContext.
+         */
+        const gatedEdges = new Set();
+        for (const edge of this.sequenceEdges) {
+            if (!edge.approvalGate) {
+                continue;
+            }
+            const sources = Array.isArray(edge.from) ? edge.from : [edge.from];
+            const destinations = Array.isArray(edge.to) ? edge.to : [edge.to];
+            for (const source of sources) {
+                for (const dest of destinations) {
+                    const gateNodeId = getApprovalGateNodeId(edge.approvalGate.gateId);
+                    const onDeny = edge.approvalGate.onDeny ?? 'stop';
+                    // Add the gate node
+                    const gateNode = createApprovalGateNode(edge.approvalGate, source, dest);
+                    // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+                    /** @ts-ignore */
+                    builder.addNode(gateNodeId, gateNode);
+                    // Wire: source → gate
+                    // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+                    /** @ts-ignore */
+                    builder.addEdge(source, gateNodeId);
+                    // Wire: gate → destination (always, since approval is handled
+                    // by the interrupt/resume mechanism — if denied, the host
+                    // can choose not to resume, or resume with approved=false
+                    // and the gate returns empty state)
+                    if (onDeny === 'skip') {
+                        // Conditional edge: approved → destination, denied → END
+                        // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+                        /** @ts-ignore */
+                        builder.addEdge(gateNodeId, dest);
+                    }
+                    else {
+                        // Direct edge to destination — denial stops via non-resume or
+                        // the host terminates the graph
+                        // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+                        /** @ts-ignore */
+                        builder.addEdge(gateNodeId, dest);
+                    }
+                }
+            }
+            gatedEdges.add(edge);
+        }
         /**
          * Add sequence edges for automatic transitions
          * Group edges by destination to handle fan-in scenarios
+         * Skip edges that have approval gates (already handled above)
          */
         const edgesByDestination = new Map();
         for (const edge of this.sequenceEdges) {
+            if (gatedEdges.has(edge)) {
+                continue;
+            }
             const destinations = Array.isArray(edge.to) ? edge.to : [edge.to];
             for (const destination of destinations) {
                 if (!edgesByDestination.has(destination)) {