@librechat/agents 3.0.74 → 3.0.76

package/src/tools/CodeExecutor.ts

@@ -17,7 +17,7 @@ export const getCodeBaseURL = (): string =>
 const imageMessage = 'Image is already displayed to the user';
 const otherMessage = 'File is already downloaded by the user';
 const accessMessage =
-  '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).';
+  'Note: Files from previous executions are automatically available and can be modified.';
 const emptyOutputMessage =
   'stdout: Empty. Ensure you\'re writing output explicitly.\n';
 
@@ -41,7 +41,8 @@ const CodeExecutionToolSchema = z.object({
   code: z.string()
     .describe(`The complete, self-contained code to execute, without any truncation or minimization.
 - The environment is stateless; variables and imports don't persist between executions.
-- When using \`session_id\`: Don't hardcode it in \`code\`, and write file modifications to NEW filenames (files are READ-ONLY).
+- 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.
@@ -50,17 +51,6 @@ const CodeExecutionToolSchema = z.object({
 - js: use the \`console\` or \`process\` methods for all outputs.
 - r: IMPORTANT: No X11 display available. ALL graphics MUST use Cairo library (library(Cairo)).
 - Other languages: use appropriate output functions.`),
-  session_id: z
-    .string()
-    .optional()
-    .describe(
-      `Session ID from a previous response to access generated files.
-- Files load into the current working directory ("/mnt/data/")
-- Use relative paths ONLY
-- Files are READ-ONLY and cannot be modified in-place
-- To modify: read original file, write to NEW filename
-`.trim()
-    ),
   args: z
     .array(z.string())
     .optional()
@@ -94,15 +84,33 @@ Usage:
 `.trim();
 
   return tool<typeof CodeExecutionToolSchema>(
-    async ({ lang, code, session_id, ...rest }) => {
-      const postData = {
+    async ({ lang, code, ...rest }, config) => {
+      /**
+       * Extract session context from config.toolCall (injected by ToolNode).
+       * - session_id: For API to associate with previous session
+       * - _injected_files: File refs to pass directly (avoids /files endpoint race condition)
+       */
+      const { session_id, _injected_files } = (config.toolCall ?? {}) as {
+        session_id?: string;
+        _injected_files?: t.CodeEnvFile[];
+      };
+
+      const postData: Record<string, unknown> = {
         lang,
         code,
         ...rest,
         ...params,
       };
 
-      if (session_id != null && session_id.length > 0) {
+      /**
+       * File injection priority:
+       * 1. Use _injected_files from ToolNode (avoids /files endpoint race condition)
+       * 2. Fall back to fetching from /files endpoint if session_id provided but no injected files
+       */
+      if (_injected_files && _injected_files.length > 0) {
+        postData.files = _injected_files;
+      } else if (session_id != null && session_id.length > 0) {
+        /** Fallback: fetch from /files endpoint (may have race condition issues) */
         try {
           const filesEndpoint = `${baseEndpoint}/files/${session_id}?detail=full`;
           const fetchOptions: RequestInit = {
@@ -127,7 +135,6 @@ Usage:
           const files = await response.json();
           if (Array.isArray(files) && files.length > 0) {
             const fileReferences: t.CodeEnvFile[] = files.map((file) => {
-              // Extract the ID from the file name (part after session ID prefix and before extension)
               const nameParts = file.name.split('/');
               const id = nameParts.length > 1 ? nameParts[1].split('.')[0] : '';
 
@@ -138,11 +145,7 @@ Usage:
               };
             });
 
-            if (!postData.files) {
-              postData.files = fileReferences;
-            } else if (Array.isArray(postData.files)) {
-              postData.files = [...postData.files, ...fileReferences];
-            }
+            postData.files = fileReferences;
           }
         } catch {
           // eslint-disable-next-line no-console
@@ -191,7 +194,7 @@ Usage:
             }
           }
 
-          formattedOutput += `\nsession_id: ${result.session_id}\n\n${accessMessage}`;
+          formattedOutput += `\n\n${accessMessage}`;
           return [
             formattedOutput.trim(),
             {

package/src/tools/ProgrammaticToolCalling.ts

@@ -19,7 +19,7 @@ config();
 const imageMessage = 'Image is already displayed to the user';
 const otherMessage = 'File is already downloaded by the user';
 const accessMessage =
-  '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).';
+  'Note: Files from previous executions are automatically available and can be modified.';
 const emptyOutputMessage =
   'stdout: Empty. Ensure you\'re writing output explicitly.\n';
 
@@ -68,12 +68,6 @@ Rules:
 - Tools are pre-defined—DO NOT write function definitions
 - Only print() output returns to the model`
     ),
-  session_id: z
-    .string()
-    .optional()
-    .describe(
-      'Session ID for file access (same as regular code execution). Files load into /mnt/data/ and are READ-ONLY.'
-    ),
   timeout: z
     .number()
     .int()
@@ -542,7 +536,7 @@ export function formatCompletedResponse(
       }
     }
 
-    formatted += `\nsession_id: ${response.session_id}\n\n${accessMessage}`;
+    formatted += `\n\n${accessMessage}`;
   }
 
   return [
@@ -613,7 +607,7 @@ Rules:
 - Do NOT define \`async def main()\` or call \`asyncio.run()\`—just write code with await
 - Tools are pre-defined—DO NOT write function definitions
 - Only \`print()\` output returns; tool results are raw dicts/lists/strings
-- Use \`session_id\` param for file persistence across calls
+- Generated files are automatically available in /mnt/data/ for subsequent executions
 - Tool names normalized: hyphens→underscores, keywords get \`_tool\` suffix
 
 When to use: loops, conditionals, parallel (\`asyncio.gather\`), multi-step pipelines.
@@ -624,11 +618,15 @@ Example (complete pipeline):
 
   return tool<typeof ProgrammaticToolCallingSchema>(
     async (params, config) => {
-      const { code, session_id, timeout = DEFAULT_TIMEOUT } = params;
+      const { code, timeout = DEFAULT_TIMEOUT } = params;
 
       // Extra params injected by ToolNode (follows web_search pattern)
-      const { toolMap, toolDefs } = (config.toolCall ?? {}) as ToolCall &
-        Partial<t.ProgrammaticCache>;
+      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(
@@ -661,9 +659,15 @@ Example (complete pipeline):
           );
         }
 
-        // Fetch files from previous session if session_id is provided
+        /**
+         * File injection priority:
+         * 1. Use _injected_files from ToolNode (avoids /files endpoint race condition)
+         * 2. Fall back to fetching from /files endpoint if session_id provided but no injected files
+         */
         let files: t.CodeEnvFile[] | undefined;
-        if (session_id != null && session_id.length > 0) {
+        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);
         }
 

package/src/tools/ToolNode.ts

@@ -42,6 +42,8 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
   private toolRegistry?: t.LCToolRegistry;
   /** Cached programmatic tools (computed once on first PTC call) */
   private programmaticCache?: t.ProgrammaticCache;
+  /** Reference to Graph's sessions map for automatic session injection */
+  private sessions?: t.ToolSessionMap;
 
   constructor({
     tools,
@@ -53,6 +55,7 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
     handleToolErrors,
     loadRuntimeTools,
     toolRegistry,
+    sessions,
   }: t.ToolNodeConstructorParams) {
     super({ name, tags, func: (input, config) => this.run(input, config) });
     this.toolMap = toolMap ?? new Map(tools.map((tool) => [tool.name, tool]));
@@ -62,6 +65,7 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
     this.errorHandler = errorHandler;
     this.toolUsageCount = new Map<string, number>();
     this.toolRegistry = toolRegistry;
+    this.sessions = sessions;
   }
 
   /**
@@ -139,6 +143,35 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
         };
       }
 
+      /**
+       * Inject session context for code execution tools when available.
+       * Both session_id and _injected_files are injected directly to invokeParams
+       * (not inside args) so they bypass Zod schema validation and reach config.toolCall.
+       * This avoids /files endpoint race conditions.
+       */
+      if (
+        call.name === Constants.EXECUTE_CODE ||
+        call.name === Constants.PROGRAMMATIC_TOOL_CALLING
+      ) {
+        const codeSession = this.sessions?.get(Constants.EXECUTE_CODE) as
+          | t.CodeSessionContext
+          | undefined;
+        if (codeSession?.session_id != null && codeSession.files.length > 0) {
+          /** Convert tracked files to CodeEnvFile format for the API */
+          const fileRefs: t.CodeEnvFile[] = codeSession.files.map((file) => ({
+            session_id: codeSession.session_id,
+            id: file.id,
+            name: file.name,
+          }));
+          /** Inject session_id and files directly - bypasses Zod, reaches config.toolCall */
+          invokeParams = {
+            ...invokeParams,
+            session_id: codeSession.session_id,
+            _injected_files: fileRefs,
+          };
+        }
+      }
+
       const output = await tool.invoke(invokeParams, config);
       if (
         (isBaseMessage(output) && output._getType() === 'tool') ||

package/src/tools/ToolSearch.ts

@@ -303,13 +303,14 @@ function simplifyParametersForSearch(
 
 /**
  * Tokenizes a string into lowercase words for BM25.
+ * Splits on underscores and non-alphanumeric characters for consistent matching.
  * @param text - The text to tokenize
  * @returns Array of lowercase tokens
  */
 function tokenize(text: string): string[] {
   return text
     .toLowerCase()
-    .replace(/[^a-z0-9_]/g, ' ')
+    .replace(/[^a-z0-9]/g, ' ')
     .split(/\s+/)
     .filter((token) => token.length > 0);
 }
@@ -426,6 +427,7 @@ function performLocalSearch(
   const scores = BM25(documents, queryTokens, { k1: 1.5, b: 0.75 }) as number[];
 
   const maxScore = Math.max(...scores.filter((s) => s > 0), 1);
+  const queryLower = query.toLowerCase().trim();
 
   const results: t.ToolSearchResult[] = [];
   for (let i = 0; i < tools.length; i++) {
@@ -435,7 +437,15 @@ function performLocalSearch(
         queryTokens,
         fields
       );
-      const normalizedScore = Math.min(scores[i] / maxScore, 1.0);
+      let normalizedScore = Math.min(scores[i] / maxScore, 1.0);
+
+      // Boost score for exact base name match
+      const baseName = getBaseToolName(tools[i].name).toLowerCase();
+      if (baseName === queryLower) {
+        normalizedScore = 1.0;
+      } else if (baseName.startsWith(queryLower)) {
+        normalizedScore = Math.max(normalizedScore, 0.95);
+      }
 
       results.push({
         tool_name: tools[i].name,

package/src/tools/__tests__/ProgrammaticToolCalling.test.ts

@@ -643,7 +643,6 @@ for member in team:
       expect(output).toContain('Generated files:');
       expect(output).toContain('report.pdf');
       expect(output).toContain('data.csv');
-      expect(output).toContain('session_id: sess_abc123');
       expect(artifact.files).toHaveLength(2);
       expect(artifact.files).toEqual(response.files);
     });
@@ -881,7 +880,6 @@ for member in team:
       expect(output).toContain('Generated files:');
       expect(output).toContain('report.csv');
       expect(output).toContain('chart.png');
-      expect(output).toContain('session_id: sess_xyz');
       expect(output).toContain('File is already downloaded');
       expect(output).toContain('Image is already displayed');
       expect(artifact.files).toHaveLength(2);

package/src/tools/__tests__/ToolSearch.test.ts

@@ -806,6 +806,90 @@ describe('ToolSearch', () => {
         'get_weather'
       );
     });
+
+    it('finds tools when query contains underscores', () => {
+      // Underscores in query should be tokenized the same as in tool names
+      const tools: ToolMetadata[] = [
+        {
+          name: 'convert_time_mcp_time',
+          description: 'Convert time between timezones',
+          parameters: undefined,
+        },
+      ];
+
+      const result = performLocalSearch(tools, 'convert_time', ['name'], 10);
+
+      expect(result.tool_references.length).toBe(1);
+      expect(result.tool_references[0].tool_name).toBe('convert_time_mcp_time');
+      expect(result.tool_references[0].match_score).toBeGreaterThan(0.5);
+    });
+
+    it('finds tools with partial underscore query', () => {
+      const tools: ToolMetadata[] = [
+        {
+          name: 'get_current_time_mcp_time',
+          description: 'Get current time',
+          parameters: undefined,
+        },
+        {
+          name: 'convert_time_mcp_time',
+          description: 'Convert time between timezones',
+          parameters: undefined,
+        },
+      ];
+
+      // "current_time" should match "get_current_time_mcp_time"
+      const result = performLocalSearch(tools, 'current_time', ['name'], 10);
+
+      expect(result.tool_references.length).toBeGreaterThan(0);
+      expect(result.tool_references[0].tool_name).toBe(
+        'get_current_time_mcp_time'
+      );
+    });
+
+    it('gives exact base name match a perfect score', () => {
+      const tools: ToolMetadata[] = [
+        {
+          name: 'convert_time_mcp_time',
+          description: 'Convert time between timezones',
+          parameters: undefined,
+        },
+        {
+          name: 'get_current_time_mcp_time',
+          description: 'Get current time',
+          parameters: undefined,
+        },
+      ];
+
+      // Exact match on base name should get score of 1.0
+      const result = performLocalSearch(tools, 'convert_time', ['name'], 10);
+
+      expect(result.tool_references[0].tool_name).toBe('convert_time_mcp_time');
+      expect(result.tool_references[0].match_score).toBe(1.0);
+    });
+
+    it('boosts starts-with matches on base name', () => {
+      const tools: ToolMetadata[] = [
+        {
+          name: 'send_email_mcp_gmail',
+          description: 'Send email',
+          parameters: undefined,
+        },
+        {
+          name: 'read_email_mcp_gmail',
+          description: 'Read email',
+          parameters: undefined,
+        },
+      ];
+
+      // "send" starts-with "send_email", should get boosted score
+      const result = performLocalSearch(tools, 'send', ['name'], 10);
+
+      expect(result.tool_references[0].tool_name).toBe('send_email_mcp_gmail');
+      expect(result.tool_references[0].match_score).toBeGreaterThanOrEqual(
+        0.95
+      );
+    });
   });
 
   describe('formatServerListing', () => {

package/src/types/tools.ts

@@ -39,6 +39,8 @@ export type ToolNodeOptions = {
   ) => Promise<void>;
   /** Tool registry for lazy computation of programmatic tools and tool search */
   toolRegistry?: LCToolRegistry;
+  /** Reference to Graph's sessions map for automatic session injection */
+  sessions?: ToolSessionMap;
 };
 
 export type ToolNodeConstructorParams = ToolRefs & ToolNodeOptions;
@@ -253,3 +255,41 @@ export type ProgrammaticToolCallingParams = {
   /** Environment variable key for API key */
   [key: string]: unknown;
 };
+
+// ============================================================================
+// Tool Session Context Types
+// ============================================================================
+
+/**
+ * Tracks code execution session state for automatic file persistence.
+ * Stored in Graph.sessions and injected into subsequent tool invocations.
+ */
+export type CodeSessionContext = {
+  /** Session ID from the code execution environment */
+  session_id: string;
+  /** Files generated in this session (for context/tracking) */
+  files: FileRefs;
+  /** Timestamp of last update */
+  lastUpdated: number;
+};
+
+/**
+ * Artifact structure returned by code execution tools (CodeExecutor, PTC).
+ * Used to extract session context after tool completion.
+ */
+export type CodeExecutionArtifact = {
+  session_id?: string;
+  files?: FileRefs;
+};
+
+/**
+ * Generic session context union type for different tool types.
+ * Extend this as new tool session types are added.
+ */
+export type ToolSessionContext = CodeSessionContext;
+
+/**
+ * Map of tool names to their session contexts.
+ * Keys are tool constants (e.g., Constants.EXECUTE_CODE, Constants.PROGRAMMATIC_TOOL_CALLING).
+ */
+export type ToolSessionMap = Map<string, ToolSessionContext>;