@illuma-ai/agents 1.1.5 → 1.1.7

package/src/graphs/gapFeatures.test.ts

@@ -538,14 +538,21 @@ describe('Proactive Summarization — Context Pressure', () => {
       indexTokenCountMap[String(i)] = tokensPerMsg;
     }
 
-    const utilization = getContextUtilization(indexTokenCountMap, 0, maxContextTokens);
+    const utilization = getContextUtilization(
+      indexTokenCountMap,
+      0,
+      maxContextTokens
+    );
     const threshold = PROACTIVE_SUMMARY_THRESHOLD * 100; // 80
 
     expect(utilization).toBeGreaterThanOrEqual(threshold);
     // At 82%, proactive summary should fire
     // But pruning should NOT have happened yet (context < 90% safety factor)
     const effectiveBudget = Math.floor(maxContextTokens * 0.9); // CONTEXT_SAFETY_FACTOR
-    const totalTokens = Object.values(indexTokenCountMap).reduce((s, v) => (s ?? 0) + (v ?? 0), 0) as number;
+    const totalTokens = Object.values(indexTokenCountMap).reduce(
+      (s, v) => (s ?? 0) + (v ?? 0),
+      0
+    ) as number;
     expect(totalTokens).toBeLessThan(effectiveBudget);
   });
 
@@ -559,7 +566,11 @@ describe('Proactive Summarization — Context Pressure', () => {
       indexTokenCountMap[String(i)] = tokensPerMsg;
     }
 
-    const utilization = getContextUtilization(indexTokenCountMap, 0, maxContextTokens);
+    const utilization = getContextUtilization(
+      indexTokenCountMap,
+      0,
+      maxContextTokens
+    );
     expect(utilization).toBeLessThan(PROACTIVE_SUMMARY_THRESHOLD * 100);
   });
 
@@ -622,7 +633,11 @@ describe('Proactive Summarization — Context Pressure', () => {
       '0': 210_000, // system + everything
     };
 
-    const utilization = getContextUtilization(indexTokenCountMap, 0, maxContextTokens);
+    const utilization = getContextUtilization(
+      indexTokenCountMap,
+      0,
+      maxContextTokens
+    );
     expect(utilization).toBeGreaterThan(100);
 
     // Even at 100%+, we use the existing cached summary — no error thrown
@@ -637,7 +652,10 @@ describe('Proactive Summarization — Context Pressure', () => {
 
 import { applyCalibration as _applyCalibration } from '@/utils/pruneCalibration';
 import { COMPACTION_RECENT_ROUNDS } from '@/common/constants';
-import { buildFileManifestBlock, FILE_MANIFEST_PREFIX } from '@/utils/fileManifest';
+import {
+  buildFileManifestBlock,
+  FILE_MANIFEST_PREFIX,
+} from '@/utils/fileManifest';
 import type { FileManifestEntry } from '@/types/graph';
 
 describe('Context Compaction — Windowed View (no message deletion)', () => {
@@ -655,7 +673,14 @@ describe('Context Compaction — Windowed View (no message deletion)', () => {
     tokenCounter: TokenCounter;
     fileManifest?: FileManifestEntry[];
   }) {
-    const { messages, indexTokenCountMap, maxTokens, summary, tokenCounter, fileManifest } = opts;
+    const {
+      messages,
+      indexTokenCountMap,
+      maxTokens,
+      summary,
+      tokenCounter,
+      fileManifest,
+    } = opts;
 
     const systemMsg = messages[0]?.getType() === 'system' ? messages[0] : null;
     const systemTokens = systemMsg != null ? (indexTokenCountMap[0] ?? 0) : 0;
@@ -711,7 +736,11 @@ describe('Context Compaction — Windowed View (no message deletion)', () => {
 
     // Inject file manifest when files exist and messages are being compacted
     let fileManifestMsg: SystemMessage | null = null;
-    if (fileManifest && fileManifest.length > 0 && compactedMessages.length > 0) {
+    if (
+      fileManifest &&
+      fileManifest.length > 0 &&
+      compactedMessages.length > 0
+    ) {
       const manifestBlock = buildFileManifestBlock(fileManifest);
       if (manifestBlock) {
         fileManifestMsg = new SystemMessage(manifestBlock);
@@ -721,7 +750,13 @@ describe('Context Compaction — Windowed View (no message deletion)', () => {
 
     view.push(...recentMessages);
 
-    return { view, compactedMessages, recentMessages, usedTokens, fileManifestMsg };
+    return {
+      view,
+      compactedMessages,
+      recentMessages,
+      usedTokens,
+      fileManifestMsg,
+    };
   }
 
   it('builds a windowed view without deleting any messages', () => {
@@ -802,7 +837,11 @@ describe('Context Compaction — Windowed View (no message deletion)', () => {
         content: 'Let me search',
         tool_calls: [{ id: 'tc_1', name: 'web_search', args: {} }],
       }),
-      new ToolMessage({ content: 'Search results', tool_call_id: 'tc_1', name: 'web_search' }),
+      new ToolMessage({
+        content: 'Search results',
+        tool_call_id: 'tc_1',
+        name: 'web_search',
+      }),
       new AIMessage('Based on the search results...'),
       new HumanMessage('latest question'),
       new AIMessage('latest answer'),
@@ -850,13 +889,14 @@ describe('Context Compaction — Windowed View (no message deletion)', () => {
 
     // Large summary eats into the budget
     const largeSummary = 'S'.repeat(1000); // ~250 tokens
-    const { view: viewWithSummary, recentMessages: recentWithSummary } = buildWindowedView({
-      messages,
-      indexTokenCountMap,
-      maxTokens: 800,
-      summary: largeSummary,
-      tokenCounter: simpleTokenCounter,
-    });
+    const { view: viewWithSummary, recentMessages: recentWithSummary } =
+      buildWindowedView({
+        messages,
+        indexTokenCountMap,
+        maxTokens: 800,
+        summary: largeSummary,
+        tokenCounter: simpleTokenCounter,
+      });
 
     // Without summary — more recent messages fit
     const { recentMessages: recentWithout } = buildWindowedView({
@@ -872,9 +912,7 @@ describe('Context Compaction — Windowed View (no message deletion)', () => {
 
   it('with summary, limits window to last 2 rounds (not budget-filling)', () => {
     // 20 messages = 10 rounds. With summary, should only keep last 2 rounds (4 msgs).
-    const messages: BaseMessage[] = [
-      new SystemMessage('System prompt'),
-    ];
+    const messages: BaseMessage[] = [new SystemMessage('System prompt')];
     for (let i = 0; i < 20; i++) {
       messages.push(
         i % 2 === 0
@@ -975,7 +1013,12 @@ describe('Context Compaction — Windowed View (no message deletion)', () => {
 
     const manifest: FileManifestEntry[] = [
       { fileId: 'f1', filename: 'report.pdf', contentId: 'abc123' },
-      { fileId: 'f2', filename: 'data.csv', contentId: 'def456', source: 'local' },
+      {
+        fileId: 'f2',
+        filename: 'data.csv',
+        contentId: 'def456',
+        source: 'local',
+      },
     ];
 
     const { view, compactedMessages, fileManifestMsg } = buildWindowedView({
@@ -1001,8 +1044,8 @@ describe('Context Compaction — Windowed View (no message deletion)', () => {
 
     // View order: [system] + [summary] + [file manifest] + [recent messages]
     expect(view[0].getType()).toBe('system');
-    expect((view[1].content as string)).toContain('[Conversation Summary]');
-    expect((view[2].content as string)).toContain(FILE_MANIFEST_PREFIX);
+    expect(view[1].content as string).toContain('[Conversation Summary]');
+    expect(view[2].content as string).toContain(FILE_MANIFEST_PREFIX);
     // Recent messages follow
     expect(view.length).toBeGreaterThan(3);
   });

package/src/tools/ToolNode.ts

@@ -19,6 +19,7 @@ import type {
 import type { BaseMessage, AIMessage } from '@langchain/core/messages';
 import type { StructuredToolInterface } from '@langchain/core/tools';
 import type * as t from '@/types';
+import { ExecutionContext } from './approval/constants';
 import { RunnableCallable } from '@/utils';
 import { processToolOutput } from '@/utils/toonFormat';
 import { safeDispatchCustomEvent } from '@/utils/events';
@@ -179,8 +180,8 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
     const { defaultPolicy, overrides, executionContext } =
       this.toolApprovalConfig;
 
-    // Scheduled and browser executions bypass all approval checks
-    if (executionContext === 'scheduled' || executionContext === 'browser') {
+    // Scheduled executions bypass all approval checks
+    if (executionContext === ExecutionContext.SCHEDULED) {
       return false;
     }
 
@@ -1001,22 +1002,20 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
           (c) => !this.directToolNames!.has(c.name)
         );
 
-        const directOutputs: (BaseMessage | Command)[] =
+        // Run direct tools and event tools in parallel — they are independent
+        const [directOutputs, eventOutputs] = (await Promise.all([
           directCalls.length > 0
-            ? await Promise.all(
-                directCalls.map((call) => this.runTool(call, config))
-              )
-            : [];
+            ? Promise.all(directCalls.map((call) => this.runTool(call, config)))
+            : [],
+          eventCalls.length > 0
+            ? this.dispatchToolEvents(eventCalls, config)
+            : [],
+        ])) as [(BaseMessage | Command)[], ToolMessage[]];
 
         if (directCalls.length > 0 && directOutputs.length > 0) {
           this.handleRunToolCompletions(directCalls, directOutputs, config);
         }
 
-        const eventOutputs: ToolMessage[] =
-          eventCalls.length > 0
-            ? await this.dispatchToolEvents(eventCalls, config)
-            : [];
-
         outputs = [...directOutputs, ...eventOutputs];
       } else {
         outputs = await Promise.all(

package/src/tools/__tests__/ToolApproval.test.ts

@@ -264,46 +264,14 @@ describe('HITL Tool Approval - Policy Evaluation', () => {
     );
   });
 
-  test('browser execution context bypasses all approvals', async () => {
-    // Browser extension has no HITL UI — all approvals should be auto-granted
-    const toolNode = new ToolNode({
-      tools: [sendEmailTool],
-      toolApprovalConfig: {
-        defaultPolicy: 'always',
-        executionContext: 'browser',
-      },
-    });
-
-    const input = {
-      messages: [
-        new AIMessage({
-          content: '',
-          tool_calls: [
-            {
-              name: 'send_email',
-              args: { to: 'user@example.com', subject: 'Test' },
-              id: 'call_browser_1',
-              type: 'tool_call' as const,
-            },
-          ],
-        }),
-      ],
-    };
-
-    // Should execute without interruption because context is 'browser'
-    const result = await toolNode.invoke(input);
-    expect(result.messages).toHaveLength(1);
-    expect((result.messages[0] as ToolMessage).content).toContain('sent');
-  });
-
-  test('browser context bypasses custom function policy', async () => {
-    // Even a custom function that always returns true should be skipped in browser context
+  test('scheduled context bypasses custom function policy', async () => {
+    // Even a custom function that always returns true should be skipped in scheduled context
     const alwaysRequire = (): boolean => true;
     const toolNode = new ToolNode({
       tools: [echoTool],
       toolApprovalConfig: {
         defaultPolicy: alwaysRequire,
-        executionContext: 'browser',
+        executionContext: 'scheduled',
       },
     });
 
@@ -314,8 +282,8 @@ describe('HITL Tool Approval - Policy Evaluation', () => {
           tool_calls: [
             {
               name: 'echo',
-              args: { message: 'browser test' },
-              id: 'call_browser_2',
+              args: { message: 'scheduled test' },
+              id: 'call_sched_2',
               type: 'tool_call' as const,
             },
           ],
@@ -326,17 +294,17 @@ describe('HITL Tool Approval - Policy Evaluation', () => {
     const result = await toolNode.invoke(input);
     expect(result.messages).toHaveLength(1);
     expect((result.messages[0] as ToolMessage).content).toContain(
-      'Echo: browser test'
+      'Echo: scheduled test'
     );
   });
 
-  test('browser context bypasses per-tool overrides', async () => {
-    // Even with an explicit 'always' override for the tool, browser context should skip it
+  test('scheduled context bypasses per-tool overrides', async () => {
+    // Even with an explicit 'always' override for the tool, scheduled context should skip it
     const toolNode = new ToolNode({
       tools: [searchTool],
       toolApprovalConfig: {
         defaultPolicy: 'never',
-        executionContext: 'browser',
+        executionContext: 'scheduled',
         overrides: {
           search: 'always',
         },
@@ -350,8 +318,8 @@ describe('HITL Tool Approval - Policy Evaluation', () => {
           tool_calls: [
             {
               name: 'search',
-              args: { query: 'browser override test' },
-              id: 'call_browser_3',
+              args: { query: 'scheduled override test' },
+              id: 'call_sched_3',
               type: 'tool_call' as const,
             },
           ],
@@ -362,12 +330,12 @@ describe('HITL Tool Approval - Policy Evaluation', () => {
     const result = await toolNode.invoke(input);
     expect(result.messages).toHaveLength(1);
     expect((result.messages[0] as ToolMessage).content).toContain(
-      'Result for: browser override test'
+      'Result for: scheduled override test'
     );
   });
 
-  test('interactive context still requires approval (browser does not)', async () => {
-    // Verify that 'interactive' context DOES require approval (contrasts with browser)
+  test('interactive context still requires approval (scheduled does not)', async () => {
+    // Verify that 'interactive' context DOES require approval (contrasts with scheduled)
     const approvalEvents: t.ToolApprovalEvent[] = [];
     const { compiled, config } = createTestGraph(
       [sendEmailTool],
@@ -709,6 +677,92 @@ describe('HITL Tool Approval - Event-Driven Flow', () => {
     expect(toolMessages[0].content.toString()).toContain('user@example.com');
   });
 
+  test('approval promise rejection is handled gracefully (host error)', async () => {
+    const toolNode = new ToolNode({
+      tools: [echoTool] as t.GenericTool[],
+      toolApprovalConfig: {
+        defaultPolicy: 'always',
+        executionContext: 'interactive',
+      },
+    });
+
+    const StateAnnotation = Annotation.Root({
+      messages: Annotation<BaseMessage[]>({
+        reducer: messagesStateReducer,
+        default: () => [],
+      }),
+    });
+
+    let callCount = 0;
+    const callModel = async (_state: {
+      messages: BaseMessage[];
+    }): Promise<{ messages: BaseMessage[] }> => {
+      callCount++;
+      if (callCount === 1) {
+        return {
+          messages: [
+            new AIMessage({
+              content: '',
+              tool_calls: [
+                {
+                  name: 'echo',
+                  args: { message: 'test' },
+                  id: 'call_reject_1',
+                  type: 'tool_call' as const,
+                },
+              ],
+            }),
+          ],
+        };
+      }
+      return { messages: [new AIMessage({ content: 'Recovered.' })] };
+    };
+
+    const routeMessage = (state: typeof StateAnnotation.State): string =>
+      toolsCondition(state, 'tools');
+
+    const workflow = new StateGraph(StateAnnotation)
+      .addNode('agent', callModel)
+      .addNode('tools', toolNode)
+      .addEdge(START, 'agent')
+      .addConditionalEdges('agent', routeMessage)
+      .addEdge('tools', 'agent');
+
+    const compiled = workflow.compile();
+    const config: Partial<RunnableConfig> & { version: 'v1' | 'v2' } = {
+      version: 'v2',
+      callbacks: [
+        {
+          handleCustomEvent: async (
+            eventName: string,
+            data: unknown
+          ): Promise<void> => {
+            if (eventName === GraphEvents.ON_TOOL_APPROVAL_REQUIRED) {
+              const event = data as t.ToolApprovalEvent;
+              // Simulate host-side error (e.g., stream disconnected)
+              event.reject(new Error('Stream closed before approval'));
+            }
+          },
+        },
+      ],
+    };
+
+    // The graph should handle rejection without crashing
+    const result = await compiled.invoke(
+      { messages: [new HumanMessage('Say hello')] },
+      config
+    );
+
+    // Should have a tool message with error content
+    const toolMessages = result.messages.filter(
+      (m: BaseMessage) => m._getType() === 'tool'
+    );
+    expect(toolMessages.length).toBeGreaterThan(0);
+    // Agent should continue after rejection
+    const lastMessage = result.messages[result.messages.length - 1];
+    expect(lastMessage._getType()).toBe('ai');
+  });
+
   test('multiple tool calls each get individual approval', async () => {
     const approvalEvents: t.ToolApprovalEvent[] = [];
 

package/src/tools/__tests__/ToolNode.hitl.test.ts

@@ -125,15 +125,16 @@ describe('ToolNode HITL approval bypass', () => {
       );
     });
 
-    it('returns false for all tools when executionContext is browser', () => {
+    it('returns false for all tools when executionContext is scheduled', () => {
       const node = createToolNode({
         toolApprovalConfig: {
           defaultPolicy: 'always',
-          executionContext: 'browser',
+          executionContext: 'scheduled',
         },
       });
 
       expect(callRequiresApproval(node, 'content_tool')).toBe(false);
+      expect(callRequiresApproval(node, 'send_email')).toBe(false);
     });
   });
 

package/src/tools/approval/__tests__/constants.test.ts

@@ -0,0 +1,74 @@
+import {
+  ExecutionContext,
+  ApprovalPolicy,
+  ApprovalTier,
+  RiskLevel,
+  ActionCategory,
+  MCP_DELIMITER,
+} from '../constants';
+
+describe('HITL Approval Constants', () => {
+  describe('ExecutionContext', () => {
+    it('should have INTERACTIVE and SCHEDULED values', () => {
+      expect(ExecutionContext.INTERACTIVE).toBe('interactive');
+      expect(ExecutionContext.SCHEDULED).toBe('scheduled');
+    });
+
+    it('should only have 2 values (no dead "browser" context)', () => {
+      const values = Object.values(ExecutionContext);
+      expect(values).toHaveLength(2);
+      expect(values).toEqual(['interactive', 'scheduled']);
+    });
+  });
+
+  describe('ApprovalPolicy', () => {
+    it('should have ALWAYS and NEVER values', () => {
+      expect(ApprovalPolicy.ALWAYS).toBe('always');
+      expect(ApprovalPolicy.NEVER).toBe('never');
+    });
+  });
+
+  describe('ApprovalTier', () => {
+    it('should define the 3-tier evaluation pipeline', () => {
+      expect(ApprovalTier.AUTO_APPROVE).toBe('auto_approve');
+      expect(ApprovalTier.RULE_BASED).toBe('rule_based');
+      expect(ApprovalTier.KEYWORD_FALLBACK).toBe('keyword_fallback');
+    });
+  });
+
+  describe('RiskLevel', () => {
+    it('should define 5 risk levels from NONE to CRITICAL', () => {
+      expect(RiskLevel.NONE).toBe('none');
+      expect(RiskLevel.LOW).toBe('low');
+      expect(RiskLevel.MEDIUM).toBe('medium');
+      expect(RiskLevel.HIGH).toBe('high');
+      expect(RiskLevel.CRITICAL).toBe('critical');
+    });
+
+    it('should have exactly 5 values', () => {
+      expect(Object.values(RiskLevel)).toHaveLength(5);
+    });
+  });
+
+  describe('ActionCategory', () => {
+    it('should define action categories', () => {
+      expect(ActionCategory.READ).toBe('read');
+      expect(ActionCategory.WRITE).toBe('write');
+      expect(ActionCategory.DELETE).toBe('delete');
+      expect(ActionCategory.SEND).toBe('send');
+      expect(ActionCategory.EXECUTE).toBe('execute');
+      expect(ActionCategory.FINANCIAL).toBe('financial');
+      expect(ActionCategory.ACCOUNT).toBe('account');
+    });
+  });
+
+  describe('MCP_DELIMITER', () => {
+    it('should match Constants.mcp_delimiter from @ranger/data-provider', () => {
+      expect(MCP_DELIMITER).toBe('_mcp_');
+    });
+
+    it('should NOT be the old double-underscore format', () => {
+      expect(MCP_DELIMITER).not.toBe('__mcp__');
+    });
+  });
+});

package/src/tools/approval/constants.ts

@@ -0,0 +1,109 @@
+/**
+ * Shared HITL (Human-in-the-Loop) constants and enums.
+ *
+ * Single source of truth for approval-related values consumed by
+ * the agents library, ranger backend, and browser extension.
+ *
+ * @module approval/constants
+ */
+
+// ============================================================================
+// Execution Context
+// ============================================================================
+
+/**
+ * Execution context determines whether HITL approval is required.
+ *
+ * - `INTERACTIVE`: User is present in the chat session — approval prompts are shown.
+ * - `SCHEDULED`: Automated/scheduled execution — all approvals are auto-granted.
+ */
+export enum ExecutionContext {
+  INTERACTIVE = 'interactive',
+  SCHEDULED = 'scheduled',
+}
+
+// ============================================================================
+// Approval Policy
+// ============================================================================
+
+/**
+ * Static approval policy values.
+ *
+ * - `ALWAYS`: Every tool call requires approval (strictest).
+ * - `NEVER`: No tool call requires approval (used for auto-approved tools).
+ */
+export enum ApprovalPolicy {
+  ALWAYS = 'always',
+  NEVER = 'never',
+}
+
+// ============================================================================
+// Approval Tier
+// ============================================================================
+
+/**
+ * Three-tier policy evaluation pipeline.
+ * Higher tiers are checked first; once a tier matches, lower tiers are skipped.
+ *
+ * - `AUTO_APPROVE`: Built-in tools that always skip approval (Tier 1).
+ * - `RULE_BASED`: Per-tool argument-aware rules (Tier 2).
+ * - `KEYWORD_FALLBACK`: Token-based keyword matching on tool name (Tier 3).
+ */
+export enum ApprovalTier {
+  AUTO_APPROVE = 'auto_approve',
+  RULE_BASED = 'rule_based',
+  KEYWORD_FALLBACK = 'keyword_fallback',
+}
+
+// ============================================================================
+// Risk Level
+// ============================================================================
+
+/**
+ * Risk classification for tool calls.
+ * Used for audit logging and future UI customization (e.g., showing risk badges).
+ *
+ * - `NONE`: Read-only, no side effects (search, list, get).
+ * - `LOW`: Minor side effects (bookmark, star, mark as read).
+ * - `MEDIUM`: User-specific mutations (send email to known contact).
+ * - `HIGH`: Destructive or irreversible (delete, modify critical data).
+ * - `CRITICAL`: Multi-system impact (transfer funds, delete account).
+ */
+export enum RiskLevel {
+  NONE = 'none',
+  LOW = 'low',
+  MEDIUM = 'medium',
+  HIGH = 'high',
+  CRITICAL = 'critical',
+}
+
+// ============================================================================
+// Action Category
+// ============================================================================
+
+/**
+ * Semantic category for tool actions.
+ * Maps action keywords to high-level intent for risk classification.
+ */
+export enum ActionCategory {
+  READ = 'read',
+  WRITE = 'write',
+  DELETE = 'delete',
+  SEND = 'send',
+  EXECUTE = 'execute',
+  FINANCIAL = 'financial',
+  ACCOUNT = 'account',
+}
+
+// ============================================================================
+// MCP Delimiter
+// ============================================================================
+
+/**
+ * Delimiter used in MCP tool names to separate the tool name from the server key.
+ *
+ * Example: `send_email_mcp_outlook` → tool = `send_email`, server = `outlook`
+ *
+ * Must match `Constants.mcp_delimiter` in `@ranger/data-provider`.
+ */
+export const MCP_DELIMITER = '_mcp_';

package/src/types/tools.ts

@@ -217,8 +217,12 @@ export type ProgrammaticCache = { toolMap: ToolMap; toolDefs: LCTool[] };
  * Execution context determines whether HITL approval is required.
  * - 'interactive': User is present in the chat, approval prompts are shown.
  * - 'scheduled': Automated/scheduled execution, approval is auto-granted.
+ *
+ * Re-exported from approval/constants for convenience.
+ * @see ExecutionContext enum in approval/constants.ts
  */
-export type ExecutionContext = 'interactive' | 'scheduled' | 'browser';
+export type ExecutionContext =
+  `${import('../tools/approval/constants').ExecutionContext}`;
 
 /**
  * Policy for when a tool requires human approval.

package/src/utils/fileManifest.ts

@@ -23,7 +23,9 @@ export const FILE_MANIFEST_PREFIX = '[Conversation Files]';
  * @param manifest - Array of file metadata entries
  * @returns Formatted text block, or empty string if manifest is empty/undefined
  */
-export function buildFileManifestBlock(manifest: FileManifestEntry[] | undefined): string {
+export function buildFileManifestBlock(
+  manifest: FileManifestEntry[] | undefined
+): string {
   if (!manifest || manifest.length === 0) {
     return '';
   }