@illuma-ai/agents 1.1.25 → 1.3.0

package/dist/esm/graphs/Graph.mjs

@@ -31,6 +31,9 @@ import { getChatModelClass, manualToolStreamProviders } from '../llm/providers.m
 import { ToolNode, toolsCondition } from '../tools/ToolNode.mjs';
 import { ChatOpenAI, AzureChatOpenAI } from '../llm/openai/index.mjs';
 import { safeDispatchCustomEvent } from '../utils/events.mjs';
+import { mwarn, mlog } from '../utils/logging.mjs';
+import { normalizeMessageToolCalls } from '../utils/toolCallNormalization.mjs';
+import { isTruncationReason } from '../utils/finishReasons.mjs';
 import { createSchemaOnlyTools } from '../tools/schema.mjs';
 import { prepareSchemaForProvider } from '../schemas/validate.mjs';
 import { AgentContext } from '../agents/AgentContext.mjs';
@@ -795,7 +798,7 @@ class StandardGraph extends Graph {
             const resolved = agentContext.resolveStructuredOutputMode();
             method = resolved.method;
             if (resolved.warnings.length > 0) {
-                console.warn('[Graph] Structured output mode warnings:', resolved.warnings);
+                mwarn('[Graph] Structured output mode warnings:', resolved.warnings);
             }
         }
         else {
@@ -818,7 +821,7 @@ class StandardGraph extends Graph {
             const { schema: prepared, warnings } = prepareSchemaForProvider(schema, provider, structuredOutputConfig.strict !== false);
             preparedSchema = prepared;
             if (warnings.length > 0) {
-                console.warn('[Graph] Schema preparation warnings:', warnings);
+                mwarn('[Graph] Schema preparation warnings:', warnings);
             }
         }
         // Use withStructuredOutput to bind the schema
@@ -888,7 +891,7 @@ class StandardGraph extends Graph {
                 const errorMessage = typeof handleErrors === 'string'
                     ? handleErrors
                     : `The response did not match the expected schema. Error: ${lastError.message}. Please try again with a valid response.`;
-                console.warn(`[Graph] Structured output attempt ${attempts} failed: ${lastError.message}. Retrying...`);
+                mwarn(`[Graph] Structured output attempt ${attempts} failed: ${lastError.message}. Retrying...`);
                 // Add the error as a human message for context
                 finalMessages = [
                     ...finalMessages,
@@ -1038,7 +1041,7 @@ class StandardGraph extends Graph {
             const cachedDiscoveries = this._toolDiscoveryCache.getNewDiscoveries(messages);
             if (cachedDiscoveries.length > 0) {
                 agentContext.markToolsAsDiscovered(cachedDiscoveries);
-                console.debug(`[Graph:ToolDiscovery] Cached ${cachedDiscoveries.length} new tools (total: ${this._toolDiscoveryCache.size})`);
+                mlog(`[Graph:ToolDiscovery] Cached ${cachedDiscoveries.length} new tools (total: ${this._toolDiscoveryCache.size})`);
             }
             const toolsForBinding = agentContext.getToolsForBinding();
             // PERF: Detect subsequent ReAct iterations (tool results present in messages)
@@ -1056,6 +1059,11 @@ class StandardGraph extends Graph {
                     provider: agentContext.provider,
                     clientOptions: effectiveClientOptions,
                 });
+            // DEBUG: Log which model and tools each agent uses during handoff
+            mlog(`[createCallModel] Agent "${agentId}" invoking LLM | provider=${agentContext.provider} | ` +
+                `model=${effectiveClientOptions.model ?? 'default'} | ` +
+                `toolsForBinding=${toolsForBinding?.length ?? 0} | ` +
+                `toolNames=[${(toolsForBinding ?? []).map((t) => t.name ?? 'unknown').join(', ')}]`);
             if (agentContext.systemRunnable) {
                 model = agentContext.systemRunnable.pipe(model);
             }
@@ -1065,7 +1073,15 @@ class StandardGraph extends Graph {
             if (!config.signal) {
                 config.signal = this.signal;
             }
-            this.config = config;
+            // First-writer-wins: `this.config` is used ONLY as a "has a run started"
+            // existence flag by the dispatch* methods (they never read its value —
+            // they read the current RunnableConfig from LangChain AsyncLocalStorage).
+            // Unconditionally reassigning here races across concurrent child
+            // subgraph.invoke() calls under parallel multi-agent handoffs; the last
+            // writer wins, and any dispatch firing between writes would historically
+            // have been tagged with the wrong child's metadata. Keeping the first
+            // write pinned makes this a true flag, eliminating the race.
+            this.config ??= config;
             let messagesToUse = messages;
             // ====================================================================
             // PRE-PRUNING DELEGATION CHECK
@@ -1131,13 +1147,13 @@ class StandardGraph extends Graph {
                     const oldMessages = messages.slice(messages[0]?.getType() === 'system' ? 1 : 0, Math.max(1, messages.length - recentTurnCount));
                     if (oldMessages.length > 0) {
                         this._summaryInFlight = true;
-                        console.debug(`[Graph:ProactiveSummary] Context at ${utilization.toFixed(1)}% (threshold ${threshold}%) — summarizing ${oldMessages.length} older msgs in background`);
+                        mlog(`[Graph:ProactiveSummary] Context at ${utilization.toFixed(1)}% (threshold ${threshold}%) — summarizing ${oldMessages.length} older msgs in background`);
                         agentContext
                             .summarizeCallback(oldMessages)
                             .then((updated) => {
                             if (updated != null && updated !== '') {
                                 this._cachedRunSummary = updated;
-                                console.debug(`[Graph:ProactiveSummary] Background summary ready (len=${updated.length})`);
+                                mlog(`[Graph:ProactiveSummary] Background summary ready (len=${updated.length})`);
                             }
                         })
                             .catch((err) => {
@@ -1313,7 +1329,7 @@ class StandardGraph extends Graph {
                     viewIdx++;
                 }
                 agentContext.indexTokenCountMap = viewTokenMap;
-                console.debug(`[Graph:Compaction] ${messages.length}→${viewParts.length} msgs | ` +
+                mlog(`[Graph:Compaction] ${messages.length}→${viewParts.length} msgs | ` +
                     `compacted=${compactedMessages.length} window=${recentMessages.length} | ` +
                     `summary=${summarySource} | budget=${usedTokens}/${recentBudget}` +
                     (fileManifestTokens > 0
@@ -1327,7 +1343,7 @@ class StandardGraph extends Graph {
                     if (shouldSummarize) {
                         if (this._summaryInFlight) {
                             this._pendingMessagesToRefine.push(...compactedMessages);
-                            console.debug(`[Graph:Compaction] Summary in-flight, queued ${compactedMessages.length} msgs (pending=${this._pendingMessagesToRefine.length})`);
+                            mlog(`[Graph:Compaction] Summary in-flight, queued ${compactedMessages.length} msgs (pending=${this._pendingMessagesToRefine.length})`);
                         }
                         else {
                             this._summaryInFlight = true;
@@ -1368,7 +1384,7 @@ class StandardGraph extends Graph {
             const { messages: dedupedMessages, removedCount } = deduplicateSystemMessages(messagesToUse);
             if (removedCount > 0) {
                 messagesToUse = dedupedMessages;
-                console.debug(`[Graph:Dedup] Removed ${removedCount} duplicate system message(s)`);
+                mlog(`[Graph:Dedup] Removed ${removedCount} duplicate system message(s)`);
             }
             let finalMessages = messagesToUse;
             if (agentContext.useLegacyContent) {
@@ -1542,8 +1558,8 @@ class StandardGraph extends Graph {
                     errorMessage.includes('prompt is too long');
                 // Log when we detect the error
                 if (isInputTooLongError) {
-                    console.warn('[Graph] Detected input too long error:', errorMessage.substring(0, 200));
-                    console.warn('[Graph] Checking emergency pruning conditions:', {
+                    mwarn('[Graph] Detected input too long error:', errorMessage.substring(0, 200));
+                    mwarn('[Graph] Checking emergency pruning conditions:', {
                         hasPruneMessages: !!agentContext.pruneMessages,
                         hasTokenCounter: !!agentContext.tokenCounter,
                         maxContextTokens: agentContext.maxContextTokens,
@@ -1563,12 +1579,12 @@ class StandardGraph extends Graph {
                         if (result)
                             break; // Exit if we got a result
                         const reducedMaxTokens = Math.floor(agentContext.maxContextTokens * reductionFactor);
-                        console.warn(`[Graph] Input too long. Retrying with ${reductionFactor * 100}% context (${reducedMaxTokens} tokens)...`);
+                        mwarn(`[Graph] Input too long. Retrying with ${reductionFactor * 100}% context (${reducedMaxTokens} tokens)...`);
                         // Build fresh indexTokenCountMap if missing/incomplete
                         // This is needed when messages were dynamically added without updating the token map
                         let tokenMapForPruning = agentContext.indexTokenCountMap;
                         if (Object.keys(tokenMapForPruning).length < messages.length) {
-                            console.warn('[Graph] Building fresh token count map for emergency pruning...');
+                            mwarn('[Graph] Building fresh token count map for emergency pruning...');
                             tokenMapForPruning = {};
                             for (let i = 0; i < messages.length; i++) {
                                 tokenMapForPruning[i] = agentContext.tokenCounter(messages[i]);
@@ -1588,7 +1604,7 @@ class StandardGraph extends Graph {
                         });
                         // Skip if we can't fit any messages
                         if (reducedMessages.length === 0) {
-                            console.warn(`[Graph] Cannot fit any messages at ${reductionFactor * 100}% reduction, trying next level...`);
+                            mwarn(`[Graph] Cannot fit any messages at ${reductionFactor * 100}% reduction, trying next level...`);
                             continue;
                         }
                         // Calculate how many messages were pruned and estimate context timeframe
@@ -1648,7 +1664,7 @@ If I seem to be missing something we discussed earlier, just give me a quick rem
                                 retryErrorMsg.includes('context length') ||
                                 retryErrorMsg.includes('validationexception');
                             if (stillTooLong && reductionFactor > 0.1) {
-                                console.warn(`[Graph] Still too long at ${reductionFactor * 100}%, trying more aggressive pruning...`);
+                                mwarn(`[Graph] Still too long at ${reductionFactor * 100}%, trying more aggressive pruning...`);
                             }
                             else {
                                 console.error(`[Graph] Retry at ${reductionFactor * 100}% failed:`, retryError.message);
@@ -1708,6 +1724,20 @@ If I seem to be missing something we discussed earlier, just give me a quick rem
              * handled everything — both paths become no-ops.
              */
             const responseMessage = result.messages?.[0];
+            // Tool-call name normalization — catches LLM output that names tools
+            // with wrong delimiters (outlook/operations), prefixes
+            // (functions.outlook_operations), case drift, counter suffixes, or
+            // empty names recoverable from the tool_call id. Mutates in place so
+            // the downstream ToolNode dispatch sees the corrected names.
+            if (responseMessage && agentContext.toolMap) {
+                const allowedNames = new Set(Object.keys(agentContext.toolMap));
+                if (allowedNames.size > 0) {
+                    const rewrote = normalizeMessageToolCalls(responseMessage, allowedNames);
+                    if (rewrote) {
+                        mlog(`[Graph] normalized tool_call names on agent "${agentId}" response`);
+                    }
+                }
+            }
             const toolCalls = responseMessage
                 ?.tool_calls;
             const hasToolCalls = Array.isArray(toolCalls) && toolCalls.length > 0;
@@ -1794,12 +1824,20 @@ If I seem to be missing something we discussed earlier, just give me a quick rem
                 const meta = finalMsg.response_metadata;
                 // Bedrock streaming nests stopReason inside messageStop: { stopReason: '...' }
                 const messageStop = meta.messageStop;
-                this.lastFinishReason =
-                    meta.finish_reason ?? // OpenAI/Azure
-                        meta.stop_reason ?? // Anthropic direct API
-                        meta.stopReason ?? // Bedrock invoke (non-streaming)
-                        messageStop?.stopReason ?? // Bedrock streaming
-                        meta.finishReason; // VertexAI/Google
+                const nextReason = meta.finish_reason ?? // OpenAI/Azure
+                    meta.stop_reason ?? // Anthropic direct API
+                    meta.stopReason ?? // Bedrock invoke (non-streaming)
+                    messageStop?.stopReason ?? // Bedrock streaming
+                    meta.finishReason; // VertexAI/Google
+                // Sticky on truncation: a single Graph instance is reused across
+                // every scoped-subgraph inner node invocation (see MultiAgentGraph
+                // buildScopedSubgraph). If an earlier inner node hit max_tokens
+                // but a later inner node finished cleanly, the host's continuation layer
+                // would miss the truncation signal unless we preserve it. Keep the
+                // truncation reason pinned so the outer caller can retry.
+                if (!isTruncationReason(this.lastFinishReason)) {
+                    this.lastFinishReason = nextReason;
+                }
             }
             this.cleanupSignalListener();
             // DEFERRED STRUCTURED OUTPUT: When the agent has tools AND structured output configured,
@@ -1847,7 +1885,7 @@ If I seem to be missing something we discussed earlier, just give me a quick rem
                         // but we couldn't format the output as structured JSON.
                         // Return the unstructured text response from attemptInvoke.
                         console.error('[Graph] Deferred structured output failed after successful tool use:', structuredError);
-                        console.warn('[Graph] Falling back to unstructured response from tool-use phase');
+                        mwarn('[Graph] Falling back to unstructured response from tool-use phase');
                         return result;
                     }
                 }
@@ -1863,7 +1901,10 @@ If I seem to be missing something we discussed earlier, just give me a quick rem
         const agentNode = `${AGENT}${agentId}`;
         const toolNode = `${TOOLS}${agentId}`;
         const routeMessage = (state, config) => {
-            this.config = config;
+            // First-writer-wins — see note in createCallModel. `this.config` is an
+            // existence flag only; assigning unconditionally would race under
+            // parallel child subgraph.invoke().
+            this.config ??= config;
             return toolsCondition(state, toolNode, this.invokedToolIds);
         };
         const StateAnnotation = Annotation.Root({
@@ -1901,10 +1942,16 @@ If I seem to be missing something we discussed earlier, just give me a quick rem
                 default: () => [],
             }),
         });
+        // Pass compileOptions (including the HITL checkpointer) to the OUTER
+        // workflow — not just the inner agent subgraph. hasInterrupts() calls
+        // getState() on the outer compiled graph; without a checkpointer here,
+        // getState reports zero tasks and the HITL interrupt/resume loop breaks
+        // out immediately even though interrupt() fired correctly inside the
+        // agent subgraph.
         const workflow = new StateGraph(StateAnnotation)
             .addNode(this.defaultAgentId, agentNode, { ends: [END] })
             .addEdge(START, this.defaultAgentId)
-            .compile();
+            .compile(this.compileOptions);
         return workflow;
     }
     /**
@@ -1975,12 +2022,16 @@ If I seem to be missing something we discussed earlier, just give me a quick rem
             }
             catch (_e) {
                 /** If we can't get agent context, that's okay - agentId remains undefined */
-                console.debug(`[dispatchRunStep] Could not resolve agentId from metadata.langgraph_node="${metadata.langgraph_node}": ${_e.message}`);
+                mlog(`[dispatchRunStep] Could not resolve agentId from metadata.langgraph_node="${metadata.langgraph_node}": ${_e.message}`);
             }
         }
         this.contentData.push(runStep);
         this.contentIndexMap.set(stepId, runStep.index);
-        await safeDispatchCustomEvent(GraphEvents.ON_RUN_STEP, runStep, this.config);
+        // Pass undefined so safeDispatchCustomEvent resolves the runnable config
+        // from LangChain's AsyncLocalStorage. Using the shared `this.config` would
+        // race across concurrent child subgraph.invoke calls under parallel
+        // multi-agent handoffs and tag events with the wrong child's spawnKey.
+        await safeDispatchCustomEvent(GraphEvents.ON_RUN_STEP, runStep);
         return stepId;
     }
     async handleToolCallCompleted(data, metadata, omitOutput) {
@@ -2088,7 +2139,7 @@ If I seem to be missing something we discussed earlier, just give me a quick rem
             throw new Error('No config provided');
         }
         if (!data.id) {
-            console.warn('No Tool ID provided for Tool Error');
+            mwarn('No Tool ID provided for Tool Error');
             return;
         }
         const stepId = graph.toolCallStepIds.get(data.id) ?? '';
@@ -2136,7 +2187,10 @@ If I seem to be missing something we discussed earlier, just give me a quick rem
             id,
             delta,
         };
-        await safeDispatchCustomEvent(GraphEvents.ON_RUN_STEP_DELTA, runStepDelta, this.config);
+        // See dispatchRunStep note: do not pass `this.config`. The implicit
+        // AsyncLocalStorage config is the correct per-async-branch source under
+        // parallel handoffs.
+        await safeDispatchCustomEvent(GraphEvents.ON_RUN_STEP_DELTA, runStepDelta);
     }
     async dispatchMessageDelta(id, delta) {
         if (!this.config) {
@@ -2146,7 +2200,8 @@ If I seem to be missing something we discussed earlier, just give me a quick rem
             id,
             delta,
         };
-        await safeDispatchCustomEvent(GraphEvents.ON_MESSAGE_DELTA, messageDelta, this.config);
+        // See dispatchRunStep note.
+        await safeDispatchCustomEvent(GraphEvents.ON_MESSAGE_DELTA, messageDelta);
     }
     dispatchReasoningDelta = async (stepId, delta) => {
         if (!this.config) {
@@ -2156,7 +2211,8 @@ If I seem to be missing something we discussed earlier, just give me a quick rem
             id: stepId,
             delta,
         };
-        await safeDispatchCustomEvent(GraphEvents.ON_REASONING_DELTA, reasoningDelta, this.config);
+        // See dispatchRunStep note.
+        await safeDispatchCustomEvent(GraphEvents.ON_REASONING_DELTA, reasoningDelta);
     };
 }