@illuma-ai/agents 1.1.18 → 1.1.20

package/dist/types/nodes/index.d.ts

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

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,9 +288,24 @@ 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[];
+    /**
+     * When set, the graph routes START to this agent instead of the default starting nodes.
+     * Used for multi-turn resumption: the caller reads `lastActiveAgentId` from the
+     * previous turn's metadata and passes it here so follow-up messages route to the
+     * agent that last handled the conversation.
+     *
+     * If the agent ID is invalid (not in the graph), falls back to default starting nodes.
+     */
+    resumeFromAgentId?: string;
 };
 /**
  * Structured output mode determines how the agent returns structured data.

package/dist/types/types/run.d.ts

@@ -91,6 +91,12 @@ export type MultiAgentGraphConfig = {
     compileOptions?: g.CompileOptions;
     agents: g.AgentInputs[];
     edges: g.GraphEdge[];
+    /**
+     * Resume from a specific agent on the next turn.
+     * When set, START routes directly to this agent instead of default starting nodes.
+     * @see MultiAgentGraphInput.resumeFromAgentId
+     */
+    resumeFromAgentId?: string;
 };
 export type StandardGraphConfig = Omit<MultiAgentGraphConfig, 'edges' | 'type'> & {
     type?: 'standard';

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.18",
+  "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;
@@ -78,9 +82,17 @@ export class MultiAgentGraph extends StandardGraph {
    */
   private lastActiveAgentId: string | undefined;
 
+  /**
+   * When set, the graph routes START to this agent instead of the default starting nodes.
+   * Enables multi-turn resumption: follow-up messages go to the agent that last handled
+   * the conversation rather than restarting from the root/router agent.
+   */
+  private resumeFromAgentId: string | undefined;
+
   constructor(input: t.MultiAgentGraphInput) {
     super(input);
     this.edges = input.edges;
+    this.resumeFromAgentId = input.resumeFromAgentId;
     this.categorizeEdges();
     this.analyzeGraph();
     this.createTransferTools();
@@ -1174,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>();
@@ -1218,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,
@@ -1585,20 +1638,127 @@ export class MultiAgentGraph extends StandardGraph {
       });
     }
 
-    // Add starting edges for all starting nodes
-    for (const startNode of this.startingNodes) {
-      // eslint-disable-next-line @typescript-eslint/ban-ts-comment
-      /** @ts-ignore */
-      builder.addEdge(START, startNode);
+    /**
+     * Add starting edges from START to entry agent(s).
+     *
+     * Multi-turn resumption: when `resumeFromAgentId` is set and refers to a
+     * valid agent in this graph, START routes exclusively to that agent so
+     * follow-up messages continue where the previous turn left off.
+     *
+     * Default behavior (no resume): static edges to all starting nodes,
+     * preserving parallel execution for graphs with multiple entry points.
+     */
+    const validResumeAgent =
+      this.resumeFromAgentId != null &&
+      this.agentContexts.has(this.resumeFromAgentId);
+
+    if (validResumeAgent) {
+      const resumeAgentId = this.resumeFromAgentId!;
+      console.debug(
+        `[MultiAgentGraph] Multi-turn resumption: routing START → "${resumeAgentId}" (skipping default starting nodes: [${Array.from(this.startingNodes).join(', ')}])`
+      );
+
+      /**
+       * Build route map containing both the resume agent and default starting
+       * nodes. This is required by LangGraph — all possible destinations must
+       * be declared even if the router always picks one.
+       */
+      const allPossibleStarts = new Set([
+        ...this.startingNodes,
+        resumeAgentId,
+      ]);
+      const routeMap: Record<string, string> = {};
+      for (const nodeId of allPossibleStarts) {
+        routeMap[nodeId] = nodeId;
+      }
+
+      builder.addConditionalEdges(
+        START,
+        () => resumeAgentId,
+        routeMap as unknown as never
+      );
+    } else {
+      if (this.resumeFromAgentId != null) {
+        console.warn(
+          `[MultiAgentGraph] resumeFromAgentId "${this.resumeFromAgentId}" not found in graph — falling back to default starting nodes`
+        );
+      }
+      for (const startNode of this.startingNodes) {
+        // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+        /** @ts-ignore */
+        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<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}`;
+}