@librechat/agents 3.1.26 → 3.1.28

package/src/messages/formatAgentMessages.test.ts

@@ -306,6 +306,375 @@ describe('formatAgentMessages', () => {
     ]);
   });
 
+  it('should dynamically discover tools from tool_search output and keep their tool calls', () => {
+    const tools = new Set(['tool_search', 'calculator']);
+    const payload = [
+      {
+        role: 'user',
+        content: 'Search for commits and list them',
+      },
+      {
+        role: 'assistant',
+        content: [
+          {
+            type: ContentTypes.TEXT,
+            [ContentTypes.TEXT]: 'I\'ll search for tools first.',
+            tool_call_ids: ['ts_1'],
+          },
+          {
+            type: ContentTypes.TOOL_CALL,
+            tool_call: {
+              id: 'ts_1',
+              name: 'tool_search',
+              args: '{"query":"commits"}',
+              output: '{"found": 1, "tools": [{"name": "list_commits"}]}',
+            },
+          },
+          {
+            type: ContentTypes.TEXT,
+            [ContentTypes.TEXT]: 'Now listing commits.',
+            tool_call_ids: ['lc_1'],
+          },
+          {
+            type: ContentTypes.TOOL_CALL,
+            tool_call: {
+              id: 'lc_1',
+              name: 'list_commits',
+              args: '{"repo":"test"}',
+              output: '[{"sha":"abc123"}]',
+            },
+          },
+          {
+            type: ContentTypes.TEXT,
+            [ContentTypes.TEXT]: 'Here are the results.',
+          },
+        ],
+      },
+      {
+        role: 'user',
+        content: 'Thanks!',
+      },
+    ];
+
+    const result = formatAgentMessages(payload, undefined, tools);
+
+    /**
+     * Since tool_search discovered list_commits, both should be kept.
+     * The dynamic discovery adds list_commits to the valid tools set.
+     */
+    const toolMessages = result.messages.filter(
+      (m) => m._getType() === 'tool'
+    ) as ToolMessage[];
+    expect(toolMessages.length).toBe(2);
+
+    const toolNames = toolMessages.map((m) => m.name).sort();
+    expect(toolNames).toEqual(['list_commits', 'tool_search']);
+  });
+
+  it('should filter out tool calls not in set and not discovered by tool_search', () => {
+    const tools = new Set(['tool_search', 'calculator']);
+    const payload = [
+      {
+        role: 'assistant',
+        content: [
+          {
+            type: ContentTypes.TEXT,
+            [ContentTypes.TEXT]: 'I\'ll call an unknown tool.',
+            tool_call_ids: ['uk_1'],
+          },
+          {
+            type: ContentTypes.TOOL_CALL,
+            tool_call: {
+              id: 'uk_1',
+              name: 'unknown_tool',
+              args: '{}',
+              output: 'result',
+            },
+          },
+          {
+            type: ContentTypes.TEXT,
+            [ContentTypes.TEXT]: 'Done.',
+          },
+        ],
+      },
+    ];
+
+    const result = formatAgentMessages(payload, undefined, tools);
+
+    /** unknown_tool should be filtered out since it's not in tools set and not discovered */
+    const toolMessages = result.messages.filter(
+      (m) => m._getType() === 'tool'
+    ) as ToolMessage[];
+    expect(toolMessages.length).toBe(0);
+  });
+
+  it('should keep all tool calls when all are in the tools set', () => {
+    const tools = new Set(['search', 'calculator']);
+    const payload = [
+      {
+        role: 'assistant',
+        content: [
+          {
+            type: ContentTypes.TEXT,
+            [ContentTypes.TEXT]: 'Let me help.',
+            tool_call_ids: ['s1', 'c1'],
+          },
+          {
+            type: ContentTypes.TOOL_CALL,
+            tool_call: {
+              id: 's1',
+              name: 'search',
+              args: '{"q":"test"}',
+              output: 'Search results',
+            },
+          },
+          {
+            type: ContentTypes.TOOL_CALL,
+            tool_call: {
+              id: 'c1',
+              name: 'calculator',
+              args: '{"expr":"2+2"}',
+              output: '4',
+            },
+          },
+        ],
+      },
+    ];
+
+    const result = formatAgentMessages(payload, undefined, tools);
+
+    const toolMessages = result.messages.filter(
+      (m) => m._getType() === 'tool'
+    ) as ToolMessage[];
+    expect(toolMessages.length).toBe(2);
+    expect(toolMessages.map((m) => m.name).sort()).toEqual([
+      'calculator',
+      'search',
+    ]);
+  });
+
+  it('should preserve discovered tools across multiple assistant messages', () => {
+    /**
+     * This test verifies that once tool_search discovers a tool, it remains valid
+     * for all subsequent messages in the conversation, not just the current message.
+     */
+    const tools = new Set(['tool_search']);
+    const payload = [
+      {
+        role: 'user',
+        content: 'Find me a tool to list commits and use it',
+      },
+      {
+        role: 'assistant',
+        content: [
+          {
+            type: ContentTypes.TEXT,
+            [ContentTypes.TEXT]: 'Let me search for that tool.',
+            tool_call_ids: ['ts_1'],
+          },
+          {
+            type: ContentTypes.TOOL_CALL,
+            tool_call: {
+              id: 'ts_1',
+              name: 'tool_search',
+              args: '{"query":"commits"}',
+              output: '{"found": 1, "tools": [{"name": "list_commits_mcp_github"}]}',
+            },
+          },
+        ],
+      },
+      {
+        role: 'assistant',
+        content: [
+          {
+            type: ContentTypes.TEXT,
+            [ContentTypes.TEXT]: 'Now using the discovered tool.',
+            tool_call_ids: ['lc_1'],
+          },
+          {
+            type: ContentTypes.TOOL_CALL,
+            tool_call: {
+              id: 'lc_1',
+              name: 'list_commits_mcp_github',
+              args: '{"repo":"test"}',
+              output: '[{"sha":"abc123","message":"Initial commit"}]',
+            },
+          },
+        ],
+      },
+      {
+        role: 'user',
+        content: 'Show me more commits',
+      },
+      {
+        role: 'assistant',
+        content: [
+          {
+            type: ContentTypes.TEXT,
+            [ContentTypes.TEXT]: 'Fetching more commits.',
+            tool_call_ids: ['lc_2'],
+          },
+          {
+            type: ContentTypes.TOOL_CALL,
+            tool_call: {
+              id: 'lc_2',
+              name: 'list_commits_mcp_github',
+              args: '{"repo":"test","page":2}',
+              output: '[{"sha":"def456","message":"Second commit"}]',
+            },
+          },
+        ],
+      },
+    ];
+
+    const result = formatAgentMessages(payload, undefined, tools);
+
+    /** All three tool calls should be preserved as ToolMessages */
+    const toolMessages = result.messages.filter(
+      (m) => m._getType() === 'tool'
+    ) as ToolMessage[];
+
+    expect(toolMessages.length).toBe(3);
+    expect(toolMessages[0].name).toBe('tool_search');
+    expect(toolMessages[1].name).toBe('list_commits_mcp_github');
+    expect(toolMessages[2].name).toBe('list_commits_mcp_github');
+  });
+
+  it('should convert invalid tools to string while keeping valid tools as ToolMessages', () => {
+    /**
+     * This test documents the hybrid behavior:
+     * - Valid tools remain as proper AIMessage + ToolMessage structures
+     * - Invalid tools are converted to string and appended to text content
+     *   (preserving context without losing information)
+     */
+    const tools = new Set(['calculator']);
+    const payload = [
+      {
+        role: 'assistant',
+        content: [
+          {
+            type: ContentTypes.TEXT,
+            [ContentTypes.TEXT]: 'I will use two tools.',
+            tool_call_ids: ['calc_1', 'unknown_1'],
+          },
+          {
+            type: ContentTypes.TOOL_CALL,
+            tool_call: {
+              id: 'calc_1',
+              name: 'calculator',
+              args: '{"expr":"2+2"}',
+              output: '4',
+            },
+          },
+          {
+            type: ContentTypes.TOOL_CALL,
+            tool_call: {
+              id: 'unknown_1',
+              name: 'some_unknown_tool',
+              args: '{"query":"test"}',
+              output: 'This is the result from unknown tool',
+            },
+          },
+        ],
+      },
+    ];
+
+    const result = formatAgentMessages(payload, undefined, tools);
+
+    /** Should have AIMessage + ToolMessage for calculator */
+    expect(result.messages.length).toBe(2);
+    expect(result.messages[0]).toBeInstanceOf(AIMessage);
+    expect(result.messages[1]).toBeInstanceOf(ToolMessage);
+
+    /** The valid tool should be kept */
+    expect((result.messages[0] as AIMessage).tool_calls).toHaveLength(1);
+    expect((result.messages[0] as AIMessage).tool_calls?.[0].name).toBe(
+      'calculator'
+    );
+    expect((result.messages[1] as ToolMessage).name).toBe('calculator');
+
+    /** The invalid tool should be converted to string in the content */
+    const aiContent = result.messages[0].content;
+    const aiContentStr =
+      typeof aiContent === 'string' ? aiContent : JSON.stringify(aiContent);
+    expect(aiContentStr).toContain('some_unknown_tool');
+    expect(aiContentStr).toContain('This is the result from unknown tool');
+  });
+
+  it('should simulate realistic deferred tools flow with tool_search', () => {
+    /**
+     * This test simulates the real-world use case:
+     * 1. Agent only has tool_search initially (deferred tools not in set)
+     * 2. User asks to do something that requires a deferred tool
+     * 3. Agent uses tool_search to discover the tool
+     * 4. Agent then uses the discovered tool
+     * 5. On subsequent conversation turns, both tool calls should be valid
+     */
+    const tools = new Set(['tool_search', 'execute_code']);
+    const payload = [
+      { role: 'user', content: 'List the recent commits from the repo' },
+      {
+        role: 'assistant',
+        content: [
+          {
+            type: ContentTypes.TEXT,
+            [ContentTypes.TEXT]:
+              'I need to find a tool for listing commits. Let me search.',
+            tool_call_ids: ['search_1'],
+          },
+          {
+            type: ContentTypes.TOOL_CALL,
+            tool_call: {
+              id: 'search_1',
+              name: 'tool_search',
+              args: '{"query":"git commits list"}',
+              output:
+                '{\n  "found": 1,\n  "tools": [\n    {\n      "name": "list_commits_mcp_github",\n      "score": 0.95,\n      "matched_in": "name",\n      "snippet": "Lists commits from a GitHub repository"\n    }\n  ],\n  "total_searched": 50,\n  "query": "git commits list"\n}',
+            },
+          },
+          {
+            type: ContentTypes.TEXT,
+            [ContentTypes.TEXT]:
+              'Found the tool! Now I will list the commits.',
+            tool_call_ids: ['commits_1'],
+          },
+          {
+            type: ContentTypes.TOOL_CALL,
+            tool_call: {
+              id: 'commits_1',
+              name: 'list_commits_mcp_github',
+              args: '{"owner":"librechat","repo":"librechat"}',
+              output:
+                '[{"sha":"abc123","message":"feat: add deferred tools"},{"sha":"def456","message":"fix: tool loading"}]',
+            },
+          },
+        ],
+      },
+    ];
+
+    const result = formatAgentMessages(payload, undefined, tools);
+
+    /** Both tool_search and list_commits_mcp_github should be preserved */
+    const toolMessages = result.messages.filter(
+      (m) => m._getType() === 'tool'
+    ) as ToolMessage[];
+
+    expect(toolMessages.length).toBe(2);
+    expect(toolMessages[0].name).toBe('tool_search');
+    expect(toolMessages[1].name).toBe('list_commits_mcp_github');
+
+    /** The AI messages should have proper tool_calls */
+    const aiMessages = result.messages.filter(
+      (m) => m._getType() === 'ai'
+    ) as AIMessage[];
+
+    const toolCallNames = aiMessages.flatMap(
+      (m) => m.tool_calls?.map((tc) => tc.name) ?? []
+    );
+    expect(toolCallNames).toContain('tool_search');
+    expect(toolCallNames).toContain('list_commits_mcp_github');
+  });
+
   it.skip('should not produce two consecutive assistant messages and format content correctly', () => {
     const payload = [
       { role: 'user', content: 'Hello' },

package/src/messages/formatAgentMessages.tools.test.ts

@@ -38,7 +38,7 @@ describe('formatAgentMessages with tools parameter', () => {
     expect((result.messages[2] as ToolMessage).tool_call_id).toBe('123');
   });
 
-  it('should treat an empty tools set the same as disallowing all tools', () => {
+  it('should filter out all tool calls when tools set is empty', () => {
     const payload: TPayload = [
       { role: 'user', content: 'What\'s the weather?' },
       {
@@ -67,19 +67,16 @@ describe('formatAgentMessages with tools parameter', () => {
 
     const result = formatAgentMessages(payload, undefined, allowedTools);
 
-    // Should convert to a single AIMessage with string content
+    // Should filter out the tool call, keeping only text content
     expect(result.messages).toHaveLength(2);
     expect(result.messages[0]).toBeInstanceOf(HumanMessage);
     expect(result.messages[1]).toBeInstanceOf(AIMessage);
 
-    // The content should be a string representation of both messages
-    expect(typeof result.messages[1].content).toBe('string');
-    expect(result.messages[1].content).toEqual(
-      'AI: Let me check the weather for you.\nTool: check_weather, Sunny, 75°F'
-    );
+    // The AIMessage should have no tool_calls (they were filtered out)
+    expect((result.messages[1] as AIMessage).tool_calls).toHaveLength(0);
   });
 
-  it('should convert tool messages to string when tool is not in the allowed set', () => {
+  it('should filter out tool calls not in the allowed set', () => {
     const payload: TPayload = [
       { role: 'user', content: 'What\'s the weather?' },
       {
@@ -108,16 +105,13 @@ describe('formatAgentMessages with tools parameter', () => {
 
     const result = formatAgentMessages(payload, undefined, allowedTools);
 
-    // Should convert to a single AIMessage with string content
+    // Should filter out the invalid tool call, keeping text content
     expect(result.messages).toHaveLength(2);
     expect(result.messages[0]).toBeInstanceOf(HumanMessage);
     expect(result.messages[1]).toBeInstanceOf(AIMessage);
 
-    // The content should be a string representation of both messages
-    expect(typeof result.messages[1].content).toBe('string');
-    expect(result.messages[1].content).toEqual(
-      'AI: Let me check the weather for you.\nTool: check_weather, Sunny, 75°F'
-    );
+    // The AIMessage should have no tool_calls (check_weather was filtered out)
+    expect((result.messages[1] as AIMessage).tool_calls).toHaveLength(0);
   });
 
   it('should not convert tool messages when tool is in the allowed set', () => {
@@ -202,21 +196,25 @@ describe('formatAgentMessages with tools parameter', () => {
 
     const result = formatAgentMessages(payload, undefined, allowedTools);
 
-    // Should convert the entire sequence to a single AIMessage
-    expect(result.messages).toHaveLength(2);
+    // Should keep valid tool (calculator) and convert invalid (check_weather) to string
+    expect(result.messages).toHaveLength(3);
     expect(result.messages[0]).toBeInstanceOf(HumanMessage);
     expect(result.messages[1]).toBeInstanceOf(AIMessage);
+    expect(result.messages[2]).toBeInstanceOf(ToolMessage);
 
-    // The content should include all parts
-    expect(typeof result.messages[1].content).toBe('string');
-    expect(result.messages[1].content).toContain(
-      'Let me check the weather first.'
+    // The AIMessage should have the calculator tool_call
+    expect((result.messages[1] as AIMessage).tool_calls).toHaveLength(1);
+    expect((result.messages[1] as AIMessage).tool_calls?.[0].name).toBe(
+      'calculator'
     );
+
+    // The content should include invalid tool as string
+    expect(result.messages[1].content).toContain('check_weather');
     expect(result.messages[1].content).toContain('Sunny, 75°F');
-    expect(result.messages[1].content).toContain(
-      'Now let me calculate something for you.'
-    );
-    expect(result.messages[1].content).toContain('2');
+
+    // The ToolMessage should be for calculator
+    expect((result.messages[2] as ToolMessage).name).toBe('calculator');
+    expect(result.messages[2].content).toBe('2');
   });
 
   it('should update indexTokenCountMap correctly when converting tool messages', () => {
@@ -268,7 +266,7 @@ describe('formatAgentMessages with tools parameter', () => {
     expect(result.indexTokenCountMap?.[1]).toBe(40);
   });
 
-  it('should heal invalid tool call structure when converting to string', () => {
+  it('should convert invalid tool to text content when no other content exists', () => {
     const payload: TPayload = [
       {
         role: 'assistant',
@@ -291,14 +289,19 @@ describe('formatAgentMessages with tools parameter', () => {
 
     const result = formatAgentMessages(payload, undefined, allowedTools);
 
-    // Should convert to a single AIMessage with string content
+    // Should create an AIMessage with the invalid tool converted to text
     expect(result.messages).toHaveLength(1);
     expect(result.messages[0]).toBeInstanceOf(AIMessage);
 
-    // The content should be a string representation of the tool message
-    expect(typeof result.messages[0].content).toBe('string');
-    expect(result.messages[0].content).toContain('check_weather');
-    expect(result.messages[0].content).toContain('Sunny, 75°F');
+    // The AIMessage should have no tool_calls (all were invalid)
+    expect((result.messages[0] as AIMessage).tool_calls).toHaveLength(0);
+
+    // The content should contain the invalid tool info
+    const content = result.messages[0].content;
+    const contentStr =
+      typeof content === 'string' ? content : JSON.stringify(content);
+    expect(contentStr).toContain('check_weather');
+    expect(contentStr).toContain('Sunny, 75°F');
   });
 
   it('should handle complex sequences with multiple tool calls', () => {
@@ -372,29 +375,45 @@ describe('formatAgentMessages with tools parameter', () => {
 
     const result = formatAgentMessages(payload, undefined, allowedTools);
 
-    // Should have the user message, search tool sequence (2 messages),
-    // a combined message for weather and calculator (since one has an invalid tool),
-    // and final message
-    expect(result.messages).toHaveLength(5);
+    // With selective filtering: valid tools are kept, invalid tools are converted to string
+    // 1. HumanMessage
+    // 2. AIMessage (search tool_call)
+    // 3. ToolMessage (search result)
+    // 4. AIMessage (text + invalid weather tool as string, no tool_calls)
+    // 5. AIMessage (calculator tool_call)
+    // 6. ToolMessage (calculator result)
+    // 7. AIMessage (final text)
+    expect(result.messages).toHaveLength(7);
 
     // Check the types of messages
     expect(result.messages[0]).toBeInstanceOf(HumanMessage);
     expect(result.messages[1]).toBeInstanceOf(AIMessage); // Search message
     expect(result.messages[2]).toBeInstanceOf(ToolMessage); // Search tool response
-    expect(result.messages[3]).toBeInstanceOf(AIMessage); // Converted weather+calculator message
-    expect(result.messages[4]).toBeInstanceOf(AIMessage); // Final message
-
-    // Check that the combined message was converted to a string
-    expect(typeof result.messages[3].content).toBe('string');
-
-    // The format might vary based on the getBufferString implementation
-    // but we should check that all the key information is present
-    const content = result.messages[3].content as string;
-    expect(content).toContain('Now I\'ll check the weather');
-    expect(content).toContain('Sunny');
-    expect(content).toContain('75');
-    expect(content).toContain('Finally');
-    expect(content).toContain('calculate');
-    expect(content).toContain('2');
+    expect(result.messages[3]).toBeInstanceOf(AIMessage); // Weather message (tool converted to string)
+    expect(result.messages[4]).toBeInstanceOf(AIMessage); // Calculator message
+    expect(result.messages[5]).toBeInstanceOf(ToolMessage); // Calculator tool response
+    expect(result.messages[6]).toBeInstanceOf(AIMessage); // Final message
+
+    // Check that search tool was kept
+    expect((result.messages[1] as AIMessage).tool_calls).toHaveLength(1);
+    expect((result.messages[1] as AIMessage).tool_calls?.[0].name).toBe(
+      'search'
+    );
+
+    // Check that weather message has no tool_calls but contains the invalid tool as text
+    expect((result.messages[3] as AIMessage).tool_calls).toHaveLength(0);
+    const weatherContent = result.messages[3].content;
+    const weatherContentStr =
+      typeof weatherContent === 'string'
+        ? weatherContent
+        : JSON.stringify(weatherContent);
+    expect(weatherContentStr).toContain('check_weather');
+    expect(weatherContentStr).toContain('Sunny');
+
+    // Check that calculator tool was kept
+    expect((result.messages[4] as AIMessage).tool_calls).toHaveLength(1);
+    expect((result.messages[4] as AIMessage).tool_calls?.[0].name).toBe(
+      'calculator'
+    );
   });
 });

package/src/tools/ProgrammaticToolCalling.ts

@@ -32,7 +32,7 @@ const DEFAULT_TIMEOUT = 60000;
 // Schema
 // ============================================================================
 
-const ProgrammaticToolCallingSchema = {
+export const ProgrammaticToolCallingSchema = {
   type: 'object',
   properties: {
     code: {
@@ -80,6 +80,34 @@ Rules:
   required: ['code'],
 } as const;
 
+export const ProgrammaticToolCallingName = Constants.PROGRAMMATIC_TOOL_CALLING;
+
+export const ProgrammaticToolCallingDescription = `
+Run tools via Python code. Auto-wrapped in async context—just use \`await\` directly.
+
+CRITICAL - STATELESS: Each call is a fresh interpreter. Variables/imports do NOT persist.
+Complete your ENTIRE workflow in ONE call: fetch → process → save. No splitting across calls.
+
+Rules:
+- Everything in ONE code block—no state carries over between executions
+- 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
+- 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.
+
+Example (complete pipeline):
+  data = await query_db(sql="..."); df = process(data); await save_to_sheet(data=df); print("Done")
+`.trim();
+
+export const ProgrammaticToolCallingDefinition = {
+  name: ProgrammaticToolCallingName,
+  description: ProgrammaticToolCallingDescription,
+  schema: ProgrammaticToolCallingSchema,
+} as const;
+
 // ============================================================================
 // Helper Functions
 // ============================================================================

package/src/tools/ToolSearch.ts

@@ -33,6 +33,49 @@ config();
 /** Maximum allowed regex pattern length */
 const MAX_PATTERN_LENGTH = 200;
 
+export const ToolSearchToolName = Constants.TOOL_SEARCH;
+
+export const ToolSearchToolDescription =
+  'Searches deferred tools using BM25 ranking. Multi-word queries supported. Use mcp_server param to filter by server.';
+
+export const ToolSearchToolSchema = {
+  type: 'object',
+  properties: {
+    query: {
+      type: 'string',
+      maxLength: MAX_PATTERN_LENGTH,
+      default: '',
+      description:
+        'Search term to find in tool names and descriptions. Case-insensitive substring matching. Optional if mcp_server is provided.',
+    },
+    fields: {
+      type: 'array',
+      items: { type: 'string', enum: ['name', 'description', 'parameters'] },
+      default: ['name', 'description'],
+      description: 'Which fields to search. Default: name and description',
+    },
+    max_results: {
+      type: 'integer',
+      minimum: 1,
+      maximum: 50,
+      default: 10,
+      description: 'Maximum number of matching tools to return',
+    },
+    mcp_server: {
+      oneOf: [{ type: 'string' }, { type: 'array', items: { type: 'string' } }],
+      description:
+        'Filter to tools from specific MCP server(s). Can be a single server name or array of names. If provided without a query, lists all tools from those servers.',
+    },
+  },
+  required: [],
+} as const;
+
+export const ToolSearchToolDefinition = {
+  name: ToolSearchToolName,
+  description: ToolSearchToolDescription,
+  schema: ToolSearchToolSchema,
+} as const;
+
 /** Maximum allowed regex nesting depth */
 const MAX_REGEX_COMPLEXITY = 5;
 

package/src/types/graph.ts

@@ -383,4 +383,10 @@ export interface AgentInputs {
    * ON_TOOL_EXECUTE events instead of invoking tools directly.
    */
   toolDefinitions?: LCTool[];
+  /**
+   * Tool names discovered from previous conversation history.
+   * These tools will be pre-marked as discovered so they're included
+   * in tool binding without requiring tool_search.
+   */
+  discoveredTools?: string[];
 }