@illuma-ai/agents 1.1.18 → 1.1.20

package/src/types/graph.ts

@@ -342,6 +342,32 @@ export type StandardGraphInput = {
   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[];
@@ -389,10 +415,25 @@ 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;
 };
 
 /**

package/src/types/run.ts

@@ -101,6 +101,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<

package/src/types/tools.ts

@@ -316,16 +316,14 @@ export type ToolApprovalResponse = {
 };
 
 /**
- * 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';

package/src/utils/run.ts

@@ -96,7 +96,15 @@ export class RunnableCallable<I = unknown, O = unknown> extends Runnable<I, O> {
         mergeConfigs(this.config, options)
       );
     } else {
-      returnValue = await this.func(input, mergeConfigs(this.config, options));
+      const mergedConfig = mergeConfigs(this.config, options);
+      // Set up AsyncLocalStorage context so LangGraph's interrupt() can find
+      // the graph config via getRunnableConfig(). Without this, interrupt()
+      // throws "Called interrupt() outside the context of a graph" because
+      // RunnableCallable (unlike RunnableLambda) doesn't use _callWithConfig.
+      returnValue = await AsyncLocalStorageProviderSingleton.runWithConfig(
+        mergedConfig,
+        () => this.func(input, mergedConfig)
+      );
     }
 
     if (Runnable.isRunnable(returnValue) && this.recurse) {