@librechat/agents 3.1.67 → 3.1.68-dev.0

package/src/specs/subagent.test.ts

@@ -0,0 +1,305 @@
+import { HumanMessage } from '@langchain/core/messages';
+import { FakeListChatModel } from '@langchain/core/utils/testing';
+import type { ToolCall } from '@langchain/core/messages/tool';
+import type { RunnableConfig } from '@langchain/core/runnables';
+import type * as t from '@/types';
+import { Run } from '@/run';
+import {
+  Constants,
+  GraphEvents,
+  Providers,
+  ToolEndHandler,
+  ModelEndHandler,
+  StandardGraph,
+} from '@/index';
+import * as providers from '@/llm/providers';
+
+const CHILD_RESPONSE = 'Research result: Paris is the capital of France.';
+
+const callerConfig: Partial<RunnableConfig> & {
+  version: 'v1' | 'v2';
+  streamMode: string;
+} = {
+  configurable: { thread_id: 'subagent-test-thread' },
+  streamMode: 'values',
+  version: 'v2' as const,
+};
+
+const createParentAgent = (): t.AgentInputs => ({
+  agentId: 'parent',
+  provider: Providers.OPENAI,
+  clientOptions: { modelName: 'gpt-4o-mini', apiKey: 'test-key' },
+  instructions:
+    'You are a supervisor. Delegate research tasks using the subagent tool.',
+  maxContextTokens: 8000,
+  subagentConfigs: [
+    {
+      type: 'researcher',
+      name: 'Research Agent',
+      description: 'Researches and summarizes information',
+      agentInputs: {
+        agentId: 'researcher',
+        provider: Providers.OPENAI,
+        clientOptions: { modelName: 'gpt-4o-mini', apiKey: 'test-key' },
+        instructions: 'You are a research agent. Answer concisely.',
+        maxContextTokens: 8000,
+      },
+    },
+  ],
+});
+
+describe('Subagent Integration', () => {
+  jest.setTimeout(30000);
+
+  let getChatModelClassSpy: jest.SpyInstance;
+  const originalGetChatModelClass = providers.getChatModelClass;
+
+  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('should create subagent tool on agent context', async () => {
+    const run = await Run.create<t.IState>({
+      runId: `subagent-test-${Date.now()}`,
+      graphConfig: {
+        type: 'standard',
+        agents: [createParentAgent()],
+      },
+      returnContent: true,
+      skipCleanup: true,
+    });
+
+    expect(run.Graph).toBeDefined();
+    const parentContext = (run.Graph as StandardGraph).agentContexts.get(
+      'parent'
+    );
+    expect(parentContext).toBeDefined();
+    expect(parentContext?.graphTools).toBeDefined();
+
+    const subagentTool = (parentContext?.graphTools as t.GenericTool[]).find(
+      (t) => 'name' in t && t.name === Constants.SUBAGENT
+    );
+    expect(subagentTool).toBeDefined();
+  });
+
+  it('should execute subagent and return filtered result to parent', async () => {
+    const customHandlers: Record<string, t.EventHandler> = {
+      [GraphEvents.TOOL_END]: new ToolEndHandler(),
+      [GraphEvents.CHAT_MODEL_END]: new ModelEndHandler(),
+    };
+
+    const run = await Run.create<t.IState>({
+      runId: `subagent-exec-${Date.now()}`,
+      graphConfig: {
+        type: 'standard',
+        agents: [createParentAgent()],
+      },
+      returnContent: true,
+      skipCleanup: true,
+      customHandlers,
+    });
+
+    const subagentToolCall: ToolCall = {
+      id: 'call_subagent_1',
+      name: Constants.SUBAGENT,
+      args: {
+        description: 'What is the capital of France?',
+        subagent_type: 'researcher',
+      },
+      type: 'tool_call',
+    };
+
+    run.Graph?.overrideTestModel(
+      [
+        'Let me delegate this research task.',
+        `Based on the research: ${CHILD_RESPONSE}`,
+      ],
+      10,
+      [subagentToolCall]
+    );
+
+    const result = await run.processStream(
+      { messages: [new HumanMessage('What is the capital of France?')] },
+      callerConfig
+    );
+
+    expect(result).toBeDefined();
+
+    const runMessages = run.getRunMessages();
+    expect(runMessages).toBeDefined();
+    expect(runMessages!.length).toBeGreaterThan(0);
+
+    const toolMessages = runMessages!.filter(
+      (msg) => msg._getType() === 'tool'
+    );
+    const subagentResult = toolMessages.find(
+      (msg) => 'name' in msg && msg.name === Constants.SUBAGENT
+    );
+    expect(subagentResult).toBeDefined();
+    expect(String(subagentResult!.content)).toContain('Paris');
+  });
+
+  it('should not create subagent tool when no subagentConfigs', async () => {
+    const agentWithoutSubagents: t.AgentInputs = {
+      agentId: 'plain',
+      provider: Providers.OPENAI,
+      clientOptions: { modelName: 'gpt-4o-mini', apiKey: 'test-key' },
+      instructions: 'Plain agent without subagents.',
+      maxContextTokens: 8000,
+    };
+
+    const run = await Run.create<t.IState>({
+      runId: `no-subagent-${Date.now()}`,
+      graphConfig: {
+        type: 'standard',
+        agents: [agentWithoutSubagents],
+      },
+      returnContent: true,
+      skipCleanup: true,
+    });
+
+    const context = (run.Graph as StandardGraph).agentContexts.get('plain');
+    const tools = context?.graphTools as t.GenericTool[] | undefined;
+    const subagentTool = tools?.find(
+      (t) => 'name' in t && t.name === Constants.SUBAGENT
+    );
+    expect(subagentTool).toBeUndefined();
+  });
+
+  it('should handle self-spawn subagent config', async () => {
+    const agentWithSelfSpawn: t.AgentInputs = {
+      agentId: 'self-parent',
+      provider: Providers.OPENAI,
+      clientOptions: { modelName: 'gpt-4o-mini', apiKey: 'test-key' },
+      instructions: 'Agent with self-spawn for context isolation.',
+      maxContextTokens: 8000,
+      subagentConfigs: [
+        {
+          type: 'isolated',
+          name: 'Isolated Worker',
+          description: 'Runs a task with isolated context',
+          self: true,
+        },
+      ],
+    };
+
+    const run = await Run.create<t.IState>({
+      runId: `self-spawn-${Date.now()}`,
+      graphConfig: {
+        type: 'standard',
+        agents: [agentWithSelfSpawn],
+      },
+      returnContent: true,
+      skipCleanup: true,
+    });
+
+    const context = (run.Graph as StandardGraph).agentContexts.get(
+      'self-parent'
+    );
+    const tools = context?.graphTools as t.GenericTool[] | undefined;
+    const subagentTool = tools?.find(
+      (t) => 'name' in t && t.name === Constants.SUBAGENT
+    );
+    expect(subagentTool).toBeDefined();
+  });
+
+  it('should not create subagent tool when maxSubagentDepth is 0', async () => {
+    const agentWithZeroDepth: t.AgentInputs = {
+      ...createParentAgent(),
+      agentId: 'zero-depth',
+      maxSubagentDepth: 0,
+    };
+
+    const run = await Run.create<t.IState>({
+      runId: `zero-depth-${Date.now()}`,
+      graphConfig: {
+        type: 'standard',
+        agents: [agentWithZeroDepth],
+      },
+      returnContent: true,
+      skipCleanup: true,
+    });
+
+    const context = (run.Graph as StandardGraph).agentContexts.get(
+      'zero-depth'
+    );
+    const tools = context?.graphTools as t.GenericTool[] | undefined;
+    const subagentTool = tools?.find(
+      (t) => 'name' in t && t.name === Constants.SUBAGENT
+    );
+    expect(subagentTool).toBeUndefined();
+  });
+
+  it('should account for subagent tool schema in toolSchemaTokens', async () => {
+    /** Simple char-count tokenizer — deterministic, lets us assert presence. */
+    const tokenCounter: t.TokenCounter = (message) => {
+      const content = message.content;
+      if (typeof content === 'string') return content.length;
+      if (Array.isArray(content)) return JSON.stringify(content).length;
+      return JSON.stringify(content).length;
+    };
+
+    const agentWithSubagent = createParentAgent();
+    const runWith = await Run.create<t.IState>({
+      runId: `with-sub-${Date.now()}`,
+      graphConfig: {
+        type: 'standard',
+        agents: [agentWithSubagent],
+      },
+      tokenCounter,
+      returnContent: true,
+      skipCleanup: true,
+    });
+
+    const agentWithoutSubagent: t.AgentInputs = {
+      agentId: 'plain',
+      provider: Providers.OPENAI,
+      clientOptions: { modelName: 'gpt-4o-mini', apiKey: 'test-key' },
+      instructions:
+        'You are a supervisor. Delegate research tasks using the subagent tool.',
+      maxContextTokens: 8000,
+    };
+    const runWithout = await Run.create<t.IState>({
+      runId: `without-sub-${Date.now()}`,
+      graphConfig: {
+        type: 'standard',
+        agents: [agentWithoutSubagent],
+      },
+      tokenCounter,
+      returnContent: true,
+      skipCleanup: true,
+    });
+
+    const contextWith = (runWith.Graph as StandardGraph).agentContexts.get(
+      'parent'
+    );
+    const contextWithout = (
+      runWithout.Graph as StandardGraph
+    ).agentContexts.get('plain');
+
+    await contextWith?.tokenCalculationPromise;
+    await contextWithout?.tokenCalculationPromise;
+
+    /** Subagent tool schema is ~600 chars; expect measurable difference. */
+    expect(contextWith!.toolSchemaTokens).toBeGreaterThan(
+      contextWithout!.toolSchemaTokens
+    );
+  });
+});

package/src/summarization/__tests__/node.test.ts

@@ -343,6 +343,48 @@ describe('createSummarizeNode', () => {
     ).toBeUndefined();
   });
 
+  it('catches model initialization errors and falls back to metadata stub', async () => {
+    captureEvents();
+
+    /**
+     * Simulate the "Unsupported LLM provider" case — e.g. when a caller
+     * forwards an unrecognized provider name (custom-endpoint label) that
+     * getChatModelClass cannot resolve. Prior to the defense-in-depth fix,
+     * this error was thrown outside the try/catch in executeSummarizationWithFallback
+     * and bubbled up silently. Now it is caught and the metadata stub is used.
+     */
+    jest.spyOn(providers, 'getChatModelClass').mockImplementation(() => {
+      throw new Error('Unsupported LLM provider: Ollama');
+    });
+
+    const setSummary = jest.fn();
+    const agentContext = createAgentContext({ setSummary } as never);
+    const graph = mockGraph();
+    const node = createSummarizeNode({
+      agentContext,
+      graph,
+      generateStepId,
+    });
+
+    await expect(
+      node(
+        {
+          messages: [new HumanMessage('Test message')],
+          summarizationRequest: {
+            remainingContextTokens: 1000,
+            agentId: 'agent_0',
+          },
+        },
+        {} as RunnableConfig
+      )
+    ).resolves.not.toThrow();
+
+    expect(setSummary).toHaveBeenCalledWith(
+      expect.stringContaining('[Metadata summary:'),
+      expect.any(Number)
+    );
+  });
+
   it('falls back to metadata stub when primary LLM call fails', async () => {
     captureEvents();
 

package/src/summarization/__tests__/trigger.test.ts

@@ -1,4 +1,7 @@
-import { shouldTriggerSummarization } from '@/summarization';
+import {
+  shouldTriggerSummarization,
+  _resetUnrecognizedTriggerWarnings,
+} from '@/summarization';
 
 describe('shouldTriggerSummarization', () => {
   it('uses pre-prune pressure for token_ratio triggers when messages were pruned', () => {
@@ -47,4 +50,100 @@ describe('shouldTriggerSummarization', () => {
 
     expect(result).toBe(false);
   });
+
+  describe('unrecognized trigger type', () => {
+    let warnSpy: jest.SpyInstance;
+
+    beforeEach(() => {
+      _resetUnrecognizedTriggerWarnings();
+      warnSpy = jest.spyOn(console, 'warn').mockImplementation(() => undefined);
+    });
+
+    afterEach(() => {
+      warnSpy.mockRestore();
+    });
+
+    it('does not fire and warns once per unrecognized type', () => {
+      const baseParams = {
+        maxContextTokens: 2500,
+        prePruneContextTokens: 2400,
+        remainingContextTokens: 100,
+        messagesToRefineCount: 4,
+      };
+
+      // Cast via `unknown` because the type union guards against this at compile
+      // time; we are intentionally exercising the runtime fallback.
+      const result1 = shouldTriggerSummarization({
+        ...baseParams,
+        trigger: { type: 'token_count', value: 8000 } as unknown as {
+          type: 'token_ratio';
+          value: number;
+        },
+      });
+
+      expect(result1).toBe(false);
+      expect(warnSpy).toHaveBeenCalledTimes(1);
+      expect(warnSpy.mock.calls[0][0]).toContain('token_count');
+      expect(warnSpy.mock.calls[0][0]).toContain('token_ratio');
+      expect(warnSpy.mock.calls[0][0]).toContain('remaining_tokens');
+      expect(warnSpy.mock.calls[0][0]).toContain('messages_to_refine');
+
+      // Same unrecognized type a second time: no duplicate warning.
+      shouldTriggerSummarization({
+        ...baseParams,
+        trigger: { type: 'token_count', value: 8000 } as unknown as {
+          type: 'token_ratio';
+          value: number;
+        },
+      });
+      expect(warnSpy).toHaveBeenCalledTimes(1);
+
+      // Different unrecognized type: warns again, once.
+      shouldTriggerSummarization({
+        ...baseParams,
+        trigger: { type: 'nonsense', value: 1 } as unknown as {
+          type: 'token_ratio';
+          value: number;
+        },
+      });
+      expect(warnSpy).toHaveBeenCalledTimes(2);
+      expect(warnSpy.mock.calls[1][0]).toContain('nonsense');
+    });
+
+    it('does not grow memory unboundedly under a flood of unique types', () => {
+      const baseParams = {
+        maxContextTokens: 2500,
+        prePruneContextTokens: 2400,
+        remainingContextTokens: 100,
+        messagesToRefineCount: 4,
+      };
+
+      for (let i = 0; i < 500; i++) {
+        shouldTriggerSummarization({
+          ...baseParams,
+          trigger: { type: `bogus-${i}`, value: 1 } as unknown as {
+            type: 'token_ratio';
+            value: number;
+          },
+        });
+      }
+
+      // Still logged each new type (up to the cap) — we never silently dropped
+      // warnings; we just evicted oldest entries from the dedup set.
+      expect(warnSpy).toHaveBeenCalledTimes(500);
+
+      // Re-warns for a recently-seen type that should still be in the cache
+      // (last one just inserted). No duplicate warning means the dedup set
+      // still functions; the size cap did not break the dedup contract.
+      const beforeRecent = warnSpy.mock.calls.length;
+      shouldTriggerSummarization({
+        ...baseParams,
+        trigger: { type: 'bogus-499', value: 1 } as unknown as {
+          type: 'token_ratio';
+          value: number;
+        },
+      });
+      expect(warnSpy).toHaveBeenCalledTimes(beforeRecent);
+    });
+  });
 });

package/src/summarization/index.ts

@@ -1,5 +1,51 @@
 import type { SummarizationTrigger } from '@/types';
 
+const VALID_TRIGGER_TYPES = [
+  'token_ratio',
+  'remaining_tokens',
+  'messages_to_refine',
+] as const;
+
+/**
+ * Upper bound on the dedup set for unrecognized trigger types. Bounds memory in
+ * case a caller threads dynamic/user-provided strings through `trigger.type`.
+ * Well above the handful of legit misconfigurations a process would ever see.
+ */
+const MAX_WARNED_TRIGGER_TYPES = 32;
+
+const warnedUnrecognizedTriggerTypes = new Set<string>();
+
+/**
+ * Warn (once per process, per unrecognized type) when the configured trigger
+ * type is something the runtime does not evaluate. Without this, a misconfigured
+ * `trigger.type` silently disables summarization with no visible signal.
+ *
+ * The dedup set is size-capped; on overflow we evict the oldest entry (Set
+ * preserves insertion order) so we keep bounded memory and still warn on
+ * recently-seen types.
+ */
+function warnUnrecognizedTriggerType(type: string): void {
+  if (warnedUnrecognizedTriggerTypes.has(type)) {
+    return;
+  }
+  if (warnedUnrecognizedTriggerTypes.size >= MAX_WARNED_TRIGGER_TYPES) {
+    const oldest = warnedUnrecognizedTriggerTypes.values().next().value;
+    if (oldest !== undefined) {
+      warnedUnrecognizedTriggerTypes.delete(oldest);
+    }
+  }
+  warnedUnrecognizedTriggerTypes.add(type);
+  console.warn(
+    `[shouldTriggerSummarization] Unrecognized trigger.type: "${type}". ` +
+      `Summarization will not fire. Valid values: ${VALID_TRIGGER_TYPES.join(', ')}.`
+  );
+}
+
+/** For tests only. Resets the dedup set so warnings can be observed again. */
+export function _resetUnrecognizedTriggerWarnings(): void {
+  warnedUnrecognizedTriggerTypes.clear();
+}
+
 /**
  * Determines whether summarization should be triggered based on the configured trigger
  * and current context state.
@@ -98,5 +144,6 @@ export function shouldTriggerSummarization(params: {
   }
 
   // Unrecognized trigger type: cannot evaluate, do not fire.
+  warnUnrecognizedTriggerType(trigger.type);
   return false;
 }