@librechat/agents 3.0.36 → 3.0.40

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.LIBRECHAT_CODE_API_KEY;
+    if (apiKey == null || apiKey === '') {
+      throw new Error(
+        'LIBRECHAT_CODE_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/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,10 @@ 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>;
 }

package/src/types/tools.ts

@@ -35,6 +35,12 @@ export type ToolNodeOptions = {
     data: ToolErrorData,
     metadata?: Record<string, unknown>
   ) => Promise<void>;
+  /** Tools available for programmatic code execution (allowed_callers includes 'code_execution') */
+  programmaticToolMap?: ToolMap;
+  /** Tool definitions for programmatic code execution (sent to Code API for stub generation) */
+  programmaticToolDefs?: LCTool[];
+  /** Tool registry for tool search (deferred tool definitions) */
+  toolRegistry?: LCToolRegistry;
 };
 
 export type ToolNodeConstructorParams = ToolRefs & ToolNodeOptions;
@@ -78,3 +84,163 @@ export type ExecuteResult = {
   stderr: string;
   files?: FileRefs;
 };
+
+/** JSON Schema type definition for tool parameters */
+export type JsonSchemaType = {
+  type:
+    | 'string'
+    | 'number'
+    | 'integer'
+    | 'float'
+    | 'boolean'
+    | 'array'
+    | 'object';
+  enum?: string[];
+  items?: JsonSchemaType;
+  properties?: Record<string, JsonSchemaType>;
+  required?: string[];
+  description?: string;
+  additionalProperties?: boolean | JsonSchemaType;
+};
+
+/**
+ * Specifies which contexts can invoke a tool (inspired by Anthropic's allowed_callers)
+ * - 'direct': Only callable directly by the LLM (default if omitted)
+ * - 'code_execution': Only callable from within programmatic code execution
+ */
+export type AllowedCaller = 'direct' | 'code_execution';
+
+/** Tool definition with optional deferred loading and caller restrictions */
+export type LCTool = {
+  name: string;
+  description?: string;
+  parameters?: JsonSchemaType;
+  /** When true, tool is not loaded into context initially (for tool search) */
+  defer_loading?: boolean;
+  /**
+   * Which contexts can invoke this tool.
+   * Default: ['direct'] (only callable directly by LLM)
+   * Options: 'direct', 'code_execution'
+   */
+  allowed_callers?: AllowedCaller[];
+};
+
+/** Map of tool names to tool definitions */
+export type LCToolRegistry = Map<string, LCTool>;
+
+/** Parameters for creating a Tool Search Regex tool */
+export type ToolSearchRegexParams = {
+  apiKey?: string;
+  toolRegistry?: LCToolRegistry;
+  onlyDeferred?: boolean;
+  baseUrl?: string;
+  [key: string]: unknown;
+};
+
+/** Simplified tool metadata for search purposes */
+export type ToolMetadata = {
+  name: string;
+  description: string;
+  parameters?: JsonSchemaType;
+};
+
+/** Individual search result for a matching tool */
+export type ToolSearchResult = {
+  tool_name: string;
+  match_score: number;
+  matched_field: string;
+  snippet: string;
+};
+
+/** Response from the tool search operation */
+export type ToolSearchResponse = {
+  tool_references: ToolSearchResult[];
+  total_tools_searched: number;
+  pattern_used: string;
+};
+
+/** Artifact returned alongside the formatted search results */
+export type ToolSearchArtifact = {
+  tool_references: ToolSearchResult[];
+  metadata: {
+    total_searched: number;
+    pattern: string;
+    error?: string;
+  };
+};
+
+// ============================================================================
+// Programmatic Tool Calling Types
+// ============================================================================
+
+/**
+ * Tool call requested by the Code API during programmatic execution
+ */
+export type PTCToolCall = {
+  /** Unique ID like "call_001" */
+  id: string;
+  /** Tool name */
+  name: string;
+  /** Input parameters */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  input: Record<string, any>;
+};
+
+/**
+ * Tool result sent back to the Code API
+ */
+export type PTCToolResult = {
+  /** Matches PTCToolCall.id */
+  call_id: string;
+  /** Tool execution result (any JSON-serializable value) */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  result: any;
+  /** Whether tool execution failed */
+  is_error: boolean;
+  /** Error details if is_error=true */
+  error_message?: string;
+};
+
+/**
+ * Response from the Code API for programmatic execution
+ */
+export type ProgrammaticExecutionResponse = {
+  status: 'tool_call_required' | 'completed' | 'error' | unknown;
+  session_id?: string;
+
+  /** Present when status='tool_call_required' */
+  continuation_token?: string;
+  tool_calls?: PTCToolCall[];
+
+  /** Present when status='completed' */
+  stdout?: string;
+  stderr?: string;
+  files?: FileRefs;
+
+  /** Present when status='error' */
+  error?: string;
+};
+
+/**
+ * Artifact returned by the PTC tool
+ */
+export type ProgrammaticExecutionArtifact = {
+  session_id?: string;
+  files?: FileRefs;
+};
+
+/**
+ * Initialization parameters for the PTC tool
+ */
+export type ProgrammaticToolCallingParams = {
+  /** Code API key (or use CODE_API_KEY env var) */
+  apiKey?: string;
+  /** Code API base URL (or use CODE_BASEURL env var) */
+  baseUrl?: string;
+  /** Safety limit for round-trips (default: 20) */
+  maxRoundTrips?: number;
+  /** HTTP proxy URL */
+  proxy?: string;
+  /** Environment variable key for API key */
+  [key: string]: unknown;
+};