@librechat/agents 3.0.43 → 3.0.45

package/src/tools/ProgrammaticToolCalling.ts

@@ -97,25 +97,90 @@ 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.
- * Matches patterns like `await tool_name(`, `tool_name(`, and asyncio.gather calls.
+ * Handles hyphen/underscore conversion since Python identifiers use underscores.
  * @param code - The Python code to analyze
- * @param availableToolNames - Set of available tool names to match against
- * @returns Set of tool names found in the code
+ * @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,
-  availableToolNames: Set<string>
+  toolNameMap: Map<string, string>
 ): Set<string> {
   const usedTools = new Set<string>();
 
-  for (const toolName of availableToolNames) {
-    const escapedName = toolName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  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(toolName);
+      usedTools.add(originalName);
     }
   }
 
@@ -124,18 +189,45 @@ export function extractUsedToolNames(
 
 /**
  * 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
+  code: string,
+  debug = false
 ): t.LCTool[] {
-  const availableToolNames = new Set(toolDefs.map((tool) => tool.name));
-  const usedToolNames = extractUsedToolNames(code, availableToolNames);
+  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;
   }
 
@@ -182,9 +274,93 @@ export async function makeRequest(
   return (await response.json()) as t.ProgrammaticExecutionResponse;
 }
 
+/**
+ * Unwraps tool responses that may be formatted as tuples.
+ * MCP tools return [content, artifacts], we need to extract the raw data.
+ * @param result - The raw result from tool.invoke()
+ * @param isMCPTool - Whether this is an MCP tool (has mcp property)
+ * @returns Unwrapped raw data (string, object, or parsed JSON)
+ */
+export function unwrapToolResponse(
+  result: unknown,
+  isMCPTool: boolean
+): unknown {
+  // Only unwrap if this is an MCP tool and result is a tuple
+  if (!isMCPTool) {
+    return result;
+  }
+
+  // Check if result is a tuple/array with [content, artifacts]
+  if (Array.isArray(result) && result.length >= 1) {
+    const [content] = result;
+
+    // If first element is a string, return it
+    if (typeof content === 'string') {
+      // Try to parse as JSON if it looks like JSON
+      if (typeof content === 'string' && content.trim().startsWith('{')) {
+        try {
+          return JSON.parse(content);
+        } catch {
+          return content;
+        }
+      }
+      return content;
+    }
+
+    // If first element is an array (content blocks), extract text/data
+    if (Array.isArray(content)) {
+      // If it's an array of content blocks (like [{ type: 'text', text: '...' }])
+      if (
+        content.length > 0 &&
+        typeof content[0] === 'object' &&
+        'type' in content[0]
+      ) {
+        // Extract text from content blocks
+        const texts = content
+          .filter((block: unknown) => {
+            if (typeof block !== 'object' || block === null) return false;
+            const b = block as Record<string, unknown>;
+            return b.type === 'text' && typeof b.text === 'string';
+          })
+          .map((block: unknown) => {
+            const b = block as Record<string, unknown>;
+            return b.text as string;
+          });
+
+        if (texts.length > 0) {
+          const combined = texts.join('\n');
+          // Try to parse as JSON if it looks like JSON (objects or arrays)
+          if (
+            combined.trim().startsWith('{') ||
+            combined.trim().startsWith('[')
+          ) {
+            try {
+              return JSON.parse(combined);
+            } catch {
+              return combined;
+            }
+          }
+          return combined;
+        }
+      }
+      // Otherwise return the content array as-is
+      return content;
+    }
+
+    // If first element is an object, return it
+    if (typeof content === 'object' && content !== null) {
+      return content;
+    }
+  }
+
+  // Not a formatted response, return as-is
+  return result;
+}
+
 /**
  * Executes tools in parallel when requested by the API.
  * Uses Promise.all for parallel execution, catching individual errors.
+ * Unwraps formatted responses (e.g., MCP tool tuples) to raw data.
  * @param toolCalls - Array of tool calls from the API
  * @param toolMap - Map of tool names to executable tools
  * @returns Array of tool results
@@ -209,9 +385,13 @@ export async function executeTools(
       const result = await tool.invoke(call.input, {
         metadata: { [Constants.PROGRAMMATIC_TOOL_CALLING]: true },
       });
+
+      const isMCPTool = tool.mcp === true;
+      const unwrappedResult = unwrapToolResponse(result, isMCPTool);
+
       return {
         call_id: call.id,
-        result,
+        result: unwrappedResult,
         is_error: false,
       };
     } catch (error) {
@@ -318,6 +498,7 @@ 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 = `
@@ -371,7 +552,15 @@ When to use this instead of calling tools directly:
         // Phase 1: Filter tools and make initial request
         // ====================================================================
 
-        const effectiveTools = filterToolsByUsage(toolDefs, code);
+        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,
@@ -400,10 +589,12 @@ When to use this instead of calling tools directly:
             );
           }
 
-          // 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/__tests__/ProgrammaticToolCalling.test.ts

@@ -11,6 +11,7 @@ import {
   extractUsedToolNames,
   filterToolsByUsage,
   executeTools,
+  normalizeToPythonIdentifier,
 } from '../ProgrammaticToolCalling';
 import {
   createProgrammaticToolRegistry,
@@ -185,8 +186,58 @@ 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 availableTools = new Set([
+    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',
@@ -262,16 +313,30 @@ x = 1 + 2`;
       expect(used.size).toBe(0);
     });
 
-    it('handles tool names with special regex characters', () => {
-      const specialTools = new Set(['get_data.v2', 'calc+plus']);
-      const code = `await get_data.v2()
-await calc+plus()`;
+    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', () => {

package/src/types/tools.ts

@@ -15,7 +15,9 @@ export type CustomToolCall = {
   output?: string;
 };
 
-export type GenericTool = StructuredToolInterface | RunnableToolLike;
+export type GenericTool = (StructuredToolInterface | RunnableToolLike) & {
+  mcp?: boolean;
+};
 
 export type ToolMap = Map<string, GenericTool>;
 export type ToolRefs = {
@@ -239,6 +241,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;
 };