@librechat/agents 3.1.67-dev.4 → 3.1.68

package/src/tools/BashExecutor.ts

@@ -1,205 +0,0 @@
-import { config } from 'dotenv';
-import fetch, { RequestInit } from 'node-fetch';
-import { HttpsProxyAgent } from 'https-proxy-agent';
-import { tool, DynamicStructuredTool } from '@langchain/core/tools';
-import { getEnvironmentVariable } from '@langchain/core/utils/env';
-import type * as t from '@/types';
-import { imageExtRegex, getCodeBaseURL } from './CodeExecutor';
-import { EnvVar, Constants } from '@/common';
-
-config();
-
-const imageMessage = 'Image is already displayed to the user';
-const otherMessage = 'File is already downloaded by the user';
-const accessMessage =
-  'Note: Files from previous executions are automatically available and can be modified.';
-const emptyOutputMessage =
-  'stdout: Empty. Ensure you\'re writing output explicitly.\n';
-
-const baseEndpoint = getCodeBaseURL();
-const EXEC_ENDPOINT = `${baseEndpoint}/exec`;
-
-export const BashExecutionToolSchema = {
-  type: 'object',
-  properties: {
-    command: {
-      type: 'string',
-      description: `The bash command or script to execute.
-- The environment is stateless; variables and state don't persist between executions.
-- Generated files from previous executions are automatically available in "/mnt/data/".
-- Files from previous executions are automatically available and can be modified in place.
-- Input code **IS ALREADY** displayed to the user, so **DO NOT** repeat it in your response unless asked.
-- Output code **IS NOT** displayed to the user, so **DO** write all desired output explicitly.
-- IMPORTANT: You MUST explicitly print/output ALL results you want the user to see.
-- Use \`echo\`, \`printf\`, or \`cat\` for all outputs.`,
-    },
-    args: {
-      type: 'array',
-      items: { type: 'string' },
-      description:
-        'Additional arguments to execute the command with. This should only be used if the input command requires additional arguments to run.',
-    },
-  },
-  required: ['command'],
-} as const;
-
-export const BashExecutionToolDescription = `
-Runs bash commands and returns stdout/stderr output from a stateless execution environment, similar to running scripts in a command-line interface. Each execution is isolated and independent.
-
-Usage:
-- No network access available.
-- Generated files are automatically delivered; **DO NOT** provide download links.
-- NEVER use this tool to execute malicious commands.
-`.trim();
-
-export const BashExecutionToolName = Constants.BASH_TOOL;
-
-export const BashExecutionToolDefinition = {
-  name: BashExecutionToolName,
-  description: BashExecutionToolDescription,
-  schema: BashExecutionToolSchema,
-} as const;
-
-function createBashExecutionTool(
-  params: t.BashExecutionToolParams = {}
-): 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 bash execution tool.');
-  }
-
-  return tool(
-    async (rawInput, config) => {
-      const { command, ...rest } = rawInput as {
-        command: string;
-        args?: string[];
-      };
-      const { session_id, _injected_files } = (config.toolCall ?? {}) as {
-        session_id?: string;
-        _injected_files?: t.CodeEnvFile[];
-      };
-
-      const postData: Record<string, unknown> = {
-        lang: 'bash',
-        code: command,
-        ...rest,
-        ...params,
-      };
-
-      if (_injected_files && _injected_files.length > 0) {
-        postData.files = _injected_files;
-      } else if (session_id != null && session_id.length > 0) {
-        try {
-          const filesEndpoint = `${baseEndpoint}/files/${session_id}?detail=full`;
-          const fetchOptions: RequestInit = {
-            method: 'GET',
-            headers: {
-              'User-Agent': 'LibreChat/1.0',
-              'X-API-Key': apiKey,
-            },
-          };
-
-          if (process.env.PROXY != null && process.env.PROXY !== '') {
-            fetchOptions.agent = new HttpsProxyAgent(process.env.PROXY);
-          }
-
-          const response = await fetch(filesEndpoint, fetchOptions);
-          if (!response.ok) {
-            throw new Error(
-              `Failed to fetch files for session: ${response.status}`
-            );
-          }
-
-          const files = await response.json();
-          if (Array.isArray(files) && files.length > 0) {
-            const fileReferences: t.CodeEnvFile[] = files.map((file) => {
-              const nameParts = file.name.split('/');
-              const id = nameParts.length > 1 ? nameParts[1].split('.')[0] : '';
-
-              return {
-                session_id,
-                id,
-                name: file.metadata['original-filename'],
-              };
-            });
-
-            postData.files = fileReferences;
-          }
-        } catch {
-          // eslint-disable-next-line no-console
-          console.warn(`Failed to fetch files for session: ${session_id}`);
-        }
-      }
-
-      try {
-        const fetchOptions: RequestInit = {
-          method: 'POST',
-          headers: {
-            'Content-Type': 'application/json',
-            'User-Agent': 'LibreChat/1.0',
-            'X-API-Key': apiKey,
-          },
-          body: JSON.stringify(postData),
-        };
-
-        if (process.env.PROXY != null && process.env.PROXY !== '') {
-          fetchOptions.agent = new HttpsProxyAgent(process.env.PROXY);
-        }
-        const response = await fetch(EXEC_ENDPOINT, fetchOptions);
-        if (!response.ok) {
-          throw new Error(`HTTP error! status: ${response.status}`);
-        }
-
-        const result: t.ExecuteResult = await response.json();
-        let formattedOutput = '';
-        if (result.stdout) {
-          formattedOutput += `stdout:\n${result.stdout}\n`;
-        } else {
-          formattedOutput += emptyOutputMessage;
-        }
-        if (result.stderr) formattedOutput += `stderr:\n${result.stderr}\n`;
-        if (result.files && result.files.length > 0) {
-          formattedOutput += 'Generated files:\n';
-
-          const fileCount = result.files.length;
-          for (let i = 0; i < fileCount; i++) {
-            const file = result.files[i];
-            const isImage = imageExtRegex.test(file.name);
-            formattedOutput += `- /mnt/data/${file.name} | ${isImage ? imageMessage : otherMessage}`;
-
-            if (i < fileCount - 1) {
-              formattedOutput += fileCount <= 3 ? ', ' : ',\n';
-            }
-          }
-
-          formattedOutput += `\n\n${accessMessage}`;
-          return [
-            formattedOutput.trim(),
-            {
-              session_id: result.session_id,
-              files: result.files,
-            },
-          ];
-        }
-
-        return [formattedOutput.trim(), { session_id: result.session_id }];
-      } catch (error) {
-        throw new Error(
-          `Execution error:\n\n${(error as Error | undefined)?.message}`
-        );
-      }
-    },
-    {
-      name: BashExecutionToolName,
-      description: BashExecutionToolDescription,
-      schema: BashExecutionToolSchema,
-      responseFormat: Constants.CONTENT_AND_ARTIFACT,
-    }
-  );
-}
-
-export { createBashExecutionTool };

package/src/tools/BashProgrammaticToolCalling.ts

@@ -1,397 +0,0 @@
-import { config } from 'dotenv';
-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 {
-  makeRequest,
-  executeTools,
-  fetchSessionFiles,
-  formatCompletedResponse,
-} from './ProgrammaticToolCalling';
-import { getCodeBaseURL } from './CodeExecutor';
-import { EnvVar, 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 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 bash 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;
-  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, apiKey, session_id, proxy);
-        }
-
-        let response = await makeRequest(
-          EXEC_ENDPOINT,
-          apiKey,
-          {
-            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,
-            apiKey,
-            {
-              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/ReadFile.ts

@@ -1,39 +0,0 @@
-// 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

@@ -1,46 +0,0 @@
-// 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;