@librechat/agents 3.0.65 → 3.0.67

package/src/tools/{ToolSearchRegex.ts → ToolSearch.ts}

@@ -1,4 +1,4 @@
-// src/tools/ToolSearchRegex.ts
+// src/tools/ToolSearch.ts
 import { z } from 'zod';
 import { config } from 'dotenv';
 import fetch, { RequestInit } from 'node-fetch';
@@ -20,28 +20,43 @@ const MAX_REGEX_COMPLEXITY = 5;
 /** Default search timeout in milliseconds */
 const SEARCH_TIMEOUT = 5000;
 
-const ToolSearchRegexSchema = z.object({
-  query: z
-    .string()
-    .min(1)
-    .max(MAX_PATTERN_LENGTH)
-    .describe(
-      'Regex pattern to search tool names and descriptions. Special regex characters will be sanitized for safety.'
-    ),
-  fields: z
-    .array(z.enum(['name', 'description', 'parameters']))
-    .optional()
-    .default(['name', 'description'])
-    .describe('Which fields to search. Default: name and description'),
-  max_results: z
-    .number()
-    .int()
-    .min(1)
-    .max(50)
-    .optional()
-    .default(10)
-    .describe('Maximum number of matching tools to return'),
-});
+/** Zod schema type for tool search parameters */
+type ToolSearchSchema = z.ZodObject<{
+  query: z.ZodString;
+  fields: z.ZodDefault<
+    z.ZodOptional<z.ZodArray<z.ZodEnum<['name', 'description', 'parameters']>>>
+  >;
+  max_results: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+}>;
+
+/**
+ * Creates the Zod schema with dynamic query description based on mode.
+ * @param mode - The search mode determining query interpretation
+ * @returns Zod schema for tool search parameters
+ */
+function createToolSearchSchema(mode: t.ToolSearchMode): ToolSearchSchema {
+  const queryDescription =
+    mode === 'local'
+      ? 'Search term to find in tool names and descriptions. Case-insensitive substring matching.'
+      : 'Regex pattern to search tool names and descriptions. Special regex characters will be sanitized for safety.';
+
+  return z.object({
+    query: z.string().min(1).max(MAX_PATTERN_LENGTH).describe(queryDescription),
+    fields: z
+      .array(z.enum(['name', 'description', 'parameters']))
+      .optional()
+      .default(['name', 'description'])
+      .describe('Which fields to search. Default: name and description'),
+    max_results: z
+      .number()
+      .int()
+      .min(1)
+      .max(50)
+      .optional()
+      .default(10)
+      .describe('Maximum number of matching tools to return'),
+  });
+}
 
 /**
  * Escapes special regex characters in a string to use as a literal pattern.
@@ -170,6 +185,80 @@ function simplifyParametersForSearch(
   return { type: parameters.type };
 }
 
+/**
+ * Performs safe local substring search without regex.
+ * Uses case-insensitive String.includes() for complete safety against ReDoS.
+ * @param tools - Array of tool metadata to search
+ * @param query - The search term (treated as literal substring)
+ * @param fields - Which fields to search
+ * @param maxResults - Maximum results to return
+ * @returns Search response with matching tools
+ */
+function performLocalSearch(
+  tools: t.ToolMetadata[],
+  query: string,
+  fields: string[],
+  maxResults: number
+): t.ToolSearchResponse {
+  const lowerQuery = query.toLowerCase();
+  const results: t.ToolSearchResult[] = [];
+
+  for (const tool of tools) {
+    let bestScore = 0;
+    let matchedField = '';
+    let snippet = '';
+
+    if (fields.includes('name')) {
+      const lowerName = tool.name.toLowerCase();
+      if (lowerName.includes(lowerQuery)) {
+        const isExactMatch = lowerName === lowerQuery;
+        const startsWithQuery = lowerName.startsWith(lowerQuery);
+        bestScore = isExactMatch ? 1.0 : startsWithQuery ? 0.95 : 0.85;
+        matchedField = 'name';
+        snippet = tool.name;
+      }
+    }
+
+    if (fields.includes('description') && tool.description) {
+      const lowerDesc = tool.description.toLowerCase();
+      if (lowerDesc.includes(lowerQuery) && bestScore === 0) {
+        bestScore = 0.7;
+        matchedField = 'description';
+        snippet = tool.description.substring(0, 100);
+      }
+    }
+
+    if (fields.includes('parameters') && tool.parameters?.properties) {
+      const paramNames = Object.keys(tool.parameters.properties)
+        .join(' ')
+        .toLowerCase();
+      if (paramNames.includes(lowerQuery) && bestScore === 0) {
+        bestScore = 0.55;
+        matchedField = 'parameters';
+        snippet = Object.keys(tool.parameters.properties).join(' ');
+      }
+    }
+
+    if (bestScore > 0) {
+      results.push({
+        tool_name: tool.name,
+        match_score: bestScore,
+        matched_field: matchedField,
+        snippet,
+      });
+    }
+  }
+
+  results.sort((a, b) => b.match_score - a.match_score);
+  const topResults = results.slice(0, maxResults);
+
+  return {
+    tool_references: topResults,
+    total_tools_searched: tools.length,
+    pattern_used: query,
+  };
+}
+
 /**
  * Generates the JavaScript search script to be executed in the sandbox.
  * Uses plain JavaScript for maximum compatibility with the Code API.
@@ -307,11 +396,15 @@ function formatSearchResults(searchResponse: t.ToolSearchResponse): string {
 }
 
 /**
- * Creates a Tool Search Regex tool for discovering tools from a large registry.
+ * Creates a Tool Search tool for discovering tools from a large registry.
  *
  * This tool enables AI agents to dynamically discover tools from a large library
  * without loading all tool definitions into the LLM context window. The agent
- * can search for relevant tools on-demand using regex patterns.
+ * can search for relevant tools on-demand.
+ *
+ * **Modes:**
+ * - `code_interpreter` (default): Uses external sandbox for regex search. Safer for complex patterns.
+ * - `local`: Uses safe substring matching locally. No network call, faster, completely safe from ReDoS.
  *
  * The tool registry can be provided either:
  * 1. At initialization time via params.toolRegistry
@@ -321,36 +414,52 @@ function formatSearchResults(searchResponse: t.ToolSearchResponse): string {
  * @returns A LangChain DynamicStructuredTool for tool searching
  *
  * @example
- * // Option 1: Registry at initialization
- * const tool = createToolSearchRegexTool({ apiKey, toolRegistry });
- * await tool.invoke({ query: 'expense' });
+ * // Option 1: Code interpreter mode (regex via sandbox)
+ * const tool = createToolSearch({ apiKey, toolRegistry });
+ * await tool.invoke({ query: 'expense.*report' });
  *
  * @example
- * // Option 2: Registry at runtime
- * const tool = createToolSearchRegexTool({ apiKey });
- * await tool.invoke(
- *   { query: 'expense' },
- *   { configurable: { toolRegistry, onlyDeferred: true } }
- * );
+ * // Option 2: Local mode (safe substring search, no API key needed)
+ * const tool = createToolSearch({ mode: 'local', toolRegistry });
+ * await tool.invoke({ query: 'expense' });
  */
-function createToolSearchRegexTool(
-  initParams: t.ToolSearchRegexParams = {}
-): DynamicStructuredTool<typeof ToolSearchRegexSchema> {
-  const apiKey: string =
-    (initParams[EnvVar.CODE_API_KEY] as string | undefined) ??
-    initParams.apiKey ??
-    getEnvironmentVariable(EnvVar.CODE_API_KEY) ??
-    '';
+function createToolSearch(
+  initParams: t.ToolSearchParams = {}
+): DynamicStructuredTool<ReturnType<typeof createToolSearchSchema>> {
+  const mode: t.ToolSearchMode = initParams.mode ?? 'code_interpreter';
+  const defaultOnlyDeferred = initParams.onlyDeferred ?? true;
+  const schema = createToolSearchSchema(mode);
 
-  if (!apiKey) {
-    throw new Error('No API key provided for tool search regex tool.');
+  const apiKey: string =
+    mode === 'code_interpreter'
+      ? ((initParams[EnvVar.CODE_API_KEY] as string | undefined) ??
+        initParams.apiKey ??
+        getEnvironmentVariable(EnvVar.CODE_API_KEY) ??
+        '')
+      : '';
+
+  if (mode === 'code_interpreter' && !apiKey) {
+    throw new Error(
+      'No API key provided for tool search in code_interpreter mode. Use mode: "local" to search without an API key.'
+    );
   }
 
   const baseEndpoint = initParams.baseUrl ?? getCodeBaseURL();
   const EXEC_ENDPOINT = `${baseEndpoint}/exec`;
-  const defaultOnlyDeferred = initParams.onlyDeferred ?? true;
 
-  const description = `
+  const description =
+    mode === 'local'
+      ? `
+Searches through available tools to find ones matching your search term.
+
+Usage:
+- Provide a search term to find in tool names and descriptions.
+- Uses case-insensitive substring matching (fast and safe).
+- Use this when you need to discover tools for a specific task.
+- Results include tool names, match quality scores, and snippets showing where the match occurred.
+- Higher scores (0.95+) indicate name matches, medium scores (0.70+) indicate description matches.
+`.trim()
+      : `
 Searches through available tools to find ones matching your query pattern.
 
 Usage:
@@ -360,7 +469,7 @@ Usage:
 - Higher scores (0.9+) indicate name matches, medium scores (0.7+) indicate description matches.
 `.trim();
 
-  return tool<typeof ToolSearchRegexSchema>(
+  return tool<typeof schema>(
     async (params, config) => {
       const {
         query,
@@ -368,21 +477,11 @@ Usage:
         max_results = 10,
       } = params;
 
-      // Extra params injected by ToolNode (follows web_search pattern)
       const {
         toolRegistry: paramToolRegistry,
         onlyDeferred: paramOnlyDeferred,
       } = config.toolCall ?? {};
 
-      const { safe: sanitizedPattern, wasEscaped } = sanitizeRegex(query);
-
-      let warningMessage = '';
-      if (wasEscaped) {
-        warningMessage =
-          'Note: The provided pattern was converted to a literal search for safety.\n\n';
-      }
-
-      // Priority: ToolNode injection (via config.toolCall) > initialization params
       const toolRegistry = paramToolRegistry ?? initParams.toolRegistry;
       const onlyDeferred =
         paramOnlyDeferred !== undefined
@@ -391,12 +490,12 @@ Usage:
 
       if (toolRegistry == null) {
         return [
-          `${warningMessage}Error: No tool registry provided. Configure toolRegistry at agent level or initialization.`,
+          'Error: No tool registry provided. Configure toolRegistry at agent level or initialization.',
           {
             tool_references: [],
             metadata: {
               total_searched: 0,
-              pattern: sanitizedPattern,
+              pattern: query,
               error: 'No tool registry provided',
             },
           },
@@ -404,14 +503,10 @@ Usage:
       }
 
       const toolsArray: t.LCTool[] = Array.from(toolRegistry.values());
-
       const deferredTools: t.ToolMetadata[] = toolsArray
-        .filter((lcTool) => {
-          if (onlyDeferred === true) {
-            return lcTool.defer_loading === true;
-          }
-          return true;
-        })
+        .filter((lcTool) =>
+          onlyDeferred === true ? lcTool.defer_loading === true : true
+        )
         .map((lcTool) => ({
           name: lcTool.name,
           description: lcTool.description ?? '',
@@ -420,17 +515,42 @@ Usage:
 
       if (deferredTools.length === 0) {
         return [
-          `${warningMessage}No tools available to search. The tool registry is empty or no deferred tools are registered.`,
+          'No tools available to search. The tool registry is empty or no deferred tools are registered.',
           {
             tool_references: [],
+            metadata: { total_searched: 0, pattern: query },
+          },
+        ];
+      }
+
+      if (mode === 'local') {
+        const searchResponse = performLocalSearch(
+          deferredTools,
+          query,
+          fields,
+          max_results
+        );
+        const formattedOutput = formatSearchResults(searchResponse);
+
+        return [
+          formattedOutput,
+          {
+            tool_references: searchResponse.tool_references,
             metadata: {
-              total_searched: 0,
-              pattern: sanitizedPattern,
+              total_searched: searchResponse.total_tools_searched,
+              pattern: searchResponse.pattern_used,
             },
           },
         ];
       }
 
+      const { safe: sanitizedPattern, wasEscaped } = sanitizeRegex(query);
+      let warningMessage = '';
+      if (wasEscaped) {
+        warningMessage =
+          'Note: The provided pattern was converted to a literal search for safety.\n\n';
+      }
+
       const searchScript = generateSearchScript(
         deferredTools,
         fields,
@@ -468,7 +588,7 @@ Usage:
 
         if (result.stderr && result.stderr.trim()) {
           // eslint-disable-next-line no-console
-          console.warn('[ToolSearchRegex] stderr:', result.stderr);
+          console.warn('[ToolSearch] stderr:', result.stderr);
         }
 
         if (!result.stdout || !result.stdout.trim()) {
@@ -499,7 +619,7 @@ Usage:
         ];
       } catch (error) {
         // eslint-disable-next-line no-console
-        console.error('[ToolSearchRegex] Error:', error);
+        console.error('[ToolSearch] Error:', error);
 
         const errorMessage =
           error instanceof Error ? error.message : String(error);
@@ -517,16 +637,17 @@ Usage:
       }
     },
     {
-      name: Constants.TOOL_SEARCH_REGEX,
+      name: Constants.TOOL_SEARCH,
       description,
-      schema: ToolSearchRegexSchema,
+      schema,
       responseFormat: Constants.CONTENT_AND_ARTIFACT,
     }
   );
 }
 
 export {
-  createToolSearchRegexTool,
+  createToolSearch,
+  performLocalSearch,
   sanitizeRegex,
   escapeRegexSpecialChars,
   isDangerousPattern,

package/src/tools/__tests__/{ToolSearchRegex.integration.test.ts → ToolSearch.integration.test.ts}

@@ -1,19 +1,19 @@
-// src/tools/__tests__/ToolSearchRegex.integration.test.ts
+// src/tools/__tests__/ToolSearch.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
+ * Run with: npm test -- ToolSearch.integration.test.ts
  */
 import { config as dotenvConfig } from 'dotenv';
 dotenvConfig();
 
 import { describe, it, expect, beforeAll } from '@jest/globals';
-import { createToolSearchRegexTool } from '../ToolSearchRegex';
+import { createToolSearch } from '../ToolSearch';
 import { createToolSearchToolRegistry } from '@/test/mockTools';
 
-describe('ToolSearchRegex - Live API Integration', () => {
-  let searchTool: ReturnType<typeof createToolSearchRegexTool>;
+describe('ToolSearch - Live API Integration', () => {
+  let searchTool: ReturnType<typeof createToolSearch>;
   const toolRegistry = createToolSearchToolRegistry();
 
   beforeAll(() => {
@@ -24,7 +24,7 @@ describe('ToolSearchRegex - Live API Integration', () => {
       );
     }
 
-    searchTool = createToolSearchRegexTool({ apiKey, toolRegistry });
+    searchTool = createToolSearch({ apiKey, toolRegistry });
   });
 
   it('searches for expense-related tools', async () => {

package/src/tools/__tests__/{ToolSearchRegex.test.ts → ToolSearch.test.ts}

@@ -1,4 +1,4 @@
-// src/tools/__tests__/ToolSearchRegex.test.ts
+// src/tools/__tests__/ToolSearch.test.ts
 /**
  * Unit tests for Tool Search Regex.
  * Tests helper functions and sanitization logic without hitting the API.
@@ -10,9 +10,11 @@ import {
   isDangerousPattern,
   countNestedGroups,
   hasNestedQuantifiers,
-} from '../ToolSearchRegex';
+  performLocalSearch,
+} from '../ToolSearch';
+import type { ToolMetadata } from '@/types';
 
-describe('ToolSearchRegex', () => {
+describe('ToolSearch', () => {
   describe('escapeRegexSpecialChars', () => {
     it('escapes special regex characters', () => {
       expect(escapeRegexSpecialChars('hello.world')).toBe('hello\\.world');
@@ -229,4 +231,211 @@ describe('ToolSearchRegex', () => {
       }
     });
   });
+
+  describe('performLocalSearch', () => {
+    const mockTools: ToolMetadata[] = [
+      {
+        name: 'get_weather',
+        description: 'Get current weather data',
+        parameters: undefined,
+      },
+      {
+        name: 'get_forecast',
+        description: 'Get weather forecast for multiple days',
+        parameters: undefined,
+      },
+      {
+        name: 'send_email',
+        description: 'Send an email message',
+        parameters: undefined,
+      },
+      {
+        name: 'get_expenses',
+        description: 'Retrieve expense reports',
+        parameters: undefined,
+      },
+      {
+        name: 'calculate_expense_totals',
+        description: 'Sum up expenses by category',
+        parameters: undefined,
+      },
+      {
+        name: 'run_database_query',
+        description: 'Execute a database query',
+        parameters: {
+          type: 'object',
+          properties: {
+            query: { type: 'string' },
+            timeout: { type: 'number' },
+          },
+        },
+      },
+    ];
+
+    it('finds tools by exact name match', () => {
+      const result = performLocalSearch(mockTools, 'get_weather', ['name'], 10);
+
+      expect(result.tool_references.length).toBe(1);
+      expect(result.tool_references[0].tool_name).toBe('get_weather');
+      expect(result.tool_references[0].match_score).toBe(1.0);
+      expect(result.tool_references[0].matched_field).toBe('name');
+    });
+
+    it('finds tools by partial name match (starts with)', () => {
+      const result = performLocalSearch(mockTools, 'get_', ['name'], 10);
+
+      expect(result.tool_references.length).toBe(3);
+      expect(result.tool_references[0].match_score).toBe(0.95);
+      expect(result.tool_references.map((r) => r.tool_name)).toContain(
+        'get_weather'
+      );
+      expect(result.tool_references.map((r) => r.tool_name)).toContain(
+        'get_forecast'
+      );
+      expect(result.tool_references.map((r) => r.tool_name)).toContain(
+        'get_expenses'
+      );
+    });
+
+    it('finds tools by substring match in name', () => {
+      const result = performLocalSearch(mockTools, 'expense', ['name'], 10);
+
+      expect(result.tool_references.length).toBe(2);
+      expect(result.tool_references.map((r) => r.tool_name)).toContain(
+        'get_expenses'
+      );
+      expect(result.tool_references.map((r) => r.tool_name)).toContain(
+        'calculate_expense_totals'
+      );
+      expect(result.tool_references[0].match_score).toBe(0.85);
+    });
+
+    it('performs case-insensitive search', () => {
+      const result = performLocalSearch(
+        mockTools,
+        'WEATHER',
+        ['name', 'description'],
+        10
+      );
+
+      expect(result.tool_references.length).toBe(2);
+      expect(result.tool_references.map((r) => r.tool_name)).toContain(
+        'get_weather'
+      );
+      expect(result.tool_references.map((r) => r.tool_name)).toContain(
+        'get_forecast'
+      );
+    });
+
+    it('searches in description field', () => {
+      const result = performLocalSearch(
+        mockTools,
+        'email',
+        ['description'],
+        10
+      );
+
+      expect(result.tool_references.length).toBe(1);
+      expect(result.tool_references[0].tool_name).toBe('send_email');
+      expect(result.tool_references[0].matched_field).toBe('description');
+      expect(result.tool_references[0].match_score).toBe(0.7);
+    });
+
+    it('searches in parameter names', () => {
+      const result = performLocalSearch(mockTools, 'query', ['parameters'], 10);
+
+      expect(result.tool_references.length).toBe(1);
+      expect(result.tool_references[0].tool_name).toBe('run_database_query');
+      expect(result.tool_references[0].matched_field).toBe('parameters');
+      expect(result.tool_references[0].match_score).toBe(0.55);
+    });
+
+    it('prioritizes name matches over description matches', () => {
+      const result = performLocalSearch(
+        mockTools,
+        'weather',
+        ['name', 'description'],
+        10
+      );
+
+      const weatherTool = result.tool_references.find(
+        (r) => r.tool_name === 'get_weather'
+      );
+      const forecastTool = result.tool_references.find(
+        (r) => r.tool_name === 'get_forecast'
+      );
+
+      expect(weatherTool?.matched_field).toBe('name');
+      expect(forecastTool?.matched_field).toBe('description');
+      expect(weatherTool!.match_score).toBeGreaterThan(
+        forecastTool!.match_score
+      );
+    });
+
+    it('limits results to max_results', () => {
+      const result = performLocalSearch(mockTools, 'get', ['name'], 2);
+
+      expect(result.tool_references.length).toBe(2);
+      expect(result.total_tools_searched).toBe(mockTools.length);
+    });
+
+    it('returns empty array when no matches found', () => {
+      const result = performLocalSearch(
+        mockTools,
+        'nonexistent_xyz_123',
+        ['name', 'description'],
+        10
+      );
+
+      expect(result.tool_references.length).toBe(0);
+      expect(result.total_tools_searched).toBe(mockTools.length);
+    });
+
+    it('sorts results by score descending', () => {
+      const result = performLocalSearch(
+        mockTools,
+        'expense',
+        ['name', 'description'],
+        10
+      );
+
+      for (let i = 1; i < result.tool_references.length; i++) {
+        expect(
+          result.tool_references[i - 1].match_score
+        ).toBeGreaterThanOrEqual(result.tool_references[i].match_score);
+      }
+    });
+
+    it('handles empty tools array', () => {
+      const result = performLocalSearch([], 'test', ['name'], 10);
+
+      expect(result.tool_references.length).toBe(0);
+      expect(result.total_tools_searched).toBe(0);
+    });
+
+    it('handles empty query gracefully', () => {
+      const result = performLocalSearch(mockTools, '', ['name'], 10);
+
+      expect(result.tool_references.length).toBe(mockTools.length);
+    });
+
+    it('includes correct metadata in response', () => {
+      const result = performLocalSearch(mockTools, 'weather', ['name'], 10);
+
+      expect(result.total_tools_searched).toBe(mockTools.length);
+      expect(result.pattern_used).toBe('weather');
+    });
+
+    it('provides snippet in results', () => {
+      const result = performLocalSearch(
+        mockTools,
+        'database',
+        ['description'],
+        10
+      );
+
+      expect(result.tool_references[0].snippet).toBeTruthy();
+      expect(result.tool_references[0].snippet.length).toBeGreaterThan(0);
+    });
+  });
 });

package/src/types/tools.ts

@@ -128,12 +128,17 @@ export type LCToolRegistry = Map<string, LCTool>;
 
 export type ProgrammaticCache = { toolMap: ToolMap; toolDefs: LCTool[] };
 
+/** Search mode: code_interpreter uses external sandbox, local uses safe substring matching */
+export type ToolSearchMode = 'code_interpreter' | 'local';
+
 /** Parameters for creating a Tool Search Regex tool */
-export type ToolSearchRegexParams = {
+export type ToolSearchParams = {
   apiKey?: string;
   toolRegistry?: LCToolRegistry;
   onlyDeferred?: boolean;
   baseUrl?: string;
+  /** Search mode: 'code_interpreter' (default) uses sandbox for regex, 'local' uses safe substring matching */
+  mode?: ToolSearchMode;
   [key: string]: unknown;
 };