@librechat/agents 3.0.36 → 3.0.40

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

@@ -0,0 +1 @@
+{"version":3,"file":"ToolSearchRegex.mjs","sources":["../../../src/tools/ToolSearchRegex.ts"],"sourcesContent":["// src/tools/ToolSearchRegex.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 * as t from '@/types';\nimport { getCodeBaseURL } from './CodeExecutor';\nimport { EnvVar, Constants } from '@/common';\n\nconfig();\n\n/** Maximum allowed regex pattern length */\nconst MAX_PATTERN_LENGTH = 200;\n\n/** Maximum allowed regex nesting depth */\nconst MAX_REGEX_COMPLEXITY = 5;\n\n/** Default search timeout in milliseconds */\nconst SEARCH_TIMEOUT = 5000;\n\nconst ToolSearchRegexSchema = z.object({\n  query: z\n    .string()\n    .min(1)\n    .max(MAX_PATTERN_LENGTH)\n    .describe(\n      'Regex pattern to search tool names and descriptions. Special regex characters will be sanitized for safety.'\n    ),\n  fields: z\n    .array(z.enum(['name', 'description', 'parameters']))\n    .optional()\n    .default(['name', 'description'])\n    .describe('Which fields to search. Default: name and description'),\n  max_results: z\n    .number()\n    .int()\n    .min(1)\n    .max(50)\n    .optional()\n    .default(10)\n    .describe('Maximum number of matching tools to return'),\n});\n\n/**\n * Escapes special regex characters in a string to use as a literal pattern.\n * @param pattern - The string to escape\n * @returns The escaped string safe for use in a RegExp\n */\nfunction escapeRegexSpecialChars(pattern: string): string {\n  return pattern.replace(/[.*+?^${}()|[\\]\\\\]/g, '\\\\$&');\n}\n\n/**\n * Counts the maximum nesting depth of groups in a regex pattern.\n * @param pattern - The regex pattern to analyze\n * @returns The maximum nesting depth\n */\nfunction countNestedGroups(pattern: string): number {\n  let maxDepth = 0;\n  let currentDepth = 0;\n\n  for (let i = 0; i < pattern.length; i++) {\n    if (pattern[i] === '(' && (i === 0 || pattern[i - 1] !== '\\\\')) {\n      currentDepth++;\n      maxDepth = Math.max(maxDepth, currentDepth);\n    } else if (pattern[i] === ')' && (i === 0 || pattern[i - 1] !== '\\\\')) {\n      currentDepth = Math.max(0, currentDepth - 1);\n    }\n  }\n\n  return maxDepth;\n}\n\n/**\n * Detects nested quantifiers that can cause catastrophic backtracking.\n * Patterns like (a+)+, (a*)*, (a+)*, etc.\n * @param pattern - The regex pattern to check\n * @returns True if nested quantifiers are detected\n */\nfunction hasNestedQuantifiers(pattern: string): boolean {\n  const nestedQuantifierPattern = /\\([^)]*[+*][^)]*\\)[+*?]/;\n  return nestedQuantifierPattern.test(pattern);\n}\n\n/**\n * Checks if a regex pattern contains potentially dangerous constructs.\n * @param pattern - The regex pattern to validate\n * @returns True if the pattern is dangerous\n */\nfunction isDangerousPattern(pattern: string): boolean {\n  if (hasNestedQuantifiers(pattern)) {\n    return true;\n  }\n\n  if (countNestedGroups(pattern) > MAX_REGEX_COMPLEXITY) {\n    return true;\n  }\n\n  const dangerousPatterns = [\n    /\\.\\{1000,\\}/, // Excessive wildcards\n    /\\(\\?=\\.\\{100,\\}\\)/, // Runaway lookaheads\n    /\\([^)]*\\|\\s*\\){20,}/, // Excessive alternation (rough check)\n    /\\(\\.\\*\\)\\+/, // (.*)+\n    /\\(\\.\\+\\)\\+/, // (.+)+\n    /\\(\\.\\*\\)\\*/, // (.*)*\n    /\\(\\.\\+\\)\\*/, // (.+)*\n  ];\n\n  for (const dangerous of dangerousPatterns) {\n    if (dangerous.test(pattern)) {\n      return true;\n    }\n  }\n\n  return false;\n}\n\n/**\n * Sanitizes a regex pattern for safe execution.\n * If the pattern is dangerous, it will be escaped to a literal string search.\n * @param pattern - The regex pattern to sanitize\n * @returns Object containing the safe pattern and whether it was escaped\n */\nfunction sanitizeRegex(pattern: string): { safe: string; wasEscaped: boolean } {\n  if (isDangerousPattern(pattern)) {\n    return {\n      safe: escapeRegexSpecialChars(pattern),\n      wasEscaped: true,\n    };\n  }\n\n  try {\n    new RegExp(pattern);\n    return { safe: pattern, wasEscaped: false };\n  } catch {\n    return {\n      safe: escapeRegexSpecialChars(pattern),\n      wasEscaped: true,\n    };\n  }\n}\n\n/**\n * Simplifies tool parameters for search purposes.\n * Extracts only the essential structure needed for parameter name searching.\n * @param parameters - The tool's JSON schema parameters\n * @returns Simplified parameters object\n */\nfunction simplifyParametersForSearch(\n  parameters?: t.JsonSchemaType\n): t.JsonSchemaType | undefined {\n  if (!parameters) {\n    return undefined;\n  }\n\n  if (parameters.properties) {\n    return {\n      type: parameters.type,\n      properties: Object.fromEntries(\n        Object.entries(parameters.properties).map(([key, value]) => [\n          key,\n          { type: (value as t.JsonSchemaType).type },\n        ])\n      ),\n    } as t.JsonSchemaType;\n  }\n\n  return { type: parameters.type };\n}\n\n/**\n * Generates the JavaScript search script to be executed in the sandbox.\n * Uses plain JavaScript for maximum compatibility with the Code API.\n * @param deferredTools - Array of tool metadata to search through\n * @param fields - Which fields to search\n * @param maxResults - Maximum number of results to return\n * @param sanitizedPattern - The sanitized regex pattern\n * @returns The JavaScript code string\n */\nfunction generateSearchScript(\n  deferredTools: t.ToolMetadata[],\n  fields: string[],\n  maxResults: number,\n  sanitizedPattern: string\n): string {\n  const lines = [\n    '// Tool definitions (injected)',\n    'var tools = ' + JSON.stringify(deferredTools) + ';',\n    'var searchFields = ' + JSON.stringify(fields) + ';',\n    'var maxResults = ' + maxResults + ';',\n    'var pattern = ' + JSON.stringify(sanitizedPattern) + ';',\n    '',\n    '// Compile regex (pattern is sanitized client-side)',\n    'var regex;',\n    'try {',\n    '  regex = new RegExp(pattern, \\'i\\');',\n    '} catch (e) {',\n    '  regex = new RegExp(pattern.replace(/[.*+?^${}()[\\\\]\\\\\\\\|]/g, \"\\\\\\\\$&\"), \"i\");',\n    '}',\n    '',\n    '// Search logic',\n    'var results = [];',\n    '',\n    'for (var j = 0; j < tools.length; j++) {',\n    '  var tool = tools[j];',\n    '  var bestScore = 0;',\n    '  var matchedField = \\'\\';',\n    '  var snippet = \\'\\';',\n    '',\n    '  // Search name (highest priority)',\n    '  if (searchFields.indexOf(\\'name\\') >= 0 && regex.test(tool.name)) {',\n    '    bestScore = 0.95;',\n    '    matchedField = \\'name\\';',\n    '    snippet = tool.name;',\n    '  }',\n    '',\n    '  // Search description (medium priority)',\n    '  if (searchFields.indexOf(\\'description\\') >= 0 && tool.description && regex.test(tool.description)) {',\n    '    if (bestScore === 0) {',\n    '      bestScore = 0.75;',\n    '      matchedField = \\'description\\';',\n    '      snippet = tool.description.substring(0, 100);',\n    '    }',\n    '  }',\n    '',\n    '  // Search parameter names (lower priority)',\n    '  if (searchFields.indexOf(\\'parameters\\') >= 0 && tool.parameters && tool.parameters.properties) {',\n    '    var paramNames = Object.keys(tool.parameters.properties).join(\\' \\');',\n    '    if (regex.test(paramNames)) {',\n    '      if (bestScore === 0) {',\n    '        bestScore = 0.60;',\n    '        matchedField = \\'parameters\\';',\n    '        snippet = paramNames;',\n    '      }',\n    '    }',\n    '  }',\n    '',\n    '  if (bestScore > 0) {',\n    '    results.push({',\n    '      tool_name: tool.name,',\n    '      match_score: bestScore,',\n    '      matched_field: matchedField,',\n    '      snippet: snippet',\n    '    });',\n    '  }',\n    '}',\n    '',\n    '// Sort by score (descending) and limit results',\n    'results.sort(function(a, b) { return b.match_score - a.match_score; });',\n    'var topResults = results.slice(0, maxResults);',\n    '',\n    '// Output as JSON',\n    'console.log(JSON.stringify({',\n    '  tool_references: topResults.map(function(r) {',\n    '    return {',\n    '      tool_name: r.tool_name,',\n    '      match_score: r.match_score,',\n    '      matched_field: r.matched_field,',\n    '      snippet: r.snippet',\n    '    };',\n    '  }),',\n    '  total_tools_searched: tools.length,',\n    '  pattern_used: pattern',\n    '}));',\n  ];\n  return lines.join('\\n');\n}\n\n/**\n * Parses the search results from stdout JSON.\n * @param stdout - The stdout string containing JSON results\n * @returns Parsed search response\n */\nfunction parseSearchResults(stdout: string): t.ToolSearchResponse {\n  const jsonMatch = stdout.trim();\n  const parsed = JSON.parse(jsonMatch) as t.ToolSearchResponse;\n  return parsed;\n}\n\n/**\n * Formats search results into a human-readable string.\n * @param searchResponse - The parsed search response\n * @returns Formatted string for LLM consumption\n */\nfunction formatSearchResults(searchResponse: t.ToolSearchResponse): string {\n  const { tool_references, total_tools_searched, pattern_used } =\n    searchResponse;\n\n  if (tool_references.length === 0) {\n    return `No tools matched the pattern \"${pattern_used}\".\\nTotal tools searched: ${total_tools_searched}`;\n  }\n\n  let response = `Found ${tool_references.length} matching tools:\\n\\n`;\n\n  for (const ref of tool_references) {\n    response += `- ${ref.tool_name} (score: ${ref.match_score.toFixed(2)})\\n`;\n    response += `  Matched in: ${ref.matched_field}\\n`;\n    response += `  Snippet: ${ref.snippet}\\n\\n`;\n  }\n\n  response += `Total tools searched: ${total_tools_searched}\\n`;\n  response += `Pattern used: ${pattern_used}`;\n\n  return response;\n}\n\n/**\n * Creates a Tool Search Regex tool for discovering tools from a large registry.\n *\n * This tool enables AI agents to dynamically discover tools from a large library\n * without loading all tool definitions into the LLM context window. The agent\n * can search for relevant tools on-demand using regex patterns.\n *\n * The tool registry can be provided either:\n * 1. At initialization time via params.toolRegistry\n * 2. At runtime via config.configurable.toolRegistry when invoking\n *\n * @param params - Configuration parameters for the tool (toolRegistry is optional)\n * @returns A LangChain DynamicStructuredTool for tool searching\n *\n * @example\n * // Option 1: Registry at initialization\n * const tool = createToolSearchRegexTool({ apiKey, toolRegistry });\n * await tool.invoke({ query: 'expense' });\n *\n * @example\n * // Option 2: Registry at runtime\n * const tool = createToolSearchRegexTool({ apiKey });\n * await tool.invoke(\n *   { query: 'expense' },\n *   { configurable: { toolRegistry, onlyDeferred: true } }\n * );\n */\nfunction createToolSearchRegexTool(\n  initParams: t.ToolSearchRegexParams = {}\n): DynamicStructuredTool<typeof ToolSearchRegexSchema> {\n  const apiKey: string =\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('No API key provided for tool search regex tool.');\n  }\n\n  const baseEndpoint = initParams.baseUrl ?? getCodeBaseURL();\n  const EXEC_ENDPOINT = `${baseEndpoint}/exec`;\n  const defaultOnlyDeferred = initParams.onlyDeferred ?? true;\n\n  const description = `\nSearches through available tools to find ones matching your query pattern.\n\nUsage:\n- Provide a regex pattern to search tool names and descriptions.\n- Use this when you need to discover tools for a specific task.\n- Results include tool names, match quality scores, and snippets showing where the match occurred.\n- Higher scores (0.9+) indicate name matches, medium scores (0.7+) indicate description matches.\n`.trim();\n\n  return tool<typeof ToolSearchRegexSchema>(\n    async (params, config) => {\n      const {\n        query,\n        fields = ['name', 'description'],\n        max_results = 10,\n      } = params;\n\n      // Extra params injected by ToolNode (follows web_search pattern)\n      const {\n        toolRegistry: paramToolRegistry,\n        onlyDeferred: paramOnlyDeferred,\n      } = config.toolCall ?? {};\n\n      const { safe: sanitizedPattern, wasEscaped } = sanitizeRegex(query);\n\n      let warningMessage = '';\n      if (wasEscaped) {\n        warningMessage =\n          'Note: The provided pattern was converted to a literal search for safety.\\n\\n';\n      }\n\n      // Priority: ToolNode injection (via config.toolCall) > initialization params\n      const toolRegistry = paramToolRegistry ?? initParams.toolRegistry;\n      const onlyDeferred =\n        paramOnlyDeferred !== undefined\n          ? paramOnlyDeferred\n          : defaultOnlyDeferred;\n\n      if (toolRegistry == null) {\n        return [\n          `${warningMessage}Error: No tool registry provided. Configure toolRegistry at agent level or initialization.`,\n          {\n            tool_references: [],\n            metadata: {\n              total_searched: 0,\n              pattern: sanitizedPattern,\n              error: 'No tool registry provided',\n            },\n          },\n        ];\n      }\n\n      const toolsArray: t.LCTool[] = Array.from(toolRegistry.values());\n\n      const deferredTools: t.ToolMetadata[] = toolsArray\n        .filter((lcTool) => {\n          if (onlyDeferred === true) {\n            return lcTool.defer_loading === true;\n          }\n          return true;\n        })\n        .map((lcTool) => ({\n          name: lcTool.name,\n          description: lcTool.description ?? '',\n          parameters: simplifyParametersForSearch(lcTool.parameters),\n        }));\n\n      if (deferredTools.length === 0) {\n        return [\n          `${warningMessage}No tools available to search. The tool registry is empty or no deferred tools are registered.`,\n          {\n            tool_references: [],\n            metadata: {\n              total_searched: 0,\n              pattern: sanitizedPattern,\n            },\n          },\n        ];\n      }\n\n      const searchScript = generateSearchScript(\n        deferredTools,\n        fields,\n        max_results,\n        sanitizedPattern\n      );\n\n      const postData = {\n        lang: 'js',\n        code: searchScript,\n        timeout: SEARCH_TIMEOUT,\n      };\n\n      try {\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(postData),\n        };\n\n        if (process.env.PROXY != null && process.env.PROXY !== '') {\n          fetchOptions.agent = new HttpsProxyAgent(process.env.PROXY);\n        }\n\n        const response = await fetch(EXEC_ENDPOINT, fetchOptions);\n        if (!response.ok) {\n          throw new Error(`HTTP error! status: ${response.status}`);\n        }\n\n        const result: t.ExecuteResult = await response.json();\n\n        if (result.stderr && result.stderr.trim()) {\n          // eslint-disable-next-line no-console\n          console.warn('[ToolSearchRegex] stderr:', result.stderr);\n        }\n\n        if (!result.stdout || !result.stdout.trim()) {\n          return [\n            `${warningMessage}No tools matched the pattern \"${sanitizedPattern}\".\\nTotal tools searched: ${deferredTools.length}`,\n            {\n              tool_references: [],\n              metadata: {\n                total_searched: deferredTools.length,\n                pattern: sanitizedPattern,\n              },\n            },\n          ];\n        }\n\n        const searchResponse = parseSearchResults(result.stdout);\n        const formattedOutput = `${warningMessage}${formatSearchResults(searchResponse)}`;\n\n        return [\n          formattedOutput,\n          {\n            tool_references: searchResponse.tool_references,\n            metadata: {\n              total_searched: searchResponse.total_tools_searched,\n              pattern: searchResponse.pattern_used,\n            },\n          },\n        ];\n      } catch (error) {\n        // eslint-disable-next-line no-console\n        console.error('[ToolSearchRegex] Error:', error);\n\n        const errorMessage =\n          error instanceof Error ? error.message : String(error);\n        return [\n          `Tool search failed: ${errorMessage}\\n\\nSuggestion: Try a simpler search pattern or search for specific tool names.`,\n          {\n            tool_references: [],\n            metadata: {\n              total_searched: 0,\n              pattern: sanitizedPattern,\n              error: errorMessage,\n            },\n          },\n        ];\n      }\n    },\n    {\n      name: Constants.TOOL_SEARCH_REGEX,\n      description,\n      schema: ToolSearchRegexSchema,\n      responseFormat: Constants.CONTENT_AND_ARTIFACT,\n    }\n  );\n}\n\nexport {\n  createToolSearchRegexTool,\n  sanitizeRegex,\n  escapeRegexSpecialChars,\n  isDangerousPattern,\n  countNestedGroups,\n  hasNestedQuantifiers,\n};\n"],"names":[],"mappings":"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"}

package/dist/types/agents/AgentContext.d.ts

@@ -38,6 +38,11 @@ export declare class AgentContext {
     tools?: t.GraphTools;
     /** Tool map for this agent */
     toolMap?: t.ToolMap;
+    /**
+     * Tool definitions registry (includes deferred and programmatic tool metadata).
+     * Used for tool search and programmatic tool calling.
+     */
+    toolRegistry?: t.LCToolRegistry;
     /** Instructions for this agent */
     instructions?: string;
     /** Additional instructions for this agent */
@@ -58,7 +63,7 @@ export declare class AgentContext {
     tokenCalculationPromise?: Promise<void>;
     /** Format content blocks as strings (for legacy compatibility) */
     useLegacyContent: boolean;
-    constructor({ agentId, provider, clientOptions, maxContextTokens, streamBuffer, tokenCounter, tools, toolMap, instructions, additionalInstructions, reasoningKey, toolEnd, instructionTokens, useLegacyContent, }: {
+    constructor({ agentId, provider, clientOptions, maxContextTokens, streamBuffer, tokenCounter, tools, toolMap, toolRegistry, instructions, additionalInstructions, reasoningKey, toolEnd, instructionTokens, useLegacyContent, }: {
         agentId: string;
         provider: Providers;
         clientOptions?: t.ClientOptions;
@@ -67,6 +72,7 @@ export declare class AgentContext {
         tokenCounter?: t.TokenCounter;
         tools?: t.GraphTools;
         toolMap?: t.ToolMap;
+        toolRegistry?: t.LCToolRegistry;
         instructions?: string;
         additionalInstructions?: string;
         reasoningKey?: 'reasoning_content' | 'reasoning';
@@ -91,4 +97,22 @@ export declare class AgentContext {
      * Note: System message tokens are calculated during systemRunnable creation
      */
     calculateInstructionTokens(tokenCounter: t.TokenCounter): Promise<void>;
+    /**
+     * Gets a map of tools that allow programmatic (code_execution) calling.
+     * Filters toolMap based on toolRegistry's allowed_callers settings.
+     * @returns ToolMap containing only tools that allow code_execution
+     */
+    getProgrammaticToolMap(): t.ToolMap;
+    /**
+     * Gets tool definitions for tools that allow programmatic calling.
+     * Used to send to the Code API for stub generation.
+     * @returns Array of LCTool definitions for programmatic tools
+     */
+    getProgrammaticToolDefs(): t.LCTool[];
+    /**
+     * Gets the tool registry for deferred tools (for tool search).
+     * @param onlyDeferred If true, only returns tools with defer_loading=true
+     * @returns LCToolRegistry with tool definitions
+     */
+    getDeferredToolRegistry(onlyDeferred?: boolean): t.LCToolRegistry;
 }

package/dist/types/common/enum.d.ts

@@ -114,6 +114,8 @@ export declare enum Callback {
 export declare enum Constants {
     OFFICIAL_CODE_BASEURL = "https://api.librechat.ai/v1",
     EXECUTE_CODE = "execute_code",
+    TOOL_SEARCH_REGEX = "tool_search_regex",
+    PROGRAMMATIC_TOOL_CALLING = "programmatic_code_execution",
     WEB_SEARCH = "web_search",
     CONTENT_AND_ARTIFACT = "content_and_artifact",
     LC_TRANSFER_TO_ = "lc_transfer_to_"

package/dist/types/graphs/Graph.d.ts

@@ -91,9 +91,10 @@ export declare class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode>
         instructions?: string;
         additional_instructions?: string;
     }): t.SystemRunnable | undefined;
-    initializeTools({ currentTools, currentToolMap, }: {
+    initializeTools({ currentTools, currentToolMap, agentContext, }: {
         currentTools?: t.GraphTools;
         currentToolMap?: t.ToolMap;
+        agentContext?: AgentContext;
     }): CustomToolNode<t.BaseGraphState> | ToolNode<t.BaseGraphState>;
     initializeModel({ provider, tools, clientOptions, }: {
         provider: Providers;

package/dist/types/index.d.ts

@@ -6,6 +6,8 @@ export * from './messages';
 export * from './graphs';
 export * from './tools/Calculator';
 export * from './tools/CodeExecutor';
+export * from './tools/ProgrammaticToolCalling';
+export * from './tools/ToolSearchRegex';
 export * from './tools/handlers';
 export * from './tools/search';
 export * from './common';

package/dist/types/test/mockTools.d.ts

@@ -0,0 +1,28 @@
+import type { StructuredToolInterface } from '@langchain/core/tools';
+import type { LCToolRegistry } from '@/types';
+/**
+ * Mock get_team_members tool - returns list of team members
+ */
+export declare function createGetTeamMembersTool(): StructuredToolInterface;
+/**
+ * Mock get_expenses tool - returns expense records for a user
+ */
+export declare function createGetExpensesTool(): StructuredToolInterface;
+/**
+ * Mock get_weather tool - returns weather data for a city
+ */
+export declare function createGetWeatherTool(): StructuredToolInterface;
+/**
+ * Mock calculator tool - evaluates mathematical expressions
+ */
+export declare function createCalculatorTool(): StructuredToolInterface;
+/**
+ * Creates a tool registry for programmatic tool calling tests.
+ * Tools are configured with allowed_callers to demonstrate classification.
+ */
+export declare function createProgrammaticToolRegistry(): LCToolRegistry;
+/**
+ * Creates a sample tool registry for tool search tests.
+ * Includes mix of deferred and non-deferred tools.
+ */
+export declare function createToolSearchToolRegistry(): LCToolRegistry;

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

@@ -0,0 +1,86 @@
+import { z } from 'zod';
+import { DynamicStructuredTool } from '@langchain/core/tools';
+import type * as t from '@/types';
+declare const ProgrammaticToolCallingSchema: z.ZodObject<{
+    code: z.ZodString;
+    tools: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        parameters: z.ZodAny;
+    }, "strip", z.ZodTypeAny, {
+        name: string;
+        description?: string | undefined;
+        parameters?: any;
+    }, {
+        name: string;
+        description?: string | undefined;
+        parameters?: any;
+    }>, "many">>;
+    session_id: z.ZodOptional<z.ZodString>;
+    timeout: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+}, "strip", z.ZodTypeAny, {
+    code: string;
+    timeout: number;
+    tools?: {
+        name: string;
+        description?: string | undefined;
+        parameters?: any;
+    }[] | undefined;
+    session_id?: string | undefined;
+}, {
+    code: string;
+    tools?: {
+        name: string;
+        description?: string | undefined;
+        parameters?: any;
+    }[] | undefined;
+    timeout?: number | undefined;
+    session_id?: string | undefined;
+}>;
+/**
+ * Makes an HTTP request to the Code API.
+ * @param endpoint - The API endpoint URL
+ * @param apiKey - The API key for authentication
+ * @param body - The request body
+ * @param proxy - Optional HTTP proxy URL
+ * @returns The parsed API response
+ */
+export declare function makeRequest(endpoint: string, apiKey: string, body: Record<string, unknown>, proxy?: string): Promise<t.ProgrammaticExecutionResponse>;
+/**
+ * Executes tools in parallel when requested by the API.
+ * Uses Promise.all for parallel execution, catching individual errors.
+ * @param toolCalls - Array of tool calls from the API
+ * @param toolMap - Map of tool names to executable tools
+ * @returns Array of tool results
+ */
+export declare function executeTools(toolCalls: t.PTCToolCall[], toolMap: t.ToolMap): Promise<t.PTCToolResult[]>;
+/**
+ * Formats the completed response for the agent.
+ * @param response - The completed API response
+ * @returns Tuple of [formatted string, artifact]
+ */
+export declare function formatCompletedResponse(response: t.ProgrammaticExecutionResponse): [string, t.ProgrammaticExecutionArtifact];
+/**
+ * Creates a Programmatic Tool Calling tool for complex multi-tool workflows.
+ *
+ * This tool enables AI agents to write Python code that orchestrates multiple
+ * tool calls programmatically, reducing LLM round-trips and token usage.
+ *
+ * The tool map must be provided at runtime via config.configurable.toolMap.
+ *
+ * @param params - Configuration parameters (apiKey, baseUrl, maxRoundTrips, proxy)
+ * @returns A LangChain DynamicStructuredTool for programmatic tool calling
+ *
+ * @example
+ * const ptcTool = createProgrammaticToolCallingTool({
+ *   apiKey: process.env.CODE_API_KEY,
+ *   maxRoundTrips: 20
+ * });
+ *
+ * const [output, artifact] = await ptcTool.invoke(
+ *   { code, tools },
+ *   { configurable: { toolMap } }
+ * );
+ */
+export declare function createProgrammaticToolCallingTool(initParams?: t.ProgrammaticToolCallingParams): DynamicStructuredTool<typeof ProgrammaticToolCallingSchema>;
+export {};

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

@@ -13,7 +13,13 @@ export declare class ToolNode<T = any> extends RunnableCallable<T, T> {
     toolCallStepIds?: Map<string, string>;
     errorHandler?: t.ToolNodeConstructorParams['errorHandler'];
     private toolUsageCount;
-    constructor({ tools, toolMap, name, tags, errorHandler, toolCallStepIds, handleToolErrors, loadRuntimeTools, }: t.ToolNodeConstructorParams);
+    /** Tools available for programmatic code execution */
+    private programmaticToolMap?;
+    /** Tool definitions for programmatic code execution (sent to Code API) */
+    private programmaticToolDefs?;
+    /** Tool registry for tool search (deferred tools) */
+    private toolRegistry?;
+    constructor({ tools, toolMap, name, tags, errorHandler, toolCallStepIds, handleToolErrors, loadRuntimeTools, programmaticToolMap, programmaticToolDefs, toolRegistry, }: t.ToolNodeConstructorParams);
     /**
      * Returns a snapshot of the current tool usage counts.
      * @returns A ReadonlyMap where keys are tool names and values are their usage counts.

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

@@ -0,0 +1,80 @@
+import { z } from 'zod';
+import { DynamicStructuredTool } from '@langchain/core/tools';
+import type * as t from '@/types';
+declare const ToolSearchRegexSchema: z.ZodObject<{
+    query: z.ZodString;
+    fields: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodEnum<["name", "description", "parameters"]>, "many">>>;
+    max_results: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+}, "strip", z.ZodTypeAny, {
+    query: string;
+    fields: ("name" | "description" | "parameters")[];
+    max_results: number;
+}, {
+    query: string;
+    fields?: ("name" | "description" | "parameters")[] | undefined;
+    max_results?: number | undefined;
+}>;
+/**
+ * Escapes special regex characters in a string to use as a literal pattern.
+ * @param pattern - The string to escape
+ * @returns The escaped string safe for use in a RegExp
+ */
+declare function escapeRegexSpecialChars(pattern: string): string;
+/**
+ * Counts the maximum nesting depth of groups in a regex pattern.
+ * @param pattern - The regex pattern to analyze
+ * @returns The maximum nesting depth
+ */
+declare function countNestedGroups(pattern: string): number;
+/**
+ * Detects nested quantifiers that can cause catastrophic backtracking.
+ * Patterns like (a+)+, (a*)*, (a+)*, etc.
+ * @param pattern - The regex pattern to check
+ * @returns True if nested quantifiers are detected
+ */
+declare function hasNestedQuantifiers(pattern: string): boolean;
+/**
+ * Checks if a regex pattern contains potentially dangerous constructs.
+ * @param pattern - The regex pattern to validate
+ * @returns True if the pattern is dangerous
+ */
+declare function isDangerousPattern(pattern: string): boolean;
+/**
+ * Sanitizes a regex pattern for safe execution.
+ * If the pattern is dangerous, it will be escaped to a literal string search.
+ * @param pattern - The regex pattern to sanitize
+ * @returns Object containing the safe pattern and whether it was escaped
+ */
+declare function sanitizeRegex(pattern: string): {
+    safe: string;
+    wasEscaped: boolean;
+};
+/**
+ * Creates a Tool Search Regex tool for discovering tools from a large registry.
+ *
+ * This tool enables AI agents to dynamically discover tools from a large library
+ * without loading all tool definitions into the LLM context window. The agent
+ * can search for relevant tools on-demand using regex patterns.
+ *
+ * The tool registry can be provided either:
+ * 1. At initialization time via params.toolRegistry
+ * 2. At runtime via config.configurable.toolRegistry when invoking
+ *
+ * @param params - Configuration parameters for the tool (toolRegistry is optional)
+ * @returns A LangChain DynamicStructuredTool for tool searching
+ *
+ * @example
+ * // Option 1: Registry at initialization
+ * const tool = createToolSearchRegexTool({ apiKey, toolRegistry });
+ * await tool.invoke({ query: 'expense' });
+ *
+ * @example
+ * // Option 2: Registry at runtime
+ * const tool = createToolSearchRegexTool({ apiKey });
+ * await tool.invoke(
+ *   { query: 'expense' },
+ *   { configurable: { toolRegistry, onlyDeferred: true } }
+ * );
+ */
+declare function createToolSearchRegexTool(initParams?: t.ToolSearchRegexParams): DynamicStructuredTool<typeof ToolSearchRegexSchema>;
+export { createToolSearchRegexTool, sanitizeRegex, escapeRegexSpecialChars, isDangerousPattern, countNestedGroups, hasNestedQuantifiers, };

package/dist/types/types/graph.d.ts

@@ -4,7 +4,7 @@ import type { BaseMessage, AIMessageChunk, SystemMessage } from '@langchain/core
 import type { RunnableConfig, Runnable } from '@langchain/core/runnables';
 import type { ChatGenerationChunk } from '@langchain/core/outputs';
 import type { GoogleAIToolType } from '@langchain/google-common';
-import type { ToolMap, ToolEndEvent, GenericTool } from '@/types/tools';
+import type { ToolMap, ToolEndEvent, GenericTool, LCTool } from '@/types/tools';
 import type { Providers, Callback, GraphNodeKeys } from '@/common';
 import type { StandardGraph, MultiAgentGraph } from '@/graphs';
 import type { ClientOptions } from '@/types/llm';
@@ -248,4 +248,10 @@ export interface AgentInputs {
     reasoningKey?: 'reasoning_content' | 'reasoning';
     /** Format content blocks as strings (for legacy compatibility i.e. Ollama/Azure Serverless) */
     useLegacyContent?: boolean;
+    /**
+     * Tool definitions for all tools, including deferred and programmatic.
+     * Used for tool search and programmatic tool calling.
+     * Maps tool name to LCTool definition.
+     */
+    toolRegistry?: Map<string, LCTool>;
 }

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

@@ -25,6 +25,12 @@ export type ToolNodeOptions = {
     loadRuntimeTools?: ToolRefGenerator;
     toolCallStepIds?: Map<string, string>;
     errorHandler?: (data: ToolErrorData, metadata?: Record<string, unknown>) => Promise<void>;
+    /** Tools available for programmatic code execution (allowed_callers includes 'code_execution') */
+    programmaticToolMap?: ToolMap;
+    /** Tool definitions for programmatic code execution (sent to Code API for stub generation) */
+    programmaticToolDefs?: LCTool[];
+    /** Tool registry for tool search (deferred tool definitions) */
+    toolRegistry?: LCToolRegistry;
 };
 export type ToolNodeConstructorParams = ToolRefs & ToolNodeOptions;
 export type ToolEndEvent = {
@@ -59,3 +65,133 @@ export type ExecuteResult = {
     stderr: string;
     files?: FileRefs;
 };
+/** JSON Schema type definition for tool parameters */
+export type JsonSchemaType = {
+    type: 'string' | 'number' | 'integer' | 'float' | 'boolean' | 'array' | 'object';
+    enum?: string[];
+    items?: JsonSchemaType;
+    properties?: Record<string, JsonSchemaType>;
+    required?: string[];
+    description?: string;
+    additionalProperties?: boolean | JsonSchemaType;
+};
+/**
+ * Specifies which contexts can invoke a tool (inspired by Anthropic's allowed_callers)
+ * - 'direct': Only callable directly by the LLM (default if omitted)
+ * - 'code_execution': Only callable from within programmatic code execution
+ */
+export type AllowedCaller = 'direct' | 'code_execution';
+/** Tool definition with optional deferred loading and caller restrictions */
+export type LCTool = {
+    name: string;
+    description?: string;
+    parameters?: JsonSchemaType;
+    /** When true, tool is not loaded into context initially (for tool search) */
+    defer_loading?: boolean;
+    /**
+     * Which contexts can invoke this tool.
+     * Default: ['direct'] (only callable directly by LLM)
+     * Options: 'direct', 'code_execution'
+     */
+    allowed_callers?: AllowedCaller[];
+};
+/** Map of tool names to tool definitions */
+export type LCToolRegistry = Map<string, LCTool>;
+/** Parameters for creating a Tool Search Regex tool */
+export type ToolSearchRegexParams = {
+    apiKey?: string;
+    toolRegistry?: LCToolRegistry;
+    onlyDeferred?: boolean;
+    baseUrl?: string;
+    [key: string]: unknown;
+};
+/** Simplified tool metadata for search purposes */
+export type ToolMetadata = {
+    name: string;
+    description: string;
+    parameters?: JsonSchemaType;
+};
+/** Individual search result for a matching tool */
+export type ToolSearchResult = {
+    tool_name: string;
+    match_score: number;
+    matched_field: string;
+    snippet: string;
+};
+/** Response from the tool search operation */
+export type ToolSearchResponse = {
+    tool_references: ToolSearchResult[];
+    total_tools_searched: number;
+    pattern_used: string;
+};
+/** Artifact returned alongside the formatted search results */
+export type ToolSearchArtifact = {
+    tool_references: ToolSearchResult[];
+    metadata: {
+        total_searched: number;
+        pattern: string;
+        error?: string;
+    };
+};
+/**
+ * Tool call requested by the Code API during programmatic execution
+ */
+export type PTCToolCall = {
+    /** Unique ID like "call_001" */
+    id: string;
+    /** Tool name */
+    name: string;
+    /** Input parameters */
+    input: Record<string, any>;
+};
+/**
+ * Tool result sent back to the Code API
+ */
+export type PTCToolResult = {
+    /** Matches PTCToolCall.id */
+    call_id: string;
+    /** Tool execution result (any JSON-serializable value) */
+    result: any;
+    /** Whether tool execution failed */
+    is_error: boolean;
+    /** Error details if is_error=true */
+    error_message?: string;
+};
+/**
+ * Response from the Code API for programmatic execution
+ */
+export type ProgrammaticExecutionResponse = {
+    status: 'tool_call_required' | 'completed' | 'error' | unknown;
+    session_id?: string;
+    /** Present when status='tool_call_required' */
+    continuation_token?: string;
+    tool_calls?: PTCToolCall[];
+    /** Present when status='completed' */
+    stdout?: string;
+    stderr?: string;
+    files?: FileRefs;
+    /** Present when status='error' */
+    error?: string;
+};
+/**
+ * Artifact returned by the PTC tool
+ */
+export type ProgrammaticExecutionArtifact = {
+    session_id?: string;
+    files?: FileRefs;
+};
+/**
+ * Initialization parameters for the PTC tool
+ */
+export type ProgrammaticToolCallingParams = {
+    /** Code API key (or use CODE_API_KEY env var) */
+    apiKey?: string;
+    /** Code API base URL (or use CODE_BASEURL env var) */
+    baseUrl?: string;
+    /** Safety limit for round-trips (default: 20) */
+    maxRoundTrips?: number;
+    /** HTTP proxy URL */
+    proxy?: string;
+    /** Environment variable key for API key */
+    [key: string]: unknown;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@librechat/agents",
-  "version": "3.0.36",
+  "version": "3.0.40",
   "main": "./dist/cjs/main.cjs",
   "module": "./dist/esm/main.mjs",
   "types": "./dist/types/index.d.ts",
@@ -53,6 +53,10 @@
     "memory": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/memory.ts --provider 'openAI' --name 'Jo' --location 'New York, NY'",
     "tool": "node --trace-warnings -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/tools.ts --provider 'openrouter' --name 'Jo' --location 'New York, NY'",
     "search": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/search.ts --provider 'bedrock' --name 'Jo' --location 'New York, NY'",
+    "tool_search_regex": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/tool_search_regex.ts",
+    "programmatic_exec": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/programmatic_exec.ts",
+    "code_exec_ptc": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/code_exec_ptc.ts --provider 'openAI' --name 'Jo' --location 'New York, NY'",
+    "programmatic_exec_agent": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/programmatic_exec_agent.ts --provider 'openAI' --name 'Jo' --location 'New York, NY'",
     "ant_web_search": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/ant_web_search.ts --name 'Jo' --location 'New York, NY'",
     "ant_web_search_edge_case": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/ant_web_search_edge_case.ts --name 'Jo' --location 'New York, NY'",
     "ant_web_search_error_edge_case": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/ant_web_search_error_edge_case.ts --name 'Jo' --location 'New York, NY'",