@librechat/agents 3.1.67 → 3.1.68-dev.0

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

@@ -0,0 +1,149 @@
+import { describe, it, expect } from '@jest/globals';
+import { Constants } from '@/common';
+import {
+  SubagentToolName,
+  SubagentToolDescription,
+  SubagentToolDefinition,
+  SubagentToolSchema,
+  createSubagentToolDefinition,
+  buildSubagentToolParams,
+} from '../SubagentTool';
+import type { SubagentConfig } from '@/types';
+
+describe('SubagentTool', () => {
+  describe('schema structure', () => {
+    it('has description as required string property', () => {
+      expect(SubagentToolSchema.properties.description.type).toBe('string');
+      expect(SubagentToolSchema.required).toContain('description');
+    });
+
+    it('has subagent_type as required string property', () => {
+      expect(SubagentToolSchema.properties.subagent_type.type).toBe('string');
+      expect(SubagentToolSchema.required).toContain('subagent_type');
+    });
+
+    it('is an object type schema', () => {
+      expect(SubagentToolSchema.type).toBe('object');
+    });
+  });
+
+  describe('SubagentToolDefinition', () => {
+    it('has correct name', () => {
+      expect(SubagentToolDefinition.name).toBe(Constants.SUBAGENT);
+    });
+
+    it('references the same schema object', () => {
+      expect(SubagentToolDefinition.parameters).toBe(SubagentToolSchema);
+    });
+
+    it('has a non-empty description', () => {
+      expect(SubagentToolDefinition.description).toBe(SubagentToolDescription);
+      expect(SubagentToolDefinition.description!.length).toBeGreaterThan(0);
+    });
+  });
+
+  describe('SubagentToolName', () => {
+    it('equals Constants.SUBAGENT', () => {
+      expect(SubagentToolName).toBe('subagent');
+      expect(SubagentToolName).toBe(Constants.SUBAGENT);
+    });
+  });
+
+  describe('createSubagentToolDefinition', () => {
+    const configs: SubagentConfig[] = [
+      {
+        type: 'researcher',
+        name: 'Research Agent',
+        description: 'Searches and summarizes information',
+      },
+      {
+        type: 'coder',
+        name: 'Coding Agent',
+        description: 'Writes and reviews code',
+      },
+    ];
+
+    it('populates subagent_type enum from configs', () => {
+      const def = createSubagentToolDefinition(configs);
+      const schema = def.parameters as Record<string, unknown>;
+      const props = schema.properties as Record<
+        string,
+        Record<string, unknown>
+      >;
+      expect(props.subagent_type.enum).toEqual(['researcher', 'coder']);
+    });
+
+    it('includes type descriptions in tool description', () => {
+      const def = createSubagentToolDefinition(configs);
+      expect(def.description).toContain('"researcher" (Research Agent)');
+      expect(def.description).toContain('"coder" (Coding Agent)');
+      expect(def.description).toContain('Searches and summarizes information');
+      expect(def.description).toContain('Writes and reviews code');
+    });
+
+    it('has correct name', () => {
+      const def = createSubagentToolDefinition(configs);
+      expect(def.name).toBe(Constants.SUBAGENT);
+    });
+
+    it('has required description and subagent_type fields', () => {
+      const def = createSubagentToolDefinition(configs);
+      const schema = def.parameters as Record<string, unknown>;
+      expect(schema.required).toContain('description');
+      expect(schema.required).toContain('subagent_type');
+    });
+
+    it('works with single config', () => {
+      const def = createSubagentToolDefinition([configs[0]]);
+      const schema = def.parameters as Record<string, unknown>;
+      const props = schema.properties as Record<
+        string,
+        Record<string, unknown>
+      >;
+      expect(props.subagent_type.enum).toEqual(['researcher']);
+    });
+  });
+
+  describe('buildSubagentToolParams', () => {
+    const configs: SubagentConfig[] = [
+      {
+        type: 'researcher',
+        name: 'Research Agent',
+        description: 'Searches and summarizes information',
+      },
+      {
+        type: 'coder',
+        name: 'Coding Agent',
+        description: 'Writes and reviews code',
+      },
+    ];
+
+    it('returns name matching Constants.SUBAGENT', () => {
+      const params = buildSubagentToolParams(configs);
+      expect(params.name).toBe(Constants.SUBAGENT);
+    });
+
+    it('schema has enum populated from config types', () => {
+      const params = buildSubagentToolParams(configs);
+      const props = params.schema.properties as Record<
+        string,
+        Record<string, unknown>
+      >;
+      expect(props.subagent_type.enum).toEqual(['researcher', 'coder']);
+    });
+
+    it('description includes type listings', () => {
+      const params = buildSubagentToolParams(configs);
+      expect(params.description).toContain('"researcher" (Research Agent)');
+      expect(params.description).toContain('"coder" (Coding Agent)');
+    });
+
+    it('produces same schema as createSubagentToolDefinition', () => {
+      const params = buildSubagentToolParams(configs);
+      const def = createSubagentToolDefinition(configs);
+      expect(params.name).toBe(def.name);
+      expect(params.description).toBe(def.description);
+      expect(params.schema).toEqual(def.parameters);
+    });
+  });
+});

package/src/tools/__tests__/ToolNode.session.test.ts

@@ -216,7 +216,7 @@ describe('ToolNode code execution session management', () => {
         toolNode as unknown as {
           storeCodeSessionFromResults: (
             results: t.ToolExecuteResult[],
-            requests: t.ToolCallRequest[]
+            requestMap: Map<string, t.ToolCallRequest>
           ) => void;
         }
       ).storeCodeSessionFromResults.bind(toolNode);
@@ -233,7 +233,7 @@ describe('ToolNode code execution session management', () => {
             status: 'success',
           },
         ],
-        [{ id: 'tc1', name: Constants.EXECUTE_CODE, args: {} }]
+        new Map([['tc1', { id: 'tc1', name: Constants.EXECUTE_CODE, args: {} }]])
       );
 
       const stored = sessions.get(
@@ -265,7 +265,7 @@ describe('ToolNode code execution session management', () => {
         toolNode as unknown as {
           storeCodeSessionFromResults: (
             results: t.ToolExecuteResult[],
-            requests: t.ToolCallRequest[]
+            requestMap: Map<string, t.ToolCallRequest>
           ) => void;
         }
       ).storeCodeSessionFromResults.bind(toolNode);
@@ -279,7 +279,7 @@ describe('ToolNode code execution session management', () => {
             status: 'success',
           },
         ],
-        [{ id: 'tc2', name: Constants.EXECUTE_CODE, args: {} }]
+        new Map([['tc2', { id: 'tc2', name: Constants.EXECUTE_CODE, args: {} }]])
       );
 
       const stored = sessions.get(
@@ -312,7 +312,7 @@ describe('ToolNode code execution session management', () => {
         toolNode as unknown as {
           storeCodeSessionFromResults: (
             results: t.ToolExecuteResult[],
-            requests: t.ToolCallRequest[]
+            requestMap: Map<string, t.ToolCallRequest>
           ) => void;
         }
       ).storeCodeSessionFromResults.bind(toolNode);
@@ -329,7 +329,7 @@ describe('ToolNode code execution session management', () => {
             status: 'success',
           },
         ],
-        [{ id: 'tc3', name: Constants.EXECUTE_CODE, args: {} }]
+        new Map([['tc3', { id: 'tc3', name: Constants.EXECUTE_CODE, args: {} }]])
       );
 
       const stored = sessions.get(
@@ -365,7 +365,7 @@ describe('ToolNode code execution session management', () => {
         toolNode as unknown as {
           storeCodeSessionFromResults: (
             results: t.ToolExecuteResult[],
-            requests: t.ToolCallRequest[]
+            requestMap: Map<string, t.ToolCallRequest>
           ) => void;
         }
       ).storeCodeSessionFromResults.bind(toolNode);
@@ -379,7 +379,7 @@ describe('ToolNode code execution session management', () => {
             status: 'success',
           },
         ],
-        [{ id: 'tc4', name: Constants.EXECUTE_CODE, args: {} }]
+        new Map([['tc4', { id: 'tc4', name: Constants.EXECUTE_CODE, args: {} }]])
       );
 
       const stored = sessions.get(
@@ -404,7 +404,7 @@ describe('ToolNode code execution session management', () => {
         toolNode as unknown as {
           storeCodeSessionFromResults: (
             results: t.ToolExecuteResult[],
-            requests: t.ToolCallRequest[]
+            requestMap: Map<string, t.ToolCallRequest>
           ) => void;
         }
       ).storeCodeSessionFromResults.bind(toolNode);
@@ -418,7 +418,7 @@ describe('ToolNode code execution session management', () => {
             status: 'success',
           },
         ],
-        [{ id: 'tc5', name: 'web_search', args: {} }]
+        new Map([['tc5', { id: 'tc5', name: 'web_search', args: {} }]])
       );
 
       expect(sessions.has(Constants.EXECUTE_CODE)).toBe(false);
@@ -438,7 +438,7 @@ describe('ToolNode code execution session management', () => {
         toolNode as unknown as {
           storeCodeSessionFromResults: (
             results: t.ToolExecuteResult[],
-            requests: t.ToolCallRequest[]
+            requestMap: Map<string, t.ToolCallRequest>
           ) => void;
         }
       ).storeCodeSessionFromResults.bind(toolNode);
@@ -456,7 +456,7 @@ describe('ToolNode code execution session management', () => {
             errorMessage: 'execution failed',
           },
         ],
-        [{ id: 'tc6', name: Constants.EXECUTE_CODE, args: {} }]
+        new Map([['tc6', { id: 'tc6', name: Constants.EXECUTE_CODE, args: {} }]])
       );
 
       expect(sessions.has(Constants.EXECUTE_CODE)).toBe(false);

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

@@ -0,0 +1,161 @@
+import { describe, it, expect } from '@jest/globals';
+import { formatSkillCatalog } from '../skillCatalog';
+import type { SkillCatalogEntry } from '@/types';
+
+describe('formatSkillCatalog', () => {
+  it('returns empty string for empty array', () => {
+    expect(formatSkillCatalog([])).toBe('');
+  });
+
+  it('formats a single skill with header', () => {
+    const skills: SkillCatalogEntry[] = [
+      {
+        name: 'pdf-processor',
+        description: 'Processes PDF files into structured data.',
+      },
+    ];
+    const result = formatSkillCatalog(skills);
+    expect(result).toBe(
+      '## Available Skills\n\n- pdf-processor: Processes PDF files into structured data.'
+    );
+  });
+
+  it('formats multiple skills within budget', () => {
+    const skills: SkillCatalogEntry[] = [
+      { name: 'pdf-processor', description: 'Processes PDF files.' },
+      { name: 'review-pr', description: 'Reviews pull requests.' },
+      { name: 'meeting-notes', description: 'Formats meeting transcripts.' },
+    ];
+    const result = formatSkillCatalog(skills);
+    expect(result).toContain('## Available Skills');
+    expect(result).toContain('- pdf-processor: Processes PDF files.');
+    expect(result).toContain('- review-pr: Reviews pull requests.');
+    expect(result).toContain('- meeting-notes: Formats meeting transcripts.');
+  });
+
+  it('caps per-entry descriptions at maxEntryChars', () => {
+    const longDesc = 'A'.repeat(300);
+    const skills: SkillCatalogEntry[] = [
+      { name: 'long-skill', description: longDesc },
+    ];
+    const result = formatSkillCatalog(skills);
+    expect(result).toContain('- long-skill: ' + 'A'.repeat(249) + '\u2026');
+    expect(result).not.toContain('A'.repeat(300));
+  });
+
+  it('truncates descriptions proportionally when over budget', () => {
+    const skills: SkillCatalogEntry[] = Array.from({ length: 10 }, (_, i) => ({
+      name: `sk-${i}`,
+      description: 'D'.repeat(200),
+    }));
+    // Budget = 10000 * 0.01 * 4 = 400 chars — enough for names + short descs, not full 200-char descs
+    const result = formatSkillCatalog(skills, {
+      contextWindowTokens: 10000,
+      budgetPercent: 0.01,
+      charsPerToken: 4,
+    });
+    expect(result).toContain('## Available Skills');
+    for (let i = 0; i < 10; i++) {
+      expect(result).toContain(`sk-${i}`);
+    }
+    // Full 200-char descriptions should be truncated
+    expect(result).not.toContain('D'.repeat(200));
+  });
+
+  it('falls back to names-only when extremely over budget', () => {
+    const skills: SkillCatalogEntry[] = Array.from({ length: 10 }, (_, i) => ({
+      name: `s${i}`,
+      description: 'Very detailed description that is quite long and verbose.',
+    }));
+    // Budget = 2000 * 0.01 * 4 = 80 chars — enough for names-only but not descriptions
+    const result = formatSkillCatalog(skills, {
+      contextWindowTokens: 2000,
+      budgetPercent: 0.01,
+      charsPerToken: 4,
+    });
+    expect(result).toContain('## Available Skills');
+    expect(result).toContain('- s0');
+    // Verify entry lines have no descriptions (names-only format)
+    const entryLines = result.split('\n').filter((l) => l.startsWith('- '));
+    for (const line of entryLines) {
+      expect(line).toMatch(/^- s\d+$/);
+    }
+  });
+
+  it('respects custom options', () => {
+    const skills: SkillCatalogEntry[] = [
+      { name: 'test', description: 'A'.repeat(100) },
+    ];
+    const result = formatSkillCatalog(skills, { maxEntryChars: 50 });
+    expect(result).toContain('A'.repeat(49) + '\u2026');
+    expect(result).not.toContain('A'.repeat(100));
+  });
+
+  it('includes skills with descriptions shorter than minDescLength', () => {
+    const skills: SkillCatalogEntry[] = [
+      { name: 'short', description: 'Hi' },
+      { name: 'normal', description: 'A normal description here.' },
+    ];
+    const result = formatSkillCatalog(skills);
+    expect(result).toContain('- short: Hi');
+    expect(result).toContain('- normal: A normal description here.');
+  });
+
+  it('handles all skills with zero-length descriptions as names-only', () => {
+    const skills: SkillCatalogEntry[] = [
+      { name: 'alpha', description: '' },
+      { name: 'beta', description: '' },
+    ];
+    const result = formatSkillCatalog(skills);
+    expect(result).toBe('## Available Skills\n\n- alpha\n- beta');
+  });
+
+  it('has no trailing or leading whitespace', () => {
+    const skills: SkillCatalogEntry[] = [
+      { name: 'test', description: 'A test skill.' },
+    ];
+    const result = formatSkillCatalog(skills);
+    expect(result).toBe(result.trim());
+    const lines = result.split('\n');
+    for (const line of lines) {
+      expect(line).toBe(line.trimEnd());
+    }
+  });
+
+  it('truncates names-only list when even names exceed budget', () => {
+    const skills: SkillCatalogEntry[] = Array.from({ length: 100 }, (_, i) => ({
+      name: `skill-with-a-long-name-${i}`,
+      description: 'Some description.',
+    }));
+    // Budget so small that even names-only for 100 skills exceeds it
+    const result = formatSkillCatalog(skills, {
+      contextWindowTokens: 100,
+      budgetPercent: 0.01,
+      charsPerToken: 4,
+    });
+    // Should still have the header and at least one entry, but not all 100
+    if (result === '') {
+      // Budget too small for even one entry — valid edge case
+      expect(result).toBe('');
+    } else {
+      expect(result).toContain('## Available Skills');
+      const entryLines = result.split('\n').filter((l) => l.startsWith('- '));
+      expect(entryLines.length).toBeLessThan(100);
+      expect(entryLines.length).toBeGreaterThan(0);
+      expect(result.length).toBeLessThanOrEqual(100 * 0.01 * 4);
+    }
+  });
+
+  it('ignores displayTitle in output', () => {
+    const skills: SkillCatalogEntry[] = [
+      {
+        name: 'my-skill',
+        description: 'Does stuff.',
+        displayTitle: 'My Fancy Skill',
+      },
+    ];
+    const result = formatSkillCatalog(skills);
+    expect(result).not.toContain('My Fancy Skill');
+    expect(result).toContain('- my-skill: Does stuff.');
+  });
+});

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

@@ -0,0 +1,215 @@
+import { HumanMessage } from '@langchain/core/messages';
+import { FakeListChatModel } from '@langchain/core/utils/testing';
+import type { ToolCall } from '@langchain/core/messages/tool';
+import type * as t from '@/types';
+import type {
+  HookCallback,
+  SubagentStartHookInput,
+  SubagentStartHookOutput,
+  SubagentStopHookInput,
+  SubagentStopHookOutput,
+} from '@/hooks/types';
+import { HookRegistry } from '@/hooks/HookRegistry';
+import { Run } from '@/run';
+import {
+  Constants,
+  GraphEvents,
+  Providers,
+  ToolEndHandler,
+  ModelEndHandler,
+} from '@/index';
+import * as providers from '@/llm/providers';
+
+const CHILD_RESPONSE = 'Hook test child response.';
+
+const callerConfig = {
+  configurable: { thread_id: 'hook-test-thread' },
+  streamMode: 'values' as const,
+  version: 'v2' as const,
+};
+
+const originalGetChatModelClass = providers.getChatModelClass;
+
+function makeSubagentToolCall(): ToolCall {
+  return {
+    name: Constants.SUBAGENT,
+    args: {
+      description: 'Test task for hook verification',
+      subagent_type: 'researcher',
+    },
+    id: `call_sub_${Date.now()}`,
+    type: 'tool_call',
+  };
+}
+
+function createParentAgent(): t.AgentInputs {
+  return {
+    agentId: 'hook-parent',
+    provider: Providers.OPENAI,
+    clientOptions: { modelName: 'gpt-4o-mini', apiKey: 'test-key' },
+    instructions: 'Delegate research tasks to subagents.',
+    maxContextTokens: 8000,
+    subagentConfigs: [
+      {
+        type: 'researcher',
+        name: 'Researcher',
+        description: 'Researches topics',
+        agentInputs: {
+          agentId: 'researcher-child',
+          provider: Providers.OPENAI,
+          clientOptions: { modelName: 'gpt-4o-mini', apiKey: 'test-key' },
+          instructions: 'Answer concisely.',
+          maxContextTokens: 8000,
+        },
+      },
+    ],
+  };
+}
+
+async function createSubagentRun(
+  hooks: HookRegistry,
+  runId = `subagent-hook-${Date.now()}`
+): Promise<Run<t.IState>> {
+  return Run.create<t.IState>({
+    runId,
+    graphConfig: {
+      type: 'standard',
+      agents: [createParentAgent()],
+    },
+    returnContent: true,
+    skipCleanup: true,
+    customHandlers: {
+      [GraphEvents.TOOL_END]: new ToolEndHandler(),
+      [GraphEvents.CHAT_MODEL_END]: new ModelEndHandler(),
+    },
+    hooks,
+  });
+}
+
+describe('Subagent hook integration (end-to-end via Run)', () => {
+  jest.setTimeout(15000);
+
+  let getChatModelClassSpy: jest.SpyInstance;
+
+  beforeEach(() => {
+    getChatModelClassSpy = jest
+      .spyOn(providers, 'getChatModelClass')
+      .mockImplementation(((provider: Providers) => {
+        if (provider === Providers.OPENAI) {
+          return class extends FakeListChatModel {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            constructor(_options: any) {
+              super({ responses: [CHILD_RESPONSE] });
+            }
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+          } as any;
+        }
+        return originalGetChatModelClass(provider);
+      }) as typeof providers.getChatModelClass);
+  });
+
+  afterEach(() => {
+    getChatModelClassSpy.mockRestore();
+  });
+
+  it('SubagentStart fires with correct payload through real Run pipeline', async () => {
+    const registry = new HookRegistry();
+    let captured: SubagentStartHookInput | undefined;
+
+    const hook: HookCallback<'SubagentStart'> = async (
+      input
+    ): Promise<SubagentStartHookOutput> => {
+      captured = input;
+      return {};
+    };
+    registry.register('SubagentStart', { hooks: [hook] });
+
+    const tc = makeSubagentToolCall();
+    const run = await createSubagentRun(registry);
+    run.Graph!.overrideTestModel(['Delegating...', 'Final answer.'], 5, [tc]);
+
+    await run.processStream(
+      { messages: [new HumanMessage('research something')] },
+      callerConfig
+    );
+
+    expect(captured).toBeDefined();
+    expect(captured!.hook_event_name).toBe('SubagentStart');
+    expect(captured!.agentType).toBe('researcher');
+    expect(captured!.parentAgentId).toBe('hook-parent');
+    expect(captured!.threadId).toBe('hook-test-thread');
+    expect(captured!.inputs).toHaveLength(1);
+    expect(captured!.inputs[0].content).toContain(
+      'Test task for hook verification'
+    );
+  });
+
+  it('SubagentStop fires with messages from child execution', async () => {
+    const registry = new HookRegistry();
+    let captured: SubagentStopHookInput | undefined;
+
+    const hook: HookCallback<'SubagentStop'> = async (
+      input
+    ): Promise<SubagentStopHookOutput> => {
+      captured = input;
+      return {};
+    };
+    registry.register('SubagentStop', { hooks: [hook] });
+
+    const tc = makeSubagentToolCall();
+    const run = await createSubagentRun(registry);
+    run.Graph!.overrideTestModel(['Delegating...', 'Final answer.'], 5, [tc]);
+
+    await run.processStream(
+      { messages: [new HumanMessage('research something')] },
+      callerConfig
+    );
+
+    expect(captured).toBeDefined();
+    expect(captured!.hook_event_name).toBe('SubagentStop');
+    expect(captured!.agentType).toBe('researcher');
+    expect(captured!.threadId).toBe('hook-test-thread');
+    expect(captured!.messages.length).toBeGreaterThan(0);
+  });
+
+  it('SubagentStart deny blocks subagent execution and returns blocked message', async () => {
+    const registry = new HookRegistry();
+    const denyHook: HookCallback<
+      'SubagentStart'
+    > = async (): Promise<SubagentStartHookOutput> => ({
+      decision: 'deny',
+      reason: 'policy violation',
+    });
+    registry.register('SubagentStart', {
+      pattern: '^researcher$',
+      hooks: [denyHook],
+    });
+
+    const tc = makeSubagentToolCall();
+    const run = await createSubagentRun(registry);
+    run.Graph!.overrideTestModel(
+      ['Delegating...', 'The subagent was blocked.'],
+      5,
+      [tc]
+    );
+
+    await run.processStream(
+      { messages: [new HumanMessage('research something')] },
+      callerConfig
+    );
+
+    const runMessages = run.getRunMessages();
+    expect(runMessages).toBeDefined();
+
+    const toolMessages = runMessages!.filter(
+      (msg) =>
+        msg._getType() === 'tool' &&
+        'name' in msg &&
+        msg.name === Constants.SUBAGENT
+    );
+    expect(toolMessages.length).toBe(1);
+    expect(String(toolMessages[0].content)).toContain(
+      'Blocked: policy violation'
+    );
+  });
+});