@illuma-ai/agents 1.1.19 → 1.1.20

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';
@@ -250,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> {
@@ -409,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({