@librechat/agents 3.1.67-dev.4 → 3.1.68

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

@@ -1,149 +0,0 @@
-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__/skillCatalog.test.ts

@@ -1,161 +0,0 @@
-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

@@ -1,215 +0,0 @@
-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'
-    );
-  });
-});

package/src/tools/skillCatalog.ts

@@ -1,126 +0,0 @@
-// src/tools/skillCatalog.ts
-import type { SkillCatalogEntry } from '@/types';
-
-const HEADER = '## Available Skills';
-const DEFAULT_CONTEXT_WINDOW_TOKENS = 200_000;
-const DEFAULT_BUDGET_PERCENT = 0.01;
-const DEFAULT_MAX_ENTRY_CHARS = 250;
-const DEFAULT_MIN_DESC_LENGTH = 20;
-const DEFAULT_CHARS_PER_TOKEN = 4;
-
-export type SkillCatalogOptions = {
-  /** Total context window in tokens. Default: 200_000 */
-  contextWindowTokens?: number;
-  /** Fraction of context budget for catalog. Default: 0.01 (1%) */
-  budgetPercent?: number;
-  /** Max chars per entry description. Default: 250 */
-  maxEntryChars?: number;
-  /** Descriptions below this length trigger names-only fallback. Default: 20 */
-  minDescLength?: number;
-  /** Approximate chars per token for budget calculation. Default: 4 */
-  charsPerToken?: number;
-};
-
-/**
- * Formats a skill catalog for injection into agent context.
- * Uses a truncation ladder: full descriptions, proportional truncation, names-only.
- * Returns empty string for empty input.
- */
-export function formatSkillCatalog(
-  skills: SkillCatalogEntry[],
-  opts?: SkillCatalogOptions
-): string {
-  if (skills.length === 0) return '';
-
-  const contextWindowTokens =
-    opts?.contextWindowTokens ?? DEFAULT_CONTEXT_WINDOW_TOKENS;
-  const budgetPercent = opts?.budgetPercent ?? DEFAULT_BUDGET_PERCENT;
-  const maxEntryChars = Math.max(
-    1,
-    opts?.maxEntryChars ?? DEFAULT_MAX_ENTRY_CHARS
-  );
-  const minDescLength = opts?.minDescLength ?? DEFAULT_MIN_DESC_LENGTH;
-  const charsPerToken = opts?.charsPerToken ?? DEFAULT_CHARS_PER_TOKEN;
-
-  const budgetChars = Math.floor(
-    contextWindowTokens * budgetPercent * charsPerToken
-  );
-
-  const capped = skills.map((s) => ({
-    name: s.name,
-    description:
-      s.description.length > maxEntryChars
-        ? s.description.slice(0, maxEntryChars - 1) + '\u2026'
-        : s.description,
-  }));
-
-  const fullOutput = formatEntries(capped);
-  if (fullOutput.length <= budgetChars) return fullOutput;
-
-  const headerLen = HEADER.length + 2;
-  const newlineChars = capped.length > 1 ? capped.length - 1 : 0;
-  const availableChars = budgetChars - headerLen - newlineChars;
-  const perEntryOverhead = 4;
-  const nameCharsTotal = capped.reduce(
-    (sum, s) => sum + s.name.length + perEntryOverhead,
-    0
-  );
-  const availableForDescs = availableChars - nameCharsTotal;
-
-  if (availableForDescs <= 0) {
-    return fitNamesOnly(capped, budgetChars);
-  }
-
-  const maxDescPerEntry = Math.floor(availableForDescs / capped.length);
-
-  if (maxDescPerEntry < minDescLength) {
-    return fitNamesOnly(capped, budgetChars);
-  }
-
-  const truncated = capped.map((s) => ({
-    name: s.name,
-    description:
-      s.description.length > maxDescPerEntry
-        ? s.description.slice(0, maxDescPerEntry - 1) + '\u2026'
-        : s.description,
-  }));
-
-  const result = formatEntries(truncated);
-  if (result.length <= budgetChars) return result;
-  return fitNamesOnly(capped, budgetChars);
-}
-
-function formatEntries(
-  entries: { name: string; description: string }[]
-): string {
-  const lines = entries.map((e) =>
-    e.description ? `- ${e.name}: ${e.description}` : `- ${e.name}`
-  );
-  return `${HEADER}\n\n${lines.join('\n')}`;
-}
-
-/** Names-only fallback that drops trailing entries if the list still exceeds budget. */
-function fitNamesOnly(
-  entries: { name: string }[],
-  budgetChars: number
-): string {
-  // Format: "HEADER\n\n- name1\n- name2\n..."
-  // Running sum avoids O(n²) repeated string construction.
-  const prefix = HEADER.length + 2; // "HEADER\n\n"
-  const entryOverhead = 2; // "- "
-  let total = prefix;
-  let fitCount = 0;
-
-  for (let i = 0; i < entries.length; i++) {
-    const added = (i > 0 ? 1 : 0) + entryOverhead + entries[i].name.length;
-    if (total + added > budgetChars) break;
-    total += added;
-    fitCount = i + 1;
-  }
-
-  if (fitCount === 0) return '';
-  const namesOnly = entries
-    .slice(0, fitCount)
-    .map((s) => ({ name: s.name, description: '' }));
-  return formatEntries(namesOnly);
-}