@illuma-ai/agents 1.0.90 → 1.0.93

package/dist/esm/graphs/MultiAgentGraph.mjs

@@ -1,9 +1,13 @@
 import { tool } from '@langchain/core/tools';
 import { PromptTemplate } from '@langchain/core/prompts';
-import { ToolMessage, AIMessage, getBufferString, HumanMessage } from '@langchain/core/messages';
+import { ToolMessage, AIMessage, getBufferString, HumanMessage, SystemMessage } from '@langchain/core/messages';
 import { getCurrentTaskInput, Command, Annotation, messagesStateReducer, StateGraph, END, START } from '@langchain/langgraph';
+import '../messages/core.mjs';
+import 'nanoid';
+import { EdgeType, Constants } from '../common/enum.mjs';
+import '../utils/toonFormat.mjs';
+import { summarize, createEmergencySummary } from '../messages/summarize.mjs';
 import { StandardGraph } from './Graph.mjs';
-import { Constants } from '../common/enum.mjs';
 
 /** Pattern to extract instructions from transfer ToolMessage content */
 const HANDOFF_INSTRUCTIONS_PATTERN = /(?:Instructions?|Context):\s*(.+)/is;
@@ -48,6 +52,7 @@ class MultiAgentGraph extends StandardGraph {
         this.categorizeEdges();
         this.analyzeGraph();
         this.createHandoffTools();
+        console.debug(`[MultiAgentGraph] Constructor complete: ${this.agentContexts.size} agents, ${this.edges.length} edges`);
     }
     /**
      * Categorize edges into handoff and direct types
@@ -56,10 +61,10 @@ class MultiAgentGraph extends StandardGraph {
         for (const edge of this.edges) {
             // Default behavior: edges with conditions or explicit 'handoff' type are handoff edges
             // Edges with explicit 'direct' type or multi-destination without conditions are direct edges
-            if (edge.edgeType === 'direct') {
+            if (edge.edgeType === EdgeType.DIRECT) {
                 this.directEdges.push(edge);
             }
-            else if (edge.edgeType === 'handoff' || edge.condition != null) {
+            else if (edge.edgeType === EdgeType.HANDOFF || edge.condition != null) {
                 this.handoffEdges.push(edge);
             }
             else {
@@ -76,6 +81,7 @@ class MultiAgentGraph extends StandardGraph {
                 }
             }
         }
+        console.debug(`[MultiAgentGraph] Edge categorization: ${this.handoffEdges.length} handoff, ${this.directEdges.length} direct (of ${this.edges.length} total)`);
     }
     /**
      * Analyze graph structure to determine starting nodes and connections
@@ -97,6 +103,7 @@ class MultiAgentGraph extends StandardGraph {
         if (this.startingNodes.size === 0 && this.agentContexts.size > 0) {
             this.startingNodes.add(this.agentContexts.keys().next().value);
         }
+        console.debug(`[MultiAgentGraph] Starting nodes identified: [${Array.from(this.startingNodes).join(', ')}]`);
         // Determine if graph has parallel execution capability
         this.computeParallelCapability();
     }
@@ -230,11 +237,11 @@ class MultiAgentGraph extends StandardGraph {
             for (const edge of edges) {
                 handoffTools.push(...this.createHandoffToolsForEdge(edge, agentId, sourceAgentName));
             }
-            // Add handoff tools to the agent's existing tools
-            if (!agentContext.tools) {
-                agentContext.tools = [];
+            if (!agentContext.graphTools) {
+                agentContext.graphTools = [];
             }
-            agentContext.tools.push(...handoffTools);
+            agentContext.graphTools.push(...handoffTools);
+            console.debug(`[MultiAgentGraph] Handoff tools for "${agentId}": [${handoffTools.map((t) => t.name).join(', ')}]`);
         }
     }
     /**
@@ -319,7 +326,8 @@ class MultiAgentGraph extends StandardGraph {
             for (const destination of destinations) {
                 const toolName = `${Constants.LC_TRANSFER_TO_}${destination}`;
                 const destContext = this.agentContexts.get(destination);
-                const toolDescription = edge.description ?? this.buildDefaultHandoffDescription(destContext, destination);
+                const toolDescription = edge.description ??
+                    this.buildDefaultHandoffDescription(destContext, destination);
                 /** Check if we have a prompt for handoff input */
                 const hasHandoffInput = edge.prompt != null && typeof edge.prompt === 'string';
                 const handoffInputDescription = hasHandoffInput
@@ -436,7 +444,7 @@ class MultiAgentGraph extends StandardGraph {
     buildDefaultHandoffDescription(destContext, destinationId) {
         const displayName = destContext?.name ?? destinationId;
         const agentDescription = destContext?.description;
-        if (agentDescription) {
+        if (agentDescription != null && agentDescription !== '') {
             return `Transfer to "${displayName}": ${agentDescription}`;
         }
         return `Transfer control to "${displayName}"`;
@@ -564,9 +572,13 @@ class MultiAgentGraph extends StandardGraph {
                     if (hasTransferCalls) {
                         if (remainingToolCalls.length > 0 ||
                             (typeof aiMsg.content === 'string' && aiMsg.content.trim())) {
-                            /** Keep the message but without transfer tool calls */
+                            /** Keep the message but without transfer tool calls.
+                             *  Trim trailing whitespace to prevent Bedrock validation errors. */
+                            const trimmedContent = typeof aiMsg.content === 'string'
+                                ? aiMsg.content.trimEnd()
+                                : aiMsg.content;
                             const filteredAiMsg = new AIMessage({
-                                content: aiMsg.content,
+                                content: trimmedContent,
                                 tool_calls: remainingToolCalls,
                                 id: aiMsg.id,
                             });
@@ -581,83 +593,97 @@ class MultiAgentGraph extends StandardGraph {
             filteredMessages.push(msg);
         }
         /**
-         * Compact content_tool messages to reduce handoff context bloat.
+         * Flatten tool call/result pairs into text summaries for handoff.
          *
-         * 1. ToolMessages: Verbose outputs (read with line-numbered code, write confirmations)
-         *    are summarized to their first line, preserving file awareness without full code.
-         * 2. AIMessages: content_tool tool_calls with large args (write/edit with full file content)
-         *    have their args compacted to remove the bulk content field.
+         * When agent A uses tools and then hands off to agent B, agent B may not
+         * have the same tools configured. Providers like Bedrock require toolConfig
+         * when tool_use/tool_result blocks are in the message history. Converting
+         * tool interactions to text summaries avoids this and reduces context bloat.
+         *
+         * Strategy: Walk through messages and merge each (AIMessage-with-tool_calls +
+         * following ToolMessages) group into a single AIMessage containing the original
+         * text plus a textual summary of the tool interaction. This preserves proper
+         * message role ordering (human/assistant alternation).
          */
-        const compactedMessages = filteredMessages.map((msg) => {
+        const compactedMessages = [];
+        for (let i = 0; i < filteredMessages.length; i++) {
+            const msg = filteredMessages[i];
             const msgType = msg.getType();
-            /** Compact content_tool ToolMessage outputs */
-            if (msgType === 'tool') {
-                const toolMsg = msg;
-                if (toolMsg.name !== 'content_tool')
-                    return msg;
-                const content = typeof toolMsg.content === 'string'
-                    ? toolMsg.content
-                    : Array.isArray(toolMsg.content)
-                        ? toolMsg.content
-                            .filter((b) => typeof b === 'object' &&
-                            b != null &&
-                            'text' in b &&
-                            typeof b.text === 'string')
-                            .map((b) => b.text)
-                            .join('\n')
-                        : JSON.stringify(toolMsg.content);
-                if (content.length > 500) {
-                    const firstLine = content.split('\n')[0];
-                    return new ToolMessage({
-                        content: firstLine + ' [content summarized for handoff]',
-                        name: toolMsg.name,
-                        tool_call_id: toolMsg.tool_call_id,
-                        status: toolMsg.status,
-                    });
-                }
-                return msg;
-            }
-            /** Compact content_tool AI message args (remove large content/old_str/new_str fields) */
             if (msgType === 'ai') {
                 const aiMsg = msg;
                 const toolCalls = aiMsg.tool_calls;
-                if (!toolCalls || toolCalls.length === 0)
-                    return msg;
-                const hasLargeContentToolArgs = toolCalls.some((tc) => tc.name === 'content_tool' &&
-                    typeof tc.args === 'object' &&
-                    tc.args != null &&
-                    (typeof tc.args.content === 'string' &&
-                        tc.args.content.length > 200));
-                if (hasLargeContentToolArgs) {
-                    const compactedToolCalls = toolCalls.map((tc) => {
-                        if (tc.name !== 'content_tool' || typeof tc.args !== 'object' || tc.args == null) {
-                            return tc;
-                        }
-                        const args = tc.args;
-                        const compacted = { action: args.action };
-                        if (args.content_id)
-                            compacted.content_id = args.content_id;
-                        if (args.name)
-                            compacted.name = args.name;
-                        if (args.content)
-                            compacted.content = '[content removed for handoff]';
-                        if (args.old_str)
-                            compacted.old_str = '[removed for handoff]';
-                        if (args.new_str)
-                            compacted.new_str = '[removed for handoff]';
-                        if (args.pattern)
-                            compacted.pattern = args.pattern;
-                        return { ...tc, args: compacted };
-                    });
-                    return new AIMessage({
-                        content: aiMsg.content,
-                        tool_calls: compactedToolCalls,
+                if (toolCalls && toolCalls.length > 0) {
+                    /** Extract text content from the AIMessage */
+                    const textContent = typeof aiMsg.content === 'string'
+                        ? aiMsg.content
+                        : Array.isArray(aiMsg.content)
+                            ? aiMsg.content
+                                .filter((b) => typeof b === 'object' &&
+                                b.type === 'text' &&
+                                'text' in b)
+                                .map((b) => b.text)
+                                .join('\n')
+                            : '';
+                    /** Collect tool_call_ids so we can match following ToolMessages */
+                    const callIds = new Set(toolCalls.map((tc) => tc.id).filter(Boolean));
+                    /** Build summary of what tools were called */
+                    const callSummaries = toolCalls.map((tc) => `[Called "${tc.name}"]`);
+                    /** Consume following ToolMessages that belong to this AI message */
+                    const resultSummaries = [];
+                    while (i + 1 < filteredMessages.length) {
+                        const next = filteredMessages[i + 1];
+                        if (next.getType() !== 'tool')
+                            break;
+                        const toolMsg = next;
+                        if (!callIds.has(toolMsg.tool_call_id))
+                            break;
+                        /** Extract and summarize the tool result */
+                        const rawContent = typeof toolMsg.content === 'string'
+                            ? toolMsg.content
+                            : Array.isArray(toolMsg.content)
+                                ? toolMsg.content
+                                    .filter((b) => typeof b === 'object' &&
+                                    'text' in b &&
+                                    typeof b.text ===
+                                        'string')
+                                    .map((b) => b.text)
+                                    .join('\n')
+                                : JSON.stringify(toolMsg.content);
+                        const summary = rawContent.length > 500
+                            ? rawContent.split('\n')[0] + ' [truncated for handoff]'
+                            : rawContent;
+                        resultSummaries.push(`[Tool "${toolMsg.name}" returned: ${summary}]`);
+                        i++; // Skip this ToolMessage in the outer loop
+                    }
+                    /** Merge everything into a single AIMessage */
+                    const parts = [
+                        textContent,
+                        ...callSummaries,
+                        ...resultSummaries,
+                    ].filter(Boolean);
+                    /** Bedrock rejects messages with trailing whitespace */
+                    const mergedContent = (parts.join('\n') || '[Agent processed tools]').trimEnd();
+                    compactedMessages.push(new AIMessage({
+                        content: mergedContent,
                         id: aiMsg.id,
-                    });
+                    }));
+                    continue;
                 }
             }
-            return msg;
-        });
+            /** Skip orphaned ToolMessages (their AI parent was already handled above,
+             *  or they belong to a transfer that was already filtered out) */
+            if (msgType === 'tool') {
+                continue;
+            }
+            /** Trim trailing whitespace on AI messages to prevent Bedrock validation errors */
+            if (msgType === 'ai' &&
+                typeof msg.content === 'string' &&
+                msg.content !== msg.content.trimEnd()) {
+                compactedMessages.push(new AIMessage({ content: msg.content.trimEnd(), id: msg.id }));
+                continue;
+            }
+            compactedMessages.push(msg);
+        }
         return {
             filteredMessages: compactedMessages,
             instructions,
@@ -725,7 +751,8 @@ class MultiAgentGraph extends StandardGraph {
             /** 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) => {
+            const agentWrapper = async (state, config) => {
+                console.debug(`[MultiAgentGraph] Agent "${agentId}" wrapper ENTRY (messages: ${state.messages.length}, needsCommandRouting: ${needsCommandRouting})`);
                 let result;
                 /**
                  * Check if this agent is receiving a handoff.
@@ -736,6 +763,7 @@ class MultiAgentGraph extends StandardGraph {
                 const handoffContext = this.processHandoffReception(state.messages, agentId);
                 if (handoffContext !== null) {
                     const { filteredMessages, instructions, sourceAgentName, parallelSiblings, } = handoffContext;
+                    console.debug(`[MultiAgentGraph] Agent "${agentId}" receiving handoff from "${sourceAgentName}" (instructions: ${instructions != null}, parallelSiblings: ${parallelSiblings.length})`);
                     /**
                      * Set handoff context on the receiving agent.
                      * Uses pre-computed graph position for depth and parallel info.
@@ -748,13 +776,36 @@ class MultiAgentGraph extends StandardGraph {
                     }
                     /** Build messages for the receiving agent */
                     let messagesForAgent = filteredMessages;
-                    /** If there are instructions, inject them as a HumanMessage to ground the agent */
+                    /**
+                     * 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) {
-                        messagesForAgent = [
-                            ...filteredMessages,
-                            new HumanMessage(instructions),
-                        ];
+                        const lastMsg = filteredMessages.length > 0
+                            ? filteredMessages[filteredMessages.length - 1]
+                            : null;
+                        if (lastMsg != null && lastMsg.getType() === 'tool') {
+                            messagesForAgent = [
+                                ...filteredMessages,
+                                new AIMessage(`[Processed tool result and transferring to ${agentId}]`),
+                                new HumanMessage(instructions),
+                            ];
+                        }
+                        else {
+                            messagesForAgent = [
+                                ...filteredMessages,
+                                new HumanMessage(instructions),
+                            ];
+                        }
                     }
                     /** Update token map if we have a token counter */
                     if (agentContext?.tokenCounter && hasInstructions) {
@@ -765,17 +816,17 @@ class MultiAgentGraph extends StandardGraph {
                                 freshTokenMap[i] = tokenCount;
                             }
                         }
-                        /** Add tokens for the instructions message */
-                        const instructionsMsg = new HumanMessage(instructions);
-                        freshTokenMap[messagesForAgent.length - 1] =
-                            agentContext.tokenCounter(instructionsMsg);
+                        /** 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);
                     }
                     const transformedState = {
                         ...state,
                         messages: messagesForAgent,
                     };
-                    result = await agentSubgraph.invoke(transformedState);
+                    result = await agentSubgraph.invoke(transformedState, config);
                     result = {
                         ...result,
                         agentMessages: [],
@@ -816,7 +867,7 @@ class MultiAgentGraph extends StandardGraph {
                         ...state,
                         messages: state.agentMessages,
                     };
-                    result = await agentSubgraph.invoke(transformedState);
+                    result = await agentSubgraph.invoke(transformedState, config);
                     result = {
                         ...result,
                         /** Clear agentMessages for next agent */
@@ -824,10 +875,11 @@ class MultiAgentGraph extends StandardGraph {
                     };
                 }
                 else {
-                    result = await agentSubgraph.invoke(state);
+                    result = await agentSubgraph.invoke(state, config);
                 }
                 /** Track the last agent that produced output for continuation support */
                 this.lastActiveAgentId = agentId;
+                console.debug(`[MultiAgentGraph] Agent "${agentId}" wrapper EXIT (result messages: ${result.messages.length})`);
                 /** If agent has both handoff and direct edges, use Command for exclusive routing */
                 if (needsCommandRouting) {
                     /** Check if a handoff occurred */
@@ -838,6 +890,84 @@ class MultiAgentGraph extends StandardGraph {
                         lastMessage.name.startsWith(Constants.LC_TRANSFER_TO_)) {
                         /** Handoff occurred - extract destination and navigate there exclusively */
                         const handoffDest = lastMessage.name.replace(Constants.LC_TRANSFER_TO_, '');
+                        console.debug(`[MultiAgentGraph] Command routing: "${agentId}" -> handoff to "${handoffDest}" (direct edges skipped: [${Array.from(directDestinations).join(', ')}])`);
+                        /** Validate destination agent exists */
+                        if (!this.agentContexts.has(handoffDest)) {
+                            const availableAgents = Array.from(this.agentContexts.keys()).join(', ');
+                            console.error(`[MultiAgentGraph] Handoff to non-existent agent "${handoffDest}". Available: ${availableAgents}`);
+                            /** Return error to model so it can self-correct */
+                            const errorMsg = new ToolMessage({
+                                content: `Transfer failed: agent "${handoffDest}" does not exist. Available agents: ${availableAgents}. Please choose a valid agent to transfer to.`,
+                                tool_call_id: lastMessage.tool_call_id,
+                                name: lastMessage.name,
+                            });
+                            errorMsg.status = 'error';
+                            return {
+                                messages: [...result.messages, errorMsg],
+                            };
+                        }
+                        /** Pre-handoff context compaction: if receiving agent has smaller budget */
+                        const receiverContext = this.agentContexts.get(handoffDest);
+                        const senderContext = this.agentContexts.get(agentId);
+                        if (receiverContext?.maxContextTokens != null &&
+                            senderContext?.tokenCounter != null &&
+                            receiverContext.maxContextTokens > 0) {
+                            let currentSize = 0;
+                            for (const msg of result.messages) {
+                                currentSize += senderContext.tokenCounter(msg);
+                            }
+                            const receiverBudget = receiverContext.maxContextTokens;
+                            if (currentSize > receiverBudget * 0.7) {
+                                console.warn(`[MultiAgentGraph] Pre-handoff compaction: context (${currentSize} tokens) exceeds ` +
+                                    `70% of receiver "${handoffDest}" budget (${receiverBudget} tokens)`);
+                                /** Generate handoff briefing */
+                                const senderName = senderContext.name ?? agentId;
+                                if (senderContext.summarizeCallback) {
+                                    try {
+                                        const briefingResult = await summarize(result.messages, async (prompt, _maxTokens) => senderContext.summarizeCallback([
+                                            new HumanMessage(prompt),
+                                        ]), {
+                                            tokenCounter: senderContext.tokenCounter,
+                                            summaryBudget: Math.floor(receiverBudget * 0.2),
+                                            isMultiAgent: true,
+                                            agentWorkflowState: {
+                                                currentAgentId: handoffDest,
+                                                agentChain: [agentId, handoffDest],
+                                                pendingAgents: [],
+                                            },
+                                        });
+                                        const briefingMsg = new SystemMessage(`[Handoff Briefing from "${senderName}"]\n${briefingResult.summary}`);
+                                        /** Replace messages with briefing + last 3 messages */
+                                        const keepCount = Math.min(3, result.messages.length);
+                                        result = {
+                                            ...result,
+                                            messages: [
+                                                briefingMsg,
+                                                ...result.messages.slice(result.messages.length - keepCount),
+                                            ],
+                                        };
+                                        console.info(`[MultiAgentGraph] Pre-handoff compaction complete: ${currentSize} tokens → briefing + ${keepCount} messages`);
+                                    }
+                                    catch (compactErr) {
+                                        console.error('[MultiAgentGraph] Pre-handoff compaction failed:', compactErr);
+                                        /** Continue without compaction — let receiver handle the overflow */
+                                    }
+                                }
+                                else {
+                                    /** No summary callback — use emergency summary */
+                                    const emergencySummary = createEmergencySummary(result.messages);
+                                    const briefingMsg = new SystemMessage(`[Handoff Briefing from "${senderName}" — Emergency]\n${emergencySummary}`);
+                                    const keepCount = Math.min(3, result.messages.length);
+                                    result = {
+                                        ...result,
+                                        messages: [
+                                            briefingMsg,
+                                            ...result.messages.slice(result.messages.length - keepCount),
+                                        ],
+                                    };
+                                }
+                            }
+                        }
                         return new Command({
                             update: result,
                             goto: handoffDest,
@@ -845,6 +975,7 @@ class MultiAgentGraph extends StandardGraph {
                     }
                     else {
                         /** No handoff - proceed with direct edges */
+                        console.debug(`[MultiAgentGraph] Command routing: "${agentId}" -> no handoff, following direct edges: [${Array.from(directDestinations).join(', ')}]`);
                         const directDests = Array.from(directDestinations);
                         if (directDests.length === 1) {
                             return new Command({