@librechat/agents 3.0.75 → 3.0.76

package/src/scripts/test_code_api.ts

@@ -0,0 +1,361 @@
+// src/scripts/test_code_api.ts
+/**
+ * Direct test of the Code API to verify session file persistence.
+ * This bypasses the LLM and tests the API directly.
+ *
+ * Run with: npx ts-node -r dotenv/config src/scripts/test_code_api.ts
+ */
+import { config } from 'dotenv';
+config();
+
+import fetch, { RequestInit } from 'node-fetch';
+import { HttpsProxyAgent } from 'https-proxy-agent';
+
+const API_KEY = process.env.LIBRECHAT_CODE_API_KEY ?? '';
+const BASE_URL =
+  process.env.LIBRECHAT_CODE_BASEURL ?? 'https://api.librechat.ai/v1';
+const PROXY = process.env.PROXY;
+
+if (!API_KEY) {
+  console.error('LIBRECHAT_CODE_API_KEY not set');
+  process.exit(1);
+}
+
+interface FileRef {
+  id: string;
+  name: string;
+  session_id?: string;
+  /** Lineage tracking - present if file was modified from previous session */
+  modified_from?: {
+    id: string;
+    session_id: string;
+  };
+}
+
+interface ExecResult {
+  session_id: string;
+  stdout: string;
+  stderr: string;
+  files?: FileRef[];
+}
+
+interface FileInfo {
+  name: string;
+  metadata: Record<string, string>;
+}
+
+async function makeRequest(
+  endpoint: string,
+  body?: Record<string, unknown>
+): Promise<unknown> {
+  const fetchOptions: RequestInit = {
+    method: body ? 'POST' : 'GET',
+    headers: {
+      'Content-Type': 'application/json',
+      'User-Agent': 'LibreChat/1.0',
+      'X-API-Key': API_KEY,
+    },
+  };
+
+  if (body) {
+    fetchOptions.body = JSON.stringify(body);
+  }
+
+  if (PROXY) {
+    fetchOptions.agent = new HttpsProxyAgent(PROXY);
+  }
+
+  console.log(`\n>>> ${body ? 'POST' : 'GET'} ${endpoint}`);
+  if (body) {
+    console.log('Body:', JSON.stringify(body, null, 2));
+  }
+
+  const response = await fetch(endpoint, fetchOptions);
+  const result = await response.json();
+
+  console.log(`<<< Response (${response.status}):`);
+  console.log(JSON.stringify(result, null, 2));
+
+  if (!response.ok) {
+    throw new Error(`HTTP ${response.status}: ${JSON.stringify(result)}`);
+  }
+
+  return result;
+}
+
+async function testCodeAPI(): Promise<void> {
+  console.log('='.repeat(60));
+  console.log('TEST 1: Create a file');
+  console.log('='.repeat(60));
+
+  const createCode = `
+import json
+
+config = {
+    "app_name": "TestApp",
+    "version": "1.0.0",
+    "debug": True
+}
+
+with open("/mnt/data/test_config.json", "w") as f:
+    json.dump(config, f, indent=2)
+
+with open("/mnt/data/test_config.json", "r") as f:
+    print(f.read())
+`;
+
+  const result1 = (await makeRequest(`${BASE_URL}/exec`, {
+    lang: 'py',
+    code: createCode,
+  })) as ExecResult;
+
+  const sessionId = result1.session_id;
+  const files = result1.files ?? [];
+
+  console.log('\n--- Result Summary ---');
+  console.log('session_id:', sessionId);
+  console.log('files:', files);
+  console.log('stdout:', result1.stdout);
+  console.log('stderr:', result1.stderr);
+
+  if (!sessionId || files.length === 0) {
+    console.error('\n❌ No session_id or files returned!');
+    return;
+  }
+
+  // Check if files now include session_id (new API feature)
+  const hasSessionIdInFiles = files.some((f) => f.session_id != null);
+  console.log('\n✅ Files include session_id:', hasSessionIdInFiles);
+
+  console.log('\n' + '='.repeat(60));
+  console.log(
+    'TEST 2: Fetch files IMMEDIATELY (no delay - testing race condition fix)'
+  );
+  console.log('='.repeat(60));
+
+  const filesResult = (await makeRequest(
+    `${BASE_URL}/files/${sessionId}?detail=full`
+  )) as FileInfo[];
+
+  console.log('\n--- Files in session (detail=full) ---');
+  for (const file of filesResult) {
+    console.log('File:', file.name);
+    console.log('  metadata:', file.metadata);
+  }
+
+  if (filesResult.length === 0) {
+    console.log(
+      '\n⚠️  Files endpoint returned empty - race condition may still exist'
+    );
+  } else {
+    console.log('\n✅ Files available immediately!');
+  }
+
+  // Test new normalized detail level
+  console.log('\n' + '='.repeat(60));
+  console.log('TEST 2b: Fetch files with detail=normalized');
+  console.log('='.repeat(60));
+
+  const normalizedResult = (await makeRequest(
+    `${BASE_URL}/files/${sessionId}?detail=normalized`
+  )) as FileRef[];
+
+  console.log('\n--- Files in session (detail=normalized) ---');
+  console.log(JSON.stringify(normalizedResult, null, 2));
+
+  console.log('\n' + '='.repeat(60));
+  console.log(
+    'TEST 3: Read file IMMEDIATELY using files from original response'
+  );
+  console.log('='.repeat(60));
+
+  // Use files directly - if API returns session_id, use that; otherwise add it
+  const fileReferences: FileRef[] = files.map((file) => ({
+    session_id: file.session_id ?? sessionId,
+    id: file.id,
+    name: file.name,
+  }));
+
+  console.log(
+    '\nFile references we will send:',
+    JSON.stringify(fileReferences, null, 2)
+  );
+
+  const readCode = `
+import json
+
+with open("/mnt/data/test_config.json", "r") as f:
+    config = json.load(f)
+    print("Read config:")
+    print(json.dumps(config, indent=2))
+    print("Version:", config.get("version"))
+`;
+
+  const result2 = (await makeRequest(`${BASE_URL}/exec`, {
+    lang: 'py',
+    code: readCode,
+    files: fileReferences,
+  })) as ExecResult;
+
+  console.log('\n--- Result Summary ---');
+  console.log('stdout:', result2.stdout);
+  console.log('stderr:', result2.stderr);
+
+  if (result2.stderr && result2.stderr.includes('FileNotFoundError')) {
+    console.log(
+      '\n❌ File not found! The file reference format might be wrong.'
+    );
+
+    // Try alternative format - just session_id
+    console.log('\n' + '='.repeat(60));
+    console.log('TEST 4: Try with just session_id in request');
+    console.log('='.repeat(60));
+
+    const result3 = (await makeRequest(`${BASE_URL}/exec`, {
+      lang: 'py',
+      code: readCode,
+      session_id: sessionId,
+    })) as ExecResult;
+
+    console.log('\n--- Result Summary ---');
+    console.log('stdout:', result3.stdout);
+    console.log('stderr:', result3.stderr);
+  } else {
+    console.log('\n✅ File read successfully!');
+  }
+
+  // ============================================================
+  // TEST 4: MODIFY the file (same filename) - tests editable files
+  // ============================================================
+  console.log('\n' + '='.repeat(60));
+  console.log('TEST 4: MODIFY file in-place (testing editable files feature)');
+  console.log('='.repeat(60));
+
+  const modifyCode = `
+import json
+
+# Read the existing file
+with open("/mnt/data/test_config.json", "r") as f:
+    config = json.load(f)
+
+print("Original config:")
+print(json.dumps(config, indent=2))
+
+# Modify the config
+config["version"] = "2.0.0"
+config["modified"] = True
+
+# Write BACK to the SAME filename (should work now!)
+with open("/mnt/data/test_config.json", "w") as f:
+    json.dump(config, f, indent=2)
+
+# Verify the write
+with open("/mnt/data/test_config.json", "r") as f:
+    updated = json.load(f)
+
+print("\\nUpdated config:")
+print(json.dumps(updated, indent=2))
+`;
+
+  const result3 = (await makeRequest(`${BASE_URL}/exec`, {
+    lang: 'py',
+    code: modifyCode,
+    files: fileReferences,
+  })) as ExecResult;
+
+  console.log('\n--- Result Summary ---');
+  console.log('stdout:', result3.stdout);
+  console.log('stderr:', result3.stderr);
+  console.log('files:', JSON.stringify(result3.files, null, 2));
+
+  if (result3.stderr && result3.stderr.includes('Permission denied')) {
+    console.log('\n❌ Permission denied - files are still read-only!');
+  } else if (result3.stderr && result3.stderr.includes('Error')) {
+    console.log('\n❌ Error modifying file:', result3.stderr);
+  } else {
+    console.log('\n✅ File modified successfully!');
+
+    // Check for modified_from lineage
+    const modifiedFile = result3.files?.find(
+      (f) => f.name === 'test_config.json'
+    );
+    if (modifiedFile) {
+      console.log('\n--- Modified File Details ---');
+      console.log('  id:', modifiedFile.id);
+      console.log('  name:', modifiedFile.name);
+      console.log('  session_id:', modifiedFile.session_id);
+      if (modifiedFile.modified_from) {
+        console.log(
+          '  modified_from:',
+          JSON.stringify(modifiedFile.modified_from)
+        );
+        console.log(
+          '\n✅ Lineage tracking working! File shows it was modified from previous session.'
+        );
+      } else {
+        console.log(
+          '\n⚠️  No modified_from field - lineage tracking not present'
+        );
+      }
+    } else {
+      console.log('\n⚠️  Modified file not found in response files array');
+    }
+  }
+
+  // ============================================================
+  // TEST 5: Verify modification persists in next execution
+  // ============================================================
+  console.log('\n' + '='.repeat(60));
+  console.log(
+    'TEST 5: Verify modified file can be read in subsequent execution'
+  );
+  console.log('='.repeat(60));
+
+  // Use the new file references from the modify response
+  const newFileRefs: FileRef[] = (result3.files ?? []).map((file) => ({
+    session_id: file.session_id ?? result3.session_id,
+    id: file.id,
+    name: file.name,
+  }));
+
+  if (newFileRefs.length === 0) {
+    console.log(
+      '\n⚠️  No files returned from modification, skipping verification'
+    );
+  } else {
+    console.log(
+      '\nUsing new file references:',
+      JSON.stringify(newFileRefs, null, 2)
+    );
+
+    const verifyCode = `
+import json
+
+with open("/mnt/data/test_config.json", "r") as f:
+    config = json.load(f)
+
+print("Verified config:")
+print(json.dumps(config, indent=2))
+
+if config.get("version") == "2.0.0" and config.get("modified") == True:
+    print("\\n✅ Modification persisted correctly!")
+else:
+    print("\\n❌ Modification did NOT persist!")
+`;
+
+    const result4 = (await makeRequest(`${BASE_URL}/exec`, {
+      lang: 'py',
+      code: verifyCode,
+      files: newFileRefs,
+    })) as ExecResult;
+
+    console.log('\n--- Result Summary ---');
+    console.log('stdout:', result4.stdout);
+    console.log('stderr:', result4.stderr);
+  }
+}
+
+testCodeAPI().catch((err) => {
+  console.error('Error:', err);
+  process.exit(1);
+});

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/__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/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>;