@illuma-ai/agents 1.1.18 → 1.1.20

package/src/nodes/__tests__/ApprovalGateNode.test.ts

@@ -0,0 +1,206 @@
+import { MemorySaver } from '@langchain/langgraph';
+import {
+  StateGraph,
+  Annotation,
+  messagesStateReducer,
+  Command,
+} from '@langchain/langgraph';
+import { AIMessage, HumanMessage } from '@langchain/core/messages';
+import type { BaseMessage } from '@langchain/core/messages';
+import type { RunnableConfig } from '@langchain/core/runnables';
+import {
+  createApprovalGateNode,
+  getApprovalGateNodeId,
+} from '../ApprovalGateNode';
+import type { ApprovalGateConfig } from '@/types/graph';
+
+// Suppress safeDispatchCustomEvent since we don't have a full graph context
+jest.mock('@/utils/events', () => ({
+  safeDispatchCustomEvent: jest.fn(),
+}));
+
+const { safeDispatchCustomEvent } = require('@/utils/events');
+
+/**
+ * Creates a simple 2-agent graph with an approval gate between them.
+ * Agent A → Gate → Agent B
+ */
+function createGatedGraph(gateConfig: ApprovalGateConfig) {
+  const GraphState = Annotation.Root({
+    messages: Annotation<BaseMessage[]>({
+      reducer: messagesStateReducer,
+    }),
+  });
+
+  const checkpointer = new MemorySaver();
+  const gateNodeId = getApprovalGateNodeId(gateConfig.gateId);
+
+  const builder = new StateGraph(GraphState);
+
+  // Agent A: echoes input
+  builder.addNode('agent_a', async (state) => ({
+    messages: [new AIMessage('Agent A done')],
+  }));
+
+  // Approval gate
+  const gateNode = createApprovalGateNode(gateConfig, 'agent_a', 'agent_b');
+  builder.addNode(gateNodeId, gateNode as any);
+
+  // Agent B: runs after approval
+  builder.addNode('agent_b', async (state) => ({
+    messages: [new AIMessage('Agent B done')],
+  }));
+
+  // Wire: START → A → gate → B → END
+  builder.addEdge('__start__' as any, 'agent_a' as any);
+  builder.addEdge('agent_a' as any, gateNodeId as any);
+  builder.addEdge(gateNodeId as any, 'agent_b' as any);
+  builder.addEdge('agent_b' as any, '__end__' as any);
+
+  const compiled = builder.compile({ checkpointer } as any);
+
+  return { compiled, checkpointer, gateNodeId };
+}
+
+describe('ApprovalGateNode', () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+  });
+
+  it('interrupts the graph at the gate node', async () => {
+    const { compiled } = createGatedGraph({
+      gateId: 'review-step',
+      channel: 'chat',
+      prompt: 'Please review before Agent B runs',
+    });
+
+    const config: Partial<RunnableConfig> = {
+      configurable: { thread_id: 'test-thread-1' },
+    };
+
+    // First invoke: Agent A runs, then gate interrupts
+    const result = await compiled.invoke(
+      { messages: [new HumanMessage('start')] },
+      config,
+    );
+
+    // Check that the graph was interrupted (Agent B should NOT have run)
+    const state = await compiled.getState(config);
+    const interrupted = state.tasks?.some((t: any) => t.interrupts?.length > 0);
+    expect(interrupted).toBe(true);
+
+    // Agent A should have run
+    const messages = result.messages as BaseMessage[];
+    const hasAgentA = messages.some(
+      (m: any) => m._getType?.() === 'ai' && m.content === 'Agent A done',
+    );
+    expect(hasAgentA).toBe(true);
+
+    // Agent B should NOT have run
+    const hasAgentB = messages.some(
+      (m: any) => m._getType?.() === 'ai' && m.content === 'Agent B done',
+    );
+    expect(hasAgentB).toBe(false);
+  });
+
+  it('resumes and runs Agent B after approval', async () => {
+    const { compiled } = createGatedGraph({
+      gateId: 'review-step',
+      channel: 'chat',
+    });
+
+    const config: Partial<RunnableConfig> = {
+      configurable: { thread_id: 'test-thread-2' },
+    };
+
+    // First invoke: hits gate interrupt
+    await compiled.invoke(
+      { messages: [new HumanMessage('start')] },
+      config,
+    );
+
+    // Resume with approval
+    const result = await compiled.invoke(
+      new Command({ resume: { approved: true } }),
+      config,
+    );
+
+    // Agent B should have run after approval
+    const messages = result.messages as BaseMessage[];
+    const hasAgentB = messages.some(
+      (m: any) => m._getType?.() === 'ai' && m.content === 'Agent B done',
+    );
+    expect(hasAgentB).toBe(true);
+  });
+
+  it('dispatches ON_APPROVAL_GATE event before interrupting', async () => {
+    const { compiled } = createGatedGraph({
+      gateId: 'notify-gate',
+      channel: 'outlook',
+      prompt: 'Review needed',
+      approver: 'manager@example.com',
+    });
+
+    const config: Partial<RunnableConfig> = {
+      configurable: { thread_id: 'test-thread-3' },
+    };
+
+    await compiled.invoke(
+      { messages: [new HumanMessage('start')] },
+      config,
+    );
+
+    // safeDispatchCustomEvent should have been called with gate data
+    expect(safeDispatchCustomEvent).toHaveBeenCalledWith(
+      'on_approval_gate',
+      expect.objectContaining({
+        type: 'approval_gate',
+        gateId: 'notify-gate',
+        channel: 'outlook',
+        prompt: 'Review needed',
+        approver: 'manager@example.com',
+        sourceAgentId: 'agent_a',
+        destinationAgentId: 'agent_b',
+      }),
+      expect.anything(),
+    );
+  });
+
+  it('resumes with denial — gate returns empty state', async () => {
+    const { compiled } = createGatedGraph({
+      gateId: 'deny-gate',
+    });
+
+    const config: Partial<RunnableConfig> = {
+      configurable: { thread_id: 'test-thread-4' },
+    };
+
+    // First invoke: hits gate interrupt
+    await compiled.invoke(
+      { messages: [new HumanMessage('start')] },
+      config,
+    );
+
+    // Resume with denial
+    const result = await compiled.invoke(
+      new Command({ resume: { approved: false, feedback: 'Not ready' } }),
+      config,
+    );
+
+    // Agent B still runs (the gate doesn't block — it's the host's
+    // responsibility to not resume on denial, or use onDeny routing).
+    // In the current implementation, the gate node returns {} regardless.
+    const messages = result.messages as BaseMessage[];
+    const hasAgentB = messages.some(
+      (m: any) => m._getType?.() === 'ai' && m.content === 'Agent B done',
+    );
+    expect(hasAgentB).toBe(true);
+  });
+
+  describe('getApprovalGateNodeId', () => {
+    it('generates consistent node IDs', () => {
+      expect(getApprovalGateNodeId('step-1')).toBe('approval_gate_step-1');
+      expect(getApprovalGateNodeId('review')).toBe('approval_gate_review');
+    });
+  });
+});

package/src/nodes/index.ts

@@ -0,0 +1,5 @@
+export {
+  createApprovalGateNode,
+  getApprovalGateNodeId,
+} from './ApprovalGateNode';
+export type { ApprovalGateInterrupt } from './ApprovalGateNode';

package/src/run.ts

@@ -1,6 +1,7 @@
 // src/run.ts
 import './instrumentation';
 import { ObservabilityCallbackHandler } from '@illuma-ai/observability-langchain';
+import { Command } from '@langchain/langgraph';
 import { PromptTemplate } from '@langchain/core/prompts';
 import { RunnableLambda } from '@langchain/core/runnables';
 import { AzureChatOpenAI, ChatOpenAI } from '@langchain/openai';
@@ -143,12 +144,13 @@ export class Run<_T extends t.BaseGraphState> {
   private createMultiAgentGraph(
     config: t.MultiAgentGraphConfig
   ): t.CompiledStateWorkflow {
-    const { agents, edges, compileOptions } = config;
+    const { agents, edges, compileOptions, resumeFromAgentId } = config;
 
     const multiAgentGraph = new MultiAgentGraph({
       runId: this.id,
       agents,
       edges,
+      resumeFromAgentId,
       tokenCounter: this.tokenCounter,
       indexTokenCountMap: this.indexTokenCountMap,
     });
@@ -249,8 +251,16 @@ export class Run<_T extends t.BaseGraphState> {
     };
   }
 
+  /**
+   * Processes the graph stream for a given input.
+   *
+   * @param inputs - Either the initial state (IState) for a new run, or a
+   *   Command (e.g., `new Command({ resume: ... })`) to resume from an interrupt.
+   * @param config - Runnable config with version and optional run_id.
+   * @param streamOptions - Optional stream event callbacks and options.
+   */
   async processStream(
-    inputs: t.IState,
+    inputs: t.IState | Command,
     config: Partial<RunnableConfig> & { version: 'v1' | 'v2'; run_id?: string },
     streamOptions?: t.EventStreamOptions
   ): Promise<MessageContentComplex[] | undefined> {
@@ -408,6 +418,51 @@ export class Run<_T extends t.BaseGraphState> {
     }) as t.SystemCallbacks[K];
   }
 
+  /**
+   * Checks whether the graph was interrupted (e.g., by HITL tool approval).
+   * Call after processStream() returns to determine if the graph is waiting
+   * for a resume via Command({ resume }).
+   *
+   * Requires a checkpointer to be configured — without one, interrupt state
+   * is not persisted and this always returns false.
+   */
+  async hasInterrupts(
+    config: Partial<RunnableConfig>
+  ): Promise<boolean> {
+    if (!this.graphRunnable) {
+      return false;
+    }
+    try {
+      const state = await this.graphRunnable.getState(config);
+      return state.tasks?.some((task) => task.interrupts?.length > 0) ?? false;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Returns the interrupt values from the graph state.
+   * Each interrupt's `value` contains the data passed to `interrupt()` by the node
+   * (e.g., a ToolApprovalRequest for HITL).
+   */
+  async getInterruptValues(
+    config: Partial<RunnableConfig>
+  ): Promise<unknown[]> {
+    if (!this.graphRunnable) {
+      return [];
+    }
+    try {
+      const state = await this.graphRunnable.getState(config);
+      return (
+        state.tasks?.flatMap((task) =>
+          (task.interrupts ?? []).map((i) => i.value)
+        ) ?? []
+      );
+    } catch {
+      return [];
+    }
+  }
+
   getCallbacks(clientCallbacks: t.ClientCallbacks): t.SystemCallbacks {
     return {
       [Callback.TOOL_ERROR]: this.createSystemCallback(

package/src/specs/agent-handoffs-bedrock.integration.test.ts

@@ -145,11 +145,11 @@ describeIf('Agent Handoff E2E with Bedrock', () => {
 
       // Verify the handoff tools have enriched descriptions
       const salesTool = findToolByName(
-        supervisorContext?.tools,
+        supervisorContext?.graphTools,
         `${Constants.LC_TRANSFER_TO_}agent_W47hBnn2RoVZEOy5595GC`
       );
       const supportTool = findToolByName(
-        supervisorContext?.tools,
+        supervisorContext?.graphTools,
         `${Constants.LC_TRANSFER_TO_}agent_X92kLmn4TpQR8vw3221HD`
       );
 

package/src/specs/agent-handoffs.test.ts

@@ -1018,7 +1018,7 @@ describe('Agent Handoffs Tests', () => {
         'supervisor'
       );
       const handoffTool = findToolByName(
-        supervisorContext?.tools,
+        supervisorContext?.graphTools,
         `${Constants.LC_TRANSFER_TO_}data_analyst`
       );
 
@@ -1052,7 +1052,7 @@ describe('Agent Handoffs Tests', () => {
         'supervisor'
       );
       const handoffTool = findToolByName(
-        supervisorContext?.tools,
+        supervisorContext?.graphTools,
         `${Constants.LC_TRANSFER_TO_}writer`
       );
 
@@ -1086,7 +1086,7 @@ describe('Agent Handoffs Tests', () => {
         'supervisor'
       );
       const handoffTool = findToolByName(
-        supervisorContext?.tools,
+        supervisorContext?.graphTools,
         `${Constants.LC_TRANSFER_TO_}agent_b`
       );
 
@@ -1130,15 +1130,15 @@ describe('Agent Handoffs Tests', () => {
       );
 
       const salesTool = findToolByName(
-        routerContext?.tools,
+        routerContext?.graphTools,
         `${Constants.LC_TRANSFER_TO_}sales`
       );
       const supportTool = findToolByName(
-        routerContext?.tools,
+        routerContext?.graphTools,
         `${Constants.LC_TRANSFER_TO_}support`
       );
       const billingTool = findToolByName(
-        routerContext?.tools,
+        routerContext?.graphTools,
         `${Constants.LC_TRANSFER_TO_}billing`
       );
 
@@ -1294,4 +1294,151 @@ describe('Agent Handoffs Tests', () => {
       }
     });
   });
+
+  describe('Multi-Turn Agent Resumption', () => {
+    it('should route START to resumeFromAgentId when valid', async () => {
+      const agents: t.AgentInputs[] = [
+        createBasicAgent('router', 'You are the router agent'),
+        createBasicAgent('writer', 'You are the writer agent'),
+        createBasicAgent('researcher', 'You are the researcher agent'),
+      ];
+
+      const edges: t.GraphEdge[] = [
+        { from: 'router', to: 'writer', edgeType: EdgeType.TRANSFER },
+        { from: 'router', to: 'researcher', edgeType: EdgeType.TRANSFER },
+      ];
+
+      // Create run WITH resumeFromAgentId set to 'writer'
+      const run = await Run.create({
+        runId: `resume-test-${Date.now()}`,
+        graphConfig: {
+          type: 'multi-agent',
+          agents,
+          edges,
+          resumeFromAgentId: 'writer',
+        },
+        returnContent: true,
+        skipCleanup: true,
+      });
+
+      // Graph should compile without error
+      expect(run.graphRunnable).toBeDefined();
+
+      // The writer agent should be reachable from START
+      // (We verify by checking that the graph compiled successfully with conditional routing)
+      expect(run.Graph).toBeDefined();
+    });
+
+    it('should fall back to default starting nodes when resumeFromAgentId is invalid', async () => {
+      const agents: t.AgentInputs[] = [
+        createBasicAgent('router', 'You are the router agent'),
+        createBasicAgent('writer', 'You are the writer agent'),
+      ];
+
+      const edges: t.GraphEdge[] = [
+        { from: 'router', to: 'writer', edgeType: EdgeType.TRANSFER },
+      ];
+
+      // Create run with an invalid resumeFromAgentId
+      const run = await Run.create({
+        runId: `resume-invalid-test-${Date.now()}`,
+        graphConfig: {
+          type: 'multi-agent',
+          agents,
+          edges,
+          resumeFromAgentId: 'nonexistent_agent',
+        },
+        returnContent: true,
+        skipCleanup: true,
+      });
+
+      // Should still compile (falls back to default starting nodes)
+      expect(run.graphRunnable).toBeDefined();
+      expect(run.Graph).toBeDefined();
+    });
+
+    it('should compile normally without resumeFromAgentId (backward compat)', async () => {
+      const agents: t.AgentInputs[] = [
+        createBasicAgent('router', 'You are the router agent'),
+        createBasicAgent('writer', 'You are the writer agent'),
+      ];
+
+      const edges: t.GraphEdge[] = [
+        { from: 'router', to: 'writer', edgeType: EdgeType.TRANSFER },
+      ];
+
+      // Create run WITHOUT resumeFromAgentId — existing behavior
+      const run = await Run.create(createTestConfig(agents, edges));
+
+      expect(run.graphRunnable).toBeDefined();
+      expect(run.Graph).toBeDefined();
+    });
+
+    it('should route to resume agent and track lastActiveAgentId correctly', async () => {
+      const agents: t.AgentInputs[] = [
+        createBasicAgent('router', 'You are the router agent'),
+        createBasicAgent('writer', 'You are the writer agent'),
+      ];
+
+      const edges: t.GraphEdge[] = [
+        { from: 'router', to: 'writer', edgeType: EdgeType.TRANSFER },
+      ];
+
+      const run = await Run.create({
+        runId: `resume-execution-test-${Date.now()}`,
+        graphConfig: {
+          type: 'multi-agent',
+          agents,
+          edges,
+          resumeFromAgentId: 'writer',
+        },
+        returnContent: true,
+        skipCleanup: true,
+      });
+
+      // Override test model to respond directly (no transfer)
+      run.Graph?.overrideTestModel(['I am the writer, continuing your work.'], 10);
+
+      const messages = [new HumanMessage('Make the intro shorter')];
+      const config: Partial<RunnableConfig> & { version: 'v1' | 'v2'; streamMode: string } = {
+        configurable: { thread_id: 'resume-exec-test' },
+        streamMode: 'values',
+        version: 'v2' as const,
+      };
+
+      await run.processStream({ messages }, config);
+
+      // After execution, lastActiveAgentId should be 'writer' (not 'router')
+      expect(run.getLastActiveAgentId()).toBe('writer');
+    });
+
+    it('should handle resumeFromAgentId with parallel starting nodes', async () => {
+      const agents: t.AgentInputs[] = [
+        createBasicAgent('agent_a', 'You are agent A'),
+        createBasicAgent('agent_b', 'You are agent B'),
+        createBasicAgent('agent_c', 'You are agent C'),
+      ];
+
+      // Both A and B are starting nodes (no incoming edges), C has incoming
+      const edges: t.GraphEdge[] = [
+        { from: 'agent_a', to: 'agent_c', edgeType: EdgeType.TRANSFER },
+        { from: 'agent_b', to: 'agent_c', edgeType: EdgeType.TRANSFER },
+      ];
+
+      // Resume from agent_c — should override the parallel start (A + B)
+      const run = await Run.create({
+        runId: `resume-parallel-test-${Date.now()}`,
+        graphConfig: {
+          type: 'multi-agent',
+          agents,
+          edges,
+          resumeFromAgentId: 'agent_c',
+        },
+        returnContent: true,
+        skipCleanup: true,
+      });
+
+      expect(run.graphRunnable).toBeDefined();
+    });
+  });
 });

package/src/tools/ToolNode.ts

@@ -9,6 +9,7 @@ import {
   Send,
   Command,
   isCommand,
+  interrupt,
   isGraphInterrupt,
   MessagesAnnotation,
 } from '@langchain/langgraph';
@@ -226,21 +227,23 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
   }
 
   /**
-   * Requests human approval for a tool call via event dispatch.
-   * Dispatches an ON_TOOL_APPROVAL_REQUIRED event and waits for the host
-   * to resolve the promise with an approval response.
+   * Requests human approval for a tool call using LangGraph's native interrupt().
    *
-   * This uses the same pattern as ON_TOOL_EXECUTE: a promise-based event
-   * dispatch where the host calls resolve/reject when the human responds.
+   * Flow:
+   * 1. Dispatches ON_TOOL_APPROVAL_REQUIRED notification (no resolve/reject — data only)
+   *    so the host can persist the request and send UI events.
+   * 2. Calls interrupt() which checkpoints graph state and pauses execution.
+   * 3. When the host resumes via Command({ resume: ToolApprovalResponse }),
+   *    interrupt() returns the response synchronously.
    *
    * @param call - The tool call requiring approval
    * @param config - The runnable config for event dispatch
    * @returns The approval response from the human
    */
-  private async requestApproval(
+  private requestApproval(
     call: ToolCall,
     config: RunnableConfig
-  ): Promise<t.ToolApprovalResponse> {
+  ): t.ToolApprovalResponse {
     const approvalRequest: t.ToolApprovalRequest = {
       type: 'tool_approval_required',
       toolCallId: call.id ?? '',
@@ -250,17 +253,18 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
       description: `Tool "${call.name}" wants to execute with the provided arguments.`,
     };
 
-    return new Promise<t.ToolApprovalResponse>((resolve, reject) => {
-      safeDispatchCustomEvent(
-        GraphEvents.ON_TOOL_APPROVAL_REQUIRED,
-        {
-          ...approvalRequest,
-          resolve,
-          reject,
-        },
-        config
-      );
-    });
+    // Notify host before interrupting — allows SSE event emission and DB persistence.
+    // This is a fire-and-forget notification, NOT the approval mechanism.
+    safeDispatchCustomEvent(
+      GraphEvents.ON_TOOL_APPROVAL_REQUIRED,
+      approvalRequest,
+      config
+    );
+
+    // interrupt() throws GraphInterrupt on first call (checkpoints state),
+    // returns the resume value on re-execution after Command({ resume }).
+    const response = interrupt(approvalRequest) as t.ToolApprovalResponse;
+    return response;
   }
 
   /**
@@ -363,13 +367,13 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
 
       // ========================================================================
       // HITL: Check if this tool requires human approval before execution.
-      // Uses event-driven pattern: dispatches ON_TOOL_APPROVAL_REQUIRED event
-      // and waits for the host to resolve/reject with a ToolApprovalResponse.
+      // Uses LangGraph interrupt() — checkpoints state and pauses the graph.
+      // Resumes when host sends Command({ resume: ToolApprovalResponse }).
       // ========================================================================
       if (
         this.requiresApproval(call.name, call.args as Record<string, unknown>)
       ) {
-        const approvalResponse = await this.requestApproval(call, config);
+        const approvalResponse = this.requestApproval(call, config);
         if (!approvalResponse.approved) {
           // Human denied the tool call - return a denial message
           return new ToolMessage({
@@ -811,7 +815,8 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
   ): Promise<ToolMessage[]> {
     // ========================================================================
     // HITL: Check approval for event-dispatched tools (browser, MCP, etc.)
-    // before dispatching. Denied tools return denial messages immediately.
+    // before dispatching. Uses LangGraph interrupt() for each tool needing
+    // approval — counter-based matching handles sequential interrupts.
     // ========================================================================
     const approvedCalls: ToolCall[] = [];
     const denialMessages: ToolMessage[] = [];
@@ -820,7 +825,7 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
       if (
         this.requiresApproval(call.name, call.args as Record<string, unknown>)
       ) {
-        const approvalResponse = await this.requestApproval(call, config);
+        const approvalResponse = this.requestApproval(call, config);
         if (!approvalResponse.approved) {
           denialMessages.push(
             new ToolMessage({