@illuma-ai/agents 1.1.16 → 1.1.18

package/src/common/enum.ts

@@ -29,6 +29,8 @@ export enum GraphEvents {
   ON_CONTEXT_PRESSURE = 'on_context_pressure',
   /** [Custom] Tool requires human approval before execution - dispatched by ToolNode HITL */
   ON_TOOL_APPROVAL_REQUIRED = 'on_tool_approval_required',
+  /** [Custom] Agent transition event — dispatched when control passes between agents */
+  ON_AGENT_TRANSITION = 'on_agent_transition',
 
   /* Official Events */
 

package/src/graphs/MultiAgentGraph.ts

@@ -25,8 +25,10 @@ import { StandardGraph } from './Graph';
 import {
   Constants,
   EdgeType,
+  GraphEvents,
   DEFAULT_HANDOFF_MAX_RESULT_CHARS,
 } from '@/common';
+import { safeDispatchCustomEvent } from '@/utils/events';
 
 /** Pattern to extract instructions from transfer ToolMessage content */
 const TRANSFER_INSTRUCTIONS_PATTERN = /(?:Instructions?|Context):\s*(.+)/is;
@@ -694,6 +696,19 @@ export class MultiAgentGraph extends StandardGraph {
                   `${truncatedResult.length < resultText.length ? `, truncated to ${truncatedResult.length}` : ''})`
               );
 
+              await safeDispatchCustomEvent(
+                GraphEvents.ON_AGENT_TRANSITION,
+                {
+                  sourceAgentId: sourceAgentId,
+                  sourceAgentName: this.agentContexts.get(sourceAgentId)?.name ?? sourceAgentId,
+                  destinationAgentId: destination,
+                  destinationAgentName: destContext?.name ?? destination,
+                  edgeType: EdgeType.HANDOFF,
+                  timestamp: Date.now(),
+                },
+                config
+              );
+
               return truncatedResult;
             } catch (err) {
               const errorMessage =
@@ -1508,6 +1523,19 @@ export class MultiAgentGraph extends StandardGraph {
               }
             }
 
+            await safeDispatchCustomEvent(
+              GraphEvents.ON_AGENT_TRANSITION,
+              {
+                sourceAgentId: agentId,
+                sourceAgentName: this.agentContexts.get(agentId)?.name ?? agentId,
+                destinationAgentId: transferDest,
+                destinationAgentName: this.agentContexts.get(transferDest)?.name ?? transferDest,
+                edgeType: EdgeType.TRANSFER,
+                timestamp: Date.now(),
+              },
+              config
+            );
+
             return new Command({
               update: result,
               goto: transferDest,
@@ -1518,6 +1546,20 @@ export class MultiAgentGraph extends StandardGraph {
               `[MultiAgentGraph] Command routing: "${agentId}" -> no transfer, following sequence edges: [${Array.from(sequenceDestinations).join(', ')}]`
             );
             const directDests = Array.from(sequenceDestinations);
+            for (const dest of directDests) {
+              await safeDispatchCustomEvent(
+                GraphEvents.ON_AGENT_TRANSITION,
+                {
+                  sourceAgentId: agentId,
+                  sourceAgentName: this.agentContexts.get(agentId)?.name ?? agentId,
+                  destinationAgentId: dest,
+                  destinationAgentName: this.agentContexts.get(dest)?.name ?? dest,
+                  edgeType: EdgeType.SEQUENCE,
+                  timestamp: Date.now(),
+                },
+                config
+              );
+            }
             if (directDests.length === 1) {
               return new Command({
                 update: result,

package/src/tools/ToolNode.ts

@@ -177,11 +177,30 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
       return false;
     }
 
-    const { defaultPolicy, overrides, executionContext } =
-      this.toolApprovalConfig;
+    const {
+      defaultPolicy,
+      overrides,
+      executionContext,
+      agentExecutionContextOverrides,
+    } = this.toolApprovalConfig;
+
+    // Resolve the effective execution context for this agent.
+    // Per-agent overrides take precedence — allows handoff agents to bypass HITL
+    // while the primary agent retains interactive approval.
+    const effectiveContext = (
+      this.agentId && agentExecutionContextOverrides?.[this.agentId]
+    ) ?? executionContext;
+
+    // Scheduled executions bypass all approval checks — no user is present
+    if (effectiveContext === ExecutionContext.SCHEDULED) {
+      return false;
+    }
 
-    // Scheduled executions bypass all approval checks
-    if (executionContext === ExecutionContext.SCHEDULED) {
+    // Handoff/delegate/workflow agents bypass HITL approval — these agents run
+    // autonomously as part of a multi-agent pipeline. Blocking on user approval
+    // would stall the entire graph since all agents share the same SSE stream.
+    // The primary (user-facing) agent retains HITL; only delegated agents skip it.
+    if (effectiveContext === ExecutionContext.HANDOFF) {
       return false;
     }
 

package/src/tools/approval/constants.ts

@@ -16,10 +16,14 @@
  *
  * - `INTERACTIVE`: User is present in the chat session — approval prompts are shown.
  * - `SCHEDULED`: Automated/scheduled execution — all approvals are auto-granted.
+ * - `HANDOFF`: Agent is running as a handoff/delegate/workflow target — approvals
+ *   are auto-granted so the autonomous multi-agent pipeline isn't blocked.
+ *   The primary agent retains HITL; only handoff agents bypass it.
  */
 export enum ExecutionContext {
   INTERACTIVE = 'interactive',
   SCHEDULED = 'scheduled',
+  HANDOFF = 'handoff',
 }
 
 // ============================================================================

package/src/types/graph.ts

@@ -48,6 +48,16 @@ export interface ChatModel {
   ) => Promise<AIMessageChunk>;
 }
 
+/** Payload for ON_AGENT_TRANSITION events */
+export type AgentTransitionEvent = {
+  sourceAgentId?: string;
+  sourceAgentName?: string;
+  destinationAgentId: string;
+  destinationAgentName: string;
+  edgeType: string; // 'handoff' | 'transfer' | 'sequence'
+  timestamp: number;
+};
+
 export type GraphNode = GraphNodeKeys | typeof START;
 export type ClientCallback<T extends unknown[]> = (
   graph: StandardGraph,

package/src/types/tools.ts

@@ -258,9 +258,29 @@ export type ToolApprovalConfig = {
   overrides?: ToolApprovalOverrides;
   /**
    * Execution context. When 'scheduled', all approvals are auto-granted.
+   * When 'handoff', approvals are auto-granted for autonomous multi-agent pipelines.
    * @default 'interactive'
    */
   executionContext?: `${ExecutionContext}`;
+  /**
+   * Per-agent execution context overrides. Keys are agent IDs.
+   * Used to give handoff/delegate agents a different execution context than the
+   * primary agent. For example, the primary agent stays 'interactive' (HITL enabled)
+   * while all handoff agents are set to 'handoff' (HITL bypassed).
+   *
+   * When a ToolNode's agentId is found in this map, the override takes precedence
+   * over the top-level `executionContext`.
+   *
+   * @example
+   * {
+   *   executionContext: 'interactive',  // primary agent: HITL on
+   *   agentExecutionContextOverrides: {
+   *     'research-agent': 'handoff',    // handoff agent: HITL off
+   *     'data-agent': 'handoff',        // handoff agent: HITL off
+   *   },
+   * }
+   */
+  agentExecutionContextOverrides?: Record<string, `${ExecutionContext}`>;
 };
 
 /**