@librechat/agents 3.1.67 → 3.1.68-dev.1

package/src/tools/BashProgrammaticToolCalling.ts

@@ -0,0 +1,381 @@
+import { config } from 'dotenv';
+import { tool, DynamicStructuredTool } from '@langchain/core/tools';
+import type { ToolCall } from '@langchain/core/messages/tool';
+import type * as t from '@/types';
+import {
+  makeRequest,
+  executeTools,
+  fetchSessionFiles,
+  formatCompletedResponse,
+} from './ProgrammaticToolCalling';
+import { getCodeBaseURL } from './CodeExecutor';
+import { Constants } from '@/common';
+
+config();
+
+// ============================================================================
+// Constants
+// ============================================================================
+
+const DEFAULT_MAX_ROUND_TRIPS = 20;
+const DEFAULT_TIMEOUT = 60000;
+
+/** Bash reserved words that get `_tool` suffix when used as function names */
+const BASH_RESERVED = new Set([
+  'if',
+  'then',
+  'else',
+  'elif',
+  'fi',
+  'case',
+  'esac',
+  'for',
+  'while',
+  'until',
+  'do',
+  'done',
+  'in',
+  'function',
+  'select',
+  'time',
+  'coproc',
+  'declare',
+  'typeset',
+  'local',
+  'readonly',
+  'export',
+  'unset',
+]);
+
+// ============================================================================
+// Description Components
+// ============================================================================
+
+const STATELESS_WARNING = `CRITICAL - STATELESS EXECUTION:
+Each call is a fresh bash shell. Variables and state do NOT persist between calls.
+You MUST complete your entire workflow in ONE code block.
+DO NOT split work across multiple calls expecting to reuse variables.`;
+
+const CORE_RULES = `Rules:
+- EVERYTHING in one call—no state persists between executions
+- Tools are pre-defined as bash functions—DO NOT redefine them
+- Each tool function accepts a JSON string argument
+- Only echo/printf output returns to the model
+- Generated files are automatically available in /mnt/data/ for subsequent executions`;
+
+const ADDITIONAL_RULES =
+  '- Tool names normalized: hyphens→underscores, reserved words get `_tool` suffix';
+
+const EXAMPLES = `Example (Complete workflow in one call):
+  # Query data and process
+  data=$(query_database '{"sql": "SELECT * FROM users"}')
+  echo "$data" | jq '.[] | .name'
+
+Example (Parallel calls):
+  web_search '{"query": "SF weather"}' > /tmp/sf.txt &
+  web_search '{"query": "NY weather"}' > /tmp/ny.txt &
+  wait
+  echo "SF: $(cat /tmp/sf.txt)"
+  echo "NY: $(cat /tmp/ny.txt)"`;
+
+const CODE_PARAM_DESCRIPTION = `Bash code that calls tools programmatically. Tools are available as bash functions.
+
+${STATELESS_WARNING}
+
+Each tool function accepts a JSON string as its argument.
+Example: tool_name '{"key": "value"}'
+
+${EXAMPLES}
+
+${CORE_RULES}`;
+
+// ============================================================================
+// Schema
+// ============================================================================
+
+export const BashProgrammaticToolCallingSchema = {
+  type: 'object',
+  properties: {
+    code: {
+      type: 'string',
+      minLength: 1,
+      description: CODE_PARAM_DESCRIPTION,
+    },
+    timeout: {
+      type: 'integer',
+      minimum: 1000,
+      maximum: 300000,
+      default: DEFAULT_TIMEOUT,
+      description:
+        'Maximum execution time in milliseconds. Default: 60 seconds. Max: 5 minutes.',
+    },
+  },
+  required: ['code'],
+} as const;
+
+export const BashProgrammaticToolCallingName =
+  Constants.BASH_PROGRAMMATIC_TOOL_CALLING;
+
+export const BashProgrammaticToolCallingDescription = `
+Run tools via bash code. Tools are available as bash functions that accept JSON string arguments.
+
+${STATELESS_WARNING}
+
+${CORE_RULES}
+${ADDITIONAL_RULES}
+
+When to use: shell pipelines, parallel execution (& and wait), file processing, text manipulation.
+
+${EXAMPLES}
+`.trim();
+
+export const BashProgrammaticToolCallingDefinition = {
+  name: BashProgrammaticToolCallingName,
+  description: BashProgrammaticToolCallingDescription,
+  schema: BashProgrammaticToolCallingSchema,
+} as const;
+
+// ============================================================================
+// Helper Functions
+// ============================================================================
+
+/**
+ * Normalizes a tool name to a valid bash function identifier.
+ * 1. Replace hyphens, spaces, dots with underscores
+ * 2. Remove any other invalid characters
+ * 3. Prefix with underscore if starts with number
+ * 4. Append `_tool` if it's a bash reserved word
+ */
+export function normalizeToBashIdentifier(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 (BASH_RESERVED.has(normalized)) {
+    normalized = normalized + '_tool';
+  }
+
+  return normalized;
+}
+
+/**
+ * Extracts tool names that are actually called in the bash code.
+ * Bash functions are invoked as commands (no parentheses), so we match
+ * the normalized name as a word boundary.
+ */
+export function extractUsedBashToolNames(
+  code: string,
+  toolNameMap: Map<string, string>
+): Set<string> {
+  const usedTools = new Set<string>();
+
+  for (const [bashName, originalName] of toolNameMap) {
+    const escapedName = bashName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const pattern = new RegExp(`\\b${escapedName}\\b`, 'g');
+
+    if (pattern.test(code)) {
+      usedTools.add(originalName);
+    }
+  }
+
+  return usedTools;
+}
+
+/**
+ * Filters tool definitions to only include tools actually used in the bash code.
+ */
+export function filterBashToolsByUsage(
+  toolDefs: t.LCTool[],
+  code: string,
+  debug = false
+): t.LCTool[] {
+  const toolNameMap = new Map<string, string>();
+  for (const def of toolDefs) {
+    const bashName = normalizeToBashIdentifier(def.name);
+    toolNameMap.set(bashName, def.name);
+  }
+
+  const usedToolNames = extractUsedBashToolNames(code, toolNameMap);
+
+  if (debug) {
+    // eslint-disable-next-line no-console
+    console.log(
+      `[BashPTC Debug] Tool filtering: found ${usedToolNames.size}/${toolDefs.length} tools in code`
+    );
+    if (usedToolNames.size > 0) {
+      // eslint-disable-next-line no-console
+      console.log(
+        `[BashPTC Debug] Matched tools: ${Array.from(usedToolNames).join(', ')}`
+      );
+    }
+  }
+
+  if (usedToolNames.size === 0) {
+    if (debug) {
+      // eslint-disable-next-line no-console
+      console.log(
+        '[BashPTC Debug] No tools detected in code - sending all tools as fallback'
+      );
+    }
+    return toolDefs;
+  }
+
+  return toolDefs.filter((def) => usedToolNames.has(def.name));
+}
+
+// ============================================================================
+// Tool Factory
+// ============================================================================
+
+/**
+ * Creates a Bash Programmatic Tool Calling tool for multi-tool orchestration.
+ *
+ * This tool enables AI agents to write bash scripts that orchestrate multiple
+ * tool calls programmatically via the remote Code API, reducing LLM round-trips.
+ *
+ * The tool map must be provided at runtime via config.toolCall (injected by ToolNode).
+ */
+export function createBashProgrammaticToolCallingTool(
+  initParams: t.BashProgrammaticToolCallingParams = {}
+): DynamicStructuredTool {
+  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.BASH_PTC_DEBUG === 'true';
+  const EXEC_ENDPOINT = `${baseUrl}/exec/programmatic`;
+
+  return tool(
+    async (rawParams, config) => {
+      const params = rawParams as { code: string; timeout?: number };
+      const { code, timeout = DEFAULT_TIMEOUT } = params;
+
+      const { toolMap, toolDefs, session_id, _injected_files } =
+        (config.toolCall ?? {}) as ToolCall &
+          Partial<t.ProgrammaticCache> & {
+            session_id?: string;
+            _injected_files?: t.CodeEnvFile[];
+          };
+
+      if (toolMap == null || toolMap.size === 0) {
+        throw new Error(
+          'No toolMap provided. ' +
+            'ToolNode should inject this from AgentContext when invoked through the graph.'
+        );
+      }
+
+      if (toolDefs == null || toolDefs.length === 0) {
+        throw new Error(
+          'No tool definitions provided. ' +
+            'Either pass tools in the input or ensure ToolNode injects toolDefs.'
+        );
+      }
+
+      let roundTrip = 0;
+
+      try {
+        // ====================================================================
+        // Phase 1: Filter tools and make initial request
+        // ====================================================================
+
+        const effectiveTools = filterBashToolsByUsage(toolDefs, code, debug);
+
+        if (debug) {
+          // eslint-disable-next-line no-console
+          console.log(
+            `[BashPTC Debug] Sending ${effectiveTools.length} tools to API ` +
+              `(filtered from ${toolDefs.length})`
+          );
+        }
+
+        let files: t.CodeEnvFile[] | undefined;
+        if (_injected_files && _injected_files.length > 0) {
+          files = _injected_files;
+        } else if (session_id != null && session_id.length > 0) {
+          files = await fetchSessionFiles(baseUrl, session_id, proxy);
+        }
+
+        let response = await makeRequest(
+          EXEC_ENDPOINT,
+          {
+            lang: 'bash',
+            code,
+            tools: effectiveTools,
+            session_id,
+            timeout,
+            ...(files && files.length > 0 ? { files } : {}),
+          },
+          proxy
+        );
+
+        // ====================================================================
+        // Phase 2: Handle response loop
+        // ====================================================================
+
+        while (response.status === 'tool_call_required') {
+          roundTrip++;
+
+          if (roundTrip > maxRoundTrips) {
+            throw new Error(
+              `Exceeded maximum round trips (${maxRoundTrips}). ` +
+                'This may indicate an infinite loop, excessive tool calls, ' +
+                'or a logic error in your code.'
+            );
+          }
+
+          if (debug) {
+            // eslint-disable-next-line no-console
+            console.log(
+              `[BashPTC 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,
+            {
+              continuation_token: response.continuation_token,
+              tool_results: toolResults,
+            },
+            proxy
+          );
+        }
+
+        // ====================================================================
+        // Phase 3: Handle final state
+        // ====================================================================
+
+        if (response.status === 'completed') {
+          return formatCompletedResponse(response);
+        }
+
+        if (response.status === 'error') {
+          throw new Error(
+            `Execution error: ${response.error}` +
+              (response.stderr != null && response.stderr !== ''
+                ? `\n\nStderr:\n${response.stderr}`
+                : '')
+          );
+        }
+
+        throw new Error(`Unexpected response status: ${response.status}`);
+      } catch (error) {
+        throw new Error(
+          `Bash programmatic execution failed: ${(error as Error).message}`
+        );
+      }
+    },
+    {
+      name: Constants.BASH_PROGRAMMATIC_TOOL_CALLING,
+      description: BashProgrammaticToolCallingDescription,
+      schema: BashProgrammaticToolCallingSchema,
+      responseFormat: Constants.CONTENT_AND_ARTIFACT,
+    }
+  );
+}

package/src/tools/CodeExecutor.ts

@@ -95,15 +95,6 @@ export const CodeExecutionToolDefinition = {
 function createCodeExecutionTool(
   params: t.CodeExecutionToolParams = {}
 ): DynamicStructuredTool {
-  const apiKey =
-    params[EnvVar.CODE_API_KEY] ??
-    params.apiKey ??
-    getEnvironmentVariable(EnvVar.CODE_API_KEY) ??
-    '';
-  if (!apiKey) {
-    throw new Error('No API key provided for code execution tool.');
-  }
-
   return tool(
     async (rawInput, config) => {
       const { lang, code, ...rest } = rawInput as {
@@ -143,7 +134,6 @@ function createCodeExecutionTool(
             method: 'GET',
             headers: {
               'User-Agent': 'LibreChat/1.0',
-              'X-API-Key': apiKey,
             },
           };
 
@@ -185,7 +175,6 @@ function createCodeExecutionTool(
           headers: {
             'Content-Type': 'application/json',
             'User-Agent': 'LibreChat/1.0',
-            'X-API-Key': apiKey,
           },
           body: JSON.stringify(postData),
         };

package/src/tools/ProgrammaticToolCalling.ts

@@ -2,12 +2,11 @@
 import { config } from 'dotenv';
 import fetch, { RequestInit } from 'node-fetch';
 import { HttpsProxyAgent } from 'https-proxy-agent';
-import { getEnvironmentVariable } from '@langchain/core/utils/env';
 import { tool, DynamicStructuredTool } from '@langchain/core/tools';
 import type { ToolCall } from '@langchain/core/messages/tool';
 import type * as t from '@/types';
 import { imageExtRegex, getCodeBaseURL } from './CodeExecutor';
-import { EnvVar, Constants } from '@/common';
+import { Constants } from '@/common';
 
 config();
 
@@ -261,14 +260,12 @@ export function filterToolsByUsage(
  * Fetches files from a previous session to make them available for the current execution.
  * Files are returned as CodeEnvFile references to be included in the request.
  * @param baseUrl - The base URL for the Code API
- * @param apiKey - The API key for authentication
  * @param sessionId - The session ID to fetch files from
  * @param proxy - Optional HTTP proxy URL
  * @returns Array of CodeEnvFile references, or empty array if fetch fails
  */
 export async function fetchSessionFiles(
   baseUrl: string,
-  apiKey: string,
   sessionId: string,
   proxy?: string
 ): Promise<t.CodeEnvFile[]> {
@@ -278,7 +275,6 @@ export async function fetchSessionFiles(
       method: 'GET',
       headers: {
         'User-Agent': 'LibreChat/1.0',
-        'X-API-Key': apiKey,
       },
     };
 
@@ -321,14 +317,12 @@ export async function fetchSessionFiles(
 /**
  * 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 async function makeRequest(
   endpoint: string,
-  apiKey: string,
   body: Record<string, unknown>,
   proxy?: string
 ): Promise<t.ProgrammaticExecutionResponse> {
@@ -337,7 +331,6 @@ export async function makeRequest(
     headers: {
       'Content-Type': 'application/json',
       'User-Agent': 'LibreChat/1.0',
-      'X-API-Key': apiKey,
     },
     body: JSON.stringify(body),
   };
@@ -596,14 +589,11 @@ export function formatCompletedResponse(
  *
  * The tool map must be provided at runtime via config.configurable.toolMap.
  *
- * @param params - Configuration parameters (apiKey, baseUrl, maxRoundTrips, proxy)
+ * @param params - Configuration parameters (baseUrl, maxRoundTrips, proxy)
  * @returns A LangChain DynamicStructuredTool for programmatic tool calling
  *
  * @example
- * const ptcTool = createProgrammaticToolCallingTool({
- *   apiKey: process.env.CODE_API_KEY,
- *   maxRoundTrips: 20
- * });
+ * const ptcTool = createProgrammaticToolCallingTool({ maxRoundTrips: 20 });
  *
  * const [output, artifact] = await ptcTool.invoke(
  *   { code, tools },
@@ -613,19 +603,6 @@ export function formatCompletedResponse(
 export function createProgrammaticToolCallingTool(
   initParams: t.ProgrammaticToolCallingParams = {}
 ): DynamicStructuredTool {
-  const apiKey =
-    (initParams[EnvVar.CODE_API_KEY] as string | undefined) ??
-    initParams.apiKey ??
-    getEnvironmentVariable(EnvVar.CODE_API_KEY) ??
-    '';
-
-  if (!apiKey) {
-    throw new Error(
-      'No API key provided for programmatic tool calling. ' +
-        'Set CODE_API_KEY environment variable or pass apiKey in initParams.'
-    );
-  }
-
   const baseUrl = initParams.baseUrl ?? getCodeBaseURL();
   const maxRoundTrips = initParams.maxRoundTrips ?? DEFAULT_MAX_ROUND_TRIPS;
   const proxy = initParams.proxy ?? process.env.PROXY;
@@ -685,12 +662,11 @@ export function createProgrammaticToolCallingTool(
         if (_injected_files && _injected_files.length > 0) {
           files = _injected_files;
         } else if (session_id != null && session_id.length > 0) {
-          files = await fetchSessionFiles(baseUrl, apiKey, session_id, proxy);
+          files = await fetchSessionFiles(baseUrl, session_id, proxy);
         }
 
         let response = await makeRequest(
           EXEC_ENDPOINT,
-          apiKey,
           {
             code,
             tools: effectiveTools,
@@ -730,7 +706,6 @@ export function createProgrammaticToolCallingTool(
 
           response = await makeRequest(
             EXEC_ENDPOINT,
-            apiKey,
             {
               continuation_token: response.continuation_token,
               tool_results: toolResults,

package/src/tools/ReadFile.ts

@@ -0,0 +1,39 @@
+// src/tools/ReadFile.ts
+import { Constants } from '@/common';
+
+export const ReadFileToolName = Constants.READ_FILE;
+
+export const ReadFileToolDescription = `Read the contents of a file. Returns text content with line numbers for easy reference.
+
+For skill files, use the path format: {skillName}/{filePath} (e.g. "pdf-analyzer/src/utils.py", "code-review/SKILL.md").
+
+BEHAVIOR:
+- Text files: returned with numbered lines.
+- Images (png, jpeg, gif, webp): returned as visual content the model can see.
+- PDFs: returned as document content.
+- Other binary files: metadata returned with a note to use bash for processing.
+- Large files (>256KB text, >10MB binary): metadata only.
+- SKILL.md: returns the skill's instructions directly.
+
+CONSTRAINTS:
+- Only files from invoked skills or code execution output are accessible.
+- Do not guess file paths. Use paths from the skill documentation or tool output.`;
+
+export const ReadFileToolSchema = {
+  type: 'object',
+  properties: {
+    file_path: {
+      type: 'string',
+      description:
+        'Path to the file. For skill files: "{skillName}/{path}" (e.g. "pdf-analyzer/src/utils.py"). For code execution output: the path as returned by the execution tool.',
+    },
+  },
+  required: ['file_path'],
+} as const;
+
+export const ReadFileToolDefinition = {
+  name: ReadFileToolName,
+  description: ReadFileToolDescription,
+  parameters: ReadFileToolSchema,
+  responseFormat: 'content_and_artifact' as const,
+} as const;

package/src/tools/SkillTool.ts

@@ -0,0 +1,46 @@
+// src/tools/SkillTool.ts
+import { Constants } from '@/common';
+
+export const SkillToolName = Constants.SKILL_TOOL;
+
+export const SkillToolDescription = `Invoke a skill from the user's library. Skills provide domain-specific instructions loaded into the conversation context, and may also provide files accessible via available tools depending on the runtime environment.
+
+WHEN TO USE:
+- The user's request matches a skill listed in the "Available Skills" section of the system prompt.
+- You MUST invoke the matching skill BEFORE attempting the task yourself.
+
+WHAT HAPPENS:
+- The skill's full instructions are loaded into the conversation as context.
+- Files bundled with the skill may become accessible via available tools.
+- Follow the skill's instructions to complete the task.
+
+CONSTRAINTS:
+- Do not invoke a skill that is already active in this conversation.
+- Skill names come from the catalog only. Do not guess names.`;
+
+/**
+ * JSON Schema for the SkillTool parameters.
+ * Single source of truth used by both SkillToolDefinition (LCTool registry)
+ * and createSkillTool() (DynamicStructuredTool instance).
+ */
+export const SkillToolSchema = {
+  type: 'object',
+  properties: {
+    skillName: {
+      type: 'string',
+      description:
+        'The kebab-case identifier of the skill to invoke (e.g. "financial-analyzer", "meeting-notes"). Must match a name from the "Available Skills" section.',
+    },
+    args: {
+      type: 'string',
+      description: 'Optional freeform arguments string passed to the skill.',
+    },
+  },
+  required: ['skillName'],
+} as const;
+
+export const SkillToolDefinition = {
+  name: SkillToolName,
+  description: SkillToolDescription,
+  parameters: SkillToolSchema,
+} as const;