@librechat/agents 3.0.61 → 3.0.63

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@librechat/agents",
-  "version": "3.0.61",
+  "version": "3.0.63",
   "main": "./dist/cjs/main.cjs",
   "module": "./dist/esm/main.mjs",
   "types": "./dist/types/index.d.ts",
@@ -75,6 +75,7 @@
     "multi-agent-sequence": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/multi-agent-sequence.ts",
     "multi-agent-conditional": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/multi-agent-conditional.ts",
     "multi-agent-supervisor": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/multi-agent-supervisor.ts",
+    "test-handoff-preamble": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/test-handoff-preamble.ts",
     "multi-agent-list-handoff": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/test-multi-agent-list-handoff.ts",
     "test-parallel-agent-labeling": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/test-parallel-agent-labeling.ts",
     "test-thinking-handoff": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/test-thinking-handoff.ts",

package/src/graphs/MultiAgentGraph.ts

@@ -2,6 +2,7 @@ import { z } from 'zod';
 import { tool } from '@langchain/core/tools';
 import { PromptTemplate } from '@langchain/core/prompts';
 import {
+  AIMessage,
   ToolMessage,
   HumanMessage,
   getBufferString,
@@ -15,12 +16,15 @@ import {
   getCurrentTaskInput,
   messagesStateReducer,
 } from '@langchain/langgraph';
+import type { BaseMessage, AIMessageChunk } from '@langchain/core/messages';
 import type { ToolRunnableConfig } from '@langchain/core/tools';
-import type { BaseMessage } from '@langchain/core/messages';
 import type * as t from '@/types';
 import { StandardGraph } from './Graph';
 import { Constants } from '@/common';
 
+/** Pattern to extract instructions from transfer ToolMessage content */
+const HANDOFF_INSTRUCTIONS_PATTERN = /(?:Instructions?|Context):\s*(.+)/is;
+
 /**
  * MultiAgentGraph extends StandardGraph to support dynamic multi-agent workflows
  * with handoffs, fan-in/fan-out, and other composable patterns.
@@ -312,6 +316,10 @@ export class MultiAgentGraph extends StandardGraph {
               content,
               name: toolName,
               tool_call_id: toolCallId,
+              additional_kwargs: {
+                /** Store destination for programmatic access in handoff detection */
+                handoff_destination: destination,
+              },
             });
 
             return new Command({
@@ -407,6 +415,153 @@ export class MultiAgentGraph extends StandardGraph {
     return this.createAgentNode(agentId);
   }
 
+  /**
+   * Detects if the current agent is receiving a handoff and processes the messages accordingly.
+   * Returns filtered messages with the transfer tool call/message removed, plus any instructions
+   * extracted from the transfer to be injected as a HumanMessage preamble.
+   *
+   * Supports both single handoffs (last message is the transfer) and parallel handoffs
+   * (multiple transfer ToolMessages, need to find the one targeting this agent).
+   *
+   * @param messages - Current state messages
+   * @param agentId - The agent ID to check for handoff reception
+   * @returns Object with filtered messages and extracted instructions, or null if not a handoff
+   */
+  private processHandoffReception(
+    messages: BaseMessage[],
+    agentId: string
+  ): { filteredMessages: BaseMessage[]; instructions: string | null } | null {
+    if (messages.length === 0) return null;
+
+    /**
+     * Search for a transfer ToolMessage targeting this agent.
+     * For parallel handoffs, multiple transfer messages may exist - find ours.
+     * Search backwards from the end to find the most recent transfer to this agent.
+     */
+    let toolMessage: ToolMessage | null = null;
+    let toolMessageIndex = -1;
+
+    for (let i = messages.length - 1; i >= 0; i--) {
+      const msg = messages[i];
+      if (msg.getType() !== 'tool') continue;
+
+      const candidateMsg = msg as ToolMessage;
+      const toolName = candidateMsg.name;
+
+      if (typeof toolName !== 'string') continue;
+
+      /** Check for standard transfer pattern */
+      const isTransferMessage = toolName.startsWith(Constants.LC_TRANSFER_TO_);
+      const isConditionalTransfer = toolName === 'conditional_transfer';
+
+      if (!isTransferMessage && !isConditionalTransfer) continue;
+
+      /** Extract destination from tool name or additional_kwargs */
+      let destinationAgent: string | null = null;
+
+      if (isTransferMessage) {
+        destinationAgent = toolName.replace(Constants.LC_TRANSFER_TO_, '');
+      } else if (isConditionalTransfer) {
+        const handoffDest = candidateMsg.additional_kwargs.handoff_destination;
+        destinationAgent = typeof handoffDest === 'string' ? handoffDest : null;
+      }
+
+      /** Check if this transfer targets our agent */
+      if (destinationAgent === agentId) {
+        toolMessage = candidateMsg;
+        toolMessageIndex = i;
+        break;
+      }
+    }
+
+    /** No transfer targeting this agent found */
+    if (toolMessage === null || toolMessageIndex < 0) return null;
+
+    /** Extract instructions from the ToolMessage content */
+    const contentStr =
+      typeof toolMessage.content === 'string'
+        ? toolMessage.content
+        : JSON.stringify(toolMessage.content);
+
+    const instructionsMatch = contentStr.match(HANDOFF_INSTRUCTIONS_PATTERN);
+    const instructions = instructionsMatch?.[1]?.trim() ?? null;
+
+    /** Get the tool_call_id to find and filter the AI message's tool call */
+    const toolCallId = toolMessage.tool_call_id;
+
+    /**
+     * Collect all transfer tool_call_ids to filter out.
+     * For parallel handoffs, we filter ALL transfer messages (not just ours)
+     * to give the receiving agent a clean context without handoff noise.
+     */
+    const transferToolCallIds = new Set<string>([toolCallId]);
+    for (const msg of messages) {
+      if (msg.getType() !== 'tool') continue;
+      const tm = msg as ToolMessage;
+      const tName = tm.name;
+      if (typeof tName !== 'string') continue;
+      if (
+        tName.startsWith(Constants.LC_TRANSFER_TO_) ||
+        tName === 'conditional_transfer'
+      ) {
+        transferToolCallIds.add(tm.tool_call_id);
+      }
+    }
+
+    /** Filter out all transfer messages */
+    const filteredMessages: BaseMessage[] = [];
+
+    for (let i = 0; i < messages.length; i++) {
+      const msg = messages[i];
+      const msgType = msg.getType();
+
+      /** Skip transfer ToolMessages */
+      if (msgType === 'tool') {
+        const tm = msg as ToolMessage;
+        if (transferToolCallIds.has(tm.tool_call_id)) {
+          continue;
+        }
+      }
+
+      if (msgType === 'ai') {
+        /** Check if this AI message contains any transfer tool calls */
+        const aiMsg = msg as AIMessage | AIMessageChunk;
+        const toolCalls = aiMsg.tool_calls;
+
+        if (toolCalls && toolCalls.length > 0) {
+          /** Filter out all transfer tool calls */
+          const remainingToolCalls = toolCalls.filter(
+            (tc) => tc.id == null || !transferToolCallIds.has(tc.id)
+          );
+
+          const hasTransferCalls = remainingToolCalls.length < toolCalls.length;
+
+          if (hasTransferCalls) {
+            if (
+              remainingToolCalls.length > 0 ||
+              (typeof aiMsg.content === 'string' && aiMsg.content.trim())
+            ) {
+              /** Keep the message but without transfer tool calls */
+              const filteredAiMsg = new AIMessage({
+                content: aiMsg.content,
+                tool_calls: remainingToolCalls,
+                id: aiMsg.id,
+              });
+              filteredMessages.push(filteredAiMsg);
+            }
+            /** If no remaining content or tool calls, skip this message entirely */
+            continue;
+          }
+        }
+      }
+
+      /** Keep all other messages */
+      filteredMessages.push(msg);
+    }
+
+    return { filteredMessages, instructions };
+  }
+
   /**
    * Create the multi-agent workflow with dynamic handoffs
    */
@@ -474,26 +629,85 @@ export class MultiAgentGraph extends StandardGraph {
       /** Agent subgraph (includes agent + tools) */
       const agentSubgraph = this.createAgentSubgraph(agentId);
 
-      /** Wrapper function that handles agentMessages channel and conditional routing */
+      /** Wrapper function that handles agentMessages channel, handoff reception, and conditional routing */
       const agentWrapper = async (
         state: t.MultiAgentGraphState
       ): Promise<t.MultiAgentGraphState | Command> => {
         let result: t.MultiAgentGraphState;
 
-        if (state.agentMessages != null && state.agentMessages.length > 0) {
+        /**
+         * Check if this agent is receiving a handoff.
+         * If so, filter out the transfer messages and inject instructions as preamble.
+         * This prevents the receiving agent from seeing the transfer as "completed work"
+         * and prematurely producing an end token.
+         */
+        const handoffContext = this.processHandoffReception(
+          state.messages,
+          agentId
+        );
+
+        if (handoffContext !== null) {
+          const { filteredMessages, instructions } = handoffContext;
+
+          /** Build messages for the receiving agent */
+          let messagesForAgent = filteredMessages;
+
+          /** If there are instructions, inject them as a HumanMessage to ground the agent */
+          const hasInstructions = instructions !== null && instructions !== '';
+          if (hasInstructions) {
+            messagesForAgent = [
+              ...filteredMessages,
+              new HumanMessage(instructions),
+            ];
+          }
+
+          /** Update token map if we have a token counter */
+          const agentContext = this.agentContexts.get(agentId);
+          if (agentContext?.tokenCounter && hasInstructions) {
+            const freshTokenMap: Record<string, number> = {};
+            for (
+              let i = 0;
+              i < Math.min(filteredMessages.length, this.startIndex);
+              i++
+            ) {
+              const tokenCount = agentContext.indexTokenCountMap[i];
+              if (tokenCount !== undefined) {
+                freshTokenMap[i] = tokenCount;
+              }
+            }
+            /** Add tokens for the instructions message */
+            const instructionsMsg = new HumanMessage(instructions);
+            freshTokenMap[messagesForAgent.length - 1] =
+              agentContext.tokenCounter(instructionsMsg);
+            agentContext.updateTokenMapWithInstructions(freshTokenMap);
+          }
+
+          const transformedState: t.MultiAgentGraphState = {
+            ...state,
+            messages: messagesForAgent,
+          };
+          result = await agentSubgraph.invoke(transformedState);
+          result = {
+            ...result,
+            agentMessages: [],
+          };
+        } else if (
+          state.agentMessages != null &&
+          state.agentMessages.length > 0
+        ) {
           /**
            * When using agentMessages (excludeResults=true), we need to update
            * the token map to account for the new prompt message
            */
           const agentContext = this.agentContexts.get(agentId);
           if (agentContext && agentContext.tokenCounter) {
-            // The agentMessages contains:
-            // 1. Filtered messages (0 to startIndex) - already have token counts
-            // 2. New prompt message - needs token counting
-
+            /** The agentMessages contains:
+             * 1. Filtered messages (0 to startIndex) - already have token counts
+             * 2. New prompt message - needs token counting
+             */
             const freshTokenMap: Record<string, number> = {};
 
-            // Copy existing token counts for filtered messages (0 to startIndex)
+            /** Copy existing token counts for filtered messages (0 to startIndex) */
             for (let i = 0; i < this.startIndex; i++) {
               const tokenCount = agentContext.indexTokenCountMap[i];
               if (tokenCount !== undefined) {
@@ -501,7 +715,7 @@ export class MultiAgentGraph extends StandardGraph {
               }
             }
 
-            // Calculate tokens only for the new prompt message (last message)
+            /** Calculate tokens only for the new prompt message (last message) */
             const promptMessageIndex = state.agentMessages.length - 1;
             if (promptMessageIndex >= this.startIndex) {
               const promptMessage = state.agentMessages[promptMessageIndex];
@@ -509,7 +723,7 @@ export class MultiAgentGraph extends StandardGraph {
                 agentContext.tokenCounter(promptMessage);
             }
 
-            // Update the agent's token map with instructions added
+            /** Update the agent's token map with instructions added */
             agentContext.updateTokenMapWithInstructions(freshTokenMap);
           }
 

package/src/scripts/multi-agent-conditional.ts

@@ -210,6 +210,7 @@ async function testConditionalMultiAgent() {
       console.log(`\n\nExpert used: ${selectedExpert}`);
       console.log('Content parts:', contentParts.length);
       console.log('---');
+      console.dir(contentParts, { depth: null });
     }
   } catch (error) {
     console.error('Error in conditional multi-agent test:', error);

package/src/scripts/multi-agent-supervisor.ts

@@ -353,6 +353,7 @@ async function testSupervisorMultiAgent() {
       );
       console.log(`                 transfer_to_legal_advisor`);
       console.log('─'.repeat(60));
+      console.dir(contentParts, { depth: null });
     }
     await sleep(3000);
   } catch (error) {

package/src/scripts/test-handoff-preamble.ts

@@ -0,0 +1,275 @@
+/**
+ * Test script for multi-turn handoff behavior.
+ *
+ * This tests the fix for the issue where receiving agents would see transfer messages
+ * and prematurely produce end tokens, thinking the work was already done.
+ *
+ * The fix:
+ * 1. Filters out transfer tool calls and ToolMessages from the receiving agent's context
+ * 2. Injects any passthrough instructions as a HumanMessage to ground the receiving agent
+ */
+import { config } from 'dotenv';
+config();
+
+import { HumanMessage, BaseMessage } from '@langchain/core/messages';
+import type { RunnableConfig } from '@langchain/core/runnables';
+import type * as t from '@/types';
+import { ChatModelStreamHandler, createContentAggregator } from '@/stream';
+import { ToolEndHandler, ModelEndHandler } from '@/events';
+import { getLLMConfig } from '@/utils/llmConfig';
+import { GraphEvents, Providers } from '@/common';
+import { Run } from '@/run';
+
+const conversationHistory: BaseMessage[] = [];
+
+/**
+ * Test multi-turn handoff between a coordinator and a specialist
+ */
+async function testHandoffPreamble(): Promise<void> {
+  console.log('='.repeat(60));
+  console.log('Testing Multi-Turn Handoff with Preamble Injection');
+  console.log('='.repeat(60));
+  console.log('\nThis test verifies that:');
+  console.log('1. Transfer messages are filtered from receiving agent context');
+  console.log('2. Passthrough instructions are injected as a HumanMessage');
+  console.log('3. Multi-turn conversations work correctly after handoffs\n');
+
+  const { contentParts, aggregateContent } = createContentAggregator();
+
+  /** Track which agent is responding */
+  let currentAgent = '';
+
+  const customHandlers = {
+    [GraphEvents.TOOL_END]: new ToolEndHandler(),
+    [GraphEvents.CHAT_MODEL_END]: new ModelEndHandler(),
+    [GraphEvents.CHAT_MODEL_STREAM]: new ChatModelStreamHandler(),
+    [GraphEvents.ON_RUN_STEP]: {
+      handle: (
+        event: GraphEvents.ON_RUN_STEP,
+        data: t.StreamEventData
+      ): void => {
+        const runStep = data as t.RunStep;
+        if (runStep.agentId) {
+          currentAgent = runStep.agentId;
+          console.log(`\n[Agent: ${currentAgent}] Processing...`);
+        }
+        aggregateContent({ event, data: runStep });
+      },
+    },
+    [GraphEvents.ON_RUN_STEP_COMPLETED]: {
+      handle: (
+        event: GraphEvents.ON_RUN_STEP_COMPLETED,
+        data: t.StreamEventData
+      ): void => {
+        aggregateContent({
+          event,
+          data: data as unknown as { result: t.ToolEndEvent },
+        });
+      },
+    },
+    [GraphEvents.ON_MESSAGE_DELTA]: {
+      handle: (
+        event: GraphEvents.ON_MESSAGE_DELTA,
+        data: t.StreamEventData
+      ): void => {
+        console.log('====== ON_MESSAGE_DELTA ======');
+        console.dir(data, { depth: null });
+        aggregateContent({ event, data: data as t.MessageDeltaEvent });
+      },
+    },
+    [GraphEvents.TOOL_START]: {
+      handle: (
+        _event: string,
+        data: t.StreamEventData,
+        _metadata?: Record<string, unknown>
+      ): void => {
+        const toolData = data as { name?: string };
+        if (toolData?.name?.includes('transfer_to_')) {
+          const specialist = toolData.name.replace('lc_transfer_to_', '');
+          console.log(`\n🔀 Handing off to: ${specialist}`);
+        }
+      },
+    },
+  };
+
+  /**
+   * Create agents:
+   * - coordinator: Decides when to hand off to specialist
+   * - specialist: Handles specific tasks delegated by coordinator
+   */
+  const agents: t.AgentInputs[] = [
+    {
+      agentId: 'coordinator',
+      provider: Providers.OPENAI,
+      clientOptions: {
+        modelName: 'gpt-4.1-mini',
+        apiKey: process.env.OPENAI_API_KEY,
+      },
+      instructions: `You are a Task Coordinator. Your role is to:
+1. Understand user requests
+2. If the request involves technical analysis, use the transfer_to_specialist tool to hand off
+3. When handing off, provide clear instructions about what needs to be done
+
+IMPORTANT: When using the handoff tool, include specific instructions for the specialist.`,
+      maxContextTokens: 8000,
+    },
+    {
+      agentId: 'specialist',
+      provider: Providers.OPENAI,
+      clientOptions: {
+        modelName: 'gpt-4.1-mini',
+        apiKey: process.env.OPENAI_API_KEY,
+      },
+      instructions: `You are a Technical Specialist. When you receive a request:
+1. Carefully read any instructions provided
+2. Provide a detailed technical response
+3. Do NOT just acknowledge - provide substantive help
+
+IMPORTANT: You are the specialist - provide a complete, helpful response to the task.`,
+      maxContextTokens: 8000,
+    },
+  ];
+
+  /** Create handoff edge with passthrough instructions */
+  const edges: t.GraphEdge[] = [
+    {
+      from: 'coordinator',
+      to: 'specialist',
+      description: 'Transfer to technical specialist for analysis',
+      edgeType: 'handoff',
+      prompt: 'Specific instructions for the specialist about what to analyze',
+      promptKey: 'instructions',
+    },
+  ];
+
+  const runConfig: t.RunConfig = {
+    runId: `handoff-test-${Date.now()}`,
+    graphConfig: {
+      type: 'multi-agent',
+      agents,
+      edges,
+    },
+    customHandlers,
+    returnContent: true,
+  };
+
+  const run = await Run.create(runConfig);
+
+  const config: Partial<RunnableConfig> & {
+    version: 'v1' | 'v2';
+    streamMode: string;
+  } = {
+    configurable: {
+      thread_id: 'handoff-test-conversation-1',
+    },
+    streamMode: 'values',
+    version: 'v2' as const,
+  };
+
+  /** TURN 1: Initial request that triggers handoff */
+  console.log('\n' + '─'.repeat(60));
+  console.log('TURN 1: Initial request (should trigger handoff)');
+  console.log('─'.repeat(60));
+
+  const userMessage1 = `
+    Hi! Can you help me understand the time complexity of quicksort?
+    I need a technical explanation.
+  `;
+
+  conversationHistory.push(new HumanMessage(userMessage1));
+  console.log('\nUser:', userMessage1.trim());
+  console.log('\nResponse:');
+
+  let inputs = { messages: conversationHistory };
+  await run.processStream(inputs, config);
+  const messages1 = run.getRunMessages();
+  if (messages1) {
+    conversationHistory.push(...messages1);
+  }
+
+  console.log('\n');
+
+  /** TURN 2: Follow-up question to test multi-turn after handoff */
+  console.log('\n' + '─'.repeat(60));
+  console.log('TURN 2: Follow-up question (tests context after handoff)');
+  console.log('─'.repeat(60));
+
+  const userMessage2 = `
+    Thanks! Can you also explain the space complexity and when quicksort 
+    might not be the best choice?
+  `;
+
+  conversationHistory.push(new HumanMessage(userMessage2));
+  console.log('\nUser:', userMessage2.trim());
+  console.log('\nResponse:');
+
+  inputs = { messages: conversationHistory };
+  await run.processStream(inputs, config);
+  const messages2 = run.getRunMessages();
+  if (messages2) {
+    conversationHistory.push(...messages2);
+  }
+
+  console.log('\n');
+
+  /** TURN 3: Another follow-up to verify sustained conversation */
+  console.log('\n' + '─'.repeat(60));
+  console.log('TURN 3: Third turn (tests sustained multi-turn)');
+  console.log('─'.repeat(60));
+
+  const userMessage3 = `
+    Great explanation! One more question - how does quicksort compare 
+    to mergesort in practice?
+  `;
+
+  conversationHistory.push(new HumanMessage(userMessage3));
+  console.log('\nUser:', userMessage3.trim());
+  console.log('\nResponse:');
+
+  inputs = { messages: conversationHistory };
+  await run.processStream(inputs, config);
+  const messages3 = run.getRunMessages();
+  if (messages3) {
+    conversationHistory.push(...messages3);
+  }
+
+  /** Summary */
+  console.log('\n\n' + '='.repeat(60));
+  console.log('TEST SUMMARY');
+  console.log('='.repeat(60));
+  console.log('\nTotal messages in conversation:', conversationHistory.length);
+  console.log('\nMessage types:');
+
+  for (let i = 0; i < conversationHistory.length; i++) {
+    const msg = conversationHistory[i];
+    const type = msg.getType();
+    const preview =
+      typeof msg.content === 'string'
+        ? msg.content.slice(0, 50).replace(/\n/g, ' ')
+        : '[complex content]';
+    console.log(`  ${i + 1}. [${type}] ${preview}...`);
+  }
+
+  console.log('\n✅ Test completed. Review the output above to verify:');
+  console.log('   - Specialist received and acted on instructions');
+  console.log('   - No premature end tokens after handoff');
+  console.log('   - Multi-turn conversation continued smoothly');
+}
+
+process.on('unhandledRejection', (reason, promise) => {
+  console.error('Unhandled Rejection at:', promise, 'reason:', reason);
+  console.log('\nConversation history at failure:');
+  console.dir(conversationHistory, { depth: null });
+  process.exit(1);
+});
+
+process.on('uncaughtException', (err) => {
+  console.error('Uncaught Exception:', err);
+});
+
+testHandoffPreamble().catch((err) => {
+  console.error('Test failed:', err);
+  console.log('\nConversation history at failure:');
+  console.dir(conversationHistory, { depth: null });
+  process.exit(1);
+});

package/src/tools/ToolNode.ts

@@ -288,6 +288,7 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
           Array.isArray(output.goto) &&
           output.goto.every((send): send is Send => isSend(send))
         ) {
+          /** Aggregate Send-based commands */
           if (parentCommand) {
             (parentCommand.goto as Send[]).push(...(output.goto as Send[]));
           } else {
@@ -297,6 +298,14 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
             });
           }
         } else {
+          /**
+           * Non-Send Commands (including handoff Commands with string goto)
+           * are passed through as-is. For single handoffs, this works correctly.
+           *
+           * Note: Parallel handoffs (LLM calling multiple transfer tools simultaneously)
+           * are not yet fully supported. For parallel agent execution, use direct edges
+           * with edgeType: 'direct' instead of handoff edges.
+           */
           combinedOutputs.push(output);
         }
       } else {