@librechat/agents 3.0.45 → 3.0.47

package/src/tools/ProgrammaticToolCalling.ts

@@ -72,6 +72,7 @@ Requirements:
 - Tools are pre-defined as async functions - DO NOT write function definitions
 - Use await for all tool calls
 - Use asyncio.gather() for parallel execution of independent calls
+- DO NOT call asyncio.run() - an event loop is already running
 - Only print() output flows back to the context window
 - Tool results from programmatic calls do NOT consume context tokens`
     ),
@@ -234,6 +235,67 @@ export function filterToolsByUsage(
   return toolDefs.filter((tool) => usedToolNames.has(tool.name));
 }
 
+/**
+ * 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[]> {
+  try {
+    const filesEndpoint = `${baseUrl}/files/${sessionId}?detail=full`;
+    const fetchOptions: RequestInit = {
+      method: 'GET',
+      headers: {
+        'User-Agent': 'LibreChat/1.0',
+        'X-API-Key': apiKey,
+      },
+    };
+
+    if (proxy != null && proxy !== '') {
+      fetchOptions.agent = new HttpsProxyAgent(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) {
+      return [];
+    }
+
+    return files.map((file: Record<string, unknown>) => {
+      // Extract the ID from the file name (part after session ID prefix and before extension)
+      const nameParts = (file.name as string).split('/');
+      const id = nameParts.length > 1 ? nameParts[1].split('.')[0] : '';
+
+      return {
+        session_id: sessionId,
+        id,
+        name: (file.metadata as Record<string, unknown>)[
+          'original-filename'
+        ] as string,
+      };
+    });
+  } catch (error) {
+    // eslint-disable-next-line no-console
+    console.warn(
+      `Failed to fetch files for session: ${sessionId}, ${(error as Error).message}`
+    );
+    return [];
+  }
+}
+
 /**
  * Makes an HTTP request to the Code API.
  * @param endpoint - The API endpoint URL
@@ -275,7 +337,7 @@ export async function makeRequest(
 }
 
 /**
- * Unwraps tool responses that may be formatted as tuples.
+ * Unwraps tool responses that may be formatted as tuples or content blocks.
  * MCP tools return [content, artifacts], we need to extract the raw data.
  * @param result - The raw result from tool.invoke()
  * @param isMCPTool - Whether this is an MCP tool (has mcp property)
@@ -290,69 +352,116 @@ export function unwrapToolResponse(
     return result;
   }
 
+  /**
+   * Checks if a value is a content block object (has type and text).
+   */
+  const isContentBlock = (value: unknown): boolean => {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+      return false;
+    }
+    const obj = value as Record<string, unknown>;
+    return typeof obj.type === 'string';
+  };
+
+  /**
+   * Checks if an array is an array of content blocks.
+   */
+  const isContentBlockArray = (arr: unknown[]): boolean => {
+    return arr.length > 0 && arr.every(isContentBlock);
+  };
+
+  /**
+   * Extracts text from a single content block object.
+   * Returns the text if it's a text block, otherwise returns null.
+   */
+  const extractTextFromBlock = (block: unknown): string | null => {
+    if (typeof block !== 'object' || block === null) return null;
+    const b = block as Record<string, unknown>;
+    if (b.type === 'text' && typeof b.text === 'string') {
+      return b.text;
+    }
+    return null;
+  };
+
+  /**
+   * Extracts text from content blocks (array or single object).
+   * Returns combined text or null if no text blocks found.
+   */
+  const extractTextFromContent = (content: unknown): string | null => {
+    // Single content block object: { type: 'text', text: '...' }
+    if (
+      typeof content === 'object' &&
+      content !== null &&
+      !Array.isArray(content)
+    ) {
+      const text = extractTextFromBlock(content);
+      if (text !== null) return text;
+    }
+
+    // Array of content blocks: [{ type: 'text', text: '...' }, ...]
+    if (Array.isArray(content) && content.length > 0) {
+      const texts = content
+        .map(extractTextFromBlock)
+        .filter((t): t is string => t !== null);
+      if (texts.length > 0) {
+        return texts.join('\n');
+      }
+    }
+
+    return null;
+  };
+
+  /**
+   * Tries to parse a string as JSON if it looks like JSON.
+   */
+  const maybeParseJSON = (str: string): unknown => {
+    const trimmed = str.trim();
+    if (trimmed.startsWith('{') || trimmed.startsWith('[')) {
+      try {
+        return JSON.parse(trimmed);
+      } catch {
+        return str;
+      }
+    }
+    return str;
+  };
+
+  // Handle array of content blocks at top level FIRST
+  // (before checking for tuple, since both are arrays)
+  if (Array.isArray(result) && isContentBlockArray(result)) {
+    const extractedText = extractTextFromContent(result);
+    if (extractedText !== null) {
+      return maybeParseJSON(extractedText);
+    }
+  }
+
   // Check if result is a tuple/array with [content, artifacts]
   if (Array.isArray(result) && result.length >= 1) {
     const [content] = result;
 
-    // If first element is a string, return it
+    // If first element is a string, return it (possibly parsed as JSON)
     if (typeof content === 'string') {
-      // Try to parse as JSON if it looks like JSON
-      if (typeof content === 'string' && content.trim().startsWith('{')) {
-        try {
-          return JSON.parse(content);
-        } catch {
-          return content;
-        }
-      }
-      return content;
+      return maybeParseJSON(content);
     }
 
-    // If first element is an array (content blocks), extract text/data
-    if (Array.isArray(content)) {
-      // If it's an array of content blocks (like [{ type: 'text', text: '...' }])
-      if (
-        content.length > 0 &&
-        typeof content[0] === 'object' &&
-        'type' in content[0]
-      ) {
-        // Extract text from content blocks
-        const texts = content
-          .filter((block: unknown) => {
-            if (typeof block !== 'object' || block === null) return false;
-            const b = block as Record<string, unknown>;
-            return b.type === 'text' && typeof b.text === 'string';
-          })
-          .map((block: unknown) => {
-            const b = block as Record<string, unknown>;
-            return b.text as string;
-          });
-
-        if (texts.length > 0) {
-          const combined = texts.join('\n');
-          // Try to parse as JSON if it looks like JSON (objects or arrays)
-          if (
-            combined.trim().startsWith('{') ||
-            combined.trim().startsWith('[')
-          ) {
-            try {
-              return JSON.parse(combined);
-            } catch {
-              return combined;
-            }
-          }
-          return combined;
-        }
-      }
-      // Otherwise return the content array as-is
-      return content;
+    // Try to extract text from content blocks
+    const extractedText = extractTextFromContent(content);
+    if (extractedText !== null) {
+      return maybeParseJSON(extractedText);
     }
 
-    // If first element is an object, return it
+    // If first element is an object (but not a text block), return it
     if (typeof content === 'object' && content !== null) {
       return content;
     }
   }
 
+  // Handle single content block object at top level (not in tuple)
+  const extractedText = extractTextFromContent(result);
+  if (extractedText !== null) {
+    return maybeParseJSON(extractedText);
+  }
+
   // Not a formatted response, return as-is
   return result;
 }
@@ -502,25 +611,21 @@ export function createProgrammaticToolCallingTool(
   const EXEC_ENDPOINT = `${baseUrl}/exec/programmatic`;
 
   const description = `
-Run tools by writing Python code. Tools are available as async functions - just call them with await.
+Run tools via Python code. Tools are injected as async functions—call with \`await\`.
 
-This is different from execute_code: here you can call your tools (like get_weather, get_expenses, etc.) directly in Python code.
+Rules:
+- Tools are pre-defined—DO NOT define them yourself
+- Use \`await\` for calls, \`asyncio.gather()\` for parallel; NEVER call \`asyncio.run()\`
+- Only \`print()\` output returns to the model; tool results are raw dicts/lists/strings
+- Stateless: variables/imports don't persist; use \`session_id\` param for file access
+- Files mount at \`/mnt/data/\` (READ-ONLY); write changes to NEW filenames
+- Tool names normalized: hyphens→underscores, keywords get \`_tool\` suffix
 
-Usage:
-- Tools are pre-defined as async functions - call them with await
-- Use asyncio.gather() to run multiple tools in parallel
-- Only print() output is returned - tool results stay in Python
+When to use (vs. direct tool calls): loops, conditionals, parallel execution, aggregation.
 
 Examples:
-- Simple: result = await get_weather(city="NYC")
-- Loop: for user in users: data = await get_expenses(user_id=user['id'])
-- Parallel: sf, ny = await asyncio.gather(get_weather(city="SF"), get_weather(city="NY"))
-
-When to use this instead of calling tools directly:
-- You need to call tools in a loop (process many items)
-- You want parallel execution (asyncio.gather)
-- You need conditionals based on tool results
-- You want to aggregate/filter data before returning
+  result = await get_weather(city="NYC"); print(result)
+  sf, ny = await asyncio.gather(get_weather(city="SF"), get_weather(city="NY"))
 `.trim();
 
   return tool<typeof ProgrammaticToolCallingSchema>(
@@ -562,6 +667,12 @@ When to use this instead of calling tools directly:
           );
         }
 
+        // Fetch files from previous session if session_id is provided
+        let files: t.CodeEnvFile[] | undefined;
+        if (session_id != null && session_id.length > 0) {
+          files = await fetchSessionFiles(baseUrl, apiKey, session_id, proxy);
+        }
+
         let response = await makeRequest(
           EXEC_ENDPOINT,
           apiKey,
@@ -570,6 +681,7 @@ When to use this instead of calling tools directly:
             tools: effectiveTools,
             session_id,
             timeout,
+            ...(files && files.length > 0 ? { files } : {}),
           },
           proxy
         );

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

@@ -12,6 +12,7 @@ import {
   filterToolsByUsage,
   executeTools,
   normalizeToPythonIdentifier,
+  unwrapToolResponse,
 } from '../ProgrammaticToolCalling';
 import {
   createProgrammaticToolRegistry,
@@ -228,6 +229,160 @@ describe('ProgrammaticToolCalling', () => {
     });
   });
 
+  describe('unwrapToolResponse', () => {
+    describe('non-MCP tools', () => {
+      it('returns result as-is for non-MCP tools', () => {
+        const result = { temperature: 65, condition: 'Foggy' };
+        expect(unwrapToolResponse(result, false)).toEqual(result);
+      });
+
+      it('returns string as-is for non-MCP tools', () => {
+        expect(unwrapToolResponse('plain string', false)).toBe('plain string');
+      });
+
+      it('returns array as-is for non-MCP tools', () => {
+        const result = [1, 2, 3];
+        expect(unwrapToolResponse(result, false)).toEqual(result);
+      });
+    });
+
+    describe('MCP tools - tuple format [content, artifacts]', () => {
+      it('extracts string content from tuple', () => {
+        const result = ['Hello world', { artifacts: [] }];
+        expect(unwrapToolResponse(result, true)).toBe('Hello world');
+      });
+
+      it('parses JSON string content from tuple', () => {
+        const result = ['{"temperature": 65}', { artifacts: [] }];
+        expect(unwrapToolResponse(result, true)).toEqual({ temperature: 65 });
+      });
+
+      it('parses JSON array string content from tuple', () => {
+        const result = ['[1, 2, 3]', { artifacts: [] }];
+        expect(unwrapToolResponse(result, true)).toEqual([1, 2, 3]);
+      });
+
+      it('extracts text from single content block in tuple', () => {
+        const result = [{ type: 'text', text: 'Spreadsheet info here' }, {}];
+        expect(unwrapToolResponse(result, true)).toBe('Spreadsheet info here');
+      });
+
+      it('extracts and parses JSON from single content block in tuple', () => {
+        const result = [
+          { type: 'text', text: '{"id": "123", "name": "Test"}' },
+          {},
+        ];
+        expect(unwrapToolResponse(result, true)).toEqual({
+          id: '123',
+          name: 'Test',
+        });
+      });
+
+      it('extracts text from array of content blocks in tuple', () => {
+        const result = [
+          [
+            { type: 'text', text: 'Line 1' },
+            { type: 'text', text: 'Line 2' },
+          ],
+          {},
+        ];
+        expect(unwrapToolResponse(result, true)).toBe('Line 1\nLine 2');
+      });
+
+      it('returns object content as-is when not a text block', () => {
+        const result = [{ temperature: 65, condition: 'Foggy' }, {}];
+        expect(unwrapToolResponse(result, true)).toEqual({
+          temperature: 65,
+          condition: 'Foggy',
+        });
+      });
+    });
+
+    describe('MCP tools - single content block (not in tuple)', () => {
+      it('extracts text from single content block object', () => {
+        const result = { type: 'text', text: 'No data found in range' };
+        expect(unwrapToolResponse(result, true)).toBe('No data found in range');
+      });
+
+      it('extracts and parses JSON from single content block object', () => {
+        const result = {
+          type: 'text',
+          text: '{"sheets": [{"name": "raw_data"}]}',
+        };
+        expect(unwrapToolResponse(result, true)).toEqual({
+          sheets: [{ name: 'raw_data' }],
+        });
+      });
+
+      it('handles real-world MCP spreadsheet response', () => {
+        const result = {
+          type: 'text',
+          text: 'Spreadsheet: "NYC Taxi - Top Pickup Neighborhoods" (ID: abc123)\nSheets (2):\n  - "raw_data" (ID: 123) | Size: 1000x26',
+        };
+        expect(unwrapToolResponse(result, true)).toBe(
+          'Spreadsheet: "NYC Taxi - Top Pickup Neighborhoods" (ID: abc123)\nSheets (2):\n  - "raw_data" (ID: 123) | Size: 1000x26'
+        );
+      });
+
+      it('handles real-world MCP no data response', () => {
+        const result = {
+          type: 'text',
+          text: 'No data found in range \'raw_data!A1:D25\' for user@example.com.',
+        };
+        expect(unwrapToolResponse(result, true)).toBe(
+          'No data found in range \'raw_data!A1:D25\' for user@example.com.'
+        );
+      });
+    });
+
+    describe('MCP tools - array of content blocks (not in tuple)', () => {
+      it('extracts text from array of content blocks', () => {
+        const result = [
+          { type: 'text', text: 'First block' },
+          { type: 'text', text: 'Second block' },
+        ];
+        expect(unwrapToolResponse(result, true)).toBe(
+          'First block\nSecond block'
+        );
+      });
+
+      it('filters out non-text blocks', () => {
+        const result = [
+          { type: 'text', text: 'Text content' },
+          { type: 'image', data: 'base64...' },
+          { type: 'text', text: 'More text' },
+        ];
+        expect(unwrapToolResponse(result, true)).toBe(
+          'Text content\nMore text'
+        );
+      });
+    });
+
+    describe('edge cases', () => {
+      it('returns non-text block object as-is', () => {
+        const result = { type: 'image', data: 'base64...' };
+        expect(unwrapToolResponse(result, true)).toEqual(result);
+      });
+
+      it('handles empty array', () => {
+        expect(unwrapToolResponse([], true)).toEqual([]);
+      });
+
+      it('handles malformed JSON in text block gracefully', () => {
+        const result = { type: 'text', text: '{ invalid json }' };
+        expect(unwrapToolResponse(result, true)).toBe('{ invalid json }');
+      });
+
+      it('handles null', () => {
+        expect(unwrapToolResponse(null, true)).toBe(null);
+      });
+
+      it('handles undefined', () => {
+        expect(unwrapToolResponse(undefined, true)).toBe(undefined);
+      });
+    });
+  });
+
   describe('extractUsedToolNames', () => {
     const createToolMap = (names: string[]): Map<string, string> => {
       const map = new Map<string, string>();