@illuma-ai/agents 1.1.19 → 1.1.20

package/dist/types/run.d.ts

@@ -1,4 +1,5 @@
 import './instrumentation';
+import { Command } from '@langchain/langgraph';
 import type { MessageContentComplex, BaseMessage } from '@langchain/core/messages';
 import type { RunnableConfig } from '@langchain/core/runnables';
 import type * as t from '@/types';
@@ -41,11 +42,34 @@ export declare class Run<_T extends t.BaseGraphState> {
      * and processes them through our handler registry instead of EventStreamCallbackHandler
      */
     private createCustomEventCallback;
-    processStream(inputs: t.IState, config: Partial<RunnableConfig> & {
+    /**
+     * 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.
+     */
+    processStream(inputs: t.IState | Command, config: Partial<RunnableConfig> & {
         version: 'v1' | 'v2';
         run_id?: string;
     }, streamOptions?: t.EventStreamOptions): Promise<MessageContentComplex[] | undefined>;
     private createSystemCallback;
+    /**
+     * 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.
+     */
+    hasInterrupts(config: Partial<RunnableConfig>): Promise<boolean>;
+    /**
+     * 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).
+     */
+    getInterruptValues(config: Partial<RunnableConfig>): Promise<unknown[]>;
     getCallbacks(clientCallbacks: t.ClientCallbacks): t.SystemCallbacks;
     generateTitle({ provider, inputText, contentParts, titlePrompt, clientOptions, chainOptions, skipLanguage, titleMethod, titlePromptTemplate, }: t.RunTitleOptions): Promise<{
         language?: string;

package/dist/types/tools/ToolNode.d.ts

@@ -48,12 +48,14 @@ export declare class ToolNode<T = any> extends RunnableCallable<T, T> {
      */
     private requiresApproval;
     /**
-     * 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

package/dist/types/types/graph.d.ts

@@ -221,6 +221,31 @@ export type StandardGraphInput = {
     tokenCounter?: TokenCounter;
     indexTokenCountMap?: Record<string, number>;
 };
+/**
+ * Configuration for an approval gate placed on a sequence edge.
+ * When present, the graph inserts an approval gate node between the source
+ * and destination agents. The gate ALWAYS fires (regardless of ExecutionContext)
+ * and calls interrupt() to pause the graph for human approval.
+ */
+export type ApprovalGateConfig = {
+    /** Unique identifier for this gate (used as node ID suffix) */
+    gateId: string;
+    /**
+     * Approval channel — where the approval UI is rendered.
+     * - 'chat': SSE-based chat UI (default)
+     * - 'outlook': MS Graph Actionable Messages
+     * - 'telegram': Telegram Bot inline keyboard
+     */
+    channel?: 'chat' | 'outlook' | 'telegram';
+    /** Optional human-readable prompt shown to the approver */
+    prompt?: string;
+    /** Optional approver identifier (e.g., email, user ID) */
+    approver?: string;
+    /** Timeout in ms before the gate auto-expires (default: 5 minutes) */
+    timeoutMs?: number;
+    /** What to do on denial: 'stop' ends the graph, 'skip' skips the destination agent */
+    onDeny?: 'stop' | 'skip';
+};
 export type GraphEdge = {
     /** Agent ID, use a list for multiple sources */
     from: string | string[];
@@ -263,6 +288,12 @@ export type GraphEdge = {
      * Defaults to DEFAULT_HANDOFF_MAX_RESULT_CHARS (32768 chars, ~8192 tokens).
      */
     maxResultChars?: number;
+    /**
+     * Approval gate configuration for sequence edges.
+     * When set, inserts an approval gate node between source and destination.
+     * The gate ALWAYS fires regardless of ExecutionContext (unlike tool approval).
+     */
+    approvalGate?: ApprovalGateConfig;
 };
 export type MultiAgentGraphInput = StandardGraphInput & {
     edges: GraphEdge[];

package/dist/types/types/tools.d.ts

@@ -271,16 +271,14 @@ export type ToolApprovalResponse = {
     modifiedArgs?: Record<string, unknown>;
 };
 /**
- * Event payload dispatched via ON_TOOL_APPROVAL_REQUIRED.
- * Extends ToolApprovalRequest with promise resolve/reject for async flow.
- * The host handles the event by showing UI and calling resolve/reject.
+ * Notification payload dispatched via ON_TOOL_APPROVAL_REQUIRED.
+ * Data-only — no resolve/reject callbacks. The approval mechanism is handled
+ * by LangGraph's native interrupt()/Command({ resume }) pattern.
+ *
+ * The host persists this data (e.g., in MongoDB) and sends UI events.
+ * The actual approval response comes back via Command({ resume: ToolApprovalResponse }).
  */
-export type ToolApprovalEvent = ToolApprovalRequest & {
-    /** Promise resolver - host calls this with the approval response */
-    resolve: (response: ToolApprovalResponse) => void;
-    /** Promise rejector - host calls this on fatal error */
-    reject: (error: Error) => void;
-};
+export type ToolApprovalNotification = ToolApprovalRequest;
 /** Search mode: code_interpreter uses external sandbox, local uses safe substring matching */
 export type ToolSearchMode = 'code_interpreter' | 'local';
 /** Format for MCP tool names in search results */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@illuma-ai/agents",
-  "version": "1.1.19",
+  "version": "1.1.20",
   "main": "./dist/cjs/main.cjs",
   "module": "./dist/esm/main.mjs",
   "types": "./dist/types/index.d.ts",

package/src/common/enum.ts

@@ -31,6 +31,8 @@ export enum GraphEvents {
   ON_TOOL_APPROVAL_REQUIRED = 'on_tool_approval_required',
   /** [Custom] Agent transition event — dispatched when control passes between agents */
   ON_AGENT_TRANSITION = 'on_agent_transition',
+  /** [Custom] Approval gate interrupt — dispatched by ApprovalGateNode before interrupt() */
+  ON_APPROVAL_GATE = 'on_approval_gate',
 
   /* Official Events */
 

package/src/graphs/MultiAgentGraph.ts

@@ -29,6 +29,10 @@ import {
   DEFAULT_HANDOFF_MAX_RESULT_CHARS,
 } from '@/common';
 import { safeDispatchCustomEvent } from '@/utils/events';
+import {
+  createApprovalGateNode,
+  getApprovalGateNodeId,
+} from '@/nodes/ApprovalGateNode';
 
 /** Pattern to extract instructions from transfer ToolMessage content */
 const TRANSFER_INSTRUCTIONS_PATTERN = /(?:Instructions?|Context):\s*(.+)/is;
@@ -1182,7 +1186,39 @@ export 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<string>();
+    const transferOrSequenceDestinations = new Set<string>();
+
+    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<string>();
@@ -1226,6 +1262,15 @@ export class MultiAgentGraph extends StandardGraph {
       /** 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: t.MultiAgentGraphState,
@@ -1645,13 +1690,75 @@ export class MultiAgentGraph extends StandardGraph {
       }
     }
 
+    /**
+     * 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<t.GraphEdge>();
+
+    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<string, t.GraphEdge[]>();
 
     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)) {

package/src/index.ts

@@ -29,6 +29,9 @@ export * from './tools/search';
 /* Schemas */
 export * from './schemas';
 
+/* Nodes */
+export * from './nodes';
+
 /* Misc. */
 export * from './common';
 export * from './utils';

package/src/nodes/ApprovalGateNode.ts

@@ -0,0 +1,117 @@
+import { interrupt } from '@langchain/langgraph';
+import type { RunnableConfig } from '@langchain/core/runnables';
+import type { ApprovalGateConfig, BaseGraphState } from '@/types/graph';
+import type { ToolApprovalResponse } from '@/types/tools';
+import { GraphEvents } from '@/common';
+import { safeDispatchCustomEvent } from '@/utils/events';
+
+/**
+ * Interrupt payload for approval gate nodes.
+ * Passed to interrupt() and persisted in the checkpoint.
+ */
+export interface ApprovalGateInterrupt {
+  /** Discriminator to distinguish from tool approval interrupts */
+  type: 'approval_gate';
+  /** Unique gate identifier */
+  gateId: string;
+  /** Approval channel (chat, outlook, telegram) */
+  channel: string;
+  /** Human-readable prompt for the approver */
+  prompt?: string;
+  /** Approver identifier */
+  approver?: string;
+  /** Timeout in ms */
+  timeoutMs?: number;
+  /** Source agent ID (who just finished) */
+  sourceAgentId?: string;
+  /** Destination agent ID (who will run next if approved) */
+  destinationAgentId?: string;
+}
+
+/**
+ * Creates a graph node function that acts as an approval gate.
+ *
+ * Unlike tool approval (which respects ExecutionContext and can be auto-approved
+ * in scheduled/handoff modes), approval gates ALWAYS fire. They are placed by
+ * the builder between agents in a sequence and represent explicit human
+ * checkpoints that cannot be bypassed.
+ *
+ * Flow:
+ * 1. Dispatch ON_APPROVAL_GATE notification (for SSE/persistence)
+ * 2. Call interrupt() — graph pauses, state is checkpointed
+ * 3. On resume, interrupt() returns the ToolApprovalResponse
+ * 4. If approved, pass state through (next agent runs)
+ * 5. If denied, return state as-is (routing handled by conditional edge)
+ *
+ * @param config - The approval gate configuration from the edge definition
+ * @param sourceAgentId - The agent that precedes this gate
+ * @param destinationAgentId - The agent that follows this gate
+ */
+export function createApprovalGateNode(
+  config: ApprovalGateConfig,
+  sourceAgentId: string,
+  destinationAgentId: string,
+) {
+  const {
+    gateId,
+    channel = 'chat',
+    prompt,
+    approver,
+    timeoutMs,
+  } = config;
+
+  /**
+   * The gate node function. Receives the current graph state,
+   * dispatches a notification, calls interrupt(), and returns
+   * the state with an approval result annotation.
+   */
+  return async function approvalGateNode(
+    state: BaseGraphState,
+    runnableConfig?: RunnableConfig,
+  ): Promise<Partial<BaseGraphState>> {
+    const interruptPayload: ApprovalGateInterrupt = {
+      type: 'approval_gate',
+      gateId,
+      channel,
+      prompt,
+      approver,
+      timeoutMs,
+      sourceAgentId,
+      destinationAgentId,
+    };
+
+    // Dispatch notification event so the host can:
+    // 1. Persist the approval request to MongoDB
+    // 2. Route to the appropriate channel adapter
+    // 3. Emit SSE event for chat UI
+    safeDispatchCustomEvent(
+      GraphEvents.ON_APPROVAL_GATE,
+      interruptPayload,
+      runnableConfig,
+    );
+
+    // Pause the graph — state is checkpointed by the MongoDBSaver.
+    // On resume via Command({ resume: ToolApprovalResponse }), interrupt()
+    // returns the response value.
+    const response = interrupt(interruptPayload) as ToolApprovalResponse;
+
+    // Return empty state update — the graph structure (conditional edges)
+    // handles routing based on the approval result. We store the response
+    // in a message so downstream nodes can access it if needed.
+    if (response.approved) {
+      return {};
+    }
+
+    // On denial, we could add a system message noting the denial.
+    // The conditional edge after this node will route to END or skip.
+    return {};
+  };
+}
+
+/**
+ * Node ID for an approval gate, derived from the gate configuration.
+ * Used by MultiAgentGraph when inserting gate nodes into the graph.
+ */
+export function getApprovalGateNodeId(gateId: string): string {
+  return `approval_gate_${gateId}`;
+}

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';