@librechat/agents 3.0.43 → 3.0.44

package/dist/cjs/main.cjs

@@ -84,6 +84,7 @@ exports.extractUsedToolNames = ProgrammaticToolCalling.extractUsedToolNames;
 exports.filterToolsByUsage = ProgrammaticToolCalling.filterToolsByUsage;
 exports.formatCompletedResponse = ProgrammaticToolCalling.formatCompletedResponse;
 exports.makeRequest = ProgrammaticToolCalling.makeRequest;
+exports.normalizeToPythonIdentifier = ProgrammaticToolCalling.normalizeToPythonIdentifier;
 exports.countNestedGroups = ToolSearchRegex.countNestedGroups;
 exports.createToolSearchRegexTool = ToolSearchRegex.createToolSearchRegexTool;
 exports.escapeRegexSpecialChars = ToolSearchRegex.escapeRegexSpecialChars;

package/dist/cjs/main.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"main.cjs","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}
+{"version":3,"file":"main.cjs","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}

package/dist/cjs/tools/ProgrammaticToolCalling.cjs

@@ -81,34 +81,111 @@ 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
+ */
+function normalizeToPythonIdentifier(name) {
+    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
  */
-function extractUsedToolNames(code, availableToolNames) {
+function extractUsedToolNames(code, toolNameMap) {
     const usedTools = new Set();
-    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);
         }
     }
     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
  */
-function filterToolsByUsage(toolDefs, code) {
-    const availableToolNames = new Set(toolDefs.map((tool) => tool.name));
-    const usedToolNames = extractUsedToolNames(code, availableToolNames);
+function filterToolsByUsage(toolDefs, code, debug = false) {
+    const toolNameMap = new Map();
+    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));
@@ -254,6 +331,7 @@ function createProgrammaticToolCallingTool(initParams = {}) {
     const baseUrl = initParams.baseUrl ?? CodeExecutor.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 = `
 Run tools by writing Python code. Tools are available as async functions - just call them with await.
@@ -293,7 +371,12 @@ 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, apiKey, {
                 code,
                 tools: effectiveTools,
@@ -310,8 +393,10 @@ When to use this instead of calling tools directly:
                         'This may indicate an infinite loop, excessive tool calls, ' +
                         'or a logic error in your code.');
                 }
-                // 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 ?? [], toolMap);
                 response = await makeRequest(EXEC_ENDPOINT, apiKey, {
                     continuation_token: response.continuation_token,
@@ -349,4 +434,5 @@ exports.extractUsedToolNames = extractUsedToolNames;
 exports.filterToolsByUsage = filterToolsByUsage;
 exports.formatCompletedResponse = formatCompletedResponse;
 exports.makeRequest = makeRequest;
+exports.normalizeToPythonIdentifier = normalizeToPythonIdentifier;
 //# sourceMappingURL=ProgrammaticToolCalling.cjs.map

package/dist/cjs/tools/ProgrammaticToolCalling.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"ProgrammaticToolCalling.cjs","sources":["../../../src/tools/ProgrammaticToolCalling.ts"],"sourcesContent":["// src/tools/ProgrammaticToolCalling.ts\nimport { z } from 'zod';\nimport { config } from 'dotenv';\nimport fetch, { RequestInit } from 'node-fetch';\nimport { HttpsProxyAgent } from 'https-proxy-agent';\nimport { getEnvironmentVariable } from '@langchain/core/utils/env';\nimport { tool, DynamicStructuredTool } from '@langchain/core/tools';\nimport type { ToolCall } from '@langchain/core/messages/tool';\nimport type * as t from '@/types';\nimport { imageExtRegex, getCodeBaseURL } from './CodeExecutor';\nimport { EnvVar, Constants } from '@/common';\n\nconfig();\n\n// ============================================================================\n// Constants\n// ============================================================================\n\nconst imageMessage = 'Image is already displayed to the user';\nconst otherMessage = 'File is already downloaded by the user';\nconst accessMessage =\n  'Note: Files are READ-ONLY. Save changes to NEW filenames. To access these files in future executions, provide the `session_id` as a parameter (not in your code).';\nconst emptyOutputMessage =\n  'stdout: Empty. Ensure you\\'re writing output explicitly.\\n';\n\n/** Default max round-trips to prevent infinite loops */\nconst DEFAULT_MAX_ROUND_TRIPS = 20;\n\n/** Default execution timeout in milliseconds */\nconst DEFAULT_TIMEOUT = 60000;\n\n// ============================================================================\n// Schema\n// ============================================================================\n\nconst ProgrammaticToolCallingSchema = z.object({\n  code: z\n    .string()\n    .min(1)\n    .describe(\n      `Python code that calls tools programmatically. Tools are automatically available as async Python functions - DO NOT define them yourself.\n\nThe Code API generates async function stubs from the tool definitions. Just call them directly:\n\nExample (Simple call):\n  result = await get_weather(city=\"San Francisco\")\n  print(result)\n\nExample (Parallel - Fastest):\n  results = await asyncio.gather(\n      get_weather(city=\"SF\"),\n      get_weather(city=\"NYC\"),\n      get_weather(city=\"London\")\n  )\n  for city, weather in zip([\"SF\", \"NYC\", \"London\"], results):\n      print(f\"{city}: {weather['temperature']}°F\")\n\nExample (Loop with processing):\n  team = await get_team_members()\n  for member in team:\n      expenses = await get_expenses(user_id=member['id'])\n      total = sum(e['amount'] for e in expenses)\n      print(f\"{member['name']}: \\${total:.2f}\")\n\nExample (Conditional logic):\n  data = await fetch_data(source=\"primary\")\n  if not data:\n      data = await fetch_data(source=\"backup\")\n  print(f\"Got {len(data)} records\")\n\nRequirements:\n- Tools are pre-defined as async functions - DO NOT write function definitions\n- Use await for all tool calls\n- Use asyncio.gather() for parallel execution of independent calls\n- Only print() output flows back to the context window\n- Tool results from programmatic calls do NOT consume context tokens`\n    ),\n  session_id: z\n    .string()\n    .optional()\n    .describe(\n      'Session ID for file access (same as regular code execution). Files load into /mnt/data/ and are READ-ONLY.'\n    ),\n  timeout: z\n    .number()\n    .int()\n    .min(1000)\n    .max(300000)\n    .optional()\n    .default(DEFAULT_TIMEOUT)\n    .describe(\n      'Maximum execution time in milliseconds. Default: 60 seconds. Max: 5 minutes.'\n    ),\n});\n\n// ============================================================================\n// Helper Functions\n// ============================================================================\n\n/**\n * Extracts tool names that are actually called in the Python code.\n * Matches patterns like `await tool_name(`, `tool_name(`, and asyncio.gather calls.\n * @param code - The Python code to analyze\n * @param availableToolNames - Set of available tool names to match against\n * @returns Set of tool names found in the code\n */\nexport function extractUsedToolNames(\n  code: string,\n  availableToolNames: Set<string>\n): Set<string> {\n  const usedTools = new Set<string>();\n\n  for (const toolName of availableToolNames) {\n    const escapedName = toolName.replace(/[.*+?^${}()|[\\]\\\\]/g, '\\\\$&');\n    const pattern = new RegExp(`\\\\b${escapedName}\\\\s*\\\\(`, 'g');\n\n    if (pattern.test(code)) {\n      usedTools.add(toolName);\n    }\n  }\n\n  return usedTools;\n}\n\n/**\n * Filters tool definitions to only include tools actually used in the code.\n * @param toolDefs - All available tool definitions\n * @param code - The Python code to analyze\n * @returns Filtered array of tool definitions\n */\nexport function filterToolsByUsage(\n  toolDefs: t.LCTool[],\n  code: string\n): t.LCTool[] {\n  const availableToolNames = new Set(toolDefs.map((tool) => tool.name));\n  const usedToolNames = extractUsedToolNames(code, availableToolNames);\n\n  if (usedToolNames.size === 0) {\n    return toolDefs;\n  }\n\n  return toolDefs.filter((tool) => usedToolNames.has(tool.name));\n}\n\n/**\n * Makes an HTTP request to the Code API.\n * @param endpoint - The API endpoint URL\n * @param apiKey - The API key for authentication\n * @param body - The request body\n * @param proxy - Optional HTTP proxy URL\n * @returns The parsed API response\n */\nexport async function makeRequest(\n  endpoint: string,\n  apiKey: string,\n  body: Record<string, unknown>,\n  proxy?: string\n): Promise<t.ProgrammaticExecutionResponse> {\n  const fetchOptions: RequestInit = {\n    method: 'POST',\n    headers: {\n      'Content-Type': 'application/json',\n      'User-Agent': 'LibreChat/1.0',\n      'X-API-Key': apiKey,\n    },\n    body: JSON.stringify(body),\n  };\n\n  if (proxy != null && proxy !== '') {\n    fetchOptions.agent = new HttpsProxyAgent(proxy);\n  }\n\n  const response = await fetch(endpoint, fetchOptions);\n\n  if (!response.ok) {\n    const errorText = await response.text();\n    throw new Error(\n      `HTTP error! status: ${response.status}, body: ${errorText}`\n    );\n  }\n\n  return (await response.json()) as t.ProgrammaticExecutionResponse;\n}\n\n/**\n * Executes tools in parallel when requested by the API.\n * Uses Promise.all for parallel execution, catching individual errors.\n * @param toolCalls - Array of tool calls from the API\n * @param toolMap - Map of tool names to executable tools\n * @returns Array of tool results\n */\nexport async function executeTools(\n  toolCalls: t.PTCToolCall[],\n  toolMap: t.ToolMap\n): Promise<t.PTCToolResult[]> {\n  const executions = toolCalls.map(async (call): Promise<t.PTCToolResult> => {\n    const tool = toolMap.get(call.name);\n\n    if (!tool) {\n      return {\n        call_id: call.id,\n        result: null,\n        is_error: true,\n        error_message: `Tool '${call.name}' not found. Available tools: ${Array.from(toolMap.keys()).join(', ')}`,\n      };\n    }\n\n    try {\n      const result = await tool.invoke(call.input, {\n        metadata: { [Constants.PROGRAMMATIC_TOOL_CALLING]: true },\n      });\n      return {\n        call_id: call.id,\n        result,\n        is_error: false,\n      };\n    } catch (error) {\n      return {\n        call_id: call.id,\n        result: null,\n        is_error: true,\n        error_message: (error as Error).message || 'Tool execution failed',\n      };\n    }\n  });\n\n  return await Promise.all(executions);\n}\n\n/**\n * Formats the completed response for the agent.\n * @param response - The completed API response\n * @returns Tuple of [formatted string, artifact]\n */\nexport function formatCompletedResponse(\n  response: t.ProgrammaticExecutionResponse\n): [string, t.ProgrammaticExecutionArtifact] {\n  let formatted = '';\n\n  if (response.stdout != null && response.stdout !== '') {\n    formatted += `stdout:\\n${response.stdout}\\n`;\n  } else {\n    formatted += emptyOutputMessage;\n  }\n\n  if (response.stderr != null && response.stderr !== '') {\n    formatted += `stderr:\\n${response.stderr}\\n`;\n  }\n\n  if (response.files && response.files.length > 0) {\n    formatted += 'Generated files:\\n';\n\n    const fileCount = response.files.length;\n    for (let i = 0; i < fileCount; i++) {\n      const file = response.files[i];\n      const isImage = imageExtRegex.test(file.name);\n      formatted += `- /mnt/data/${file.name} | ${isImage ? imageMessage : otherMessage}`;\n\n      if (i < fileCount - 1) {\n        formatted += fileCount <= 3 ? ', ' : ',\\n';\n      }\n    }\n\n    formatted += `\\nsession_id: ${response.session_id}\\n\\n${accessMessage}`;\n  }\n\n  return [\n    formatted.trim(),\n    {\n      session_id: response.session_id,\n      files: response.files,\n    },\n  ];\n}\n\n// ============================================================================\n// Tool Factory\n// ============================================================================\n\n/**\n * Creates a Programmatic Tool Calling tool for complex multi-tool workflows.\n *\n * This tool enables AI agents to write Python code that orchestrates multiple\n * tool calls programmatically, reducing LLM round-trips and token usage.\n *\n * The tool map must be provided at runtime via config.configurable.toolMap.\n *\n * @param params - Configuration parameters (apiKey, baseUrl, maxRoundTrips, proxy)\n * @returns A LangChain DynamicStructuredTool for programmatic tool calling\n *\n * @example\n * const ptcTool = createProgrammaticToolCallingTool({\n *   apiKey: process.env.CODE_API_KEY,\n *   maxRoundTrips: 20\n * });\n *\n * const [output, artifact] = await ptcTool.invoke(\n *   { code, tools },\n *   { configurable: { toolMap } }\n * );\n */\nexport function createProgrammaticToolCallingTool(\n  initParams: t.ProgrammaticToolCallingParams = {}\n): DynamicStructuredTool<typeof ProgrammaticToolCallingSchema> {\n  const apiKey =\n    (initParams[EnvVar.CODE_API_KEY] as string | undefined) ??\n    initParams.apiKey ??\n    getEnvironmentVariable(EnvVar.CODE_API_KEY) ??\n    '';\n\n  if (!apiKey) {\n    throw new Error(\n      'No API key provided for programmatic tool calling. ' +\n        'Set CODE_API_KEY environment variable or pass apiKey in initParams.'\n    );\n  }\n\n  const baseUrl = initParams.baseUrl ?? getCodeBaseURL();\n  const maxRoundTrips = initParams.maxRoundTrips ?? DEFAULT_MAX_ROUND_TRIPS;\n  const proxy = initParams.proxy ?? process.env.PROXY;\n  const EXEC_ENDPOINT = `${baseUrl}/exec/programmatic`;\n\n  const description = `\nRun tools by writing Python code. Tools are available as async functions - just call them with await.\n\nThis is different from execute_code: here you can call your tools (like get_weather, get_expenses, etc.) directly in Python code.\n\nUsage:\n- Tools are pre-defined as async functions - call them with await\n- Use asyncio.gather() to run multiple tools in parallel\n- Only print() output is returned - tool results stay in Python\n\nExamples:\n- Simple: result = await get_weather(city=\"NYC\")\n- Loop: for user in users: data = await get_expenses(user_id=user['id'])\n- Parallel: sf, ny = await asyncio.gather(get_weather(city=\"SF\"), get_weather(city=\"NY\"))\n\nWhen to use this instead of calling tools directly:\n- You need to call tools in a loop (process many items)\n- You want parallel execution (asyncio.gather)\n- You need conditionals based on tool results\n- You want to aggregate/filter data before returning\n`.trim();\n\n  return tool<typeof ProgrammaticToolCallingSchema>(\n    async (params, config) => {\n      const { code, session_id, timeout = DEFAULT_TIMEOUT } = params;\n\n      // Extra params injected by ToolNode (follows web_search pattern)\n      const { toolMap, toolDefs } = (config.toolCall ?? {}) as ToolCall &\n        Partial<t.ProgrammaticCache>;\n\n      if (toolMap == null || toolMap.size === 0) {\n        throw new Error(\n          'No toolMap provided. ' +\n            'ToolNode should inject this from AgentContext when invoked through the graph.'\n        );\n      }\n\n      if (toolDefs == null || toolDefs.length === 0) {\n        throw new Error(\n          'No tool definitions provided. ' +\n            'Either pass tools in the input or ensure ToolNode injects toolDefs.'\n        );\n      }\n\n      let roundTrip = 0;\n\n      try {\n        // ====================================================================\n        // Phase 1: Filter tools and make initial request\n        // ====================================================================\n\n        const effectiveTools = filterToolsByUsage(toolDefs, code);\n\n        let response = await makeRequest(\n          EXEC_ENDPOINT,\n          apiKey,\n          {\n            code,\n            tools: effectiveTools,\n            session_id,\n            timeout,\n          },\n          proxy\n        );\n\n        // ====================================================================\n        // Phase 2: Handle response loop\n        // ====================================================================\n\n        while (response.status === 'tool_call_required') {\n          roundTrip++;\n\n          if (roundTrip > maxRoundTrips) {\n            throw new Error(\n              `Exceeded maximum round trips (${maxRoundTrips}). ` +\n                'This may indicate an infinite loop, excessive tool calls, ' +\n                'or a logic error in your code.'\n            );\n          }\n\n          // eslint-disable-next-line no-console\n          console.log(\n            `[PTC] Round trip ${roundTrip}: ${response.tool_calls?.length ?? 0} tool(s) to execute`\n          );\n\n          const toolResults = await executeTools(\n            response.tool_calls ?? [],\n            toolMap\n          );\n\n          response = await makeRequest(\n            EXEC_ENDPOINT,\n            apiKey,\n            {\n              continuation_token: response.continuation_token,\n              tool_results: toolResults,\n            },\n            proxy\n          );\n        }\n\n        // ====================================================================\n        // Phase 3: Handle final state\n        // ====================================================================\n\n        if (response.status === 'completed') {\n          return formatCompletedResponse(response);\n        }\n\n        if (response.status === 'error') {\n          throw new Error(\n            `Execution error: ${response.error}` +\n              (response.stderr != null && response.stderr !== ''\n                ? `\\n\\nStderr:\\n${response.stderr}`\n                : '')\n          );\n        }\n\n        throw new Error(`Unexpected response status: ${response.status}`);\n      } catch (error) {\n        throw new Error(\n          `Programmatic execution failed: ${(error as Error).message}`\n        );\n      }\n    },\n    {\n      name: Constants.PROGRAMMATIC_TOOL_CALLING,\n      description,\n      schema: ProgrammaticToolCallingSchema,\n      responseFormat: Constants.CONTENT_AND_ARTIFACT,\n    }\n  );\n}\n"],"names":["config","z","HttpsProxyAgent","Constants","imageExtRegex","EnvVar","getEnvironmentVariable","getCodeBaseURL","tool"],"mappings":"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"}
+{"version":3,"file":"ProgrammaticToolCalling.cjs","sources":["../../../src/tools/ProgrammaticToolCalling.ts"],"sourcesContent":["// src/tools/ProgrammaticToolCalling.ts\nimport { z } from 'zod';\nimport { config } from 'dotenv';\nimport fetch, { RequestInit } from 'node-fetch';\nimport { HttpsProxyAgent } from 'https-proxy-agent';\nimport { getEnvironmentVariable } from '@langchain/core/utils/env';\nimport { tool, DynamicStructuredTool } from '@langchain/core/tools';\nimport type { ToolCall } from '@langchain/core/messages/tool';\nimport type * as t from '@/types';\nimport { imageExtRegex, getCodeBaseURL } from './CodeExecutor';\nimport { EnvVar, Constants } from '@/common';\n\nconfig();\n\n// ============================================================================\n// Constants\n// ============================================================================\n\nconst imageMessage = 'Image is already displayed to the user';\nconst otherMessage = 'File is already downloaded by the user';\nconst accessMessage =\n  'Note: Files are READ-ONLY. Save changes to NEW filenames. To access these files in future executions, provide the `session_id` as a parameter (not in your code).';\nconst emptyOutputMessage =\n  'stdout: Empty. Ensure you\\'re writing output explicitly.\\n';\n\n/** Default max round-trips to prevent infinite loops */\nconst DEFAULT_MAX_ROUND_TRIPS = 20;\n\n/** Default execution timeout in milliseconds */\nconst DEFAULT_TIMEOUT = 60000;\n\n// ============================================================================\n// Schema\n// ============================================================================\n\nconst ProgrammaticToolCallingSchema = z.object({\n  code: z\n    .string()\n    .min(1)\n    .describe(\n      `Python code that calls tools programmatically. Tools are automatically available as async Python functions - DO NOT define them yourself.\n\nThe Code API generates async function stubs from the tool definitions. Just call them directly:\n\nExample (Simple call):\n  result = await get_weather(city=\"San Francisco\")\n  print(result)\n\nExample (Parallel - Fastest):\n  results = await asyncio.gather(\n      get_weather(city=\"SF\"),\n      get_weather(city=\"NYC\"),\n      get_weather(city=\"London\")\n  )\n  for city, weather in zip([\"SF\", \"NYC\", \"London\"], results):\n      print(f\"{city}: {weather['temperature']}°F\")\n\nExample (Loop with processing):\n  team = await get_team_members()\n  for member in team:\n      expenses = await get_expenses(user_id=member['id'])\n      total = sum(e['amount'] for e in expenses)\n      print(f\"{member['name']}: \\${total:.2f}\")\n\nExample (Conditional logic):\n  data = await fetch_data(source=\"primary\")\n  if not data:\n      data = await fetch_data(source=\"backup\")\n  print(f\"Got {len(data)} records\")\n\nRequirements:\n- Tools are pre-defined as async functions - DO NOT write function definitions\n- Use await for all tool calls\n- Use asyncio.gather() for parallel execution of independent calls\n- Only print() output flows back to the context window\n- Tool results from programmatic calls do NOT consume context tokens`\n    ),\n  session_id: z\n    .string()\n    .optional()\n    .describe(\n      'Session ID for file access (same as regular code execution). Files load into /mnt/data/ and are READ-ONLY.'\n    ),\n  timeout: z\n    .number()\n    .int()\n    .min(1000)\n    .max(300000)\n    .optional()\n    .default(DEFAULT_TIMEOUT)\n    .describe(\n      'Maximum execution time in milliseconds. Default: 60 seconds. Max: 5 minutes.'\n    ),\n});\n\n// ============================================================================\n// Helper Functions\n// ============================================================================\n\n/** Python reserved keywords that get `_tool` suffix in Code API */\nconst PYTHON_KEYWORDS = new Set([\n  'False',\n  'None',\n  'True',\n  'and',\n  'as',\n  'assert',\n  'async',\n  'await',\n  'break',\n  'class',\n  'continue',\n  'def',\n  'del',\n  'elif',\n  'else',\n  'except',\n  'finally',\n  'for',\n  'from',\n  'global',\n  'if',\n  'import',\n  'in',\n  'is',\n  'lambda',\n  'nonlocal',\n  'not',\n  'or',\n  'pass',\n  'raise',\n  'return',\n  'try',\n  'while',\n  'with',\n  'yield',\n]);\n\n/**\n * Normalizes a tool name to Python identifier format.\n * Must match the Code API's `normalizePythonFunctionName` exactly:\n * 1. Replace hyphens and spaces with underscores\n * 2. Remove any other invalid characters\n * 3. Prefix with underscore if starts with number\n * 4. Append `_tool` if it's a Python keyword\n * @param name - The tool name to normalize\n * @returns Normalized Python-safe identifier\n */\nexport function normalizeToPythonIdentifier(name: string): string {\n  let normalized = name.replace(/[-\\s]/g, '_');\n\n  normalized = normalized.replace(/[^a-zA-Z0-9_]/g, '');\n\n  if (/^[0-9]/.test(normalized)) {\n    normalized = '_' + normalized;\n  }\n\n  if (PYTHON_KEYWORDS.has(normalized)) {\n    normalized = normalized + '_tool';\n  }\n\n  return normalized;\n}\n\n/**\n * Extracts tool names that are actually called in the Python code.\n * Handles hyphen/underscore conversion since Python identifiers use underscores.\n * @param code - The Python code to analyze\n * @param toolNameMap - Map from normalized Python name to original tool name\n * @returns Set of original tool names found in the code\n */\nexport function extractUsedToolNames(\n  code: string,\n  toolNameMap: Map<string, string>\n): Set<string> {\n  const usedTools = new Set<string>();\n\n  for (const [pythonName, originalName] of toolNameMap) {\n    const escapedName = pythonName.replace(/[.*+?^${}()|[\\]\\\\]/g, '\\\\$&');\n    const pattern = new RegExp(`\\\\b${escapedName}\\\\s*\\\\(`, 'g');\n\n    if (pattern.test(code)) {\n      usedTools.add(originalName);\n    }\n  }\n\n  return usedTools;\n}\n\n/**\n * Filters tool definitions to only include tools actually used in the code.\n * Handles the hyphen-to-underscore conversion for Python compatibility.\n * @param toolDefs - All available tool definitions\n * @param code - The Python code to analyze\n * @param debug - Enable debug logging\n * @returns Filtered array of tool definitions\n */\nexport function filterToolsByUsage(\n  toolDefs: t.LCTool[],\n  code: string,\n  debug = false\n): t.LCTool[] {\n  const toolNameMap = new Map<string, string>();\n  for (const tool of toolDefs) {\n    const pythonName = normalizeToPythonIdentifier(tool.name);\n    toolNameMap.set(pythonName, tool.name);\n  }\n\n  const usedToolNames = extractUsedToolNames(code, toolNameMap);\n\n  if (debug) {\n    // eslint-disable-next-line no-console\n    console.log(\n      `[PTC Debug] Tool filtering: found ${usedToolNames.size}/${toolDefs.length} tools in code`\n    );\n    if (usedToolNames.size > 0) {\n      // eslint-disable-next-line no-console\n      console.log(\n        `[PTC Debug] Matched tools: ${Array.from(usedToolNames).join(', ')}`\n      );\n    }\n  }\n\n  if (usedToolNames.size === 0) {\n    if (debug) {\n      // eslint-disable-next-line no-console\n      console.log(\n        '[PTC Debug] No tools detected in code - sending all tools as fallback'\n      );\n    }\n    return toolDefs;\n  }\n\n  return toolDefs.filter((tool) => usedToolNames.has(tool.name));\n}\n\n/**\n * Makes an HTTP request to the Code API.\n * @param endpoint - The API endpoint URL\n * @param apiKey - The API key for authentication\n * @param body - The request body\n * @param proxy - Optional HTTP proxy URL\n * @returns The parsed API response\n */\nexport async function makeRequest(\n  endpoint: string,\n  apiKey: string,\n  body: Record<string, unknown>,\n  proxy?: string\n): Promise<t.ProgrammaticExecutionResponse> {\n  const fetchOptions: RequestInit = {\n    method: 'POST',\n    headers: {\n      'Content-Type': 'application/json',\n      'User-Agent': 'LibreChat/1.0',\n      'X-API-Key': apiKey,\n    },\n    body: JSON.stringify(body),\n  };\n\n  if (proxy != null && proxy !== '') {\n    fetchOptions.agent = new HttpsProxyAgent(proxy);\n  }\n\n  const response = await fetch(endpoint, fetchOptions);\n\n  if (!response.ok) {\n    const errorText = await response.text();\n    throw new Error(\n      `HTTP error! status: ${response.status}, body: ${errorText}`\n    );\n  }\n\n  return (await response.json()) as t.ProgrammaticExecutionResponse;\n}\n\n/**\n * Executes tools in parallel when requested by the API.\n * Uses Promise.all for parallel execution, catching individual errors.\n * @param toolCalls - Array of tool calls from the API\n * @param toolMap - Map of tool names to executable tools\n * @returns Array of tool results\n */\nexport async function executeTools(\n  toolCalls: t.PTCToolCall[],\n  toolMap: t.ToolMap\n): Promise<t.PTCToolResult[]> {\n  const executions = toolCalls.map(async (call): Promise<t.PTCToolResult> => {\n    const tool = toolMap.get(call.name);\n\n    if (!tool) {\n      return {\n        call_id: call.id,\n        result: null,\n        is_error: true,\n        error_message: `Tool '${call.name}' not found. Available tools: ${Array.from(toolMap.keys()).join(', ')}`,\n      };\n    }\n\n    try {\n      const result = await tool.invoke(call.input, {\n        metadata: { [Constants.PROGRAMMATIC_TOOL_CALLING]: true },\n      });\n      return {\n        call_id: call.id,\n        result,\n        is_error: false,\n      };\n    } catch (error) {\n      return {\n        call_id: call.id,\n        result: null,\n        is_error: true,\n        error_message: (error as Error).message || 'Tool execution failed',\n      };\n    }\n  });\n\n  return await Promise.all(executions);\n}\n\n/**\n * Formats the completed response for the agent.\n * @param response - The completed API response\n * @returns Tuple of [formatted string, artifact]\n */\nexport function formatCompletedResponse(\n  response: t.ProgrammaticExecutionResponse\n): [string, t.ProgrammaticExecutionArtifact] {\n  let formatted = '';\n\n  if (response.stdout != null && response.stdout !== '') {\n    formatted += `stdout:\\n${response.stdout}\\n`;\n  } else {\n    formatted += emptyOutputMessage;\n  }\n\n  if (response.stderr != null && response.stderr !== '') {\n    formatted += `stderr:\\n${response.stderr}\\n`;\n  }\n\n  if (response.files && response.files.length > 0) {\n    formatted += 'Generated files:\\n';\n\n    const fileCount = response.files.length;\n    for (let i = 0; i < fileCount; i++) {\n      const file = response.files[i];\n      const isImage = imageExtRegex.test(file.name);\n      formatted += `- /mnt/data/${file.name} | ${isImage ? imageMessage : otherMessage}`;\n\n      if (i < fileCount - 1) {\n        formatted += fileCount <= 3 ? ', ' : ',\\n';\n      }\n    }\n\n    formatted += `\\nsession_id: ${response.session_id}\\n\\n${accessMessage}`;\n  }\n\n  return [\n    formatted.trim(),\n    {\n      session_id: response.session_id,\n      files: response.files,\n    },\n  ];\n}\n\n// ============================================================================\n// Tool Factory\n// ============================================================================\n\n/**\n * Creates a Programmatic Tool Calling tool for complex multi-tool workflows.\n *\n * This tool enables AI agents to write Python code that orchestrates multiple\n * tool calls programmatically, reducing LLM round-trips and token usage.\n *\n * The tool map must be provided at runtime via config.configurable.toolMap.\n *\n * @param params - Configuration parameters (apiKey, baseUrl, maxRoundTrips, proxy)\n * @returns A LangChain DynamicStructuredTool for programmatic tool calling\n *\n * @example\n * const ptcTool = createProgrammaticToolCallingTool({\n *   apiKey: process.env.CODE_API_KEY,\n *   maxRoundTrips: 20\n * });\n *\n * const [output, artifact] = await ptcTool.invoke(\n *   { code, tools },\n *   { configurable: { toolMap } }\n * );\n */\nexport function createProgrammaticToolCallingTool(\n  initParams: t.ProgrammaticToolCallingParams = {}\n): DynamicStructuredTool<typeof ProgrammaticToolCallingSchema> {\n  const apiKey =\n    (initParams[EnvVar.CODE_API_KEY] as string | undefined) ??\n    initParams.apiKey ??\n    getEnvironmentVariable(EnvVar.CODE_API_KEY) ??\n    '';\n\n  if (!apiKey) {\n    throw new Error(\n      'No API key provided for programmatic tool calling. ' +\n        'Set CODE_API_KEY environment variable or pass apiKey in initParams.'\n    );\n  }\n\n  const baseUrl = initParams.baseUrl ?? getCodeBaseURL();\n  const maxRoundTrips = initParams.maxRoundTrips ?? DEFAULT_MAX_ROUND_TRIPS;\n  const proxy = initParams.proxy ?? process.env.PROXY;\n  const debug = initParams.debug ?? process.env.PTC_DEBUG === 'true';\n  const EXEC_ENDPOINT = `${baseUrl}/exec/programmatic`;\n\n  const description = `\nRun tools by writing Python code. Tools are available as async functions - just call them with await.\n\nThis is different from execute_code: here you can call your tools (like get_weather, get_expenses, etc.) directly in Python code.\n\nUsage:\n- Tools are pre-defined as async functions - call them with await\n- Use asyncio.gather() to run multiple tools in parallel\n- Only print() output is returned - tool results stay in Python\n\nExamples:\n- Simple: result = await get_weather(city=\"NYC\")\n- Loop: for user in users: data = await get_expenses(user_id=user['id'])\n- Parallel: sf, ny = await asyncio.gather(get_weather(city=\"SF\"), get_weather(city=\"NY\"))\n\nWhen to use this instead of calling tools directly:\n- You need to call tools in a loop (process many items)\n- You want parallel execution (asyncio.gather)\n- You need conditionals based on tool results\n- You want to aggregate/filter data before returning\n`.trim();\n\n  return tool<typeof ProgrammaticToolCallingSchema>(\n    async (params, config) => {\n      const { code, session_id, timeout = DEFAULT_TIMEOUT } = params;\n\n      // Extra params injected by ToolNode (follows web_search pattern)\n      const { toolMap, toolDefs } = (config.toolCall ?? {}) as ToolCall &\n        Partial<t.ProgrammaticCache>;\n\n      if (toolMap == null || toolMap.size === 0) {\n        throw new Error(\n          'No toolMap provided. ' +\n            'ToolNode should inject this from AgentContext when invoked through the graph.'\n        );\n      }\n\n      if (toolDefs == null || toolDefs.length === 0) {\n        throw new Error(\n          'No tool definitions provided. ' +\n            'Either pass tools in the input or ensure ToolNode injects toolDefs.'\n        );\n      }\n\n      let roundTrip = 0;\n\n      try {\n        // ====================================================================\n        // Phase 1: Filter tools and make initial request\n        // ====================================================================\n\n        const effectiveTools = filterToolsByUsage(toolDefs, code, debug);\n\n        if (debug) {\n          // eslint-disable-next-line no-console\n          console.log(\n            `[PTC Debug] Sending ${effectiveTools.length} tools to API ` +\n              `(filtered from ${toolDefs.length})`\n          );\n        }\n\n        let response = await makeRequest(\n          EXEC_ENDPOINT,\n          apiKey,\n          {\n            code,\n            tools: effectiveTools,\n            session_id,\n            timeout,\n          },\n          proxy\n        );\n\n        // ====================================================================\n        // Phase 2: Handle response loop\n        // ====================================================================\n\n        while (response.status === 'tool_call_required') {\n          roundTrip++;\n\n          if (roundTrip > maxRoundTrips) {\n            throw new Error(\n              `Exceeded maximum round trips (${maxRoundTrips}). ` +\n                'This may indicate an infinite loop, excessive tool calls, ' +\n                'or a logic error in your code.'\n            );\n          }\n\n          if (debug) {\n            // eslint-disable-next-line no-console\n            console.log(\n              `[PTC Debug] Round trip ${roundTrip}: ${response.tool_calls?.length ?? 0} tool(s) to execute`\n            );\n          }\n\n          const toolResults = await executeTools(\n            response.tool_calls ?? [],\n            toolMap\n          );\n\n          response = await makeRequest(\n            EXEC_ENDPOINT,\n            apiKey,\n            {\n              continuation_token: response.continuation_token,\n              tool_results: toolResults,\n            },\n            proxy\n          );\n        }\n\n        // ====================================================================\n        // Phase 3: Handle final state\n        // ====================================================================\n\n        if (response.status === 'completed') {\n          return formatCompletedResponse(response);\n        }\n\n        if (response.status === 'error') {\n          throw new Error(\n            `Execution error: ${response.error}` +\n              (response.stderr != null && response.stderr !== ''\n                ? `\\n\\nStderr:\\n${response.stderr}`\n                : '')\n          );\n        }\n\n        throw new Error(`Unexpected response status: ${response.status}`);\n      } catch (error) {\n        throw new Error(\n          `Programmatic execution failed: ${(error as Error).message}`\n        );\n      }\n    },\n    {\n      name: Constants.PROGRAMMATIC_TOOL_CALLING,\n      description,\n      schema: ProgrammaticToolCallingSchema,\n      responseFormat: Constants.CONTENT_AND_ARTIFACT,\n    }\n  );\n}\n"],"names":["config","z","HttpsProxyAgent","Constants","imageExtRegex","EnvVar","getEnvironmentVariable","getCodeBaseURL","tool"],"mappings":"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"}

package/dist/esm/main.mjs

@@ -13,7 +13,7 @@ export { Graph, StandardGraph } from './graphs/Graph.mjs';
 export { MultiAgentGraph } from './graphs/MultiAgentGraph.mjs';
 export { Calculator } from './tools/Calculator.mjs';
 export { createCodeExecutionTool, getCodeBaseURL, imageExtRegex } from './tools/CodeExecutor.mjs';
-export { createProgrammaticToolCallingTool, executeTools, extractUsedToolNames, filterToolsByUsage, formatCompletedResponse, makeRequest } from './tools/ProgrammaticToolCalling.mjs';
+export { createProgrammaticToolCallingTool, executeTools, extractUsedToolNames, filterToolsByUsage, formatCompletedResponse, makeRequest, normalizeToPythonIdentifier } from './tools/ProgrammaticToolCalling.mjs';
 export { countNestedGroups, createToolSearchRegexTool, escapeRegexSpecialChars, hasNestedQuantifiers, isDangerousPattern, sanitizeRegex } from './tools/ToolSearchRegex.mjs';
 export { handleServerToolResult, handleToolCallChunks, handleToolCalls, toolResultTypes } from './tools/handlers.mjs';
 export { createSearchTool } from './tools/search/tool.mjs';

package/dist/esm/tools/ProgrammaticToolCalling.mjs

@@ -79,34 +79,111 @@ 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
+ */
+function normalizeToPythonIdentifier(name) {
+    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
  */
-function extractUsedToolNames(code, availableToolNames) {
+function extractUsedToolNames(code, toolNameMap) {
     const usedTools = new Set();
-    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);
         }
     }
     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
  */
-function filterToolsByUsage(toolDefs, code) {
-    const availableToolNames = new Set(toolDefs.map((tool) => tool.name));
-    const usedToolNames = extractUsedToolNames(code, availableToolNames);
+function filterToolsByUsage(toolDefs, code, debug = false) {
+    const toolNameMap = new Map();
+    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));
@@ -252,6 +329,7 @@ function createProgrammaticToolCallingTool(initParams = {}) {
     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 = `
 Run tools by writing Python code. Tools are available as async functions - just call them with await.
@@ -291,7 +369,12 @@ 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, apiKey, {
                 code,
                 tools: effectiveTools,
@@ -308,8 +391,10 @@ When to use this instead of calling tools directly:
                         'This may indicate an infinite loop, excessive tool calls, ' +
                         'or a logic error in your code.');
                 }
-                // 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 ?? [], toolMap);
                 response = await makeRequest(EXEC_ENDPOINT, apiKey, {
                     continuation_token: response.continuation_token,
@@ -341,5 +426,5 @@ When to use this instead of calling tools directly:
     });
 }
 
-export { createProgrammaticToolCallingTool, executeTools, extractUsedToolNames, filterToolsByUsage, formatCompletedResponse, makeRequest };
+export { createProgrammaticToolCallingTool, executeTools, extractUsedToolNames, filterToolsByUsage, formatCompletedResponse, makeRequest, normalizeToPythonIdentifier };
 //# sourceMappingURL=ProgrammaticToolCalling.mjs.map

package/dist/esm/tools/ProgrammaticToolCalling.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"ProgrammaticToolCalling.mjs","sources":["../../../src/tools/ProgrammaticToolCalling.ts"],"sourcesContent":["// src/tools/ProgrammaticToolCalling.ts\nimport { z } from 'zod';\nimport { config } from 'dotenv';\nimport fetch, { RequestInit } from 'node-fetch';\nimport { HttpsProxyAgent } from 'https-proxy-agent';\nimport { getEnvironmentVariable } from '@langchain/core/utils/env';\nimport { tool, DynamicStructuredTool } from '@langchain/core/tools';\nimport type { ToolCall } from '@langchain/core/messages/tool';\nimport type * as t from '@/types';\nimport { imageExtRegex, getCodeBaseURL } from './CodeExecutor';\nimport { EnvVar, Constants } from '@/common';\n\nconfig();\n\n// ============================================================================\n// Constants\n// ============================================================================\n\nconst imageMessage = 'Image is already displayed to the user';\nconst otherMessage = 'File is already downloaded by the user';\nconst accessMessage =\n  'Note: Files are READ-ONLY. Save changes to NEW filenames. To access these files in future executions, provide the `session_id` as a parameter (not in your code).';\nconst emptyOutputMessage =\n  'stdout: Empty. Ensure you\\'re writing output explicitly.\\n';\n\n/** Default max round-trips to prevent infinite loops */\nconst DEFAULT_MAX_ROUND_TRIPS = 20;\n\n/** Default execution timeout in milliseconds */\nconst DEFAULT_TIMEOUT = 60000;\n\n// ============================================================================\n// Schema\n// ============================================================================\n\nconst ProgrammaticToolCallingSchema = z.object({\n  code: z\n    .string()\n    .min(1)\n    .describe(\n      `Python code that calls tools programmatically. Tools are automatically available as async Python functions - DO NOT define them yourself.\n\nThe Code API generates async function stubs from the tool definitions. Just call them directly:\n\nExample (Simple call):\n  result = await get_weather(city=\"San Francisco\")\n  print(result)\n\nExample (Parallel - Fastest):\n  results = await asyncio.gather(\n      get_weather(city=\"SF\"),\n      get_weather(city=\"NYC\"),\n      get_weather(city=\"London\")\n  )\n  for city, weather in zip([\"SF\", \"NYC\", \"London\"], results):\n      print(f\"{city}: {weather['temperature']}°F\")\n\nExample (Loop with processing):\n  team = await get_team_members()\n  for member in team:\n      expenses = await get_expenses(user_id=member['id'])\n      total = sum(e['amount'] for e in expenses)\n      print(f\"{member['name']}: \\${total:.2f}\")\n\nExample (Conditional logic):\n  data = await fetch_data(source=\"primary\")\n  if not data:\n      data = await fetch_data(source=\"backup\")\n  print(f\"Got {len(data)} records\")\n\nRequirements:\n- Tools are pre-defined as async functions - DO NOT write function definitions\n- Use await for all tool calls\n- Use asyncio.gather() for parallel execution of independent calls\n- Only print() output flows back to the context window\n- Tool results from programmatic calls do NOT consume context tokens`\n    ),\n  session_id: z\n    .string()\n    .optional()\n    .describe(\n      'Session ID for file access (same as regular code execution). Files load into /mnt/data/ and are READ-ONLY.'\n    ),\n  timeout: z\n    .number()\n    .int()\n    .min(1000)\n    .max(300000)\n    .optional()\n    .default(DEFAULT_TIMEOUT)\n    .describe(\n      'Maximum execution time in milliseconds. Default: 60 seconds. Max: 5 minutes.'\n    ),\n});\n\n// ============================================================================\n// Helper Functions\n// ============================================================================\n\n/**\n * Extracts tool names that are actually called in the Python code.\n * Matches patterns like `await tool_name(`, `tool_name(`, and asyncio.gather calls.\n * @param code - The Python code to analyze\n * @param availableToolNames - Set of available tool names to match against\n * @returns Set of tool names found in the code\n */\nexport function extractUsedToolNames(\n  code: string,\n  availableToolNames: Set<string>\n): Set<string> {\n  const usedTools = new Set<string>();\n\n  for (const toolName of availableToolNames) {\n    const escapedName = toolName.replace(/[.*+?^${}()|[\\]\\\\]/g, '\\\\$&');\n    const pattern = new RegExp(`\\\\b${escapedName}\\\\s*\\\\(`, 'g');\n\n    if (pattern.test(code)) {\n      usedTools.add(toolName);\n    }\n  }\n\n  return usedTools;\n}\n\n/**\n * Filters tool definitions to only include tools actually used in the code.\n * @param toolDefs - All available tool definitions\n * @param code - The Python code to analyze\n * @returns Filtered array of tool definitions\n */\nexport function filterToolsByUsage(\n  toolDefs: t.LCTool[],\n  code: string\n): t.LCTool[] {\n  const availableToolNames = new Set(toolDefs.map((tool) => tool.name));\n  const usedToolNames = extractUsedToolNames(code, availableToolNames);\n\n  if (usedToolNames.size === 0) {\n    return toolDefs;\n  }\n\n  return toolDefs.filter((tool) => usedToolNames.has(tool.name));\n}\n\n/**\n * Makes an HTTP request to the Code API.\n * @param endpoint - The API endpoint URL\n * @param apiKey - The API key for authentication\n * @param body - The request body\n * @param proxy - Optional HTTP proxy URL\n * @returns The parsed API response\n */\nexport async function makeRequest(\n  endpoint: string,\n  apiKey: string,\n  body: Record<string, unknown>,\n  proxy?: string\n): Promise<t.ProgrammaticExecutionResponse> {\n  const fetchOptions: RequestInit = {\n    method: 'POST',\n    headers: {\n      'Content-Type': 'application/json',\n      'User-Agent': 'LibreChat/1.0',\n      'X-API-Key': apiKey,\n    },\n    body: JSON.stringify(body),\n  };\n\n  if (proxy != null && proxy !== '') {\n    fetchOptions.agent = new HttpsProxyAgent(proxy);\n  }\n\n  const response = await fetch(endpoint, fetchOptions);\n\n  if (!response.ok) {\n    const errorText = await response.text();\n    throw new Error(\n      `HTTP error! status: ${response.status}, body: ${errorText}`\n    );\n  }\n\n  return (await response.json()) as t.ProgrammaticExecutionResponse;\n}\n\n/**\n * Executes tools in parallel when requested by the API.\n * Uses Promise.all for parallel execution, catching individual errors.\n * @param toolCalls - Array of tool calls from the API\n * @param toolMap - Map of tool names to executable tools\n * @returns Array of tool results\n */\nexport async function executeTools(\n  toolCalls: t.PTCToolCall[],\n  toolMap: t.ToolMap\n): Promise<t.PTCToolResult[]> {\n  const executions = toolCalls.map(async (call): Promise<t.PTCToolResult> => {\n    const tool = toolMap.get(call.name);\n\n    if (!tool) {\n      return {\n        call_id: call.id,\n        result: null,\n        is_error: true,\n        error_message: `Tool '${call.name}' not found. Available tools: ${Array.from(toolMap.keys()).join(', ')}`,\n      };\n    }\n\n    try {\n      const result = await tool.invoke(call.input, {\n        metadata: { [Constants.PROGRAMMATIC_TOOL_CALLING]: true },\n      });\n      return {\n        call_id: call.id,\n        result,\n        is_error: false,\n      };\n    } catch (error) {\n      return {\n        call_id: call.id,\n        result: null,\n        is_error: true,\n        error_message: (error as Error).message || 'Tool execution failed',\n      };\n    }\n  });\n\n  return await Promise.all(executions);\n}\n\n/**\n * Formats the completed response for the agent.\n * @param response - The completed API response\n * @returns Tuple of [formatted string, artifact]\n */\nexport function formatCompletedResponse(\n  response: t.ProgrammaticExecutionResponse\n): [string, t.ProgrammaticExecutionArtifact] {\n  let formatted = '';\n\n  if (response.stdout != null && response.stdout !== '') {\n    formatted += `stdout:\\n${response.stdout}\\n`;\n  } else {\n    formatted += emptyOutputMessage;\n  }\n\n  if (response.stderr != null && response.stderr !== '') {\n    formatted += `stderr:\\n${response.stderr}\\n`;\n  }\n\n  if (response.files && response.files.length > 0) {\n    formatted += 'Generated files:\\n';\n\n    const fileCount = response.files.length;\n    for (let i = 0; i < fileCount; i++) {\n      const file = response.files[i];\n      const isImage = imageExtRegex.test(file.name);\n      formatted += `- /mnt/data/${file.name} | ${isImage ? imageMessage : otherMessage}`;\n\n      if (i < fileCount - 1) {\n        formatted += fileCount <= 3 ? ', ' : ',\\n';\n      }\n    }\n\n    formatted += `\\nsession_id: ${response.session_id}\\n\\n${accessMessage}`;\n  }\n\n  return [\n    formatted.trim(),\n    {\n      session_id: response.session_id,\n      files: response.files,\n    },\n  ];\n}\n\n// ============================================================================\n// Tool Factory\n// ============================================================================\n\n/**\n * Creates a Programmatic Tool Calling tool for complex multi-tool workflows.\n *\n * This tool enables AI agents to write Python code that orchestrates multiple\n * tool calls programmatically, reducing LLM round-trips and token usage.\n *\n * The tool map must be provided at runtime via config.configurable.toolMap.\n *\n * @param params - Configuration parameters (apiKey, baseUrl, maxRoundTrips, proxy)\n * @returns A LangChain DynamicStructuredTool for programmatic tool calling\n *\n * @example\n * const ptcTool = createProgrammaticToolCallingTool({\n *   apiKey: process.env.CODE_API_KEY,\n *   maxRoundTrips: 20\n * });\n *\n * const [output, artifact] = await ptcTool.invoke(\n *   { code, tools },\n *   { configurable: { toolMap } }\n * );\n */\nexport function createProgrammaticToolCallingTool(\n  initParams: t.ProgrammaticToolCallingParams = {}\n): DynamicStructuredTool<typeof ProgrammaticToolCallingSchema> {\n  const apiKey =\n    (initParams[EnvVar.CODE_API_KEY] as string | undefined) ??\n    initParams.apiKey ??\n    getEnvironmentVariable(EnvVar.CODE_API_KEY) ??\n    '';\n\n  if (!apiKey) {\n    throw new Error(\n      'No API key provided for programmatic tool calling. ' +\n        'Set CODE_API_KEY environment variable or pass apiKey in initParams.'\n    );\n  }\n\n  const baseUrl = initParams.baseUrl ?? getCodeBaseURL();\n  const maxRoundTrips = initParams.maxRoundTrips ?? DEFAULT_MAX_ROUND_TRIPS;\n  const proxy = initParams.proxy ?? process.env.PROXY;\n  const EXEC_ENDPOINT = `${baseUrl}/exec/programmatic`;\n\n  const description = `\nRun tools by writing Python code. Tools are available as async functions - just call them with await.\n\nThis is different from execute_code: here you can call your tools (like get_weather, get_expenses, etc.) directly in Python code.\n\nUsage:\n- Tools are pre-defined as async functions - call them with await\n- Use asyncio.gather() to run multiple tools in parallel\n- Only print() output is returned - tool results stay in Python\n\nExamples:\n- Simple: result = await get_weather(city=\"NYC\")\n- Loop: for user in users: data = await get_expenses(user_id=user['id'])\n- Parallel: sf, ny = await asyncio.gather(get_weather(city=\"SF\"), get_weather(city=\"NY\"))\n\nWhen to use this instead of calling tools directly:\n- You need to call tools in a loop (process many items)\n- You want parallel execution (asyncio.gather)\n- You need conditionals based on tool results\n- You want to aggregate/filter data before returning\n`.trim();\n\n  return tool<typeof ProgrammaticToolCallingSchema>(\n    async (params, config) => {\n      const { code, session_id, timeout = DEFAULT_TIMEOUT } = params;\n\n      // Extra params injected by ToolNode (follows web_search pattern)\n      const { toolMap, toolDefs } = (config.toolCall ?? {}) as ToolCall &\n        Partial<t.ProgrammaticCache>;\n\n      if (toolMap == null || toolMap.size === 0) {\n        throw new Error(\n          'No toolMap provided. ' +\n            'ToolNode should inject this from AgentContext when invoked through the graph.'\n        );\n      }\n\n      if (toolDefs == null || toolDefs.length === 0) {\n        throw new Error(\n          'No tool definitions provided. ' +\n            'Either pass tools in the input or ensure ToolNode injects toolDefs.'\n        );\n      }\n\n      let roundTrip = 0;\n\n      try {\n        // ====================================================================\n        // Phase 1: Filter tools and make initial request\n        // ====================================================================\n\n        const effectiveTools = filterToolsByUsage(toolDefs, code);\n\n        let response = await makeRequest(\n          EXEC_ENDPOINT,\n          apiKey,\n          {\n            code,\n            tools: effectiveTools,\n            session_id,\n            timeout,\n          },\n          proxy\n        );\n\n        // ====================================================================\n        // Phase 2: Handle response loop\n        // ====================================================================\n\n        while (response.status === 'tool_call_required') {\n          roundTrip++;\n\n          if (roundTrip > maxRoundTrips) {\n            throw new Error(\n              `Exceeded maximum round trips (${maxRoundTrips}). ` +\n                'This may indicate an infinite loop, excessive tool calls, ' +\n                'or a logic error in your code.'\n            );\n          }\n\n          // eslint-disable-next-line no-console\n          console.log(\n            `[PTC] Round trip ${roundTrip}: ${response.tool_calls?.length ?? 0} tool(s) to execute`\n          );\n\n          const toolResults = await executeTools(\n            response.tool_calls ?? [],\n            toolMap\n          );\n\n          response = await makeRequest(\n            EXEC_ENDPOINT,\n            apiKey,\n            {\n              continuation_token: response.continuation_token,\n              tool_results: toolResults,\n            },\n            proxy\n          );\n        }\n\n        // ====================================================================\n        // Phase 3: Handle final state\n        // ====================================================================\n\n        if (response.status === 'completed') {\n          return formatCompletedResponse(response);\n        }\n\n        if (response.status === 'error') {\n          throw new Error(\n            `Execution error: ${response.error}` +\n              (response.stderr != null && response.stderr !== ''\n                ? `\\n\\nStderr:\\n${response.stderr}`\n                : '')\n          );\n        }\n\n        throw new Error(`Unexpected response status: ${response.status}`);\n      } catch (error) {\n        throw new Error(\n          `Programmatic execution failed: ${(error as Error).message}`\n        );\n      }\n    },\n    {\n      name: Constants.PROGRAMMATIC_TOOL_CALLING,\n      description,\n      schema: ProgrammaticToolCallingSchema,\n      responseFormat: Constants.CONTENT_AND_ARTIFACT,\n    }\n  );\n}\n"],"names":[],"mappings":"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"}
+{"version":3,"file":"ProgrammaticToolCalling.mjs","sources":["../../../src/tools/ProgrammaticToolCalling.ts"],"sourcesContent":["// src/tools/ProgrammaticToolCalling.ts\nimport { z } from 'zod';\nimport { config } from 'dotenv';\nimport fetch, { RequestInit } from 'node-fetch';\nimport { HttpsProxyAgent } from 'https-proxy-agent';\nimport { getEnvironmentVariable } from '@langchain/core/utils/env';\nimport { tool, DynamicStructuredTool } from '@langchain/core/tools';\nimport type { ToolCall } from '@langchain/core/messages/tool';\nimport type * as t from '@/types';\nimport { imageExtRegex, getCodeBaseURL } from './CodeExecutor';\nimport { EnvVar, Constants } from '@/common';\n\nconfig();\n\n// ============================================================================\n// Constants\n// ============================================================================\n\nconst imageMessage = 'Image is already displayed to the user';\nconst otherMessage = 'File is already downloaded by the user';\nconst accessMessage =\n  'Note: Files are READ-ONLY. Save changes to NEW filenames. To access these files in future executions, provide the `session_id` as a parameter (not in your code).';\nconst emptyOutputMessage =\n  'stdout: Empty. Ensure you\\'re writing output explicitly.\\n';\n\n/** Default max round-trips to prevent infinite loops */\nconst DEFAULT_MAX_ROUND_TRIPS = 20;\n\n/** Default execution timeout in milliseconds */\nconst DEFAULT_TIMEOUT = 60000;\n\n// ============================================================================\n// Schema\n// ============================================================================\n\nconst ProgrammaticToolCallingSchema = z.object({\n  code: z\n    .string()\n    .min(1)\n    .describe(\n      `Python code that calls tools programmatically. Tools are automatically available as async Python functions - DO NOT define them yourself.\n\nThe Code API generates async function stubs from the tool definitions. Just call them directly:\n\nExample (Simple call):\n  result = await get_weather(city=\"San Francisco\")\n  print(result)\n\nExample (Parallel - Fastest):\n  results = await asyncio.gather(\n      get_weather(city=\"SF\"),\n      get_weather(city=\"NYC\"),\n      get_weather(city=\"London\")\n  )\n  for city, weather in zip([\"SF\", \"NYC\", \"London\"], results):\n      print(f\"{city}: {weather['temperature']}°F\")\n\nExample (Loop with processing):\n  team = await get_team_members()\n  for member in team:\n      expenses = await get_expenses(user_id=member['id'])\n      total = sum(e['amount'] for e in expenses)\n      print(f\"{member['name']}: \\${total:.2f}\")\n\nExample (Conditional logic):\n  data = await fetch_data(source=\"primary\")\n  if not data:\n      data = await fetch_data(source=\"backup\")\n  print(f\"Got {len(data)} records\")\n\nRequirements:\n- Tools are pre-defined as async functions - DO NOT write function definitions\n- Use await for all tool calls\n- Use asyncio.gather() for parallel execution of independent calls\n- Only print() output flows back to the context window\n- Tool results from programmatic calls do NOT consume context tokens`\n    ),\n  session_id: z\n    .string()\n    .optional()\n    .describe(\n      'Session ID for file access (same as regular code execution). Files load into /mnt/data/ and are READ-ONLY.'\n    ),\n  timeout: z\n    .number()\n    .int()\n    .min(1000)\n    .max(300000)\n    .optional()\n    .default(DEFAULT_TIMEOUT)\n    .describe(\n      'Maximum execution time in milliseconds. Default: 60 seconds. Max: 5 minutes.'\n    ),\n});\n\n// ============================================================================\n// Helper Functions\n// ============================================================================\n\n/** Python reserved keywords that get `_tool` suffix in Code API */\nconst PYTHON_KEYWORDS = new Set([\n  'False',\n  'None',\n  'True',\n  'and',\n  'as',\n  'assert',\n  'async',\n  'await',\n  'break',\n  'class',\n  'continue',\n  'def',\n  'del',\n  'elif',\n  'else',\n  'except',\n  'finally',\n  'for',\n  'from',\n  'global',\n  'if',\n  'import',\n  'in',\n  'is',\n  'lambda',\n  'nonlocal',\n  'not',\n  'or',\n  'pass',\n  'raise',\n  'return',\n  'try',\n  'while',\n  'with',\n  'yield',\n]);\n\n/**\n * Normalizes a tool name to Python identifier format.\n * Must match the Code API's `normalizePythonFunctionName` exactly:\n * 1. Replace hyphens and spaces with underscores\n * 2. Remove any other invalid characters\n * 3. Prefix with underscore if starts with number\n * 4. Append `_tool` if it's a Python keyword\n * @param name - The tool name to normalize\n * @returns Normalized Python-safe identifier\n */\nexport function normalizeToPythonIdentifier(name: string): string {\n  let normalized = name.replace(/[-\\s]/g, '_');\n\n  normalized = normalized.replace(/[^a-zA-Z0-9_]/g, '');\n\n  if (/^[0-9]/.test(normalized)) {\n    normalized = '_' + normalized;\n  }\n\n  if (PYTHON_KEYWORDS.has(normalized)) {\n    normalized = normalized + '_tool';\n  }\n\n  return normalized;\n}\n\n/**\n * Extracts tool names that are actually called in the Python code.\n * Handles hyphen/underscore conversion since Python identifiers use underscores.\n * @param code - The Python code to analyze\n * @param toolNameMap - Map from normalized Python name to original tool name\n * @returns Set of original tool names found in the code\n */\nexport function extractUsedToolNames(\n  code: string,\n  toolNameMap: Map<string, string>\n): Set<string> {\n  const usedTools = new Set<string>();\n\n  for (const [pythonName, originalName] of toolNameMap) {\n    const escapedName = pythonName.replace(/[.*+?^${}()|[\\]\\\\]/g, '\\\\$&');\n    const pattern = new RegExp(`\\\\b${escapedName}\\\\s*\\\\(`, 'g');\n\n    if (pattern.test(code)) {\n      usedTools.add(originalName);\n    }\n  }\n\n  return usedTools;\n}\n\n/**\n * Filters tool definitions to only include tools actually used in the code.\n * Handles the hyphen-to-underscore conversion for Python compatibility.\n * @param toolDefs - All available tool definitions\n * @param code - The Python code to analyze\n * @param debug - Enable debug logging\n * @returns Filtered array of tool definitions\n */\nexport function filterToolsByUsage(\n  toolDefs: t.LCTool[],\n  code: string,\n  debug = false\n): t.LCTool[] {\n  const toolNameMap = new Map<string, string>();\n  for (const tool of toolDefs) {\n    const pythonName = normalizeToPythonIdentifier(tool.name);\n    toolNameMap.set(pythonName, tool.name);\n  }\n\n  const usedToolNames = extractUsedToolNames(code, toolNameMap);\n\n  if (debug) {\n    // eslint-disable-next-line no-console\n    console.log(\n      `[PTC Debug] Tool filtering: found ${usedToolNames.size}/${toolDefs.length} tools in code`\n    );\n    if (usedToolNames.size > 0) {\n      // eslint-disable-next-line no-console\n      console.log(\n        `[PTC Debug] Matched tools: ${Array.from(usedToolNames).join(', ')}`\n      );\n    }\n  }\n\n  if (usedToolNames.size === 0) {\n    if (debug) {\n      // eslint-disable-next-line no-console\n      console.log(\n        '[PTC Debug] No tools detected in code - sending all tools as fallback'\n      );\n    }\n    return toolDefs;\n  }\n\n  return toolDefs.filter((tool) => usedToolNames.has(tool.name));\n}\n\n/**\n * Makes an HTTP request to the Code API.\n * @param endpoint - The API endpoint URL\n * @param apiKey - The API key for authentication\n * @param body - The request body\n * @param proxy - Optional HTTP proxy URL\n * @returns The parsed API response\n */\nexport async function makeRequest(\n  endpoint: string,\n  apiKey: string,\n  body: Record<string, unknown>,\n  proxy?: string\n): Promise<t.ProgrammaticExecutionResponse> {\n  const fetchOptions: RequestInit = {\n    method: 'POST',\n    headers: {\n      'Content-Type': 'application/json',\n      'User-Agent': 'LibreChat/1.0',\n      'X-API-Key': apiKey,\n    },\n    body: JSON.stringify(body),\n  };\n\n  if (proxy != null && proxy !== '') {\n    fetchOptions.agent = new HttpsProxyAgent(proxy);\n  }\n\n  const response = await fetch(endpoint, fetchOptions);\n\n  if (!response.ok) {\n    const errorText = await response.text();\n    throw new Error(\n      `HTTP error! status: ${response.status}, body: ${errorText}`\n    );\n  }\n\n  return (await response.json()) as t.ProgrammaticExecutionResponse;\n}\n\n/**\n * Executes tools in parallel when requested by the API.\n * Uses Promise.all for parallel execution, catching individual errors.\n * @param toolCalls - Array of tool calls from the API\n * @param toolMap - Map of tool names to executable tools\n * @returns Array of tool results\n */\nexport async function executeTools(\n  toolCalls: t.PTCToolCall[],\n  toolMap: t.ToolMap\n): Promise<t.PTCToolResult[]> {\n  const executions = toolCalls.map(async (call): Promise<t.PTCToolResult> => {\n    const tool = toolMap.get(call.name);\n\n    if (!tool) {\n      return {\n        call_id: call.id,\n        result: null,\n        is_error: true,\n        error_message: `Tool '${call.name}' not found. Available tools: ${Array.from(toolMap.keys()).join(', ')}`,\n      };\n    }\n\n    try {\n      const result = await tool.invoke(call.input, {\n        metadata: { [Constants.PROGRAMMATIC_TOOL_CALLING]: true },\n      });\n      return {\n        call_id: call.id,\n        result,\n        is_error: false,\n      };\n    } catch (error) {\n      return {\n        call_id: call.id,\n        result: null,\n        is_error: true,\n        error_message: (error as Error).message || 'Tool execution failed',\n      };\n    }\n  });\n\n  return await Promise.all(executions);\n}\n\n/**\n * Formats the completed response for the agent.\n * @param response - The completed API response\n * @returns Tuple of [formatted string, artifact]\n */\nexport function formatCompletedResponse(\n  response: t.ProgrammaticExecutionResponse\n): [string, t.ProgrammaticExecutionArtifact] {\n  let formatted = '';\n\n  if (response.stdout != null && response.stdout !== '') {\n    formatted += `stdout:\\n${response.stdout}\\n`;\n  } else {\n    formatted += emptyOutputMessage;\n  }\n\n  if (response.stderr != null && response.stderr !== '') {\n    formatted += `stderr:\\n${response.stderr}\\n`;\n  }\n\n  if (response.files && response.files.length > 0) {\n    formatted += 'Generated files:\\n';\n\n    const fileCount = response.files.length;\n    for (let i = 0; i < fileCount; i++) {\n      const file = response.files[i];\n      const isImage = imageExtRegex.test(file.name);\n      formatted += `- /mnt/data/${file.name} | ${isImage ? imageMessage : otherMessage}`;\n\n      if (i < fileCount - 1) {\n        formatted += fileCount <= 3 ? ', ' : ',\\n';\n      }\n    }\n\n    formatted += `\\nsession_id: ${response.session_id}\\n\\n${accessMessage}`;\n  }\n\n  return [\n    formatted.trim(),\n    {\n      session_id: response.session_id,\n      files: response.files,\n    },\n  ];\n}\n\n// ============================================================================\n// Tool Factory\n// ============================================================================\n\n/**\n * Creates a Programmatic Tool Calling tool for complex multi-tool workflows.\n *\n * This tool enables AI agents to write Python code that orchestrates multiple\n * tool calls programmatically, reducing LLM round-trips and token usage.\n *\n * The tool map must be provided at runtime via config.configurable.toolMap.\n *\n * @param params - Configuration parameters (apiKey, baseUrl, maxRoundTrips, proxy)\n * @returns A LangChain DynamicStructuredTool for programmatic tool calling\n *\n * @example\n * const ptcTool = createProgrammaticToolCallingTool({\n *   apiKey: process.env.CODE_API_KEY,\n *   maxRoundTrips: 20\n * });\n *\n * const [output, artifact] = await ptcTool.invoke(\n *   { code, tools },\n *   { configurable: { toolMap } }\n * );\n */\nexport function createProgrammaticToolCallingTool(\n  initParams: t.ProgrammaticToolCallingParams = {}\n): DynamicStructuredTool<typeof ProgrammaticToolCallingSchema> {\n  const apiKey =\n    (initParams[EnvVar.CODE_API_KEY] as string | undefined) ??\n    initParams.apiKey ??\n    getEnvironmentVariable(EnvVar.CODE_API_KEY) ??\n    '';\n\n  if (!apiKey) {\n    throw new Error(\n      'No API key provided for programmatic tool calling. ' +\n        'Set CODE_API_KEY environment variable or pass apiKey in initParams.'\n    );\n  }\n\n  const baseUrl = initParams.baseUrl ?? getCodeBaseURL();\n  const maxRoundTrips = initParams.maxRoundTrips ?? DEFAULT_MAX_ROUND_TRIPS;\n  const proxy = initParams.proxy ?? process.env.PROXY;\n  const debug = initParams.debug ?? process.env.PTC_DEBUG === 'true';\n  const EXEC_ENDPOINT = `${baseUrl}/exec/programmatic`;\n\n  const description = `\nRun tools by writing Python code. Tools are available as async functions - just call them with await.\n\nThis is different from execute_code: here you can call your tools (like get_weather, get_expenses, etc.) directly in Python code.\n\nUsage:\n- Tools are pre-defined as async functions - call them with await\n- Use asyncio.gather() to run multiple tools in parallel\n- Only print() output is returned - tool results stay in Python\n\nExamples:\n- Simple: result = await get_weather(city=\"NYC\")\n- Loop: for user in users: data = await get_expenses(user_id=user['id'])\n- Parallel: sf, ny = await asyncio.gather(get_weather(city=\"SF\"), get_weather(city=\"NY\"))\n\nWhen to use this instead of calling tools directly:\n- You need to call tools in a loop (process many items)\n- You want parallel execution (asyncio.gather)\n- You need conditionals based on tool results\n- You want to aggregate/filter data before returning\n`.trim();\n\n  return tool<typeof ProgrammaticToolCallingSchema>(\n    async (params, config) => {\n      const { code, session_id, timeout = DEFAULT_TIMEOUT } = params;\n\n      // Extra params injected by ToolNode (follows web_search pattern)\n      const { toolMap, toolDefs } = (config.toolCall ?? {}) as ToolCall &\n        Partial<t.ProgrammaticCache>;\n\n      if (toolMap == null || toolMap.size === 0) {\n        throw new Error(\n          'No toolMap provided. ' +\n            'ToolNode should inject this from AgentContext when invoked through the graph.'\n        );\n      }\n\n      if (toolDefs == null || toolDefs.length === 0) {\n        throw new Error(\n          'No tool definitions provided. ' +\n            'Either pass tools in the input or ensure ToolNode injects toolDefs.'\n        );\n      }\n\n      let roundTrip = 0;\n\n      try {\n        // ====================================================================\n        // Phase 1: Filter tools and make initial request\n        // ====================================================================\n\n        const effectiveTools = filterToolsByUsage(toolDefs, code, debug);\n\n        if (debug) {\n          // eslint-disable-next-line no-console\n          console.log(\n            `[PTC Debug] Sending ${effectiveTools.length} tools to API ` +\n              `(filtered from ${toolDefs.length})`\n          );\n        }\n\n        let response = await makeRequest(\n          EXEC_ENDPOINT,\n          apiKey,\n          {\n            code,\n            tools: effectiveTools,\n            session_id,\n            timeout,\n          },\n          proxy\n        );\n\n        // ====================================================================\n        // Phase 2: Handle response loop\n        // ====================================================================\n\n        while (response.status === 'tool_call_required') {\n          roundTrip++;\n\n          if (roundTrip > maxRoundTrips) {\n            throw new Error(\n              `Exceeded maximum round trips (${maxRoundTrips}). ` +\n                'This may indicate an infinite loop, excessive tool calls, ' +\n                'or a logic error in your code.'\n            );\n          }\n\n          if (debug) {\n            // eslint-disable-next-line no-console\n            console.log(\n              `[PTC Debug] Round trip ${roundTrip}: ${response.tool_calls?.length ?? 0} tool(s) to execute`\n            );\n          }\n\n          const toolResults = await executeTools(\n            response.tool_calls ?? [],\n            toolMap\n          );\n\n          response = await makeRequest(\n            EXEC_ENDPOINT,\n            apiKey,\n            {\n              continuation_token: response.continuation_token,\n              tool_results: toolResults,\n            },\n            proxy\n          );\n        }\n\n        // ====================================================================\n        // Phase 3: Handle final state\n        // ====================================================================\n\n        if (response.status === 'completed') {\n          return formatCompletedResponse(response);\n        }\n\n        if (response.status === 'error') {\n          throw new Error(\n            `Execution error: ${response.error}` +\n              (response.stderr != null && response.stderr !== ''\n                ? `\\n\\nStderr:\\n${response.stderr}`\n                : '')\n          );\n        }\n\n        throw new Error(`Unexpected response status: ${response.status}`);\n      } catch (error) {\n        throw new Error(\n          `Programmatic execution failed: ${(error as Error).message}`\n        );\n      }\n    },\n    {\n      name: Constants.PROGRAMMATIC_TOOL_CALLING,\n      description,\n      schema: ProgrammaticToolCallingSchema,\n      responseFormat: Constants.CONTENT_AND_ARTIFACT,\n    }\n  );\n}\n"],"names":[],"mappings":";;;;;;;;;AAAA;AAYA,MAAM,EAAE;AAER;AACA;AACA;AAEA,MAAM,YAAY,GAAG,wCAAwC;AAC7D,MAAM,YAAY,GAAG,wCAAwC;AAC7D,MAAM,aAAa,GACjB,mKAAmK;AACrK,MAAM,kBAAkB,GACtB,4DAA4D;AAE9D;AACA,MAAM,uBAAuB,GAAG,EAAE;AAElC;AACA,MAAM,eAAe,GAAG,KAAK;AAE7B;AACA;AACA;AAEA,MAAM,6BAA6B,GAAG,CAAC,CAAC,MAAM,CAAC;AAC7C,IAAA,IAAI,EAAE;AACH,SAAA,MAAM;SACN,GAAG,CAAC,CAAC;AACL,SAAA,QAAQ,CACP,CAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qEAmC+D,CAChE;AACH,IAAA,UAAU,EAAE;AACT,SAAA,MAAM;AACN,SAAA,QAAQ;SACR,QAAQ,CACP,4GAA4G,CAC7G;AACH,IAAA,OAAO,EAAE;AACN,SAAA,MAAM;AACN,SAAA,GAAG;SACH,GAAG,CAAC,IAAI;SACR,GAAG,CAAC,MAAM;AACV,SAAA,QAAQ;SACR,OAAO,CAAC,eAAe;SACvB,QAAQ,CACP,8EAA8E,CAC/E;AACJ,CAAA,CAAC;AAEF;AACA;AACA;AAEA;AACA,MAAM,eAAe,GAAG,IAAI,GAAG,CAAC;IAC9B,OAAO;IACP,MAAM;IACN,MAAM;IACN,KAAK;IACL,IAAI;IACJ,QAAQ;IACR,OAAO;IACP,OAAO;IACP,OAAO;IACP,OAAO;IACP,UAAU;IACV,KAAK;IACL,KAAK;IACL,MAAM;IACN,MAAM;IACN,QAAQ;IACR,SAAS;IACT,KAAK;IACL,MAAM;IACN,QAAQ;IACR,IAAI;IACJ,QAAQ;IACR,IAAI;IACJ,IAAI;IACJ,QAAQ;IACR,UAAU;IACV,KAAK;IACL,IAAI;IACJ,MAAM;IACN,OAAO;IACP,QAAQ;IACR,KAAK;IACL,OAAO;IACP,MAAM;IACN,OAAO;AACR,CAAA,CAAC;AAEF;;;;;;;;;AASG;AACG,SAAU,2BAA2B,CAAC,IAAY,EAAA;IACtD,IAAI,UAAU,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,GAAG,CAAC;IAE5C,UAAU,GAAG,UAAU,CAAC,OAAO,CAAC,gBAAgB,EAAE,EAAE,CAAC;AAErD,IAAA,IAAI,QAAQ,CAAC,IAAI,CAAC,UAAU,CAAC,EAAE;AAC7B,QAAA,UAAU,GAAG,GAAG,GAAG,UAAU;;AAG/B,IAAA,IAAI,eAAe,CAAC,GAAG,CAAC,UAAU,CAAC,EAAE;AACnC,QAAA,UAAU,GAAG,UAAU,GAAG,OAAO;;AAGnC,IAAA,OAAO,UAAU;AACnB;AAEA;;;;;;AAMG;AACa,SAAA,oBAAoB,CAClC,IAAY,EACZ,WAAgC,EAAA;AAEhC,IAAA,MAAM,SAAS,GAAG,IAAI,GAAG,EAAU;IAEnC,KAAK,MAAM,CAAC,UAAU,EAAE,YAAY,CAAC,IAAI,WAAW,EAAE;QACpD,MAAM,WAAW,GAAG,UAAU,CAAC,OAAO,CAAC,qBAAqB,EAAE,MAAM,CAAC;QACrE,MAAM,OAAO,GAAG,IAAI,MAAM,CAAC,CAAM,GAAA,EAAA,WAAW,CAAS,OAAA,CAAA,EAAE,GAAG,CAAC;AAE3D,QAAA,IAAI,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE;AACtB,YAAA,SAAS,CAAC,GAAG,CAAC,YAAY,CAAC;;;AAI/B,IAAA,OAAO,SAAS;AAClB;AAEA;;;;;;;AAOG;AACG,SAAU,kBAAkB,CAChC,QAAoB,EACpB,IAAY,EACZ,KAAK,GAAG,KAAK,EAAA;AAEb,IAAA,MAAM,WAAW,GAAG,IAAI,GAAG,EAAkB;AAC7C,IAAA,KAAK,MAAM,IAAI,IAAI,QAAQ,EAAE;QAC3B,MAAM,UAAU,GAAG,2BAA2B,CAAC,IAAI,CAAC,IAAI,CAAC;QACzD,WAAW,CAAC,GAAG,CAAC,UAAU,EAAE,IAAI,CAAC,IAAI,CAAC;;IAGxC,MAAM,aAAa,GAAG,oBAAoB,CAAC,IAAI,EAAE,WAAW,CAAC;IAE7D,IAAI,KAAK,EAAE;;AAET,QAAA,OAAO,CAAC,GAAG,CACT,CAAA,kCAAA,EAAqC,aAAa,CAAC,IAAI,CAAA,CAAA,EAAI,QAAQ,CAAC,MAAM,CAAA,cAAA,CAAgB,CAC3F;AACD,QAAA,IAAI,aAAa,CAAC,IAAI,GAAG,CAAC,EAAE;;AAE1B,YAAA,OAAO,CAAC,GAAG,CACT,CAA8B,2BAAA,EAAA,KAAK,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA,CAAE,CACrE;;;AAIL,IAAA,IAAI,aAAa,CAAC,IAAI,KAAK,CAAC,EAAE;QAC5B,IAAI,KAAK,EAAE;;AAET,YAAA,OAAO,CAAC,GAAG,CACT,uEAAuE,CACxE;;AAEH,QAAA,OAAO,QAAQ;;AAGjB,IAAA,OAAO,QAAQ,CAAC,MAAM,CAAC,CAAC,IAAI,KAAK,aAAa,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAChE;AAEA;;;;;;;AAOG;AACI,eAAe,WAAW,CAC/B,QAAgB,EAChB,MAAc,EACd,IAA6B,EAC7B,KAAc,EAAA;AAEd,IAAA,MAAM,YAAY,GAAgB;AAChC,QAAA,MAAM,EAAE,MAAM;AACd,QAAA,OAAO,EAAE;AACP,YAAA,cAAc,EAAE,kBAAkB;AAClC,YAAA,YAAY,EAAE,eAAe;AAC7B,YAAA,WAAW,EAAE,MAAM;AACpB,SAAA;AACD,QAAA,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC;KAC3B;IAED,IAAI,KAAK,IAAI,IAAI,IAAI,KAAK,KAAK,EAAE,EAAE;QACjC,YAAY,CAAC,KAAK,GAAG,IAAI,eAAe,CAAC,KAAK,CAAC;;IAGjD,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,QAAQ,EAAE,YAAY,CAAC;AAEpD,IAAA,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE;AAChB,QAAA,MAAM,SAAS,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE;QACvC,MAAM,IAAI,KAAK,CACb,CAAuB,oBAAA,EAAA,QAAQ,CAAC,MAAM,CAAW,QAAA,EAAA,SAAS,CAAE,CAAA,CAC7D;;AAGH,IAAA,QAAQ,MAAM,QAAQ,CAAC,IAAI,EAAE;AAC/B;AAEA;;;;;;AAMG;AACI,eAAe,YAAY,CAChC,SAA0B,EAC1B,OAAkB,EAAA;IAElB,MAAM,UAAU,GAAG,SAAS,CAAC,GAAG,CAAC,OAAO,IAAI,KAA8B;QACxE,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC;QAEnC,IAAI,CAAC,IAAI,EAAE;YACT,OAAO;gBACL,OAAO,EAAE,IAAI,CAAC,EAAE;AAChB,gBAAA,MAAM,EAAE,IAAI;AACZ,gBAAA,QAAQ,EAAE,IAAI;gBACd,aAAa,EAAE,SAAS,IAAI,CAAC,IAAI,CAAiC,8BAAA,EAAA,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAE,CAAA;aAC1G;;AAGH,QAAA,IAAI;YACF,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,EAAE;gBAC3C,QAAQ,EAAE,EAAE,CAAC,SAAS,CAAC,yBAAyB,GAAG,IAAI,EAAE;AAC1D,aAAA,CAAC;YACF,OAAO;gBACL,OAAO,EAAE,IAAI,CAAC,EAAE;gBAChB,MAAM;AACN,gBAAA,QAAQ,EAAE,KAAK;aAChB;;QACD,OAAO,KAAK,EAAE;YACd,OAAO;gBACL,OAAO,EAAE,IAAI,CAAC,EAAE;AAChB,gBAAA,MAAM,EAAE,IAAI;AACZ,gBAAA,QAAQ,EAAE,IAAI;AACd,gBAAA,aAAa,EAAG,KAAe,CAAC,OAAO,IAAI,uBAAuB;aACnE;;AAEL,KAAC,CAAC;AAEF,IAAA,OAAO,MAAM,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC;AACtC;AAEA;;;;AAIG;AACG,SAAU,uBAAuB,CACrC,QAAyC,EAAA;IAEzC,IAAI,SAAS,GAAG,EAAE;AAElB,IAAA,IAAI,QAAQ,CAAC,MAAM,IAAI,IAAI,IAAI,QAAQ,CAAC,MAAM,KAAK,EAAE,EAAE;AACrD,QAAA,SAAS,IAAI,CAAY,SAAA,EAAA,QAAQ,CAAC,MAAM,IAAI;;SACvC;QACL,SAAS,IAAI,kBAAkB;;AAGjC,IAAA,IAAI,QAAQ,CAAC,MAAM,IAAI,IAAI,IAAI,QAAQ,CAAC,MAAM,KAAK,EAAE,EAAE;AACrD,QAAA,SAAS,IAAI,CAAY,SAAA,EAAA,QAAQ,CAAC,MAAM,IAAI;;AAG9C,IAAA,IAAI,QAAQ,CAAC,KAAK,IAAI,QAAQ,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE;QAC/C,SAAS,IAAI,oBAAoB;AAEjC,QAAA,MAAM,SAAS,GAAG,QAAQ,CAAC,KAAK,CAAC,MAAM;AACvC,QAAA,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,SAAS,EAAE,CAAC,EAAE,EAAE;YAClC,MAAM,IAAI,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC;YAC9B,MAAM,OAAO,GAAG,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC;AAC7C,YAAA,SAAS,IAAI,CAAe,YAAA,EAAA,IAAI,CAAC,IAAI,MAAM,OAAO,GAAG,YAAY,GAAG,YAAY,EAAE;AAElF,YAAA,IAAI,CAAC,GAAG,SAAS,GAAG,CAAC,EAAE;AACrB,gBAAA,SAAS,IAAI,SAAS,IAAI,CAAC,GAAG,IAAI,GAAG,KAAK;;;QAI9C,SAAS,IAAI,iBAAiB,QAAQ,CAAC,UAAU,CAAO,IAAA,EAAA,aAAa,EAAE;;IAGzE,OAAO;QACL,SAAS,CAAC,IAAI,EAAE;AAChB,QAAA;YACE,UAAU,EAAE,QAAQ,CAAC,UAAU;YAC/B,KAAK,EAAE,QAAQ,CAAC,KAAK;AACtB,SAAA;KACF;AACH;AAEA;AACA;AACA;AAEA;;;;;;;;;;;;;;;;;;;;;AAqBG;AACa,SAAA,iCAAiC,CAC/C,UAAA,GAA8C,EAAE,EAAA;AAEhD,IAAA,MAAM,MAAM,GACT,UAAU,CAAC,MAAM,CAAC,YAAY,CAAwB;AACvD,QAAA,UAAU,CAAC,MAAM;AACjB,QAAA,sBAAsB,CAAC,MAAM,CAAC,YAAY,CAAC;AAC3C,QAAA,EAAE;IAEJ,IAAI,CAAC,MAAM,EAAE;QACX,MAAM,IAAI,KAAK,CACb,qDAAqD;AACnD,YAAA,qEAAqE,CACxE;;IAGH,MAAM,OAAO,GAAG,UAAU,CAAC,OAAO,IAAI,cAAc,EAAE;AACtD,IAAA,MAAM,aAAa,GAAG,UAAU,CAAC,aAAa,IAAI,uBAAuB;IACzE,MAAM,KAAK,GAAG,UAAU,CAAC,KAAK,IAAI,OAAO,CAAC,GAAG,CAAC,KAAK;AACnD,IAAA,MAAM,KAAK,GAAG,UAAU,CAAC,KAAK,IAAI,OAAO,CAAC,GAAG,CAAC,SAAS,KAAK,MAAM;AAClE,IAAA,MAAM,aAAa,GAAG,CAAG,EAAA,OAAO,oBAAoB;AAEpD,IAAA,MAAM,WAAW,GAAG;;;;;;;;;;;;;;;;;;;;CAoBrB,CAAC,IAAI,EAAE;IAEN,OAAO,IAAI,CACT,OAAO,MAAM,EAAE,MAAM,KAAI;QACvB,MAAM,EAAE,IAAI,EAAE,UAAU,EAAE,OAAO,GAAG,eAAe,EAAE,GAAG,MAAM;;AAG9D,QAAA,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,IAAI,MAAM,CAAC,QAAQ,IAAI,EAAE,CACtB;QAE9B,IAAI,OAAO,IAAI,IAAI,IAAI,OAAO,CAAC,IAAI,KAAK,CAAC,EAAE;YACzC,MAAM,IAAI,KAAK,CACb,uBAAuB;AACrB,gBAAA,+EAA+E,CAClF;;QAGH,IAAI,QAAQ,IAAI,IAAI,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE;YAC7C,MAAM,IAAI,KAAK,CACb,gCAAgC;AAC9B,gBAAA,qEAAqE,CACxE;;QAGH,IAAI,SAAS,GAAG,CAAC;AAEjB,QAAA,IAAI;;;;YAKF,MAAM,cAAc,GAAG,kBAAkB,CAAC,QAAQ,EAAE,IAAI,EAAE,KAAK,CAAC;YAEhE,IAAI,KAAK,EAAE;;AAET,gBAAA,OAAO,CAAC,GAAG,CACT,uBAAuB,cAAc,CAAC,MAAM,CAAgB,cAAA,CAAA;AAC1D,oBAAA,CAAA,eAAA,EAAkB,QAAQ,CAAC,MAAM,CAAA,CAAA,CAAG,CACvC;;YAGH,IAAI,QAAQ,GAAG,MAAM,WAAW,CAC9B,aAAa,EACb,MAAM,EACN;gBACE,IAAI;AACJ,gBAAA,KAAK,EAAE,cAAc;gBACrB,UAAU;gBACV,OAAO;aACR,EACD,KAAK,CACN;;;;AAMD,YAAA,OAAO,QAAQ,CAAC,MAAM,KAAK,oBAAoB,EAAE;AAC/C,gBAAA,SAAS,EAAE;AAEX,gBAAA,IAAI,SAAS,GAAG,aAAa,EAAE;AAC7B,oBAAA,MAAM,IAAI,KAAK,CACb,CAAA,8BAAA,EAAiC,aAAa,CAAK,GAAA,CAAA;wBACjD,4DAA4D;AAC5D,wBAAA,gCAAgC,CACnC;;gBAGH,IAAI,KAAK,EAAE;;AAET,oBAAA,OAAO,CAAC,GAAG,CACT,CAAA,uBAAA,EAA0B,SAAS,CAAK,EAAA,EAAA,QAAQ,CAAC,UAAU,EAAE,MAAM,IAAI,CAAC,CAAA,mBAAA,CAAqB,CAC9F;;AAGH,gBAAA,MAAM,WAAW,GAAG,MAAM,YAAY,CACpC,QAAQ,CAAC,UAAU,IAAI,EAAE,EACzB,OAAO,CACR;AAED,gBAAA,QAAQ,GAAG,MAAM,WAAW,CAC1B,aAAa,EACb,MAAM,EACN;oBACE,kBAAkB,EAAE,QAAQ,CAAC,kBAAkB;AAC/C,oBAAA,YAAY,EAAE,WAAW;iBAC1B,EACD,KAAK,CACN;;;;;AAOH,YAAA,IAAI,QAAQ,CAAC,MAAM,KAAK,WAAW,EAAE;AACnC,gBAAA,OAAO,uBAAuB,CAAC,QAAQ,CAAC;;AAG1C,YAAA,IAAI,QAAQ,CAAC,MAAM,KAAK,OAAO,EAAE;AAC/B,gBAAA,MAAM,IAAI,KAAK,CACb,oBAAoB,QAAQ,CAAC,KAAK,CAAE,CAAA;qBACjC,QAAQ,CAAC,MAAM,IAAI,IAAI,IAAI,QAAQ,CAAC,MAAM,KAAK;AAC9C,0BAAE,CAAA,aAAA,EAAgB,QAAQ,CAAC,MAAM,CAAE;AACnC,0BAAE,EAAE,CAAC,CACV;;YAGH,MAAM,IAAI,KAAK,CAAC,CAAA,4BAAA,EAA+B,QAAQ,CAAC,MAAM,CAAE,CAAA,CAAC;;QACjE,OAAO,KAAK,EAAE;YACd,MAAM,IAAI,KAAK,CACb,CAAA,+BAAA,EAAmC,KAAe,CAAC,OAAO,CAAE,CAAA,CAC7D;;AAEL,KAAC,EACD;QACE,IAAI,EAAE,SAAS,CAAC,yBAAyB;QACzC,WAAW;AACX,QAAA,MAAM,EAAE,6BAA6B;QACrC,cAAc,EAAE,SAAS,CAAC,oBAAoB;AAC/C,KAAA,CACF;AACH;;;;"}

package/dist/types/tools/ProgrammaticToolCalling.d.ts

@@ -14,21 +14,34 @@ declare const ProgrammaticToolCallingSchema: z.ZodObject<{
     timeout?: number | undefined;
     session_id?: string | undefined;
 }>;
+/**
+ * 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 declare function normalizeToPythonIdentifier(name: string): string;
 /**
  * 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 declare function extractUsedToolNames(code: string, availableToolNames: Set<string>): Set<string>;
+export declare function extractUsedToolNames(code: string, toolNameMap: Map<string, string>): Set<string>;
 /**
  * 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 declare function filterToolsByUsage(toolDefs: t.LCTool[], code: string): t.LCTool[];
+export declare function filterToolsByUsage(toolDefs: t.LCTool[], code: string, debug?: boolean): t.LCTool[];
 /**
  * Makes an HTTP request to the Code API.
  * @param endpoint - The API endpoint URL

package/dist/types/types/tools.d.ts

@@ -192,6 +192,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;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@librechat/agents",
-  "version": "3.0.43",
+  "version": "3.0.44",
   "main": "./dist/cjs/main.cjs",
   "module": "./dist/esm/main.mjs",
   "types": "./dist/types/index.d.ts",

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;
   }
 
@@ -318,6 +410,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 +464,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 +501,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

@@ -239,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;
 };