🦥 feat: Add Deferred Tools as Agents Capability (#11295)

api/server/services/ToolService.js

@@ -409,8 +409,14 @@ async function loadAgentTools({
   const checkCapability = (capability) => {
     const enabled = enabledCapabilities.has(capability);
     if (!enabled) {
+      const isToolCapability = [
+        AgentCapabilities.file_search,
+        AgentCapabilities.execute_code,
+        AgentCapabilities.web_search,
+      ].includes(capability);
+      const suffix = isToolCapability ? ' despite configured tool.' : '.';
       logger.warn(
-        `Capability "${capability}" disabled${capability === AgentCapabilities.tools ? '.' : ' despite configured tool.'} User: ${req.user.id} | Agent: ${agent.id}`,
+        `Capability "${capability}" disabled${suffix} User: ${req.user.id} | Agent: ${agent.id}`,
       );
     }
     return enabled;
@@ -519,11 +525,13 @@ async function loadAgentTools({
   }, {});
 
   /** Build tool registry from MCP tools and create PTC/tool search tools if configured */
+  const deferredToolsEnabled = checkCapability(AgentCapabilities.deferred_tools);
   const { toolRegistry, additionalTools, hasDeferredTools } = await buildToolClassification({
     loadedTools,
     userId: req.user.id,
     agentId: agent.id,
     agentToolOptions: agent.tool_options,
+    deferredToolsEnabled,
     loadAuthValues,
   });
   agentTools.push(...additionalTools);

api/server/services/__tests__/ToolService.spec.js

@@ -0,0 +1,149 @@
+const { AgentCapabilities, defaultAgentCapabilities } = require('librechat-data-provider');
+
+/**
+ * Tests for ToolService capability checking logic.
+ * The actual loadAgentTools function has many dependencies, so we test
+ * the capability checking logic in isolation.
+ */
+describe('ToolService - Capability Checking', () => {
+  describe('checkCapability logic', () => {
+    /**
+     * Simulates the checkCapability function from loadAgentTools
+     */
+    const createCheckCapability = (enabledCapabilities, logger = { warn: jest.fn() }) => {
+      return (capability) => {
+        const enabled = enabledCapabilities.has(capability);
+        if (!enabled) {
+          const isToolCapability = [
+            AgentCapabilities.file_search,
+            AgentCapabilities.execute_code,
+            AgentCapabilities.web_search,
+          ].includes(capability);
+          const suffix = isToolCapability ? ' despite configured tool.' : '.';
+          logger.warn(`Capability "${capability}" disabled${suffix}`);
+        }
+        return enabled;
+      };
+    };
+
+    it('should return true when capability is enabled', () => {
+      const enabledCapabilities = new Set([AgentCapabilities.deferred_tools]);
+      const checkCapability = createCheckCapability(enabledCapabilities);
+
+      expect(checkCapability(AgentCapabilities.deferred_tools)).toBe(true);
+    });
+
+    it('should return false when capability is not enabled', () => {
+      const enabledCapabilities = new Set([]);
+      const checkCapability = createCheckCapability(enabledCapabilities);
+
+      expect(checkCapability(AgentCapabilities.deferred_tools)).toBe(false);
+    });
+
+    it('should log warning with "despite configured tool" for tool capabilities', () => {
+      const logger = { warn: jest.fn() };
+      const enabledCapabilities = new Set([]);
+      const checkCapability = createCheckCapability(enabledCapabilities, logger);
+
+      checkCapability(AgentCapabilities.file_search);
+      expect(logger.warn).toHaveBeenCalledWith(expect.stringContaining('despite configured tool'));
+
+      logger.warn.mockClear();
+      checkCapability(AgentCapabilities.execute_code);
+      expect(logger.warn).toHaveBeenCalledWith(expect.stringContaining('despite configured tool'));
+
+      logger.warn.mockClear();
+      checkCapability(AgentCapabilities.web_search);
+      expect(logger.warn).toHaveBeenCalledWith(expect.stringContaining('despite configured tool'));
+    });
+
+    it('should log warning without "despite configured tool" for non-tool capabilities', () => {
+      const logger = { warn: jest.fn() };
+      const enabledCapabilities = new Set([]);
+      const checkCapability = createCheckCapability(enabledCapabilities, logger);
+
+      checkCapability(AgentCapabilities.deferred_tools);
+      expect(logger.warn).toHaveBeenCalledWith(
+        expect.stringContaining('Capability "deferred_tools" disabled.'),
+      );
+      expect(logger.warn).not.toHaveBeenCalledWith(
+        expect.stringContaining('despite configured tool'),
+      );
+
+      logger.warn.mockClear();
+      checkCapability(AgentCapabilities.tools);
+      expect(logger.warn).toHaveBeenCalledWith(
+        expect.stringContaining('Capability "tools" disabled.'),
+      );
+      expect(logger.warn).not.toHaveBeenCalledWith(
+        expect.stringContaining('despite configured tool'),
+      );
+
+      logger.warn.mockClear();
+      checkCapability(AgentCapabilities.actions);
+      expect(logger.warn).toHaveBeenCalledWith(
+        expect.stringContaining('Capability "actions" disabled.'),
+      );
+    });
+
+    it('should not log warning when capability is enabled', () => {
+      const logger = { warn: jest.fn() };
+      const enabledCapabilities = new Set([
+        AgentCapabilities.deferred_tools,
+        AgentCapabilities.file_search,
+      ]);
+      const checkCapability = createCheckCapability(enabledCapabilities, logger);
+
+      checkCapability(AgentCapabilities.deferred_tools);
+      checkCapability(AgentCapabilities.file_search);
+
+      expect(logger.warn).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('defaultAgentCapabilities', () => {
+    it('should include deferred_tools capability by default', () => {
+      expect(defaultAgentCapabilities).toContain(AgentCapabilities.deferred_tools);
+    });
+
+    it('should include all expected default capabilities', () => {
+      expect(defaultAgentCapabilities).toContain(AgentCapabilities.execute_code);
+      expect(defaultAgentCapabilities).toContain(AgentCapabilities.file_search);
+      expect(defaultAgentCapabilities).toContain(AgentCapabilities.web_search);
+      expect(defaultAgentCapabilities).toContain(AgentCapabilities.artifacts);
+      expect(defaultAgentCapabilities).toContain(AgentCapabilities.actions);
+      expect(defaultAgentCapabilities).toContain(AgentCapabilities.context);
+      expect(defaultAgentCapabilities).toContain(AgentCapabilities.tools);
+      expect(defaultAgentCapabilities).toContain(AgentCapabilities.chain);
+      expect(defaultAgentCapabilities).toContain(AgentCapabilities.ocr);
+    });
+  });
+
+  describe('deferredToolsEnabled integration', () => {
+    it('should correctly determine deferredToolsEnabled from capabilities set', () => {
+      const createCheckCapability = (enabledCapabilities) => {
+        return (capability) => enabledCapabilities.has(capability);
+      };
+
+      // When deferred_tools is in capabilities
+      const withDeferred = new Set([AgentCapabilities.deferred_tools, AgentCapabilities.tools]);
+      const checkWithDeferred = createCheckCapability(withDeferred);
+      expect(checkWithDeferred(AgentCapabilities.deferred_tools)).toBe(true);
+
+      // When deferred_tools is NOT in capabilities
+      const withoutDeferred = new Set([AgentCapabilities.tools, AgentCapabilities.actions]);
+      const checkWithoutDeferred = createCheckCapability(withoutDeferred);
+      expect(checkWithoutDeferred(AgentCapabilities.deferred_tools)).toBe(false);
+    });
+
+    it('should use defaultAgentCapabilities when no capabilities configured', () => {
+      // Simulates the fallback behavior in loadAgentTools
+      const endpointsConfig = {}; // No capabilities configured
+      const enabledCapabilities = new Set(
+        endpointsConfig?.capabilities ?? defaultAgentCapabilities,
+      );
+
+      expect(enabledCapabilities.has(AgentCapabilities.deferred_tools)).toBe(true);
+    });
+  });
+});