@librechat/agents 3.0.42 → 3.0.44

package/src/scripts/code_exec_ptc.ts

@@ -18,25 +18,79 @@ import type { RunnableConfig } from '@langchain/core/runnables';
 import type * as t from '@/types';
 import { ChatModelStreamHandler, createContentAggregator } from '@/stream';
 import {
-  ToolEndHandler,
-  ModelEndHandler,
+  // createProgrammaticToolRegistry,
+  createGetTeamMembersTool,
+  createGetExpensesTool,
+  createGetWeatherTool,
+} from '@/test/mockTools';
+import {
   createMetadataAggregator,
+  ModelEndHandler,
+  ToolEndHandler,
 } from '@/events';
+import { createProgrammaticToolCallingTool } from '@/tools/ProgrammaticToolCalling';
+import { createCodeExecutionTool } from '@/tools/CodeExecutor';
 import { getLLMConfig } from '@/utils/llmConfig';
 import { getArgs } from '@/scripts/args';
 import { GraphEvents } from '@/common';
 import { Run } from '@/run';
-import { createCodeExecutionTool } from '@/tools/CodeExecutor';
-import { createProgrammaticToolCallingTool } from '@/tools/ProgrammaticToolCalling';
-import {
-  createGetTeamMembersTool,
-  createGetExpensesTool,
-  createGetWeatherTool,
-  createProgrammaticToolRegistry,
-} from '@/test/mockTools';
 
 const conversationHistory: BaseMessage[] = [];
 
+/**
+ * Creates a tool registry where ALL business tools are code_execution ONLY.
+ * This forces the LLM to use PTC - it cannot call these tools directly.
+ */
+function createPTCOnlyToolRegistry(): t.LCToolRegistry {
+  const toolDefs: t.LCTool[] = [
+    {
+      name: 'get_team_members',
+      description:
+        'Get list of team members. Returns array of objects with id, name, and department fields.',
+      parameters: {
+        type: 'object',
+        properties: {},
+        required: [],
+      },
+      allowed_callers: ['code_execution'], // PTC ONLY - not direct
+    },
+    {
+      name: 'get_expenses',
+      description:
+        'Get expense records for a user. Returns array of objects with amount and category fields.',
+      parameters: {
+        type: 'object',
+        properties: {
+          user_id: {
+            type: 'string',
+            description: 'The user ID to fetch expenses for',
+          },
+        },
+        required: ['user_id'],
+      },
+      allowed_callers: ['code_execution'], // PTC ONLY - not direct
+    },
+    {
+      name: 'get_weather',
+      description:
+        'Get current weather for a city. Returns object with temperature (number) and condition (string) fields.',
+      parameters: {
+        type: 'object',
+        properties: {
+          city: {
+            type: 'string',
+            description: 'City name',
+          },
+        },
+        required: ['city'],
+      },
+      allowed_callers: ['code_execution'], // PTC ONLY - not direct (changed from ['direct', 'code_execution'])
+    },
+  ];
+
+  return new Map(toolDefs.map((def) => [def.name, def]));
+}
+
 async function testProgrammaticToolCalling(): Promise<void> {
   const { userName, location, provider, currentDate } = await getArgs();
   const { contentParts, aggregateContent } = createContentAggregator();
@@ -111,10 +165,10 @@ async function testProgrammaticToolCalling(): Promise<void> {
   const allTools = [teamTool, expensesTool, weatherTool, codeExecTool, ptcTool];
   const toolMap = new Map(allTools.map((t) => [t.name, t]));
 
-  // Create tool registry with allowed_callers configuration
-  // Only includes business logic tools (not special tools)
-  // Special tools (execute_code, PTC) are always bound directly to LLM
-  const toolRegistry = createProgrammaticToolRegistry();
+  // Create tool registry where ALL business tools are PTC-only
+  // This means the LLM CANNOT call get_team_members, get_expenses, get_weather directly
+  // It MUST use run_tools_with_code to invoke them
+  const toolRegistry = createPTCOnlyToolRegistry();
 
   console.log('\n' + '='.repeat(70));
   console.log('Tool Configuration Summary:');
@@ -150,11 +204,14 @@ async function testProgrammaticToolCalling(): Promise<void> {
           toolMap,
           toolRegistry,
           instructions:
-            'You are a friendly AI assistant with advanced coding capabilities. ' +
-            'You have access to team and expense management tools, but ONLY through programmatic code execution. ' +
-            'When you need to analyze expenses or process team data, use the programmatic_code_execution tool ' +
-            'to write Python code that calls get_team_members(), get_expenses(), and get_weather() functions. ' +
-            'These functions are async - use await. Use asyncio.gather() for parallel execution.',
+            'You are a friendly AI assistant with advanced coding capabilities.\n\n' +
+            'IMPORTANT: The tools get_team_members(), get_expenses(), and get_weather() are NOT available ' +
+            'for direct function calling. You MUST use the run_tools_with_code tool to invoke them.\n\n' +
+            'When you need to use these tools, write Python code using run_tools_with_code that calls:\n' +
+            '- await get_team_members() - returns list of team members\n' +
+            '- await get_expenses(user_id="...") - returns expenses for a user\n' +
+            '- await get_weather(city="...") - returns weather data\n\n' +
+            'Use asyncio.gather() for parallel execution when calling multiple tools.',
           additional_instructions: `The user's name is ${userName} and they are located in ${location}. Today is ${currentDate}.`,
         },
       ],
@@ -187,7 +244,7 @@ async function testProgrammaticToolCalling(): Promise<void> {
 4. Identify anyone who spent more than $500
 5. Show me a summary report
 
-IMPORTANT: Use the programmatic_code_execution tool to do this efficiently. 
+IMPORTANT: Use the run_tools_with_code tool to do this efficiently. 
 Don't call each tool separately - write Python code that orchestrates all the calls!`;
 
   conversationHistory.push(new HumanMessage(userMessage1));
@@ -217,7 +274,7 @@ Don't call each tool separately - write Python code that orchestrates all the ca
 3. For the Engineering team members only, calculate their travel expenses
 4. Show me the results
 
-Again, use programmatic_code_execution for maximum efficiency. Use asyncio.gather() 
+Again, use run_tools_with_code for maximum efficiency. Use asyncio.gather() 
 to check both cities' weather at the same time!`;
 
   conversationHistory.push(new HumanMessage(userMessage2));

package/src/scripts/programmatic_exec.ts

@@ -353,8 +353,8 @@ print(f"Temperature difference: {difference}°F")
   console.log('='.repeat(70));
   console.log(
     '\nWhen PTC is invoked through ToolNode in a real agent:\n' +
-      '- ToolNode detects call.name === "programmatic_code_execution"\n' +
-      '- ToolNode injects: { ...invokeParams, toolMap, programmaticToolDefs }\n' +
+      '- ToolNode detects call.name === "run_tools_with_code"\n' +
+      '- ToolNode injects: { ...invokeParams, toolMap, toolDefs }\n' +
       '- PTC tool extracts these from params (not from config)\n' +
       '- No explicit tools parameter needed in schema\n\n' +
       'This test demonstrates param injection with explicit tools:\n'
@@ -364,7 +364,7 @@ print(f"Temperature difference: {difference}°F")
     ptcTool,
     'Runtime injection with explicit tools',
     `
-# ToolNode would inject toolMap+programmaticToolDefs
+# ToolNode would inject toolMap+toolDefs
 # For this test, we pass tools explicitly (same effect)
 team = await get_team_members()
 print(f"Team size: {len(team)}")

package/src/scripts/programmatic_exec_agent.ts

@@ -40,7 +40,7 @@ import {
 
 /**
  * Tool registry only needs business logic tools that require filtering.
- * Special tools (execute_code, programmatic_code_execution, tool_search_regex)
+ * Special tools (execute_code, run_tools_with_code, tool_search_regex)
  * are always bound directly to the LLM and don't need registry entries.
  */
 function createAgentToolRegistry(): t.LCToolRegistry {
@@ -133,7 +133,7 @@ async function main(): Promise<void> {
           instructions:
             'You are an AI assistant with access to programmatic tool calling. ' +
             'When you need to process multiple items or perform complex data operations, ' +
-            'use the programmatic_code_execution tool to write Python code that calls tools efficiently.',
+            'use the run_tools_with_code tool to write Python code that calls tools efficiently.',
         },
       ],
     },
@@ -164,7 +164,7 @@ async function main(): Promise<void> {
 4. Identify anyone who spent more than $300
 5. Show me the results in a nice format
 
-Use the programmatic_code_execution tool to do this efficiently - don't call each tool separately!`
+Use the run_tools_with_code tool to do this efficiently - don't call each tool separately!`
   );
 
   conversationHistory.push(userMessage);
@@ -199,7 +199,7 @@ Use the programmatic_code_execution tool to do this efficiently - don't call eac
   console.log('='.repeat(70));
   console.log('\nKey observations:');
   console.log(
-    '1. LLM only sees tools with allowed_callers including "direct" (get_weather, execute_code, programmatic_code_execution, tool_search_regex)'
+    '1. LLM only sees tools with allowed_callers including "direct" (get_weather, execute_code, run_tools_with_code, tool_search_regex)'
   );
   console.log(
     '2. When PTC is invoked, ToolNode automatically injects programmatic tools (get_team_members, get_expenses, get_weather)'

package/src/tools/ProgrammaticToolCalling.ts

@@ -5,6 +5,7 @@ import fetch, { RequestInit } from 'node-fetch';
 import { HttpsProxyAgent } from 'https-proxy-agent';
 import { getEnvironmentVariable } from '@langchain/core/utils/env';
 import { tool, DynamicStructuredTool } from '@langchain/core/tools';
+import type { ToolCall } from '@langchain/core/messages/tool';
 import type * as t from '@/types';
 import { imageExtRegex, getCodeBaseURL } from './CodeExecutor';
 import { EnvVar, Constants } from '@/common';
@@ -74,18 +75,6 @@ Requirements:
 - Only print() output flows back to the context window
 - Tool results from programmatic calls do NOT consume context tokens`
     ),
-  tools: z
-    .array(
-      z.object({
-        name: z.string(),
-        description: z.string().optional(),
-        parameters: z.any(), // JsonSchemaType
-      })
-    )
-    .optional()
-    .describe(
-      'Optional array of tool definitions that can be called from the code. If not provided, uses programmatic tools configured in the agent context. Tool names must match tools available in the toolMap.'
-    ),
   session_id: z
     .string()
     .optional()
@@ -108,6 +97,143 @@ Requirements:
 // Helper Functions
 // ============================================================================
 
+/** Python reserved keywords that get `_tool` suffix in Code API */
+const PYTHON_KEYWORDS = new Set([
+  'False',
+  'None',
+  'True',
+  'and',
+  'as',
+  'assert',
+  'async',
+  'await',
+  'break',
+  'class',
+  'continue',
+  'def',
+  'del',
+  'elif',
+  'else',
+  'except',
+  'finally',
+  'for',
+  'from',
+  'global',
+  'if',
+  'import',
+  'in',
+  'is',
+  'lambda',
+  'nonlocal',
+  'not',
+  'or',
+  'pass',
+  'raise',
+  'return',
+  'try',
+  'while',
+  'with',
+  'yield',
+]);
+
+/**
+ * Normalizes a tool name to Python identifier format.
+ * Must match the Code API's `normalizePythonFunctionName` exactly:
+ * 1. Replace hyphens and spaces with underscores
+ * 2. Remove any other invalid characters
+ * 3. Prefix with underscore if starts with number
+ * 4. Append `_tool` if it's a Python keyword
+ * @param name - The tool name to normalize
+ * @returns Normalized Python-safe identifier
+ */
+export function normalizeToPythonIdentifier(name: string): string {
+  let normalized = name.replace(/[-\s]/g, '_');
+
+  normalized = normalized.replace(/[^a-zA-Z0-9_]/g, '');
+
+  if (/^[0-9]/.test(normalized)) {
+    normalized = '_' + normalized;
+  }
+
+  if (PYTHON_KEYWORDS.has(normalized)) {
+    normalized = normalized + '_tool';
+  }
+
+  return normalized;
+}
+
+/**
+ * Extracts tool names that are actually called in the Python code.
+ * Handles hyphen/underscore conversion since Python identifiers use underscores.
+ * @param code - The Python code to analyze
+ * @param toolNameMap - Map from normalized Python name to original tool name
+ * @returns Set of original tool names found in the code
+ */
+export function extractUsedToolNames(
+  code: string,
+  toolNameMap: Map<string, string>
+): Set<string> {
+  const usedTools = new Set<string>();
+
+  for (const [pythonName, originalName] of toolNameMap) {
+    const escapedName = pythonName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const pattern = new RegExp(`\\b${escapedName}\\s*\\(`, 'g');
+
+    if (pattern.test(code)) {
+      usedTools.add(originalName);
+    }
+  }
+
+  return usedTools;
+}
+
+/**
+ * Filters tool definitions to only include tools actually used in the code.
+ * Handles the hyphen-to-underscore conversion for Python compatibility.
+ * @param toolDefs - All available tool definitions
+ * @param code - The Python code to analyze
+ * @param debug - Enable debug logging
+ * @returns Filtered array of tool definitions
+ */
+export function filterToolsByUsage(
+  toolDefs: t.LCTool[],
+  code: string,
+  debug = false
+): t.LCTool[] {
+  const toolNameMap = new Map<string, string>();
+  for (const tool of toolDefs) {
+    const pythonName = normalizeToPythonIdentifier(tool.name);
+    toolNameMap.set(pythonName, tool.name);
+  }
+
+  const usedToolNames = extractUsedToolNames(code, toolNameMap);
+
+  if (debug) {
+    // eslint-disable-next-line no-console
+    console.log(
+      `[PTC Debug] Tool filtering: found ${usedToolNames.size}/${toolDefs.length} tools in code`
+    );
+    if (usedToolNames.size > 0) {
+      // eslint-disable-next-line no-console
+      console.log(
+        `[PTC Debug] Matched tools: ${Array.from(usedToolNames).join(', ')}`
+      );
+    }
+  }
+
+  if (usedToolNames.size === 0) {
+    if (debug) {
+      // eslint-disable-next-line no-console
+      console.log(
+        '[PTC Debug] No tools detected in code - sending all tools as fallback'
+      );
+    }
+    return toolDefs;
+  }
+
+  return toolDefs.filter((tool) => usedToolNames.has(tool.name));
+}
+
 /**
  * Makes an HTTP request to the Code API.
  * @param endpoint - The API endpoint URL
@@ -284,38 +410,38 @@ export function createProgrammaticToolCallingTool(
   const baseUrl = initParams.baseUrl ?? getCodeBaseURL();
   const maxRoundTrips = initParams.maxRoundTrips ?? DEFAULT_MAX_ROUND_TRIPS;
   const proxy = initParams.proxy ?? process.env.PROXY;
+  const debug = initParams.debug ?? process.env.PTC_DEBUG === 'true';
   const EXEC_ENDPOINT = `${baseUrl}/exec/programmatic`;
 
   const description = `
-Executes Python code with programmatic tool calling. Tools are automatically generated as async Python functions from the tool definitions - DO NOT define them in your code.
+Run tools by writing Python code. Tools are available as async functions - just call them with await.
+
+This is different from execute_code: here you can call your tools (like get_weather, get_expenses, etc.) directly in Python code.
 
 Usage:
-- Write Python code that calls tools using await: result = await get_data()
-- Tools are pre-defined as async functions - just call them
-- Use asyncio.gather() for parallel execution (single round-trip!)
-- Only print() output flows through the context window
-- Tool results from programmatic calls do NOT consume context tokens
-
-When to use:
-- Processing multiple records with tool calls (10+ items)
-- Loops, conditionals, or aggregation based on tool results
-- Any workflow requiring 3+ sequential tool calls
-- Parallel execution of independent tool calls
-- Filtering/summarizing large data before returning to context
-
-Patterns:
-- Simple: result = await get_data()
-- Loop: for item in items: data = await fetch(item)
-- Parallel: results = await asyncio.gather(t1(), t2(), t3())
-- Conditional: if x: await tool_a() else: await tool_b()
+- Tools are pre-defined as async functions - call them with await
+- Use asyncio.gather() to run multiple tools in parallel
+- Only print() output is returned - tool results stay in Python
+
+Examples:
+- Simple: result = await get_weather(city="NYC")
+- Loop: for user in users: data = await get_expenses(user_id=user['id'])
+- Parallel: sf, ny = await asyncio.gather(get_weather(city="SF"), get_weather(city="NY"))
+
+When to use this instead of calling tools directly:
+- You need to call tools in a loop (process many items)
+- You want parallel execution (asyncio.gather)
+- You need conditionals based on tool results
+- You want to aggregate/filter data before returning
 `.trim();
 
   return tool<typeof ProgrammaticToolCallingSchema>(
     async (params, config) => {
-      const { code, tools, session_id, timeout = DEFAULT_TIMEOUT } = params;
+      const { code, session_id, timeout = DEFAULT_TIMEOUT } = params;
 
       // Extra params injected by ToolNode (follows web_search pattern)
-      const { toolMap, programmaticToolDefs } = config.toolCall ?? {};
+      const { toolMap, toolDefs } = (config.toolCall ?? {}) as ToolCall &
+        Partial<t.ProgrammaticCache>;
 
       if (toolMap == null || toolMap.size === 0) {
         throw new Error(
@@ -324,13 +450,10 @@ Patterns:
         );
       }
 
-      // Use provided tools or fall back to programmaticToolDefs from ToolNode
-      const effectiveTools = tools ?? programmaticToolDefs;
-
-      if (effectiveTools == null || effectiveTools.length === 0) {
+      if (toolDefs == null || toolDefs.length === 0) {
         throw new Error(
           'No tool definitions provided. ' +
-            'Either pass tools in the input or ensure ToolNode injects programmaticToolDefs.'
+            'Either pass tools in the input or ensure ToolNode injects toolDefs.'
         );
       }
 
@@ -338,9 +461,19 @@ Patterns:
 
       try {
         // ====================================================================
-        // Phase 1: Initial request
+        // Phase 1: Filter tools and make initial request
         // ====================================================================
 
+        const effectiveTools = filterToolsByUsage(toolDefs, code, debug);
+
+        if (debug) {
+          // eslint-disable-next-line no-console
+          console.log(
+            `[PTC Debug] Sending ${effectiveTools.length} tools to API ` +
+              `(filtered from ${toolDefs.length})`
+          );
+        }
+
         let response = await makeRequest(
           EXEC_ENDPOINT,
           apiKey,
@@ -368,10 +501,12 @@ Patterns:
             );
           }
 
-          // eslint-disable-next-line no-console
-          console.log(
-            `[PTC] Round trip ${roundTrip}: ${response.tool_calls?.length ?? 0} tool(s) to execute`
-          );
+          if (debug) {
+            // eslint-disable-next-line no-console
+            console.log(
+              `[PTC Debug] Round trip ${roundTrip}: ${response.tool_calls?.length ?? 0} tool(s) to execute`
+            );
+          }
 
           const toolResults = await executeTools(
             response.tool_calls ?? [],

package/src/tools/ToolNode.ts

@@ -31,7 +31,6 @@ function isSend(value: unknown): value is Send {
 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export class ToolNode<T = any> extends RunnableCallable<T, T> {
-  tools: t.GenericTool[];
   private toolMap: Map<string, StructuredToolInterface | RunnableToolLike>;
   private loadRuntimeTools?: t.ToolRefGenerator;
   handleToolErrors = true;
@@ -39,12 +38,10 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
   toolCallStepIds?: Map<string, string>;
   errorHandler?: t.ToolNodeConstructorParams['errorHandler'];
   private toolUsageCount: Map<string, number>;
-  /** Tools available for programmatic code execution */
-  private programmaticToolMap?: t.ToolMap;
-  /** Tool definitions for programmatic code execution (sent to Code API) */
-  private programmaticToolDefs?: t.LCTool[];
-  /** Tool registry for tool search (deferred tools) */
+  /** Tool registry for filtering (lazy computation of programmatic maps) */
   private toolRegistry?: t.LCToolRegistry;
+  /** Cached programmatic tools (computed once on first PTC call) */
+  private programmaticCache?: t.ProgrammaticCache;
 
   constructor({
     tools,
@@ -55,23 +52,44 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
     toolCallStepIds,
     handleToolErrors,
     loadRuntimeTools,
-    programmaticToolMap,
-    programmaticToolDefs,
     toolRegistry,
   }: t.ToolNodeConstructorParams) {
     super({ name, tags, func: (input, config) => this.run(input, config) });
-    this.tools = tools;
     this.toolMap = toolMap ?? new Map(tools.map((tool) => [tool.name, tool]));
     this.toolCallStepIds = toolCallStepIds;
     this.handleToolErrors = handleToolErrors ?? this.handleToolErrors;
     this.loadRuntimeTools = loadRuntimeTools;
     this.errorHandler = errorHandler;
     this.toolUsageCount = new Map<string, number>();
-    this.programmaticToolMap = programmaticToolMap;
-    this.programmaticToolDefs = programmaticToolDefs;
     this.toolRegistry = toolRegistry;
   }
 
+  /**
+   * Returns cached programmatic tools, computing once on first access.
+   * Single iteration builds both toolMap and toolDefs simultaneously.
+   */
+  private getProgrammaticTools(): { toolMap: t.ToolMap; toolDefs: t.LCTool[] } {
+    if (this.programmaticCache) return this.programmaticCache;
+
+    const toolMap: t.ToolMap = new Map();
+    const toolDefs: t.LCTool[] = [];
+
+    if (this.toolRegistry) {
+      for (const [name, toolDef] of this.toolRegistry) {
+        if (
+          (toolDef.allowed_callers ?? ['direct']).includes('code_execution')
+        ) {
+          toolDefs.push(toolDef);
+          const tool = this.toolMap.get(name);
+          if (tool) toolMap.set(name, tool);
+        }
+      }
+    }
+
+    this.programmaticCache = { toolMap, toolDefs };
+    return this.programmaticCache;
+  }
+
   /**
    * Returns a snapshot of the current tool usage counts.
    * @returns A ReadonlyMap where keys are tool names and values are their usage counts.
@@ -108,10 +126,11 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
 
       // Inject runtime data for special tools (becomes available at config.toolCall)
       if (call.name === Constants.PROGRAMMATIC_TOOL_CALLING) {
+        const { toolMap, toolDefs } = this.getProgrammaticTools();
         invokeParams = {
           ...invokeParams,
-          toolMap: this.programmaticToolMap,
-          programmaticToolDefs: this.programmaticToolDefs,
+          toolMap,
+          toolDefs,
         };
       } else if (call.name === Constants.TOOL_SEARCH_REGEX) {
         invokeParams = {
@@ -228,9 +247,9 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
         const { tools, toolMap } = this.loadRuntimeTools(
           aiMessage.tool_calls ?? []
         );
-        this.tools = tools;
         this.toolMap =
           toolMap ?? new Map(tools.map((tool) => [tool.name, tool]));
+        this.programmaticCache = undefined; // Invalidate cache on toolMap change
       }
 
       outputs = await Promise.all(