@illuma-ai/agents 1.0.90 → 1.0.93

package/src/graphs/MultiAgentGraph.ts

@@ -4,6 +4,7 @@ import {
   AIMessage,
   ToolMessage,
   HumanMessage,
+  SystemMessage,
   getBufferString,
 } from '@langchain/core/messages';
 import {
@@ -15,11 +16,13 @@ import {
   getCurrentTaskInput,
   messagesStateReducer,
 } from '@langchain/langgraph';
+import type { LangGraphRunnableConfig } from '@langchain/langgraph';
 import type { BaseMessage, AIMessageChunk } from '@langchain/core/messages';
 import type { ToolRunnableConfig } from '@langchain/core/tools';
 import type * as t from '@/types';
+import { summarize, createEmergencySummary } from '@/messages';
 import { StandardGraph } from './Graph';
-import { Constants } from '@/common';
+import { Constants, EdgeType } from '@/common';
 
 /** Pattern to extract instructions from transfer ToolMessage content */
 const HANDOFF_INSTRUCTIONS_PATTERN = /(?:Instructions?|Context):\s*(.+)/is;
@@ -66,6 +69,9 @@ export class MultiAgentGraph extends StandardGraph {
     this.categorizeEdges();
     this.analyzeGraph();
     this.createHandoffTools();
+    console.debug(
+      `[MultiAgentGraph] Constructor complete: ${this.agentContexts.size} agents, ${this.edges.length} edges`
+    );
   }
 
   /**
@@ -75,9 +81,9 @@ export 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 {
         // Default: single-to-single edges are handoff, single-to-multiple are direct
@@ -93,6 +99,9 @@ export class MultiAgentGraph extends StandardGraph {
         }
       }
     }
+    console.debug(
+      `[MultiAgentGraph] Edge categorization: ${this.handoffEdges.length} handoff, ${this.directEdges.length} direct (of ${this.edges.length} total)`
+    );
   }
 
   /**
@@ -119,6 +128,10 @@ export class MultiAgentGraph extends StandardGraph {
       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();
   }
@@ -269,11 +282,13 @@ export class MultiAgentGraph extends StandardGraph {
         );
       }
 
-      // 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(', ')}]`
+      );
     }
   }
 
@@ -358,15 +373,15 @@ export class MultiAgentGraph extends StandardGraph {
             name: toolName,
             schema: hasHandoffInput
               ? {
-                type: 'object',
-                properties: {
-                  [promptKey]: {
-                    type: 'string',
-                    description: handoffInputDescription as string,
+                  type: 'object',
+                  properties: {
+                    [promptKey]: {
+                      type: 'string',
+                      description: handoffInputDescription as string,
+                    },
                   },
-                },
-                required: [],
-              }
+                  required: [],
+                }
               : { type: 'object', properties: {}, required: [] },
             description: toolDescription,
           }
@@ -378,7 +393,8 @@ export class MultiAgentGraph extends StandardGraph {
         const toolName = `${Constants.LC_TRANSFER_TO_}${destination}`;
         const destContext = this.agentContexts.get(destination);
         const toolDescription =
-          edge.description ?? this.buildDefaultHandoffDescription(destContext, destination);
+          edge.description ??
+          this.buildDefaultHandoffDescription(destContext, destination);
 
         /** Check if we have a prompt for handoff input */
         const hasHandoffInput =
@@ -491,15 +507,15 @@ export class MultiAgentGraph extends StandardGraph {
               name: toolName,
               schema: hasHandoffInput
                 ? {
-                  type: 'object',
-                  properties: {
-                    [promptKey]: {
-                      type: 'string',
-                      description: handoffInputDescription as string,
+                    type: 'object',
+                    properties: {
+                      [promptKey]: {
+                        type: 'string',
+                        description: handoffInputDescription as string,
+                      },
                     },
-                  },
-                  required: [],
-                }
+                    required: [],
+                  }
                 : { type: 'object', properties: {}, required: [] },
               description: toolDescription,
             }
@@ -525,7 +541,7 @@ export class MultiAgentGraph extends StandardGraph {
     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}"`;
@@ -686,9 +702,14 @@ export class MultiAgentGraph extends StandardGraph {
               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,
               });
@@ -705,89 +726,129 @@ export class MultiAgentGraph extends StandardGraph {
     }
 
     /**
-     * Compact content_tool messages to reduce handoff context bloat.
+     * Flatten tool call/result pairs into text summaries for handoff.
+     *
+     * 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.
      *
-     * 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.
+     * 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 msgType = msg.getType();
+    const compactedMessages: BaseMessage[] = [];
 
-      /** Compact content_tool ToolMessage outputs */
-      if (msgType === 'tool') {
-        const toolMsg = msg as ToolMessage;
-        if (toolMsg.name !== 'content_tool') return msg;
-
-        const content =
-          typeof toolMsg.content === 'string'
-            ? toolMsg.content
-            : Array.isArray(toolMsg.content)
-              ? toolMsg.content
-                .filter(
-                  (b): b is { type: string; text: string } =>
-                    typeof b === 'object' &&
-                    b != null &&
-                    'text' in b &&
-                    typeof (b as Record<string, unknown>).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 as 'success' | 'error' | undefined,
-          });
-        }
-        return msg;
-      }
+    for (let i = 0; i < filteredMessages.length; i++) {
+      const msg = filteredMessages[i];
+      const msgType = msg.getType();
 
-      /** Compact content_tool AI message args (remove large content/old_str/new_str fields) */
       if (msgType === 'ai') {
         const aiMsg = msg as AIMessage | AIMessageChunk;
         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 as Record<string, unknown>).content === 'string' &&
-              ((tc.args as Record<string, unknown>).content as string).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 as Record<string, unknown>;
-            const compacted: Record<string, unknown> = { 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,
-            id: aiMsg.id,
-          });
+        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): b is { type: string; text: string } =>
+                        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: string[] = [];
+          while (i + 1 < filteredMessages.length) {
+            const next = filteredMessages[i + 1];
+            if (next.getType() !== 'tool') break;
+
+            const toolMsg = next as ToolMessage;
+            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): b is { type: string; text: string } =>
+                          typeof b === 'object' &&
+                          'text' in b &&
+                          typeof (b as Record<string, unknown>).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,
@@ -866,8 +927,12 @@ export class MultiAgentGraph extends StandardGraph {
 
       /** Wrapper function that handles agentMessages channel, handoff reception, and conditional routing */
       const agentWrapper = async (
-        state: t.MultiAgentGraphState
+        state: t.MultiAgentGraphState,
+        config?: LangGraphRunnableConfig
       ): Promise<t.MultiAgentGraphState | Command> => {
+        console.debug(
+          `[MultiAgentGraph] Agent "${agentId}" wrapper ENTRY (messages: ${state.messages.length}, needsCommandRouting: ${needsCommandRouting})`
+        );
         let result: t.MultiAgentGraphState;
 
         /**
@@ -888,6 +953,9 @@ export class MultiAgentGraph extends StandardGraph {
             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.
@@ -905,13 +973,39 @@ export 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 */
@@ -927,10 +1021,14 @@ export 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);
           }
 
@@ -938,7 +1036,7 @@ export class MultiAgentGraph extends StandardGraph {
             ...state,
             messages: messagesForAgent,
           };
-          result = await agentSubgraph.invoke(transformedState);
+          result = await agentSubgraph.invoke(transformedState, config);
           result = {
             ...result,
             agentMessages: [],
@@ -984,19 +1082,23 @@ export 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 */
             agentMessages: [],
           };
         } 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 */
@@ -1014,12 +1116,129 @@ export class MultiAgentGraph extends StandardGraph {
               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 as ToolMessage).tool_call_id,
+                name: lastMessage.name,
+              });
+              (errorMsg as ToolMessage).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,
             });
           } 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({