@librechat/agents 3.4.7 → 3.5.1

package/dist/cjs/graphs/MultiAgentGraph.cjs

@@ -8,16 +8,8 @@ let _langchain_langgraph = require("@langchain/langgraph");
 let _langchain_core_messages = require("@langchain/core/messages");
 let _langchain_core_tools = require("@langchain/core/tools");
 //#region src/graphs/MultiAgentGraph.ts
-/** Pattern to extract instructions from transfer ToolMessage content */
 const HANDOFF_INSTRUCTIONS_PATTERN = /(?:Instructions?|Context):\s*(.+)/is;
 const HANDOFF_INSTRUCTIONS_KEY = "handoff_instructions";
-/**
-* Handoff and fan-in prompts that route work between agents. Built in-run and
-* never persisted as standalone payload entries, so they are marked synthetic:
-* `messagesStateReducer` would otherwise give them a plain UUID and downstream
-* consumers — compaction coverage anchors — could not tell them apart from a
-* message replayed out of the payload.
-*/
 function buildRoutingPrompt(content) {
 	return new _langchain_core_messages.HumanMessage({
 		content,
@@ -50,19 +42,9 @@ function extractLegacyHandoffInstructions(content, promptLabels) {
 	if (markerIndex >= 0) return content.slice(markerIndex + markerLength).trim();
 	return content.match(HANDOFF_INSTRUCTIONS_PATTERN)?.[1]?.trim() ?? null;
 }
-/** Whether a tool name marks a handoff transfer (static or conditional). */
 function isTransferToolName(name) {
 	return typeof name === "string" && (name.startsWith("lc_transfer_to_") || name === "conditional_transfer");
 }
-/**
-* Drop transfer `tool_use` content blocks from an AI message's array content.
-* Companion to the reception's tool-call filtering: array-content providers
-* (Anthropic) serialize retained blocks verbatim, so a transfer block whose
-* call/result the reception stripped — or a parallel sibling's transfer block,
-* whose result never reaches this recipient's state — would replay as an
-* unmatched `tool_use`. Matched by the gathered ids AND by transfer name
-* (sibling blocks have no collectable id here). String content passes through.
-*/
 function filterTransferToolUseBlocks(content, transferToolCallIds) {
 	if (!Array.isArray(content)) return content;
 	return content.filter((block) => {
@@ -93,20 +75,6 @@ function withHandoffGroupMetadata(config, groupId) {
 		}
 	};
 }
-/**
-* MultiAgentGraph extends StandardGraph to support dynamic multi-agent workflows
-* with handoffs, fan-in/fan-out, and other composable patterns.
-*
-* Key behavior:
-* - Agents with ONLY handoff edges: Can dynamically route to any handoff destination
-* - Agents with ONLY direct edges: Always follow their direct edges
-* - Agents with BOTH: Use Command for exclusive routing (handoff OR direct, not both)
-*   - If handoff occurs: Only the handoff destination executes
-*   - If no handoff: Direct edges execute (potentially in parallel)
-*
-* This enables the common pattern where an agent either delegates (handoff)
-* OR continues its workflow (direct edges), but not both simultaneously.
-*/
 var MultiAgentGraph = class extends require_Graph.StandardGraph {
 	edges;
 	startingNodes = /* @__PURE__ */ new Set();
@@ -116,16 +84,6 @@ var MultiAgentGraph = class extends require_Graph.StandardGraph {
 	resultAgentId;
 	memberRecursionLimit;
 	handoffPromptLabels = /* @__PURE__ */ new Map();
-	/**
-	* Map of agentId to parallel group info.
-	* Contains groupId (incrementing number reflecting execution order) for agents in parallel groups.
-	* Sequential agents (not in any parallel group) have undefined entry.
-	*
-	* Example for: researcher -> [analyst1, analyst2, analyst3] -> summarizer
-	* - researcher: undefined (sequential, order 0)
-	* - analyst1, analyst2, analyst3: { groupId: 1 } (parallel group, order 1)
-	* - summarizer: undefined (sequential, order 2)
-	*/
 	agentParallelGroups = /* @__PURE__ */ new Map();
 	constructor(input, dependencies) {
 		super(input, dependencies);
@@ -140,17 +98,6 @@ var MultiAgentGraph = class extends require_Graph.StandardGraph {
 		this.analyzeGraph();
 		this.createHandoffTools();
 	}
-	/**
-	* Fails fast when an edge references an agent that is not in
-	* `agentContexts`. Without this check, the underlying LangGraph
-	* `StateGraph.compile()` would throw the opaque
-	* `Found edge ending at unknown node "<id>"` error after graph
-	* construction — far from the true root cause.
-	*
-	* This catches the common misuse of passing `edges` into a multi-agent
-	* config without also passing the corresponding sub-agent configs in
-	* `agents` (e.g. a host that forgot to pre-load handoff targets).
-	*/
 	validateEdgeAgents() {
 		const known = new Set(this.agentContexts.keys());
 		const unknown = /* @__PURE__ */ new Set();
@@ -162,9 +109,6 @@ var MultiAgentGraph = class extends require_Graph.StandardGraph {
 		const missing = Array.from(unknown).map((id) => `"${id}"`).join(", ");
 		throw new Error(`MultiAgentGraph: edges reference agent(s) not present in agents: [${missing}]. Ensure every agent referenced by an edge is also included in the \`agents\` array, or filter orphaned edges before constructing the graph.`);
 	}
-	/**
-	* Categorize edges into handoff and direct types
-	*/
 	categorizeEdges() {
 		for (const edge of this.edges) {
 			const sources = Array.isArray(edge.from) ? edge.from : [edge.from];
@@ -178,7 +122,6 @@ var MultiAgentGraph = class extends require_Graph.StandardGraph {
 			for (const source of sources) this.handoffSourceIds.add(source);
 		}
 	}
-	/** Static waiting/prompt edges cannot also be driven by Command routing. */
 	validateCommandRoutedDirectEdges() {
 		const destinationGroups = /* @__PURE__ */ new Map();
 		for (const edge of this.directEdges) {
@@ -199,9 +142,6 @@ var MultiAgentGraph = class extends require_Graph.StandardGraph {
 			throw new Error(`MultiAgentGraph: prompted direct edge cannot include command-routed source "${commandSource}". Move the prompt into the routed node.`);
 		}
 	}
-	/**
-	* Analyze graph structure to determine starting nodes and connections
-	*/
 	analyzeGraph() {
 		const hasIncomingEdge = /* @__PURE__ */ new Set();
 		for (const edge of this.edges) (Array.isArray(edge.to) ? edge.to : [edge.to]).forEach((dest) => hasIncomingEdge.add(dest));
@@ -209,20 +149,6 @@ var MultiAgentGraph = class extends require_Graph.StandardGraph {
 		if (this.startingNodes.size === 0 && this.agentContexts.size > 0) this.startingNodes.add(this.agentContexts.keys().next().value);
 		this.computeParallelCapability();
 	}
-	/**
-	* Compute parallel groups by traversing the graph in execution order.
-	* Assigns incrementing group IDs that reflect the sequential order of execution.
-	*
-	* For: researcher -> [analyst1, analyst2, analyst3] -> summarizer
-	* - researcher: no group (first sequential node)
-	* - analyst1, analyst2, analyst3: groupId 1 (first parallel group)
-	* - summarizer: no group (next sequential node)
-	*
-	* This allows frontend to render in order:
-	* Row 0: researcher
-	* Row 1: [analyst1, analyst2, analyst3] (grouped)
-	* Row 2: summarizer
-	*/
 	computeParallelCapability() {
 		let groupCounter = 1;
 		if (this.startingNodes.size > 1) {
@@ -253,30 +179,15 @@ var MultiAgentGraph = class extends require_Graph.StandardGraph {
 			}
 		}
 	}
-	/**
-	* Get the parallel group ID for an agent, if any.
-	* Returns undefined if the agent is not part of a parallel group.
-	* Group IDs are incrementing numbers reflecting execution order.
-	*/
 	getParallelGroupId(agentId) {
 		return this.agentParallelGroups.get(agentId);
 	}
-	/**
-	* Override to indicate this is a multi-agent graph.
-	* Enables agentId to be included in RunStep for frontend agent labeling.
-	*/
 	isMultiAgentGraph() {
 		return true;
 	}
-	/**
-	* Override base class method to provide parallel group IDs for run steps.
-	*/
 	getParallelGroupIdForAgent(agentId) {
 		return this.agentParallelGroups.get(agentId);
 	}
-	/**
-	* Create handoff tools for agents based on handoff edges only
-	*/
 	createHandoffTools() {
 		const handoffsByAgent = /* @__PURE__ */ new Map();
 		for (const edge of this.handoffEdges) {
@@ -304,20 +215,12 @@ var MultiAgentGraph = class extends require_Graph.StandardGraph {
 			agentContext.graphTools.push(...handoffTools);
 		}
 	}
-	/**
-	* Create handoff tools for an edge (handles multiple destinations)
-	* @param edge - The graph edge defining the handoff
-	* @param sourceAgentId - The ID of the agent that will perform the handoff
-	* @param sourceAgentName - The human-readable name of the source agent
-	*/
 	createHandoffToolsForEdge(edge, sourceAgentId, sourceAgentName) {
 		const tools = [];
 		const destinations = Array.isArray(edge.to) ? edge.to : [edge.to];
-		/** If there's a condition, create a single conditional handoff tool */
 		if (edge.condition != null) {
 			const toolName = "conditional_transfer";
 			const toolDescription = edge.description ?? "Conditionally transfer control based on state";
-			/** Check if we have a prompt for handoff input */
 			const hasHandoffInput = edge.prompt != null && typeof edge.prompt === "string";
 			const handoffInputDescription = hasHandoffInput ? edge.prompt : void 0;
 			const promptKey = edge.promptKey ?? "instructions";
@@ -325,17 +228,13 @@ var MultiAgentGraph = class extends require_Graph.StandardGraph {
 				const input = rawInput;
 				const state = runtime.state;
 				const toolCallId = runtime.toolCall?.id ?? "unknown";
-				/** Evaluated condition */
 				const result = edge.condition(state);
 				let destination;
 				if (typeof result === "boolean") {
-					/** If true, use first destination; if false, don't transfer */
 					if (!result) return null;
 					destination = destinations[0];
 				} else if (typeof result === "string") destination = result;
-				else
- /** Array of destinations - for now, use the first */
-				destination = Array.isArray(result) ? result[0] : destinations[0];
+				else destination = Array.isArray(result) ? result[0] : destinations[0];
 				const handoffInstructions = getHandoffInstructions(input, promptKey, hasHandoffInput);
 				let content = `Conditionally transferred to ${destination}`;
 				if (handoffInstructions !== null) content += `\n\n${formatHandoffPromptLabel(promptKey)}: ${handoffInstructions}`;
@@ -344,9 +243,7 @@ var MultiAgentGraph = class extends require_Graph.StandardGraph {
 					name: toolName,
 					tool_call_id: toolCallId,
 					additional_kwargs: {
-						/** Store destination for programmatic access in handoff detection */
 						handoff_destination: destination,
-						/** Store source agent name for receiving agent to know who handed off */
 						handoff_source_name: sourceAgentName,
 						...handoffInstructions !== null && { [HANDOFF_INSTRUCTIONS_KEY]: handoffInstructions }
 					}
@@ -372,12 +269,9 @@ var MultiAgentGraph = class extends require_Graph.StandardGraph {
 				},
 				description: toolDescription
 			}));
-		} else
- /** Create individual tools for each destination */
-		for (const destination of destinations) {
+		} else for (const destination of destinations) {
 			const toolName = `lc_transfer_to_${destination}`;
 			const toolDescription = edge.description ?? `Transfer control to agent '${destination}'`;
-			/** Check if we have a prompt for handoff input */
 			const hasHandoffInput = edge.prompt != null && typeof edge.prompt === "string";
 			const handoffInputDescription = hasHandoffInput ? edge.prompt : void 0;
 			const promptKey = edge.promptKey ?? "instructions";
@@ -392,26 +286,13 @@ var MultiAgentGraph = class extends require_Graph.StandardGraph {
 					name: toolName,
 					tool_call_id: toolCallId,
 					additional_kwargs: {
-						/** Store source agent name for receiving agent to know who handed off */
 						handoff_source_name: sourceAgentName,
 						...handoffInstructions !== null && { [HANDOFF_INSTRUCTIONS_KEY]: handoffInstructions }
 					}
 				});
-				/**
-				* For parallel handoff support:
-				* Build messages that include ONLY this tool call's context.
-				* This prevents errors when LLM calls multiple transfers simultaneously -
-				* each destination gets a valid AIMessage with matching tool_call and tool_result.
-				*
-				* Strategy:
-				* 1. Find the AIMessage containing this tool call
-				* 2. Create a filtered AIMessage with ONLY this tool_call
-				* 3. Include all messages before the AIMessage plus the filtered pair
-				*/
 				const messages = runtime.state.messages;
 				let filteredMessages;
 				let aiMessageIndex = -1;
-				/** Find the AIMessage containing this tool call */
 				for (let i = messages.length - 1; i >= 0; i--) {
 					const msg = messages[i];
 					if (msg.getType() === "ai") {
@@ -425,10 +306,6 @@ var MultiAgentGraph = class extends require_Graph.StandardGraph {
 					const originalAiMsg = messages[aiMessageIndex];
 					const thisToolCall = originalAiMsg.tool_calls?.find((tc) => tc.id === toolCallId);
 					if (thisToolCall != null && (originalAiMsg.tool_calls?.length ?? 0) > 1) {
-						/**
-						* Multiple tool calls - create filtered AIMessage with ONLY this call.
-						* This ensures valid message structure for parallel handoffs.
-						*/
 						const filteredAiMsg = new _langchain_core_messages.AIMessage({
 							content: originalAiMsg.content,
 							tool_calls: [thisToolCall],
@@ -439,12 +316,8 @@ var MultiAgentGraph = class extends require_Graph.StandardGraph {
 							filteredAiMsg,
 							toolMessage
 						];
-					} else
- /** Single tool call - use messages as-is */
-					filteredMessages = messages.concat(toolMessage);
-				} else
- /** Fallback - append tool message */
-				filteredMessages = messages.concat(toolMessage);
+					} else filteredMessages = messages.concat(toolMessage);
+				} else filteredMessages = messages.concat(toolMessage);
 				return new _langchain_langgraph.Command({
 					goto: destination,
 					update: { messages: filteredMessages },
@@ -469,33 +342,11 @@ var MultiAgentGraph = class extends require_Graph.StandardGraph {
 		}
 		return tools;
 	}
-	/**
-	* Create a complete agent subgraph (similar to createReactAgent)
-	*/
 	createAgentSubgraph(agentId) {
-		/** This is essentially the same as `createAgentNode` from `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,
-	* source agent, and parallel sibling information extracted from the transfer.
-	*
-	* 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, extracted instructions, source agent, and parallel siblings
-	*/
 	processHandoffReception(messages, agentId) {
 		if (messages.length === 0) return null;
-		/**
-		* A handoff is active only while resolving the most recent assistant
-		* tool-call round. Older transfer results remain in conversation history,
-		* but must not be reused when this agent is reached later through a direct
-		* edge or cycle.
-		*/
 		const activeTransferToolCallIds = /* @__PURE__ */ new Set();
 		let activeToolMessageStartIndex = messages.length;
 		for (let i = messages.length - 1; i >= 0; i--) {
@@ -509,11 +360,6 @@ var MultiAgentGraph = class extends require_Graph.StandardGraph {
 			break;
 		}
 		if (activeTransferToolCallIds.size === 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 = null;
 		let toolMessageIndex = -1;
 		for (let i = messages.length - 1; i >= activeToolMessageStartIndex; i--) {
@@ -522,48 +368,34 @@ var MultiAgentGraph = class extends require_Graph.StandardGraph {
 			const candidateMsg = msg;
 			const toolName = candidateMsg.name;
 			if (typeof toolName !== "string" || !activeTransferToolCallIds.has(candidateMsg.tool_call_id)) continue;
-			/** Check for standard transfer pattern */
 			const isTransferMessage = toolName.startsWith("lc_transfer_to_");
 			const isConditionalTransfer = toolName === "conditional_transfer";
 			if (!isTransferMessage && !isConditionalTransfer) continue;
-			/** Extract destination from tool name or additional_kwargs */
 			let destinationAgent = null;
 			if (isTransferMessage) destinationAgent = toolName.replace("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 : require_toolContent.serializeToolContentBounded(toolMessage.content, require_truncation.HARD_MAX_TOOL_RESULT_CHARS);
 		const structuredInstructions = toolMessage.additional_kwargs[HANDOFF_INSTRUCTIONS_KEY];
 		const instructions = typeof structuredInstructions === "string" ? structuredInstructions.trim() : extractLegacyHandoffInstructions(contentStr, this.handoffPromptLabels.get(agentId));
-		/** Extract source agent name from additional_kwargs */
 		const handoffSourceName = toolMessage.additional_kwargs.handoff_source_name;
 		const sourceAgentName = typeof handoffSourceName === "string" ? handoffSourceName : null;
-		/** Extract parallel siblings (set by ToolNode for parallel handoffs) */
 		const rawSiblings = toolMessage.additional_kwargs.handoff_parallel_siblings;
-		/** Convert IDs to display names */
 		const parallelSiblings = (Array.isArray(rawSiblings) ? rawSiblings.filter((s) => typeof s === "string") : []).map((id) => {
 			return this.agentContexts.get(id)?.name ?? id;
 		});
 		const storedParallelGroupId = toolMessage.additional_kwargs["__handoff_group_id"];
 		const parallelGroupId = isValidHandoffGroupId(storedParallelGroupId) ? storedParallelGroupId : void 0;
-		/** 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([toolCallId]);
 		for (const msg of messages) if (msg.getType() === "tool") {
 			const tm = msg;
@@ -573,37 +405,21 @@ var MultiAgentGraph = class extends require_Graph.StandardGraph {
 			const aiMsg = msg;
 			for (const toolCall of aiMsg.tool_calls ?? []) if (toolCall.id != null && (toolCall.name.startsWith("lc_transfer_to_") || toolCall.name === "conditional_transfer")) transferToolCallIds.add(toolCall.id);
 		}
-		/** Filter out all transfer messages */
 		const filteredMessages = [];
 		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;
 				if (transferToolCallIds.has(tm.tool_call_id)) continue;
 			}
 			if (msgType === "ai") {
-				/** Check if this AI message contains any transfer tool calls */
 				const aiMsg = msg;
 				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));
 					if (remainingToolCalls.length < toolCalls.length) {
 						if (remainingToolCalls.length > 0 || typeof aiMsg.content === "string" && aiMsg.content.trim()) {
-							/**
-							* Keep the message but without transfer tool calls — AND
-							* without their `tool_use` content blocks. Array-content
-							* providers (Anthropic) serialize the retained blocks
-							* verbatim, so a transfer block whose call/result this
-							* filter just stripped would reach the receiving agent as
-							* an unmatched `tool_use` and the provider rejects the
-							* request. Filtered by transfer NAME as well as the
-							* gathered ids: a parallel sibling's transfer block has no
-							* result in THIS recipient's state, so its id is never
-							* collected, but its name still marks it.
-							*/
 							const filteredAiMsg = new _langchain_core_messages.AIMessage({
 								content: filterTransferToolUseBlocks(aiMsg.content, transferToolCallIds),
 								tool_calls: remainingToolCalls,
@@ -611,12 +427,10 @@ var MultiAgentGraph = class extends require_Graph.StandardGraph {
 							});
 							filteredMessages.push(filteredAiMsg);
 						}
-						/** If no remaining content or tool calls, skip this message entirely */
 						continue;
 					}
 				}
 			}
-			/** Keep all other messages */
 			filteredMessages.push(msg);
 		}
 		return {
@@ -627,9 +441,6 @@ var MultiAgentGraph = class extends require_Graph.StandardGraph {
 			parallelGroupId
 		};
 	}
-	/**
-	* Create the multi-agent workflow with dynamic handoffs
-	*/
 	createWorkflow() {
 		this.hasCompiledCheckpointer = this.compileOptions?.checkpointer != null;
 		const builder = new _langchain_langgraph.StateGraph(_langchain_langgraph.Annotation.Root({
@@ -642,9 +453,7 @@ var MultiAgentGraph = class extends require_Graph.StandardGraph {
 				},
 				default: () => []
 			}),
-			/** Channel for passing filtered messages to agents when excludeResults is true */
 			agentMessages: (0, _langchain_langgraph.Annotation)({
-				/** Replaces state entirely */
 				reducer: (a, b) => b,
 				default: () => []
 			}),
@@ -656,7 +465,6 @@ var MultiAgentGraph = class extends require_Graph.StandardGraph {
 		const addDirectEdge = (sources, destination) => {
 			if (sources.length === 0) return;
 			const source = sources.length === 1 ? sources[0] : sources;
-			/** @ts-ignore */
 			builder.addEdge(source, destination);
 		};
 		for (const [agentId] of this.agentContexts) {
@@ -664,16 +472,12 @@ var MultiAgentGraph = class extends require_Graph.StandardGraph {
 			const directDestinations = /* @__PURE__ */ new Set();
 			for (const edge of this.handoffEdges) if ((Array.isArray(edge.from) ? edge.from : [edge.from]).includes(agentId) === true) (Array.isArray(edge.to) ? edge.to : [edge.to]).forEach((dest) => handoffDestinations.add(dest));
 			for (const edge of this.directEdges) if ((Array.isArray(edge.from) ? edge.from : [edge.from]).includes(agentId) === true) (Array.isArray(edge.to) ? edge.to : [edge.to]).forEach((dest) => directDestinations.add(dest));
-			/** Check if this agent has BOTH handoff and direct edges */
 			const hasHandoffEdges = handoffDestinations.size > 0;
 			const hasDirectEdges = directDestinations.size > 0;
 			const needsCommandRouting = hasHandoffEdges && hasDirectEdges;
-			/** Collect all possible destinations for this agent */
 			const allDestinations = new Set([...handoffDestinations, ...directDestinations]);
 			if (handoffDestinations.size > 0 || directDestinations.size === 0) allDestinations.add(_langchain_langgraph.END);
-			/** Agent subgraph (includes agent + tools) */
 			const agentSubgraph = this.createAgentSubgraph(agentId);
-			/** Wrapper function that handles agentMessages channel, handoff reception, and conditional routing */
 			const agentWrapper = async (state, config) => {
 				let result;
 				let inputMessages = state.messages;
@@ -681,32 +485,13 @@ var MultiAgentGraph = class extends require_Graph.StandardGraph {
 					...config,
 					recursionLimit: this.memberRecursionLimit
 				};
-				/**
-				* 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);
 				const agentContext = this.agentContexts.get(agentId);
 				if (handoffContext?.sourceAgentName != null && handoffContext.sourceAgentName !== "") agentContext?.setHandoffContext(handoffContext.sourceAgentName, handoffContext.parallelSiblings);
 				else agentContext?.clearHandoffContext();
 				if (handoffContext !== null) {
 					const { filteredMessages, instructions, parallelGroupId } = handoffContext;
-					/** Build messages for the receiving agent */
 					let messagesForAgent = filteredMessages;
-					/**
-					* If there are instructions, inject them as a HumanMessage to
-					* ground the receiving agent.
-					*
-					* When the last filtered message is a ToolMessage (e.g. from a
-					* non-handoff tool the router called before handing off), a
-					* synthetic AIMessage is inserted first to satisfy the
-					* tool → assistant role ordering required by chat APIs.  Without
-					* this bridge, appending a HumanMessage directly after a
-					* ToolMessage causes "400 Unexpected role 'user' after role
-					* 'tool'" errors (see issue #54).
-					*/
 					const hasInstructions = instructions !== null && instructions !== "";
 					if (hasInstructions) {
 						const lastMsg = filteredMessages.length > 0 ? filteredMessages[filteredMessages.length - 1] : null;
@@ -717,14 +502,12 @@ var MultiAgentGraph = class extends require_Graph.StandardGraph {
 						];
 						else messagesForAgent = [...filteredMessages, buildRoutingPrompt(instructions)];
 					}
-					/** Update token map if we have a token counter */
 					if (agentContext?.tokenCounter && hasInstructions) {
 						const freshTokenMap = {};
 						for (let i = 0; i < Math.min(filteredMessages.length, this.startIndex); i++) {
 							const tokenCount = agentContext.indexTokenCountMap[i];
 							if (tokenCount !== void 0) freshTokenMap[i] = tokenCount;
 						}
-						/** Add tokens for the bridge AIMessage + instructions HumanMessage */
 						for (let i = filteredMessages.length; i < messagesForAgent.length; i++) freshTokenMap[i] = agentContext.tokenCounter(messagesForAgent[i]);
 						agentContext.updateTokenMapWithInstructions(freshTokenMap);
 					}
@@ -739,31 +522,19 @@ var MultiAgentGraph = class extends require_Graph.StandardGraph {
 						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
-					*/
 					if (agentContext && agentContext.tokenCounter) {
-						/** The agentMessages contains:
-						* 1. Filtered messages (0 to startIndex) - already have token counts
-						* 2. New prompt message - needs token counting
-						*/
 						const freshTokenMap = {};
-						/** 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 !== void 0) freshTokenMap[i] = tokenCount;
 						}
-						/** 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];
 							freshTokenMap[promptMessageIndex] = agentContext.tokenCounter(promptMessage);
 						}
-						/** Update the agent's token map with instructions added */
 						agentContext.updateTokenMapWithInstructions(freshTokenMap);
 					}
-					/** Temporary state with messages replaced by `agentMessages` */
 					const transformedState = {
 						...state,
 						messages: state.agentMessages
@@ -772,7 +543,6 @@ var MultiAgentGraph = class extends require_Graph.StandardGraph {
 					result = await agentSubgraph.invoke(transformedState, memberConfig);
 					result = {
 						...result,
-						/** Clear agentMessages for next agent */
 						agentMessages: []
 					};
 				} else result = await agentSubgraph.invoke(state, memberConfig);
@@ -783,45 +553,31 @@ var MultiAgentGraph = class extends require_Graph.StandardGraph {
 						message: getLastNewAiMessage(result.messages, inputMessages)
 					}
 				};
-				/** If agent has both handoff and direct edges, use Command for exclusive routing */
 				if (needsCommandRouting) {
-					/** Check if a handoff occurred */
 					const lastMessage = result.messages[result.messages.length - 1];
 					if (lastMessage != null && lastMessage.getType() === "tool" && typeof lastMessage.name === "string" && lastMessage.name.startsWith("lc_transfer_to_")) {
-						/** Handoff occurred - extract destination and navigate there exclusively */
 						const handoffDest = lastMessage.name.replace("lc_transfer_to_", "");
 						return new _langchain_langgraph.Command({
 							update: result,
 							goto: handoffDest
 						});
 					} else {
-						/** No handoff - proceed with direct edges */
 						const directDests = Array.from(directDestinations);
 						if (directDests.length === 1) return new _langchain_langgraph.Command({
 							update: result,
 							goto: directDests[0]
 						});
-						else if (directDests.length > 1)
- /** Multiple direct destinations - they'll run in parallel */
-						return new _langchain_langgraph.Command({
+						else if (directDests.length > 1) return new _langchain_langgraph.Command({
 							update: result,
 							goto: directDests
 						});
 					}
 				}
-				/** No special routing needed - return state normally */
 				return result;
 			};
-			/** Wrapped agent as a node with its possible destinations */
 			builder.addNode(agentId, agentWrapper, { ends: Array.from(allDestinations) });
 		}
-		for (const startNode of this.startingNodes)
- /** @ts-ignore */
-		builder.addEdge(_langchain_langgraph.START, startNode);
-		/**
-		* Add direct edges for automatic transitions
-		* Group edges by destination to handle fan-in scenarios
-		*/
+		for (const startNode of this.startingNodes) builder.addEdge(_langchain_langgraph.START, startNode);
 		const edgesByDestination = /* @__PURE__ */ new Map();
 		for (const edge of this.directEdges) {
 			const destinations = Array.isArray(edge.to) ? edge.to : [edge.to];
@@ -831,22 +587,10 @@ var MultiAgentGraph = class extends require_Graph.StandardGraph {
 			}
 		}
 		for (const [destination, edges] of edgesByDestination) {
-			/** Checks if this is a fan-in scenario with prompt instructions */
 			const edgesWithPrompt = edges.filter((edge) => edge.prompt != null && edge.prompt !== "");
 			if (edgesWithPrompt.length > 0) {
-				/**
-				* Single wrapper node for destination (Fan-in with prompt)
-				*/
 				const wrapperNodeId = `fan_in_${destination}_prompt`;
-				/**
-				* First edge's `prompt`
-				* (they should all be the same for fan-in)
-				*/
 				const prompt = edgesWithPrompt[0].prompt;
-				/**
-				* First edge's `excludeResults` flag
-				* (they should all be the same for fan-in)
-				*/
 				const excludeResults = edgesWithPrompt[0].excludeResults;
 				builder.addNode(wrapperNodeId, async (state) => {
 					let promptText;
@@ -859,9 +603,6 @@ var MultiAgentGraph = class extends require_Graph.StandardGraph {
 					} else promptText = prompt;
 					if (promptText != null && promptText !== "") {
 						if (effectiveExcludeResults == null || effectiveExcludeResults === false) return { messages: [buildRoutingPrompt(promptText)] };
-						/** When `excludeResults` is true, use agentMessages channel
-						* to pass filtered messages + prompt to the destination agent
-						*/
 						const filteredMessages = state.messages.slice(0, this.startIndex);
 						const promptMessage = buildRoutingPrompt(promptText);
 						return {
@@ -869,17 +610,11 @@ var MultiAgentGraph = class extends require_Graph.StandardGraph {
 							agentMessages: (0, _langchain_langgraph.messagesStateReducer)(filteredMessages, [promptMessage])
 						};
 					}
-					/** No prompt needed, return empty update */
 					return {};
 				});
-				/** Add edges from all sources to the wrapper, then wrapper to destination */
 				for (const edge of edges) addDirectEdge(Array.isArray(edge.from) ? edge.from : [edge.from], wrapperNodeId);
-				/** Single edge from wrapper to destination */
-				/** @ts-ignore */
 				builder.addEdge(wrapperNodeId, destination);
-			} else
- /** No prompt instructions, add direct edges (skip if source uses Command routing) */
-			for (const edge of edges) addDirectEdge((Array.isArray(edge.from) ? edge.from : [edge.from]).filter((source) => !this.handoffEdges.some((handoffEdge) => {
+			} else for (const edge of edges) addDirectEdge((Array.isArray(edge.from) ? edge.from : [edge.from]).filter((source) => !this.handoffEdges.some((handoffEdge) => {
 				return (Array.isArray(handoffEdge.from) ? handoffEdge.from : [handoffEdge.from]).includes(source);
 			})), destination);
 		}