@librechat/agents 3.0.42 → 3.0.44

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

@@ -52,12 +52,12 @@ result = await get_weather(city="San Francisco")
 print(f"Temperature: {result['temperature']}°F")
 print(f"Condition: {result['condition']}")
       `,
-      tools: toolDefinitions,
     };
     const toolCall = {
       name: 'programmatic_code_execution',
       args,
       toolMap,
+      toolDefs: toolDefinitions,
     };
 
     const output = await ptcTool.invoke(args, { toolCall });
@@ -85,12 +85,12 @@ for member in team:
 
 print(f"Grand total: \${total:.2f}")
       `,
-      tools: toolDefinitions,
     };
     const toolCall = {
       name: 'programmatic_code_execution',
       args,
       toolMap,
+      toolDefs: toolDefinitions,
     };
 
     const output = await ptcTool.invoke(args, { toolCall });
@@ -116,12 +116,12 @@ results = await asyncio.gather(*[
 for city, weather in zip(cities, results):
     print(f"{city}: {weather['temperature']}°F, {weather['condition']}")
       `,
-      tools: toolDefinitions,
     };
     const toolCall = {
       name: 'programmatic_code_execution',
       args,
       toolMap,
+      toolDefs: toolDefinitions,
     };
 
     const output = await ptcTool.invoke(args, { toolCall });
@@ -150,12 +150,12 @@ if high_spenders:
 else:
     print("No high spenders found.")
       `,
-      tools: toolDefinitions,
     };
     const toolCall = {
       name: 'programmatic_code_execution',
       args,
       toolMap,
+      toolDefs: toolDefinitions,
     };
 
     const output = await ptcTool.invoke(args, { toolCall });
@@ -180,12 +180,12 @@ for member in team:
 else:
     print("No equipment expenses found")
       `,
-      tools: toolDefinitions,
     };
     const toolCall = {
       name: 'programmatic_code_execution',
       args,
       toolMap,
+      toolDefs: toolDefinitions,
     };
 
     const output = await ptcTool.invoke(args, { toolCall });
@@ -206,12 +206,12 @@ for city in cities:
     except Exception as e:
         print(f"{city}: Error - {e}")
       `,
-      tools: toolDefinitions,
     };
     const toolCall = {
       name: 'programmatic_code_execution',
       args,
       toolMap,
+      toolDefs: toolDefinitions,
     };
 
     const output = await ptcTool.invoke(args, { toolCall });
@@ -230,12 +230,12 @@ result2 = await calculator(expression="(10 + 5) / 3")
 print(f"2 + 2 * 3 = {result1['result']}")
 print(f"(10 + 5) / 3 = {result2['result']:.2f}")
       `,
-      tools: toolDefinitions,
     };
     const toolCall = {
       name: 'programmatic_code_execution',
       args,
       toolMap,
+      toolDefs: toolDefinitions,
     };
 
     const output = await ptcTool.invoke(args, { toolCall });
@@ -265,12 +265,12 @@ for member, expenses in zip(team, all_expenses):
     total = sum(e['amount'] for e in expenses)
     print(f"  {member['name']}: \${total:.2f} ({len(expenses)} items)")
       `,
-      tools: toolDefinitions,
     };
     const toolCall = {
       name: 'programmatic_code_execution',
       args,
       toolMap,
+      toolDefs: toolDefinitions,
     };
 
     const output = await ptcTool.invoke(args, { toolCall });
@@ -302,12 +302,12 @@ print(f"SF: {sf['temperature']}°F vs NYC: {nyc['temperature']}°F")
 difference = abs(sf['temperature'] - nyc['temperature'])
 print(f"Temperature difference: {difference}°F")
       `,
-      tools: [weatherToolDef!],
     };
     const toolCall = {
       name: 'programmatic_code_execution',
       args,
       toolMap,
+      toolDefs: [weatherToolDef!],
     };
 
     const output = await ptcTool.invoke(args, { toolCall });

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

@@ -6,16 +6,19 @@
 import { describe, it, expect, beforeEach } from '@jest/globals';
 import type * as t from '@/types';
 import {
-  executeTools,
-  formatCompletedResponse,
   createProgrammaticToolCallingTool,
+  formatCompletedResponse,
+  extractUsedToolNames,
+  filterToolsByUsage,
+  executeTools,
+  normalizeToPythonIdentifier,
 } from '../ProgrammaticToolCalling';
 import {
+  createProgrammaticToolRegistry,
   createGetTeamMembersTool,
   createGetExpensesTool,
   createGetWeatherTool,
   createCalculatorTool,
-  createProgrammaticToolRegistry,
 } from '@/test/mockTools';
 
 describe('ProgrammaticToolCalling', () => {
@@ -183,6 +186,243 @@ describe('ProgrammaticToolCalling', () => {
     });
   });
 
+  describe('normalizeToPythonIdentifier', () => {
+    it('converts hyphens to underscores', () => {
+      expect(normalizeToPythonIdentifier('my-tool-name')).toBe('my_tool_name');
+    });
+
+    it('converts spaces to underscores', () => {
+      expect(normalizeToPythonIdentifier('my tool name')).toBe('my_tool_name');
+    });
+
+    it('leaves underscores unchanged', () => {
+      expect(normalizeToPythonIdentifier('my_tool_name')).toBe('my_tool_name');
+    });
+
+    it('handles mixed hyphens and underscores', () => {
+      expect(normalizeToPythonIdentifier('my-tool_name-v2')).toBe(
+        'my_tool_name_v2'
+      );
+    });
+
+    it('handles MCP-style names with hyphens', () => {
+      expect(
+        normalizeToPythonIdentifier('create_spreadsheet_mcp_Google-Workspace')
+      ).toBe('create_spreadsheet_mcp_Google_Workspace');
+    });
+
+    it('removes invalid characters', () => {
+      expect(normalizeToPythonIdentifier('tool@name!v2')).toBe('toolnamev2');
+      expect(normalizeToPythonIdentifier('get.data.v2')).toBe('getdatav2');
+    });
+
+    it('prefixes with underscore if starts with number', () => {
+      expect(normalizeToPythonIdentifier('123tool')).toBe('_123tool');
+      expect(normalizeToPythonIdentifier('1-tool')).toBe('_1_tool');
+    });
+
+    it('appends _tool suffix for Python keywords', () => {
+      expect(normalizeToPythonIdentifier('return')).toBe('return_tool');
+      expect(normalizeToPythonIdentifier('async')).toBe('async_tool');
+      expect(normalizeToPythonIdentifier('import')).toBe('import_tool');
+    });
+  });
+
+  describe('extractUsedToolNames', () => {
+    const createToolMap = (names: string[]): Map<string, string> => {
+      const map = new Map<string, string>();
+      for (const name of names) {
+        map.set(normalizeToPythonIdentifier(name), name);
+      }
+      return map;
+    };
+
+    const availableTools = createToolMap([
+      'get_weather',
+      'get_team_members',
+      'get_expenses',
+      'calculator',
+      'search_docs',
+    ]);
+
+    it('extracts single tool name from simple code', () => {
+      const code = `result = await get_weather(city="SF")
+print(result)`;
+      const used = extractUsedToolNames(code, availableTools);
+
+      expect(used.size).toBe(1);
+      expect(used.has('get_weather')).toBe(true);
+    });
+
+    it('extracts multiple tool names from code', () => {
+      const code = `team = await get_team_members()
+for member in team:
+    expenses = await get_expenses(user_id=member['id'])
+    print(f"{member['name']}: {sum(e['amount'] for e in expenses)}")`;
+
+      const used = extractUsedToolNames(code, availableTools);
+
+      expect(used.size).toBe(2);
+      expect(used.has('get_team_members')).toBe(true);
+      expect(used.has('get_expenses')).toBe(true);
+    });
+
+    it('extracts tools from asyncio.gather calls', () => {
+      const code = `results = await asyncio.gather(
+    get_weather(city="SF"),
+    get_weather(city="NYC"),
+    get_expenses(user_id="u1")
+)`;
+      const used = extractUsedToolNames(code, availableTools);
+
+      expect(used.size).toBe(2);
+      expect(used.has('get_weather')).toBe(true);
+      expect(used.has('get_expenses')).toBe(true);
+    });
+
+    it('does not match partial tool names', () => {
+      const code = `# Using get_weather_data instead
+result = await get_weather_data(city="SF")`;
+
+      const used = extractUsedToolNames(code, availableTools);
+      expect(used.has('get_weather')).toBe(false);
+    });
+
+    it('matches tool names in different contexts', () => {
+      const code = `# direct call
+x = await calculator(expression="1+1")
+# in list comprehension
+results = [await get_weather(city=c) for c in cities]
+# conditional
+if condition:
+    await get_team_members()`;
+
+      const used = extractUsedToolNames(code, availableTools);
+
+      expect(used.size).toBe(3);
+      expect(used.has('calculator')).toBe(true);
+      expect(used.has('get_weather')).toBe(true);
+      expect(used.has('get_team_members')).toBe(true);
+    });
+
+    it('returns empty set when no tools are used', () => {
+      const code = `print("Hello, World!")
+x = 1 + 2`;
+
+      const used = extractUsedToolNames(code, availableTools);
+      expect(used.size).toBe(0);
+    });
+
+    it('handles tool names with special characters via normalization', () => {
+      const specialTools = createToolMap(['get_data.v2', 'calc+plus']);
+      const code = `await get_datav2()
+await calcplus()`;
+
+      const used = extractUsedToolNames(code, specialTools);
+
+      expect(used.has('get_data.v2')).toBe(true);
+      expect(used.has('calc+plus')).toBe(true);
+    });
+
+    it('matches hyphenated tool names using underscore in code', () => {
+      const mcpTools = createToolMap([
+        'create_spreadsheet_mcp_Google-Workspace',
+        'search_gmail_mcp_Google-Workspace',
+      ]);
+      const code = `result = await create_spreadsheet_mcp_Google_Workspace(title="Test")
+print(result)`;
+
+      const used = extractUsedToolNames(code, mcpTools);
+
+      expect(used.size).toBe(1);
+      expect(used.has('create_spreadsheet_mcp_Google-Workspace')).toBe(true);
+    });
+  });
+
+  describe('filterToolsByUsage', () => {
+    const allToolDefs: t.LCTool[] = [
+      {
+        name: 'get_weather',
+        description: 'Get weather for a city',
+        parameters: {
+          type: 'object',
+          properties: { city: { type: 'string' } },
+        },
+      },
+      {
+        name: 'get_team_members',
+        description: 'Get team members',
+        parameters: { type: 'object', properties: {} },
+      },
+      {
+        name: 'get_expenses',
+        description: 'Get expenses for a user',
+        parameters: {
+          type: 'object',
+          properties: { user_id: { type: 'string' } },
+        },
+      },
+      {
+        name: 'calculator',
+        description: 'Evaluate an expression',
+        parameters: {
+          type: 'object',
+          properties: { expression: { type: 'string' } },
+        },
+      },
+    ];
+
+    it('filters to only used tools', () => {
+      const code = `result = await get_weather(city="SF")
+print(result)`;
+
+      const filtered = filterToolsByUsage(allToolDefs, code);
+
+      expect(filtered).toHaveLength(1);
+      expect(filtered[0].name).toBe('get_weather');
+    });
+
+    it('filters to multiple used tools', () => {
+      const code = `team = await get_team_members()
+for member in team:
+    expenses = await get_expenses(user_id=member['id'])`;
+
+      const filtered = filterToolsByUsage(allToolDefs, code);
+
+      expect(filtered).toHaveLength(2);
+      expect(filtered.map((t) => t.name).sort()).toEqual([
+        'get_expenses',
+        'get_team_members',
+      ]);
+    });
+
+    it('returns all tools when no tools are detected', () => {
+      const code = 'print("Hello, World!")';
+
+      const filtered = filterToolsByUsage(allToolDefs, code);
+
+      expect(filtered).toHaveLength(4);
+    });
+
+    it('preserves tool definition structure', () => {
+      const code = 'await calculator(expression="2+2")';
+
+      const filtered = filterToolsByUsage(allToolDefs, code);
+
+      expect(filtered).toHaveLength(1);
+      expect(filtered[0]).toEqual(allToolDefs[3]);
+      expect(filtered[0].parameters).toBeDefined();
+      expect(filtered[0].description).toBe('Evaluate an expression');
+    });
+
+    it('handles empty tool definitions', () => {
+      const code = 'await get_weather(city="SF")';
+      const filtered = filterToolsByUsage([], code);
+
+      expect(filtered).toHaveLength(0);
+    });
+  });
+
   describe('formatCompletedResponse', () => {
     it('formats response with stdout', () => {
       const response: t.ProgrammaticExecutionResponse = {
@@ -332,7 +572,7 @@ describe('ProgrammaticToolCalling', () => {
         name: 'programmatic_code_execution',
         args,
         toolMap,
-        // No programmaticToolDefs
+        // No `toolDefs`
       };
 
       await expect(ptcTool.invoke(args, { toolCall })).rejects.toThrow(
@@ -340,7 +580,7 @@ describe('ProgrammaticToolCalling', () => {
       );
     });
 
-    it('uses programmaticToolDefs from config when tools not provided', async () => {
+    it('uses toolDefs from config when tools not provided', async () => {
       // Skip this test - requires mocking fetch which has complex typing
       // This functionality is tested in the live script tests instead
     });

package/src/types/tools.ts

@@ -35,11 +35,7 @@ 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) */
+  /** Tool registry for lazy computation of programmatic tools and tool search */
   toolRegistry?: LCToolRegistry;
 };
 
@@ -128,6 +124,8 @@ export type LCTool = {
 /** Map of tool names to tool definitions */
 export type LCToolRegistry = Map<string, LCTool>;
 
+export type ProgrammaticCache = { toolMap: ToolMap; toolDefs: LCTool[] };
+
 /** Parameters for creating a Tool Search Regex tool */
 export type ToolSearchRegexParams = {
   apiKey?: string;
@@ -241,6 +239,8 @@ export type ProgrammaticToolCallingParams = {
   maxRoundTrips?: number;
   /** HTTP proxy URL */
   proxy?: string;
+  /** Enable debug logging (or set PTC_DEBUG=true env var) */
+  debug?: boolean;
   /** Environment variable key for API key */
   [key: string]: unknown;
 };