@librechat/agents 3.1.81 → 3.1.83

package/src/specs/agent-handoffs.test.ts

@@ -1,11 +1,13 @@
 // src/specs/agent-handoffs.test.ts
 import { DynamicStructuredTool } from '@langchain/core/tools';
-import { HumanMessage, ToolMessage } from '@langchain/core/messages';
+import { AIMessage, HumanMessage, ToolMessage } from '@langchain/core/messages';
 import type { ToolCall } from '@langchain/core/messages/tool';
 import type { RunnableConfig } from '@langchain/core/runnables';
 import type * as t from '@/types';
-import { Providers, Constants } from '@/common';
+import { Providers, GraphEvents, Constants } from '@/common';
 import { StandardGraph } from '@/graphs/Graph';
+import { ToolNode } from '@/tools/ToolNode';
+import * as events from '@/utils/events';
 import { Run } from '@/run';
 
 /**
@@ -989,5 +991,267 @@ describe('Agent Handoffs Tests', () => {
         `${Constants.LC_TRANSFER_TO_}AgentWithCamelCase`
       );
     });
+
+    it('should return exact-name guidance for handoff names with extra suffixes', async () => {
+      const agents: t.AgentInputs[] = [
+        createBasicAgent('router', 'You are a router'),
+        createBasicAgent('data_analyst', 'You are a data analyst'),
+      ];
+
+      const edges: t.GraphEdge[] = [
+        {
+          from: 'router',
+          to: 'data_analyst',
+          edgeType: 'handoff',
+        },
+      ];
+
+      const run = await Run.create(createTestConfig(agents, edges));
+      const correctName = `${Constants.LC_TRANSFER_TO_}data_analyst`;
+      const wrongName = `${correctName}_analyst`;
+
+      run.Graph?.overrideTestModel(
+        ['Trying to transfer', 'Stopping after invalid tool name'],
+        10,
+        [
+          {
+            id: 'tool_call_wrong_handoff',
+            name: wrongName,
+            args: { instructions: 'Analyze the uploaded data' },
+          } as ToolCall,
+        ]
+      );
+
+      const config: Partial<RunnableConfig> & {
+        version: 'v1' | 'v2';
+        streamMode: string;
+      } = {
+        configurable: {
+          thread_id: 'test-wrong-handoff-name-thread',
+        },
+        streamMode: 'values',
+        version: 'v2' as const,
+      };
+
+      await run.processStream(
+        { messages: [new HumanMessage('Please analyze my data')] },
+        config
+      );
+
+      const toolMessages = run
+        .getRunMessages()!
+        .filter((msg) => msg.getType() === 'tool') as ToolMessage[];
+      const wrongNameMessage = toolMessages.find(
+        (msg) => msg.name === wrongName
+      );
+
+      expect(wrongNameMessage).toBeDefined();
+      expect(wrongNameMessage?.status).toBe('error');
+      expect(wrongNameMessage?.content).toContain(
+        `Did you mean "${correctName}"`
+      );
+    });
+
+    it('should include toolMap handoffs when direct tool names are present', async () => {
+      const correctName = `${Constants.LC_TRANSFER_TO_}data_analyst`;
+      const wrongName = `${correctName}_analyst`;
+      const handoffTool = new DynamicStructuredTool({
+        name: correctName,
+        description: 'Transfer to data analyst',
+        schema: { type: 'object', properties: {}, required: [] },
+        func: async (): Promise<string> => 'transferred',
+      }) as t.GenericTool;
+      const node = new ToolNode({
+        tools: [handoffTool],
+        directToolNames: new Set(['execute_code']),
+      });
+      const result = (await node.invoke({
+        messages: [
+          new AIMessage({
+            content: '',
+            tool_calls: [{ id: 'wrong_handoff', name: wrongName, args: {} }],
+          }),
+        ],
+      })) as { messages: ToolMessage[] };
+      const wrongNameMessage = result.messages.find(
+        (msg) => msg.tool_call_id === 'wrong_handoff'
+      );
+
+      expect(wrongNameMessage).toBeDefined();
+      expect(wrongNameMessage?.status).toBe('error');
+      expect(wrongNameMessage?.content).toContain(
+        `Did you mean "${correctName}"`
+      );
+    });
+
+    it('should keep event-driven unknown handoffs local without direct tool names', async () => {
+      const executedToolNames: string[] = [];
+      const correctName = `${Constants.LC_TRANSFER_TO_}data_analyst`;
+      const wrongName = `${correctName}_analyst`;
+      const lookupName = 'lookup_sessions';
+      const handoffTool = new DynamicStructuredTool({
+        name: correctName,
+        description: 'Transfer to data analyst',
+        schema: { type: 'object', properties: {}, required: [] },
+        func: async (): Promise<string> => 'transferred',
+      }) as t.GenericTool;
+      const lookupTool = new DynamicStructuredTool({
+        name: lookupName,
+        description: 'List upload sessions',
+        schema: { type: 'object', properties: {}, required: [] },
+        func: async (): Promise<string> => 'sessions',
+      }) as t.GenericTool;
+      const dispatchSpy = jest
+        .spyOn(events, 'safeDispatchCustomEvent')
+        .mockImplementation(async (event, data): Promise<void> => {
+          if (event !== GraphEvents.ON_TOOL_EXECUTE) {
+            return;
+          }
+          const batch = data as t.ToolExecuteBatchRequest;
+          executedToolNames.push(
+            ...batch.toolCalls.map((toolCall) => toolCall.name)
+          );
+          batch.resolve(
+            batch.toolCalls.map((toolCall) => ({
+              toolCallId: toolCall.id,
+              status: 'success' as const,
+              content: `host result for ${toolCall.name}`,
+            }))
+          );
+        });
+      const node = new ToolNode({
+        tools: [handoffTool, lookupTool],
+        eventDrivenMode: true,
+        toolCallStepIds: new Map([
+          ['lookup_call', 'step_lookup'],
+          ['wrong_handoff', 'step_wrong_handoff'],
+        ]),
+      });
+
+      try {
+        const result = (await node.invoke({
+          messages: [
+            new AIMessage({
+              content: '',
+              tool_calls: [
+                { id: 'lookup_call', name: lookupName, args: {} },
+                { id: 'wrong_handoff', name: wrongName, args: {} },
+              ],
+            }),
+          ],
+        })) as { messages: ToolMessage[] };
+        const wrongNameMessage = result.messages.find(
+          (msg) => msg.tool_call_id === 'wrong_handoff'
+        );
+
+        expect(executedToolNames).toEqual([lookupName]);
+        expect(wrongNameMessage).toBeDefined();
+        expect(wrongNameMessage?.status).toBe('error');
+        expect(wrongNameMessage?.content).toContain(
+          `Did you mean "${correctName}"`
+        );
+      } finally {
+        dispatchSpy.mockRestore();
+      }
+    });
+
+    it('should not dispatch mistyped graph handoffs to event-driven tool hosts', async () => {
+      const executedToolNames: string[] = [];
+      const agents: t.AgentInputs[] = [
+        {
+          ...createBasicAgent('router', 'You are a router'),
+          toolDefinitions: [
+            {
+              name: 'lookup_sessions',
+              description: 'List upload sessions',
+              parameters: {
+                type: 'object',
+                properties: {},
+                required: [],
+              },
+            },
+          ],
+        },
+        createBasicAgent('data_analyst', 'You are a data analyst'),
+      ];
+
+      const edges: t.GraphEdge[] = [
+        {
+          from: 'router',
+          to: 'data_analyst',
+          edgeType: 'handoff',
+        },
+      ];
+
+      const run = await Run.create({
+        ...createTestConfig(agents, edges),
+        customHandlers: {
+          [GraphEvents.ON_TOOL_EXECUTE]: {
+            handle: (_event: string, data: t.StreamEventData): void => {
+              const batch = data as t.ToolExecuteBatchRequest;
+              executedToolNames.push(
+                ...batch.toolCalls.map((toolCall) => toolCall.name)
+              );
+              batch.resolve(
+                batch.toolCalls.map((toolCall) => ({
+                  toolCallId: toolCall.id,
+                  status: 'success' as const,
+                  content: `host result for ${toolCall.name}`,
+                }))
+              );
+            },
+          },
+        },
+      });
+      const correctName = `${Constants.LC_TRANSFER_TO_}data_analyst`;
+      const wrongName = `${correctName}_analyst`;
+
+      run.Graph?.overrideTestModel(
+        ['Checking sessions and transferring', 'Handled invalid transfer'],
+        10,
+        [
+          {
+            id: 'tool_call_lookup',
+            name: 'lookup_sessions',
+            args: {},
+          } as ToolCall,
+          {
+            id: 'tool_call_wrong_handoff',
+            name: wrongName,
+            args: { instructions: 'Analyze the upload session data' },
+          } as ToolCall,
+        ]
+      );
+
+      const config: Partial<RunnableConfig> & {
+        version: 'v1' | 'v2';
+        streamMode: string;
+      } = {
+        configurable: {
+          thread_id: 'test-event-wrong-handoff-name-thread',
+        },
+        streamMode: 'values',
+        version: 'v2' as const,
+      };
+
+      await run.processStream(
+        { messages: [new HumanMessage('Check my sessions and analyze them')] },
+        config
+      );
+
+      const toolMessages = run
+        .getRunMessages()!
+        .filter((msg) => msg.getType() === 'tool') as ToolMessage[];
+      const wrongNameMessage = toolMessages.find(
+        (msg) => msg.name === wrongName
+      );
+
+      expect(executedToolNames).toEqual(['lookup_sessions']);
+      expect(wrongNameMessage).toBeDefined();
+      expect(wrongNameMessage?.status).toBe('error');
+      expect(wrongNameMessage?.content).toContain(
+        `Did you mean "${correctName}"`
+      );
+    });
   });
 });

package/src/specs/openrouter.simple.test.ts

@@ -21,6 +21,11 @@ const hasOpenRouter = (process.env.OPENROUTER_API_KEY ?? '').trim() !== '';
 const describeIf = hasOpenRouter ? describe : describe.skip;
 
 const provider = Providers.OPENROUTER;
+const LIVE_MAX_TOKENS = 4096;
+const GEMINI_REASONING_MODEL = 'google/gemini-3.1-pro-preview';
+const ANTHROPIC_REASONING_MODEL = 'anthropic/claude-sonnet-4';
+const ANTHROPIC_LATEST_REASONING_MODEL = 'anthropic/claude-sonnet-4.6';
+
 describeIf(`${capitalizeFirstLetter(provider)} Streaming Tests`, () => {
   jest.setTimeout(60000);
   let run: Run<t.IState>;
@@ -75,6 +80,7 @@ describeIf(`${capitalizeFirstLetter(provider)} Streaming Tests`, () => {
     const llmConfig = {
       ...baseWithoutReasoning,
       model: opts.model,
+      maxTokens: LIVE_MAX_TOKENS,
       ...(opts.reasoning != null ? { reasoning: opts.reasoning } : {}),
     } as t.LLMConfig;
     const customHandlers = setupCustomHandlers();
@@ -178,7 +184,8 @@ describeIf(`${capitalizeFirstLetter(provider)} Streaming Tests`, () => {
       baseLLMConfig as unknown as Record<string, unknown>;
     const llmConfig = {
       ...baseWithoutReasoning,
-      model: 'anthropic/claude-sonnet-4',
+      model: ANTHROPIC_REASONING_MODEL,
+      maxTokens: LIVE_MAX_TOKENS,
     } as t.LLMConfig;
     const customHandlers = setupCustomHandlers();
 
@@ -214,7 +221,7 @@ describeIf(`${capitalizeFirstLetter(provider)} Streaming Tests`, () => {
 
   test(`${capitalizeFirstLetter(provider)}: Gemini 3 reasons by default (no config)`, async () => {
     await runReasoningTest({
-      model: 'google/gemini-3-pro-preview',
+      model: GEMINI_REASONING_MODEL,
       reasoning: undefined,
       threadId: 'or-gemini-default-1',
       runId: 'or-gemini-default-1',
@@ -223,7 +230,7 @@ describeIf(`${capitalizeFirstLetter(provider)} Streaming Tests`, () => {
 
   test(`${capitalizeFirstLetter(provider)}: Gemini reasoning with max_tokens`, async () => {
     await runReasoningTest({
-      model: 'google/gemini-3-pro-preview',
+      model: GEMINI_REASONING_MODEL,
       reasoning: { max_tokens: 4000 },
       threadId: 'or-gemini-reasoning-1',
       runId: 'or-gemini-reasoning-1',
@@ -232,7 +239,7 @@ describeIf(`${capitalizeFirstLetter(provider)} Streaming Tests`, () => {
 
   test(`${capitalizeFirstLetter(provider)}: Gemini reasoning with effort`, async () => {
     await runReasoningTest({
-      model: 'google/gemini-3-flash-preview',
+      model: GEMINI_REASONING_MODEL,
       reasoning: { effort: 'low' },
       threadId: 'or-gemini-effort-1',
       runId: 'or-gemini-effort-1',
@@ -241,7 +248,7 @@ describeIf(`${capitalizeFirstLetter(provider)} Streaming Tests`, () => {
 
   test(`${capitalizeFirstLetter(provider)}: Anthropic reasoning with max_tokens`, async () => {
     await runReasoningTest({
-      model: 'anthropic/claude-sonnet-4',
+      model: ANTHROPIC_REASONING_MODEL,
       reasoning: { max_tokens: 4000 },
       threadId: 'or-anthropic-reasoning-1',
       runId: 'or-anthropic-reasoning-1',
@@ -250,16 +257,16 @@ describeIf(`${capitalizeFirstLetter(provider)} Streaming Tests`, () => {
 
   test(`${capitalizeFirstLetter(provider)}: Anthropic sonnet-4 reasoning with effort`, async () => {
     await runReasoningTest({
-      model: 'anthropic/claude-sonnet-4',
+      model: ANTHROPIC_REASONING_MODEL,
       reasoning: { effort: 'medium' },
       threadId: 'or-anthropic-effort-s4-1',
       runId: 'or-anthropic-effort-s4-1',
     });
   });
 
-  test(`${capitalizeFirstLetter(provider)}: Anthropic sonnet-4-6 reasoning with effort`, async () => {
+  test(`${capitalizeFirstLetter(provider)}: Anthropic sonnet-4.6 reasoning with effort`, async () => {
     await runReasoningTest({
-      model: 'anthropic/claude-sonnet-4-6',
+      model: ANTHROPIC_LATEST_REASONING_MODEL,
       reasoning: { effort: 'medium' },
       threadId: 'or-anthropic-effort-s46-1',
       runId: 'or-anthropic-effort-s46-1',

package/src/tools/ToolNode.ts

@@ -131,6 +131,10 @@ function isSend(value: unknown): value is Send {
   return value instanceof Send;
 }
 
+function isHandoffToolName(name: string): boolean {
+  return name.startsWith(Constants.LC_TRANSFER_TO_);
+}
+
 /**
  * Format a fail-closed diagnostic for malformed approval-decision
  * fields. Hosts deserialize resume payloads from untyped JSON, so
@@ -581,6 +585,72 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
     return this.fileCheckpointer;
   }
 
+  private *getRegisteredHandoffNames(): IterableIterator<string> {
+    if (this.directToolNames != null) {
+      for (const toolName of this.directToolNames) {
+        yield toolName;
+      }
+    }
+
+    for (const toolName of this.toolMap.keys()) {
+      if (this.directToolNames?.has(toolName) === true) {
+        continue;
+      }
+      yield toolName;
+    }
+  }
+
+  private hasRegisteredHandoffTool(): boolean {
+    for (const toolName of this.getRegisteredHandoffNames()) {
+      if (isHandoffToolName(toolName)) {
+        return true;
+      }
+    }
+    return false;
+  }
+
+  private getHandoffToolNameSuggestion(callName: string): string | undefined {
+    if (!isHandoffToolName(callName)) {
+      return undefined;
+    }
+
+    let suggestion: string | undefined;
+    for (const toolName of this.getRegisteredHandoffNames()) {
+      if (
+        !isHandoffToolName(toolName) ||
+        toolName.length >= callName.length ||
+        !callName.startsWith(toolName)
+      ) {
+        continue;
+      }
+      if (suggestion == null || toolName.length > suggestion.length) {
+        suggestion = toolName;
+      }
+    }
+    return suggestion;
+  }
+
+  private shouldHandleUnknownHandoffLocally(
+    callName: string,
+    hasRegisteredHandoffTool?: boolean
+  ): boolean {
+    if (!isHandoffToolName(callName) || this.toolMap.has(callName)) {
+      return false;
+    }
+    return hasRegisteredHandoffTool ?? this.hasRegisteredHandoffTool();
+  }
+
+  private getUnknownToolErrorMessage(callName: string): string {
+    const suggestion = this.getHandoffToolNameSuggestion(callName);
+    if (suggestion == null) {
+      return `Tool "${callName}" not found.`;
+    }
+    return (
+      `Tool "${callName}" not found. Did you mean "${suggestion}"? ` +
+      'Handoff tool names must match exactly.'
+    );
+  }
+
   /**
    * Flush the per-Run direct-path turn cache. Called by the Graph at
    * end-of-Run via `clearHeavyState`. The map intentionally survives
@@ -699,7 +769,7 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
       batchScopeId ?? (config.configurable?.run_id as string | undefined);
     try {
       if (tool === undefined) {
-        throw new Error(`Tool "${call.name}" not found.`);
+        throw new Error(this.getUnknownToolErrorMessage(call.name));
       }
       /**
        * `usageCount` is the per-tool-name invocation index that
@@ -2742,8 +2812,10 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
     let outputs: (BaseMessage | Command)[];
 
     if (this.isSendInput(input)) {
-      const isDirectTool = this.directToolNames?.has(input.lg_tool_call.name);
-      if (this.eventDrivenMode && isDirectTool !== true) {
+      const isLocalTool =
+        this.directToolNames?.has(input.lg_tool_call.name) === true ||
+        this.shouldHandleUnknownHandoffLocally(input.lg_tool_call.name);
+      if (this.eventDrivenMode && !isLocalTool) {
         return this.executeViaEvent([input.lg_tool_call], config, input, {
           batchIndices: [0],
           turn,
@@ -2848,28 +2920,35 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
         }) ?? [];
 
       if (this.eventDrivenMode && filteredCalls.length > 0) {
-        const filteredIndices = filteredCalls.map((_, idx) => idx);
-
-        if (!this.directToolNames || this.directToolNames.size === 0) {
-          return this.executeViaEvent(filteredCalls, config, input, {
-            batchIndices: filteredIndices,
-            turn,
-            batchScopeId,
-          });
-        }
+        const directToolNames = this.directToolNames;
+        const hasRegisteredHandoffTool = this.hasRegisteredHandoffTool();
 
         const directEntries: Array<{ call: ToolCall; batchIndex: number }> = [];
         const eventEntries: Array<{ call: ToolCall; batchIndex: number }> = [];
         for (let i = 0; i < filteredCalls.length; i++) {
           const call = filteredCalls[i];
           const entry = { call, batchIndex: i };
-          if (this.directToolNames!.has(call.name)) {
+          if (
+            directToolNames?.has(call.name) === true ||
+            this.shouldHandleUnknownHandoffLocally(
+              call.name,
+              hasRegisteredHandoffTool
+            )
+          ) {
             directEntries.push(entry);
           } else {
             eventEntries.push(entry);
           }
         }
 
+        if (directEntries.length === 0) {
+          return this.executeViaEvent(filteredCalls, config, input, {
+            batchIndices: eventEntries.map((entry) => entry.batchIndex),
+            turn,
+            batchScopeId,
+          });
+        }
+
         const directCalls = directEntries.map((e) => e.call);
         const directIndices = directEntries.map((e) => e.batchIndex);
         const eventCalls = eventEntries.map((e) => e.call);

package/src/types/run.ts

@@ -216,6 +216,8 @@ export type TokenBudgetBreakdown = {
   instructionTokens: number;
   /** Tokens from the system message text alone. */
   systemMessageTokens: number;
+  /** Tokens from instruction text emitted outside the system message. */
+  dynamicInstructionTokens: number;
   /** Tokens from tool schema definitions. */
   toolSchemaTokens: number;
   /** Tokens from the conversation summary. */