illuma-agents 1.0.10 → 1.0.12

package/src/tools/__tests__/ToolSearchRegex.integration.test.ts

@@ -0,0 +1,161 @@
+// src/tools/__tests__/ToolSearchRegex.integration.test.ts
+/**
+ * Integration tests for Tool Search Regex.
+ * These tests hit the LIVE Code API and verify end-to-end search functionality.
+ *
+ * Run with: npm test -- ToolSearchRegex.integration.test.ts
+ */
+import { config as dotenvConfig } from 'dotenv';
+dotenvConfig();
+
+import { describe, it, expect, beforeAll } from '@jest/globals';
+import { createToolSearchRegexTool } from '../ToolSearchRegex';
+import { createToolSearchToolRegistry } from '@/test/mockTools';
+
+describe('ToolSearchRegex - Live API Integration', () => {
+  let searchTool: ReturnType<typeof createToolSearchRegexTool>;
+  const toolRegistry = createToolSearchToolRegistry();
+
+  beforeAll(() => {
+    const apiKey = process.env.CODE_EXECUTOR_API_KEY;
+    if (apiKey == null || apiKey === '') {
+      throw new Error(
+        'CODE_EXECUTOR_API_KEY not set. Required for integration tests.'
+      );
+    }
+
+    searchTool = createToolSearchRegexTool({ apiKey, toolRegistry });
+  });
+
+  it('searches for expense-related tools', async () => {
+    const output = await searchTool.invoke({ query: 'expense' });
+
+    expect(typeof output).toBe('string');
+    expect(output).toContain('Found');
+    expect(output).toContain('matching tools');
+    expect(output).toContain('get_expenses');
+    expect(output).toContain('calculate_expense_totals');
+    expect(output).toContain('score: 0.95');
+  }, 10000);
+
+  it('searches for weather tools with OR pattern', async () => {
+    const output = await searchTool.invoke({ query: 'weather|forecast' });
+
+    expect(output).toContain('Found');
+    expect(output).toContain('get_weather');
+    expect(output).toContain('get_forecast');
+  }, 10000);
+
+  it('performs case-insensitive search', async () => {
+    const output = await searchTool.invoke({ query: 'EMAIL' });
+
+    expect(output).toContain('send_email');
+  }, 10000);
+
+  it('searches descriptions only', async () => {
+    const output = await searchTool.invoke({
+      query: 'database',
+      fields: ['description'],
+    });
+
+    expect(output).toContain('Found');
+    expect(output).toContain('Matched in: description');
+    expect(output).toContain('run_database_query');
+  }, 10000);
+
+  it('searches parameter names', async () => {
+    const output = await searchTool.invoke({
+      query: 'query',
+      fields: ['parameters'],
+    });
+
+    expect(output).toContain('Found');
+    expect(output).toContain('Matched in: parameters');
+  }, 10000);
+
+  it('limits results to specified count', async () => {
+    const output = await searchTool.invoke({
+      query: 'get',
+      max_results: 2,
+    });
+
+    expect(output).toContain('Found 2 matching tools');
+    const toolMatches = output.match(/- \w+ \(score:/g);
+    expect(toolMatches?.length).toBe(2);
+  }, 10000);
+
+  it('returns no matches for nonsense pattern', async () => {
+    const output = await searchTool.invoke({
+      query: 'xyznonexistent999',
+    });
+
+    expect(output).toContain('No tools matched');
+    expect(output).toContain('Total tools searched:');
+  }, 10000);
+
+  it('uses regex character classes', async () => {
+    const output = await searchTool.invoke({ query: 'get_[a-z]+' });
+
+    expect(output).toContain('Found');
+    expect(output).toContain('matching tools');
+  }, 10000);
+
+  it('sanitizes dangerous patterns with warning', async () => {
+    const output = await searchTool.invoke({ query: '(a+)+' });
+
+    expect(output).toContain(
+      'Note: The provided pattern was converted to a literal search for safety'
+    );
+    // After sanitization, pattern is shown in the output
+    expect(output).toContain('Total tools searched:');
+    expect(output).toContain('No tools matched');
+  }, 10000);
+
+  it('searches across all fields', async () => {
+    const output = await searchTool.invoke({
+      query: 'text',
+      fields: ['name', 'description', 'parameters'],
+    });
+
+    expect(output).toContain('Found');
+    expect(output).toContain('translate_text');
+  }, 10000);
+
+  it('handles complex regex patterns', async () => {
+    const output = await searchTool.invoke({
+      query: '^(get|create)_.*',
+    });
+
+    expect(output).toContain('Found');
+    expect(output).toContain('matching tools');
+  }, 10000);
+
+  it('prioritizes name matches over description matches', async () => {
+    const output = await searchTool.invoke({ query: 'generate' });
+
+    expect(output).toContain('generate_report');
+    expect(output).toContain('score:');
+
+    const lines = output.split('\n');
+    const generateLine = lines.find((l: string) =>
+      l.includes('generate_report')
+    );
+    expect(generateLine).toContain('score: 0.95'); // Name match = 0.95
+  }, 10000);
+
+  it('finds tools by partial name match', async () => {
+    const output = await searchTool.invoke({ query: 'budget' });
+
+    expect(output).toContain('create_budget');
+  }, 10000);
+
+  it('handles very specific patterns', async () => {
+    const output = await searchTool.invoke({
+      query: 'send_email',
+    });
+
+    expect(output).toContain('Found');
+    expect(output).toContain('send_email');
+    expect(output).toContain('score: 0.95');
+  }, 10000);
+});

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

@@ -0,0 +1,232 @@
+// src/tools/__tests__/ToolSearchRegex.test.ts
+/**
+ * Unit tests for Tool Search Regex.
+ * Tests helper functions and sanitization logic without hitting the API.
+ */
+import { describe, it, expect } from '@jest/globals';
+import {
+  sanitizeRegex,
+  escapeRegexSpecialChars,
+  isDangerousPattern,
+  countNestedGroups,
+  hasNestedQuantifiers,
+} from '../ToolSearchRegex';
+
+describe('ToolSearchRegex', () => {
+  describe('escapeRegexSpecialChars', () => {
+    it('escapes special regex characters', () => {
+      expect(escapeRegexSpecialChars('hello.world')).toBe('hello\\.world');
+      expect(escapeRegexSpecialChars('test*pattern')).toBe('test\\*pattern');
+      expect(escapeRegexSpecialChars('query+result')).toBe('query\\+result');
+      expect(escapeRegexSpecialChars('a?b')).toBe('a\\?b');
+      expect(escapeRegexSpecialChars('(group)')).toBe('\\(group\\)');
+      expect(escapeRegexSpecialChars('[abc]')).toBe('\\[abc\\]');
+      expect(escapeRegexSpecialChars('a|b')).toBe('a\\|b');
+      expect(escapeRegexSpecialChars('a^b$c')).toBe('a\\^b\\$c');
+      expect(escapeRegexSpecialChars('a{2,3}')).toBe('a\\{2,3\\}');
+    });
+
+    it('handles empty string', () => {
+      expect(escapeRegexSpecialChars('')).toBe('');
+    });
+
+    it('handles string with no special chars', () => {
+      expect(escapeRegexSpecialChars('hello_world')).toBe('hello_world');
+      expect(escapeRegexSpecialChars('test123')).toBe('test123');
+    });
+
+    it('handles multiple consecutive special chars', () => {
+      expect(escapeRegexSpecialChars('...')).toBe('\\.\\.\\.');
+      expect(escapeRegexSpecialChars('***')).toBe('\\*\\*\\*');
+    });
+  });
+
+  describe('countNestedGroups', () => {
+    it('counts simple nesting', () => {
+      expect(countNestedGroups('(a)')).toBe(1);
+      expect(countNestedGroups('((a))')).toBe(2);
+      expect(countNestedGroups('(((a)))')).toBe(3);
+    });
+
+    it('counts maximum depth with multiple groups', () => {
+      expect(countNestedGroups('(a)(b)(c)')).toBe(1);
+      expect(countNestedGroups('(a(b)c)')).toBe(2);
+      expect(countNestedGroups('(a(b(c)))')).toBe(3);
+    });
+
+    it('handles mixed nesting levels', () => {
+      expect(countNestedGroups('(a)((b)(c))')).toBe(2);
+      expect(countNestedGroups('((a)(b))((c))')).toBe(2);
+    });
+
+    it('ignores escaped parentheses', () => {
+      expect(countNestedGroups('\\(not a group\\)')).toBe(0);
+      expect(countNestedGroups('(a\\(b\\)c)')).toBe(1);
+    });
+
+    it('handles no groups', () => {
+      expect(countNestedGroups('abc')).toBe(0);
+      expect(countNestedGroups('test.*pattern')).toBe(0);
+    });
+
+    it('handles unbalanced groups', () => {
+      expect(countNestedGroups('((a)')).toBe(2);
+      expect(countNestedGroups('(a))')).toBe(1);
+    });
+  });
+
+  describe('hasNestedQuantifiers', () => {
+    it('detects nested quantifiers', () => {
+      expect(hasNestedQuantifiers('(a+)+')).toBe(true);
+      expect(hasNestedQuantifiers('(a*)*')).toBe(true);
+      expect(hasNestedQuantifiers('(a+)*')).toBe(true);
+      expect(hasNestedQuantifiers('(a*)?')).toBe(true);
+    });
+
+    it('allows safe quantifiers', () => {
+      expect(hasNestedQuantifiers('a+')).toBe(false);
+      expect(hasNestedQuantifiers('(abc)+')).toBe(false);
+      expect(hasNestedQuantifiers('a+b*c?')).toBe(false);
+    });
+
+    it('handles complex patterns', () => {
+      expect(hasNestedQuantifiers('(a|b)+')).toBe(false);
+      // Note: This pattern might not be detected by the simple regex check
+      const complexPattern = '((a|b)+)+';
+      const result = hasNestedQuantifiers(complexPattern);
+      // Just verify it doesn't crash - detection may vary
+      expect(typeof result).toBe('boolean');
+    });
+  });
+
+  describe('isDangerousPattern', () => {
+    it('detects nested quantifiers', () => {
+      expect(isDangerousPattern('(a+)+')).toBe(true);
+      expect(isDangerousPattern('(a*)*')).toBe(true);
+      expect(isDangerousPattern('(.+)+')).toBe(true);
+      expect(isDangerousPattern('(.*)*')).toBe(true);
+    });
+
+    it('detects excessive nesting', () => {
+      expect(isDangerousPattern('((((((a))))))')).toBe(true); // Depth > 5
+    });
+
+    it('detects excessive wildcards', () => {
+      const pattern = '.{1000,}';
+      expect(isDangerousPattern(pattern)).toBe(true);
+    });
+
+    it('allows safe patterns', () => {
+      expect(isDangerousPattern('weather')).toBe(false);
+      expect(isDangerousPattern('get_.*_data')).toBe(false);
+      expect(isDangerousPattern('(a|b|c)')).toBe(false);
+      expect(isDangerousPattern('test\\d+')).toBe(false);
+    });
+
+    it('detects various dangerous patterns', () => {
+      expect(isDangerousPattern('(.*)+')).toBe(true);
+      expect(isDangerousPattern('(.+)*')).toBe(true);
+    });
+  });
+
+  describe('sanitizeRegex', () => {
+    it('returns safe pattern unchanged', () => {
+      const result = sanitizeRegex('weather');
+      expect(result.safe).toBe('weather');
+      expect(result.wasEscaped).toBe(false);
+    });
+
+    it('escapes dangerous patterns', () => {
+      const result = sanitizeRegex('(a+)+');
+      expect(result.safe).toBe('\\(a\\+\\)\\+');
+      expect(result.wasEscaped).toBe(true);
+    });
+
+    it('escapes invalid regex', () => {
+      const result = sanitizeRegex('(unclosed');
+      expect(result.wasEscaped).toBe(true);
+      expect(result.safe).toContain('\\(');
+    });
+
+    it('allows complex but safe patterns', () => {
+      const result = sanitizeRegex('get_[a-z]+_data');
+      expect(result.safe).toBe('get_[a-z]+_data');
+      expect(result.wasEscaped).toBe(false);
+    });
+
+    it('handles alternation patterns', () => {
+      const result = sanitizeRegex('weather|forecast');
+      expect(result.safe).toBe('weather|forecast');
+      expect(result.wasEscaped).toBe(false);
+    });
+  });
+
+  describe('Pattern Validation Edge Cases', () => {
+    it('handles empty pattern', () => {
+      expect(countNestedGroups('')).toBe(0);
+      expect(hasNestedQuantifiers('')).toBe(false);
+      expect(isDangerousPattern('')).toBe(false);
+    });
+
+    it('handles pattern with only quantifiers', () => {
+      expect(hasNestedQuantifiers('+++')).toBe(false);
+      expect(hasNestedQuantifiers('***')).toBe(false);
+    });
+
+    it('handles escaped special sequences', () => {
+      const result = sanitizeRegex('\\d+\\w*\\s?');
+      expect(result.wasEscaped).toBe(false);
+    });
+
+    it('sanitizes exponential backtracking patterns', () => {
+      // These can cause catastrophic backtracking
+      expect(isDangerousPattern('(a+)+')).toBe(true);
+      expect(isDangerousPattern('(a*)*')).toBe(true);
+      expect(isDangerousPattern('(.*)*')).toBe(true);
+    });
+  });
+
+  describe('Real-World Pattern Examples', () => {
+    it('handles common search patterns safely', () => {
+      const safePatterns = [
+        'expense',
+        'weather|forecast',
+        'data.*query',
+        '_tool$',
+      ];
+
+      for (const pattern of safePatterns) {
+        const result = sanitizeRegex(pattern);
+        expect(result.wasEscaped).toBe(false);
+      }
+    });
+
+    it('escapes clearly dangerous patterns', () => {
+      const dangerousPatterns = ['(a+)+', '(.*)+', '(.+)*'];
+
+      for (const pattern of dangerousPatterns) {
+        const result = sanitizeRegex(pattern);
+        expect(result.wasEscaped).toBe(true);
+      }
+    });
+
+    it('handles patterns that may or may not be escaped', () => {
+      // These patterns might be escaped depending on validation logic
+      const edgeCasePatterns = [
+        '(?i)email',
+        '^create_',
+        'get_[a-z]+_info',
+        'get_.*',
+        '((((((a))))))',
+        '(a|a)*',
+      ];
+
+      for (const pattern of edgeCasePatterns) {
+        const result = sanitizeRegex(pattern);
+        // Just verify it returns a result without crashing
+        expect(typeof result.safe).toBe('string');
+        expect(typeof result.wasEscaped).toBe('boolean');
+      }
+    });
+  });
+});

package/src/tools/search/jina-reranker.test.ts

@@ -3,14 +3,14 @@ import { createDefaultLogger } from './utils';
 
 describe('JinaReranker', () => {
   const mockLogger = createDefaultLogger();
-
+  
   describe('constructor', () => {
     it('should use default API URL when no apiUrl is provided', () => {
       const reranker = new JinaReranker({
         apiKey: 'test-key',
         logger: mockLogger,
       });
-
+      
       // Access private property for testing
       const apiUrl = (reranker as any).apiUrl;
       expect(apiUrl).toBe('https://api.jina.ai/v1/rerank');
@@ -23,7 +23,7 @@ describe('JinaReranker', () => {
         apiUrl: customUrl,
         logger: mockLogger,
       });
-
+      
       const apiUrl = (reranker as any).apiUrl;
       expect(apiUrl).toBe(customUrl);
     });
@@ -31,15 +31,15 @@ describe('JinaReranker', () => {
     it('should use environment variable JINA_API_URL when available', () => {
       const originalEnv = process.env.JINA_API_URL;
       process.env.JINA_API_URL = 'https://env-jina-endpoint.com/v1/rerank';
-
+      
       const reranker = new JinaReranker({
         apiKey: 'test-key',
         logger: mockLogger,
       });
-
+      
       const apiUrl = (reranker as any).apiUrl;
       expect(apiUrl).toBe('https://env-jina-endpoint.com/v1/rerank');
-
+      
       // Restore original environment
       if (originalEnv) {
         process.env.JINA_API_URL = originalEnv;
@@ -51,17 +51,17 @@ describe('JinaReranker', () => {
     it('should prioritize explicit apiUrl over environment variable', () => {
       const originalEnv = process.env.JINA_API_URL;
       process.env.JINA_API_URL = 'https://env-jina-endpoint.com/v1/rerank';
-
+      
       const customUrl = 'https://explicit-jina-endpoint.com/v1/rerank';
       const reranker = new JinaReranker({
         apiKey: 'test-key',
         apiUrl: customUrl,
         logger: mockLogger,
       });
-
+      
       const apiUrl = (reranker as any).apiUrl;
       expect(apiUrl).toBe(customUrl);
-
+      
       // Restore original environment
       if (originalEnv) {
         process.env.JINA_API_URL = originalEnv;
@@ -79,19 +79,19 @@ describe('JinaReranker', () => {
         apiUrl: customUrl,
         logger: mockLogger,
       });
-
+      
       const logSpy = jest.spyOn(mockLogger, 'debug');
-
+      
       try {
         await reranker.rerank('test query', ['document1', 'document2'], 2);
       } catch (error) {
         // Expected to fail due to missing API key, but we can check the log
       }
-
+      
       expect(logSpy).toHaveBeenCalledWith(
         expect.stringContaining(`Reranking 2 chunks with Jina using API URL: ${customUrl}`)
       );
-
+      
       logSpy.mockRestore();
     });
   });
@@ -99,7 +99,7 @@ describe('JinaReranker', () => {
 
 describe('createReranker', () => {
   const { createReranker } = require('./rerankers');
-
+  
   it('should create JinaReranker with jinaApiUrl when provided', () => {
     const customUrl = 'https://custom-jina-endpoint.com/v1/rerank';
     const reranker = createReranker({
@@ -107,7 +107,7 @@ describe('createReranker', () => {
       jinaApiKey: 'test-key',
       jinaApiUrl: customUrl,
     });
-
+    
     expect(reranker).toBeInstanceOf(JinaReranker);
     const apiUrl = (reranker as any).apiUrl;
     expect(apiUrl).toBe(customUrl);
@@ -118,7 +118,7 @@ describe('createReranker', () => {
       rerankerType: 'jina',
       jinaApiKey: 'test-key',
     });
-
+    
     expect(reranker).toBeInstanceOf(JinaReranker);
     const apiUrl = (reranker as any).apiUrl;
     expect(apiUrl).toBe('https://api.jina.ai/v1/rerank');

package/src/tools/search/schema.ts

@@ -9,17 +9,10 @@ export enum DATE_RANGE {
 }
 
 export const DEFAULT_QUERY_DESCRIPTION = `
-Search query OR a URL for direct content extraction.
-
-**IMPORTANT - URL REQUESTS:**
-If the user provides a URL to read, summarize, or analyze, you MUST include the complete URL in this field.
-- User says: "Summarize https://example.com/article" → query: "https://example.com/article"
-- User says: "What does this page say? https://news.site/story" → query: "https://news.site/story"
-DO NOT convert URLs into search keywords. Pass the URL directly.
-
-**SEARCH MODE GUIDELINES:**
+GUIDELINES:
 - Start broad, then narrow: Begin with key concepts, then refine with specifics
 - Think like sources: Use terminology experts would use in the field
+- Consider perspective: Frame queries from different viewpoints for better results
 - Quality over quantity: A precise 3-4 word query often beats lengthy sentences
 
 TECHNIQUES (combine for power searches):
@@ -28,6 +21,11 @@ TECHNIQUES (combine for power searches):
 - SITE-SPECIFIC: Restrict to websites (site:edu research)
 - FILETYPE: Find specific documents (filetype:pdf study)
 - OR OPERATOR: Find alternatives (electric OR hybrid cars)
+- DATE RANGE: Recent information (data after:2020)
+- WILDCARDS: Use * for unknown terms (how to * bread)
+- SPECIFIC QUESTIONS: Use who/what/when/where/why/how
+- DOMAIN TERMS: Include technical terminology for specialized topics
+- CONCISE TERMS: Prioritize keywords over sentences
 `.trim();
 
 export const DEFAULT_COUNTRY_DESCRIPTION =

package/src/types/graph.ts

@@ -18,7 +18,7 @@ import type {
 import type { RunnableConfig, Runnable } from '@langchain/core/runnables';
 import type { ChatGenerationChunk } from '@langchain/core/outputs';
 import type { GoogleAIToolType } from '@langchain/google-common';
-import type { ToolMap, ToolEndEvent, GenericTool } from '@/types/tools';
+import type { ToolMap, ToolEndEvent, GenericTool, LCTool } from '@/types/tools';
 import type { Providers, Callback, GraphNodeKeys } from '@/common';
 import type { StandardGraph, MultiAgentGraph } from '@/graphs';
 import type { ClientOptions } from '@/types/llm';
@@ -369,4 +369,17 @@ export interface AgentInputs {
   reasoningKey?: 'reasoning_content' | 'reasoning';
   /** Format content blocks as strings (for legacy compatibility i.e. Ollama/Azure Serverless) */
   useLegacyContent?: boolean;
+  /**
+   * Tool definitions for all tools, including deferred and programmatic.
+   * Used for tool search and programmatic tool calling.
+   * Maps tool name to LCTool definition.
+   */
+  toolRegistry?: Map<string, LCTool>;
+  /**
+   * Dynamic context that changes per-request (e.g., current time, user info).
+   * This is injected as a user message rather than system prompt to preserve cache.
+   * Keeping this separate from instructions ensures the system message stays static
+   * and can be cached by Bedrock/Anthropic prompt caching.
+   */
+  dynamicContext?: string;
 }