@illuma-ai/agents 1.0.90 → 1.0.93

package/dist/esm/graphs/Graph.mjs

@@ -4,17 +4,21 @@ import { ChatVertexAI } from '@langchain/google-vertexai';
 import { Annotation, messagesStateReducer, StateGraph, START, END } from '@langchain/langgraph';
 import { RunnableLambda } from '@langchain/core/runnables';
 import { SystemMessage, HumanMessage, AIMessageChunk } from '@langchain/core/messages';
-import { GraphNodeKeys, ContentTypes, Providers, GraphEvents, MessageTypes, StepTypes, Constants } from '../common/enum.mjs';
 import { convertMessagesToContent, modifyDeltaProperties, formatAnthropicArtifactContent, formatArtifactPayload } from '../messages/core.mjs';
+import { getMessageId } from '../messages/ids.mjs';
 import { createPruneMessages } from '../messages/prune.mjs';
 import { ensureThinkingBlockInMessages } from '../messages/format.mjs';
 import { addCacheControl, addBedrockCacheControl } from '../messages/cache.mjs';
 import { formatContentStrings } from '../messages/content.mjs';
 import { extractToolDiscoveries } from '../messages/tools.mjs';
+import { GraphNodeKeys, Providers, ContentTypes, GraphEvents, MessageTypes, StepTypes, Constants } from '../common/enum.mjs';
+import { TOOL_TURN_THINKING_BUDGET } from '../common/constants.mjs';
 import { resetIfNotEmpty, joinKeys } from '../utils/graph.mjs';
 import { isOpenAILike, isGoogleLike } from '../utils/llm.mjs';
+import { ChatModelStreamHandler } from '../stream.mjs';
+import { handleToolCalls } from '../tools/handlers.mjs';
 import { sleep } from '../utils/run.mjs';
-import 'js-tiktoken';
+import 'ai-tokenizer';
 import '../utils/toonFormat.mjs';
 import { buildContextAnalytics } from '../utils/contextAnalytics.mjs';
 import 'zod-to-json-schema';
@@ -27,6 +31,7 @@ import { prepareSchemaForProvider } from '../schemas/validate.mjs';
 import { AgentContext } from '../agents/AgentContext.mjs';
 import { StructuredOutputTruncatedError, StructuredOutputRefusalError } from '../types/graph.mjs';
 import { createFakeStreamingLLM } from '../llm/fake.mjs';
+import { StreamingToolCallBuffer } from '../tools/StreamingToolCallBuffer.mjs';
 
 /* eslint-disable no-console */
 // src/graphs/Graph.ts
@@ -50,6 +55,32 @@ class Graph {
      * Currently supports code execution session tracking (session_id, files).
      */
     sessions = new Map();
+    /**
+     * Streaming tool call buffer — accumulates raw arg strings during streaming
+     * so that truncated tool call content can be recovered by the ToolNode.
+     * Fed by handleToolCallChunks, consumed by ToolNode.run when args are incomplete.
+     */
+    streamingToolCallBuffer = new StreamingToolCallBuffer();
+    /**
+     * Clears heavy references to allow GC to reclaim memory held by
+     * LangGraph's internal config / AsyncLocalStorage RunTree chain.
+     * Call after a run completes and content has been extracted.
+     */
+    clearHeavyState() {
+        this.config = undefined;
+        this.signal = undefined;
+        this.contentData = [];
+        this.contentIndexMap = new Map();
+        this.stepKeyIds = new Map();
+        this.toolCallStepIds.clear();
+        this.messageIdsByStepKey = new Map();
+        this.messageStepHasToolCalls = new Map();
+        this.prelimMessageIdsByStepKey = new Map();
+        this.invokedToolIds = undefined;
+        this.handlerRegistry = undefined;
+        this.sessions.clear();
+        this.streamingToolCallBuffer.clearAll();
+    }
 }
 class StandardGraph extends Graph {
     overrideModel;
@@ -90,7 +121,13 @@ class StandardGraph extends Graph {
             this.contentIndexMap = resetIfNotEmpty(this.contentIndexMap, new Map());
         }
         this.stepKeyIds = resetIfNotEmpty(this.stepKeyIds, new Map());
-        this.toolCallStepIds = resetIfNotEmpty(this.toolCallStepIds, new Map());
+        /**
+         * Clear in-place instead of replacing with a new Map to preserve the
+         * shared reference held by ToolNode (passed at construction time).
+         * Using resetIfNotEmpty would create a new Map, leaving ToolNode with
+         * a stale reference on 2nd+ processStream calls.
+         */
+        this.toolCallStepIds.clear();
         this.messageIdsByStepKey = resetIfNotEmpty(this.messageIdsByStepKey, new Map());
         this.messageStepHasToolCalls = resetIfNotEmpty(this.messageStepHasToolCalls, new Map());
         this.prelimMessageIdsByStepKey = resetIfNotEmpty(this.prelimMessageIdsByStepKey, new Map());
@@ -99,6 +136,90 @@ class StandardGraph extends Graph {
             context.reset();
         }
     }
+    clearHeavyState() {
+        super.clearHeavyState();
+        this.messages = [];
+        this.overrideModel = undefined;
+        for (const context of this.agentContexts.values()) {
+            context.reset();
+        }
+    }
+    /**
+     * Returns clientOptions with a reduced thinking budget for subsequent
+     * ReAct loop iterations (tool-result turns).
+     *
+     * **Rationale:** The first LLM call in a conversation processes the user's
+     * original query and may benefit from deep extended thinking. Subsequent
+     * iterations — where the model receives tool results and decides whether
+     * to call another tool or produce a final response — require minimal
+     * reasoning. Reducing the thinking budget from the user's configured
+     * value to TOOL_TURN_THINKING_BUDGET (1024 tokens) cuts wall-clock
+     * latency by ~15-20s per iteration, compounding across multi-tool flows.
+     *
+     * Provider handling:
+     * - **Anthropic (direct):** Reduces `thinking.budget_tokens` if > threshold
+     * - **Bedrock (Anthropic models):** Reduces `additionalModelRequestFields.thinking.budget_tokens`
+     * - **VertexAI / Google:** Reduces `thinkingConfig.thinkingBudget` if > threshold
+     * - **All others:** Returns clientOptions unchanged (no-op)
+     *
+     * @param clientOptions - The original client options from AgentContext
+     * @param provider - The LLM provider enum value
+     * @returns Shallow-cloned clientOptions with reduced thinking budget, or the original if no reduction needed
+     */
+    getAdaptiveClientOptions(clientOptions, provider) {
+        if (provider === Providers.ANTHROPIC) {
+            const anthropicOpts = clientOptions;
+            if (anthropicOpts.thinking != null &&
+                typeof anthropicOpts.thinking === 'object' &&
+                'type' in anthropicOpts.thinking &&
+                (anthropicOpts.thinking.type === 'enabled' ||
+                    anthropicOpts.thinking.type === 'adaptive') &&
+                'budget_tokens' in anthropicOpts.thinking &&
+                anthropicOpts.thinking.budget_tokens >
+                    TOOL_TURN_THINKING_BUDGET) {
+                return {
+                    ...anthropicOpts,
+                    thinking: {
+                        ...anthropicOpts.thinking,
+                        budget_tokens: TOOL_TURN_THINKING_BUDGET,
+                    },
+                };
+            }
+        }
+        if (provider === Providers.BEDROCK) {
+            const bedrockOpts = clientOptions;
+            const thinkingField = bedrockOpts.additionalModelRequestFields?.thinking;
+            if (thinkingField != null &&
+                typeof thinkingField === 'object' &&
+                'budget_tokens' in thinkingField &&
+                thinkingField.budget_tokens > TOOL_TURN_THINKING_BUDGET) {
+                return {
+                    ...bedrockOpts,
+                    additionalModelRequestFields: {
+                        ...(bedrockOpts.additionalModelRequestFields ?? {}),
+                        thinking: {
+                            ...thinkingField,
+                            budget_tokens: TOOL_TURN_THINKING_BUDGET,
+                        },
+                    },
+                };
+            }
+        }
+        if (provider === Providers.VERTEXAI || provider === Providers.GOOGLE) {
+            const googleOpts = clientOptions;
+            if (googleOpts.thinkingConfig?.thinkingBudget != null &&
+                googleOpts.thinkingConfig.thinkingBudget > TOOL_TURN_THINKING_BUDGET) {
+                return {
+                    ...googleOpts,
+                    thinkingConfig: {
+                        ...googleOpts.thinkingConfig,
+                        thinkingBudget: TOOL_TURN_THINKING_BUDGET,
+                    },
+                };
+            }
+        }
+        return clientOptions;
+    }
     /**
      * Returns the normalized finish/stop reason from the last LLM invocation.
      * Used by callers to detect when the response was truncated due to max_tokens.
@@ -135,7 +256,7 @@ class StandardGraph extends Graph {
             return 'the past few hours';
         }
         else if (messageCount <= 300) {
-            return 'roughly a day\'s worth';
+            return "roughly a day's worth";
         }
         else if (messageCount <= 700) {
             return 'the past few days';
@@ -224,7 +345,7 @@ class StandardGraph extends Graph {
             keyList.push('reasoning');
         }
         else if (agentContext.tokenTypeSwitch === 'content') {
-            keyList.push('post-reasoning');
+            keyList.push(`post-reasoning-${agentContext.reasoningTransitionCount}`);
         }
         if (this.invokedToolIds != null && this.invokedToolIds.size > 0) {
             keyList.push(this.invokedToolIds.size + '');
@@ -236,7 +357,9 @@ class StandardGraph extends Graph {
     }
     /* Misc.*/
     getRunMessages() {
-        return this.messages.slice(this.startIndex);
+        const result = this.messages.slice(this.startIndex);
+        console.debug(`[Graph] getRunMessages() | totalMessages=${this.messages.length} | startIndex=${this.startIndex} | runMessages=${result.length}`);
+        return result;
     }
     getContentParts() {
         return convertMessagesToContent(this.messages.slice(this.startIndex));
@@ -349,26 +472,77 @@ class StandardGraph extends Graph {
         if (eventDrivenMode) {
             const schemaTools = createSchemaOnlyTools(toolDefinitions);
             const toolDefMap = new Map(toolDefinitions.map((def) => [def.name, def]));
+            const graphTools = agentContext?.graphTools;
+            const directToolNames = new Set();
+            const allTools = [...schemaTools];
+            const allToolMap = new Map(schemaTools.map((tool) => [tool.name, tool]));
+            if (graphTools && graphTools.length > 0) {
+                for (const tool of graphTools) {
+                    if ('name' in tool) {
+                        allTools.push(tool);
+                        allToolMap.set(tool.name, tool);
+                        directToolNames.add(tool.name);
+                    }
+                }
+            }
             return new ToolNode({
-                tools: schemaTools,
-                toolMap: new Map(schemaTools.map((tool) => [tool.name, tool])),
-                toolCallStepIds: this.toolCallStepIds,
-                errorHandler: (data, metadata) => StandardGraph.handleToolCallErrorStatic(this, data, metadata),
-                toolRegistry: agentContext?.toolRegistry,
-                sessions: this.sessions,
+                tools: allTools,
+                toolMap: allToolMap,
                 eventDrivenMode: true,
+                sessions: this.sessions,
                 toolDefinitions: toolDefMap,
                 agentId: agentContext?.agentId,
+                toolCallStepIds: this.toolCallStepIds,
+                toolRegistry: agentContext?.toolRegistry,
+                directToolNames: directToolNames.size > 0 ? directToolNames : undefined,
+                streamingToolCallBuffer: this.streamingToolCallBuffer,
+                errorHandler: (data, metadata) => StandardGraph.handleToolCallErrorStatic(this, data, metadata),
                 toolApprovalConfig,
             });
         }
+        const graphTools = agentContext?.graphTools;
+        const baseTools = currentTools ?? [];
+        const allTraditionalTools = graphTools && graphTools.length > 0
+            ? [...baseTools, ...graphTools]
+            : baseTools;
+        /**
+         * Build tool map from all sources: agent's toolMap, agent's tools array, and graph tools.
+         * Previously, baseTools were missing from the map when no explicit toolMap was provided,
+         * causing ToolNode to not find agent-defined tools (e.g., custom DynamicStructuredTools).
+         */
+        const traditionalToolMap = graphTools && graphTools.length > 0
+            ? new Map([
+                ...(currentToolMap ?? new Map()),
+                ...baseTools
+                    .filter((t) => 'name' in t)
+                    .map((t) => [t.name, t]),
+                ...graphTools
+                    .filter((t) => 'name' in t)
+                    .map((t) => [t.name, t]),
+            ])
+            : currentToolMap;
+        /** Build directToolNames from graph-managed tools (handoff/transfer) so HITL can bypass them */
+        let directToolNames;
+        if (graphTools && graphTools.length > 0) {
+            directToolNames = new Set();
+            for (const tool of graphTools) {
+                if ('name' in tool) {
+                    directToolNames.add(tool.name);
+                }
+            }
+            if (directToolNames.size === 0) {
+                directToolNames = undefined;
+            }
+        }
         return new ToolNode({
-            tools: currentTools ?? [],
-            toolMap: currentToolMap,
+            tools: allTraditionalTools,
+            toolMap: traditionalToolMap,
             toolCallStepIds: this.toolCallStepIds,
+            streamingToolCallBuffer: this.streamingToolCallBuffer,
             errorHandler: (data, metadata) => StandardGraph.handleToolCallErrorStatic(this, data, metadata),
             toolRegistry: agentContext?.toolRegistry,
             sessions: this.sessions,
+            directToolNames,
             toolApprovalConfig,
         });
     }
@@ -425,25 +599,50 @@ class StandardGraph extends Graph {
         }
     }
     /** Execute model invocation with streaming support */
-    async attemptInvoke({ currentModel, finalMessages, provider, tools, }, config) {
+    async attemptInvoke({ currentModel, finalMessages, provider, tools: _tools, }, config) {
         const model = this.overrideModel ?? currentModel;
         if (!model) {
             throw new Error('No model found');
         }
-        if ((tools?.length ?? 0) > 0 && manualToolStreamProviders.has(provider)) {
-            if (!model.stream) {
-                throw new Error('Model does not support stream');
-            }
+        if (model.stream) {
+            /**
+             * Process all model output through a local ChatModelStreamHandler in the
+             * graph execution context. Each chunk is awaited before the next one is
+             * consumed, so by the time the stream is exhausted every run step
+             * (MESSAGE_CREATION, TOOL_CALLS) has been created and toolCallStepIds is
+             * fully populated — the graph will not transition to ToolNode until this
+             * is done.
+             *
+             * This replaces the previous pattern where ChatModelStreamHandler lived
+             * in the for-await stream consumer (handler registry). That consumer
+             * runs concurrently with graph execution, so the graph could advance to
+             * ToolNode before the consumer had processed all events. By handling
+             * chunks here, inside the agent node, the race is eliminated.
+             *
+             * The for-await consumer no longer needs a ChatModelStreamHandler; its
+             * on_chat_model_stream events are simply ignored (no handler registered).
+             * The dispatched custom events (ON_RUN_STEP, ON_MESSAGE_DELTA, etc.)
+             * still reach the content aggregator and SSE handlers through the custom
+             * event callback in Run.createCustomEventCallback.
+             */
+            const metadata = config?.metadata;
+            const streamHandler = new ChatModelStreamHandler();
             const stream = await model.stream(finalMessages, config);
             let finalChunk;
             for await (const chunk of stream) {
-                await safeDispatchCustomEvent(GraphEvents.CHAT_MODEL_STREAM, { chunk, emitted: true }, config);
+                await streamHandler.handle(GraphEvents.CHAT_MODEL_STREAM, { chunk }, metadata, this);
                 finalChunk = finalChunk ? concat(finalChunk, chunk) : chunk;
             }
-            finalChunk = modifyDeltaProperties(provider, finalChunk);
+            if (manualToolStreamProviders.has(provider)) {
+                finalChunk = modifyDeltaProperties(provider, finalChunk);
+            }
+            if ((finalChunk?.tool_calls?.length ?? 0) > 0) {
+                finalChunk.tool_calls = finalChunk.tool_calls?.filter((tool_call) => !!tool_call.name);
+            }
             return { messages: [finalChunk] };
         }
         else {
+            /** Fallback for models without stream support. */
             const finalMessage = await model.invoke(finalMessages, config);
             if ((finalMessage.tool_calls?.length ?? 0) > 0) {
                 finalMessage.tool_calls = finalMessage.tool_calls?.filter((tool_call) => !!tool_call.name);
@@ -463,15 +662,12 @@ class StandardGraph extends Graph {
      */
     async attemptStructuredInvoke({ currentModel, finalMessages, schema, structuredOutputConfig, provider, agentContext, }, config) {
         const model = this.overrideModel ?? currentModel;
-        if (!model) {
-            throw new Error('No model found');
-        }
         // Check if model supports withStructuredOutput
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
         if (typeof model.withStructuredOutput !== 'function') {
-            throw new Error(`The selected model does not support structured output. ` +
-                `Please use a model that supports JSON schema output (e.g., OpenAI GPT-4, Anthropic Claude, Google Gemini) ` +
-                `or disable structured output for this agent.`);
+            throw new Error('The selected model does not support structured output. ' +
+                'Please use a model that supports JSON schema output (e.g., OpenAI GPT-4, Anthropic Claude, Google Gemini) ' +
+                'or disable structured output for this agent.');
         }
         const { name = 'StructuredResponse', includeRaw: _includeRaw = false, handleErrors = true, maxRetries = 2, } = structuredOutputConfig;
         // Resolve the structured output method using AgentContext's provider-aware logic
@@ -490,7 +686,8 @@ class StandardGraph extends Graph {
                 method = 'functionCalling';
             }
             else if (mode === 'provider') {
-                method = provider === Providers.BEDROCK ? 'functionCalling' : 'jsonMode';
+                method =
+                    provider === Providers.BEDROCK ? 'functionCalling' : 'jsonMode';
             }
             else {
                 method = undefined;
@@ -498,11 +695,11 @@ class StandardGraph extends Graph {
         }
         // Prepare schema for provider-specific constraints when using native/jsonSchema mode
         let preparedSchema = schema;
-        if (method === 'jsonSchema' && provider) {
+        if (method === 'jsonSchema' && provider != null) {
             const { schema: prepared, warnings } = prepareSchemaForProvider(schema, provider, structuredOutputConfig.strict !== false);
             preparedSchema = prepared;
             if (warnings.length > 0) {
-                console.log('[Graph] Schema preparation warnings:', warnings);
+                console.warn('[Graph] Schema preparation warnings:', warnings);
             }
         }
         // Use withStructuredOutput to bind the schema
@@ -514,14 +711,6 @@ class StandardGraph extends Graph {
             includeRaw: true, // Always true internally for debugging
             strict: structuredOutputConfig.strict !== false,
         });
-        console.log('[Graph] Structured output config:', {
-            name,
-            method,
-            provider,
-            schemaKeys: Object.keys(preparedSchema),
-            // eslint-disable-next-line @typescript-eslint/no-explicit-any
-            modelName: model.model || model.modelId || 'unknown',
-        });
         let lastError;
         let attempts = 0;
         while (attempts <= maxRetries) {
@@ -529,18 +718,11 @@ class StandardGraph extends Graph {
                 // Note: We pass the original config here. The stream aggregator will filter out
                 // the synthetic "response" tool call events from withStructuredOutput()
                 const result = await structuredModel.invoke(finalMessages, config);
-                // Debug: log what we got back
-                console.log('[Graph] Structured output raw result type:', typeof result);
                 // Check for refusal or truncation in the raw message
-                if (result?.raw) {
+                if (result?.raw != null) {
                     const rawMsg = result.raw;
-                    console.log('[Graph] Raw message content type:', typeof rawMsg?.content);
-                    console.log('[Graph] Raw message tool_calls:', rawMsg?.tool_calls?.length ?? 0);
-                    if (rawMsg?.content && typeof rawMsg.content === 'string' && rawMsg.content.length > 0) {
-                        console.log('[Graph] Raw message text content (first 200):', rawMsg.content.substring(0, 200));
-                    }
                     // Check stop reason for refusal or truncation
-                    const responseMetadata = rawMsg.response_metadata ?? {};
+                    const responseMetadata = rawMsg.response_metadata;
                     const stopReason = responseMetadata.stop_reason ?? // Anthropic
                         responseMetadata.finish_reason ?? // OpenAI
                         responseMetadata.stopReason; // Bedrock
@@ -549,13 +731,14 @@ class StandardGraph extends Graph {
                     }
                     // Check for Anthropic refusal (stop_reason won't be 'refusal' but content may indicate it)
                     // OpenAI uses message.refusal field
-                    const refusal = rawMsg.refusal;
-                    if (refusal) {
+                    const refusal = rawMsg
+                        .refusal;
+                    if (refusal != null && refusal !== '') {
                         throw new StructuredOutputRefusalError(refusal);
                     }
                 }
                 // Handle response - we always use includeRaw internally
-                if (result?.raw && result?.parsed !== undefined) {
+                if (result?.raw != null && result?.parsed !== undefined) {
                     return {
                         structuredResponse: result.parsed,
                         rawMessage: result.raw,
@@ -628,7 +811,9 @@ class StandardGraph extends Graph {
         // Get a fresh model WITHOUT tools bound
         // bindTools() returns RunnableBinding which lacks withStructuredOutput
         // Also disable thinking mode - Anthropic/Bedrock doesn't allow tool_choice with thinking enabled
-        const structuredClientOptions = { ...agentContext.clientOptions };
+        const structuredClientOptions = {
+            ...agentContext.clientOptions,
+        };
         // Determine if streaming is possible for this structured output mode
         // Native/jsonSchema modes can stream; tool/functionCalling modes cannot (synthetic tool calls break UX)
         const resolved = agentContext.resolveStructuredOutputMode();
@@ -646,12 +831,12 @@ class StandardGraph extends Graph {
             // Remove thinking configuration for Bedrock
             if (agentContext.provider === Providers.BEDROCK) {
                 const bedrockOpts = structuredClientOptions;
-                if (bedrockOpts.additionalModelRequestFields) {
-                    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                if (bedrockOpts.additionalModelRequestFields != null) {
                     const additionalFields = Object.assign({}, bedrockOpts.additionalModelRequestFields);
                     delete additionalFields.thinking;
                     delete additionalFields.budgetTokens;
-                    bedrockOpts.additionalModelRequestFields = additionalFields;
+                    bedrockOpts.additionalModelRequestFields =
+                        additionalFields;
                 }
             }
             // Remove thinking configuration for Anthropic direct API
@@ -715,7 +900,8 @@ class StandardGraph extends Graph {
             // This keeps the system message static (cacheable) while providing dynamic context
             // (timestamps, user info, tool context) as conversation content instead.
             // Only inject on the first turn when messages don't already have the context marker.
-            if (agentContext.dynamicContext &&
+            if (agentContext.dynamicContext != null &&
+                agentContext.dynamicContext !== '' &&
                 messages.length > 0 &&
                 !messages.some((m) => m instanceof HumanMessage &&
                     typeof m.content === 'string' &&
@@ -734,11 +920,20 @@ class StandardGraph extends Graph {
                 agentContext.markToolsAsDiscovered(discoveredNames);
             }
             const toolsForBinding = agentContext.getToolsForBinding();
+            // PERF: Detect subsequent ReAct iterations (tool results present in messages)
+            // and reduce thinking budget to minimize per-iteration latency.
+            // First iteration gets the user's configured budget; follow-up turns
+            // use TOOL_TURN_THINKING_BUDGET (1024) since they only need to route
+            // "call next tool" or "produce final response".
+            const isSubsequentIteration = messages.some((m) => m._getType() === 'tool');
+            const effectiveClientOptions = isSubsequentIteration && agentContext.clientOptions
+                ? this.getAdaptiveClientOptions(agentContext.clientOptions, agentContext.provider)
+                : agentContext.clientOptions;
             let model = this.overrideModel ??
                 this.initializeModel({
                     tools: toolsForBinding,
                     provider: agentContext.provider,
-                    clientOptions: agentContext.clientOptions,
+                    clientOptions: effectiveClientOptions,
                 });
             if (agentContext.systemRunnable) {
                 model = agentContext.systemRunnable.pipe(model);
@@ -765,7 +960,7 @@ class StandardGraph extends Graph {
                     : '';
                 return toolName === 'task';
             });
-            if (hasTaskToolPrePrune &&
+            if (hasTaskToolPrePrune === true &&
                 agentContext.tokenCounter &&
                 agentContext.maxContextTokens != null) {
                 // Estimate total tokens in messages BEFORE pruning
@@ -774,12 +969,12 @@ class StandardGraph extends Graph {
                     prePruneTokens += agentContext.tokenCounter(msg);
                 }
                 // Add instruction tokens (system prompt)
-                prePruneTokens += agentContext.instructionTokens ?? 0;
+                prePruneTokens += agentContext.instructionTokens;
                 const prePruneUtilization = (prePruneTokens / agentContext.maxContextTokens) * 100;
                 if (prePruneUtilization > 70) {
                     console.warn(`[Graph] PRE-PRUNE delegation check: ${prePruneUtilization.toFixed(1)}% utilization ` +
                         `(${prePruneTokens}/${agentContext.maxContextTokens} tokens). ` +
-                        `Injecting delegation hint INSTEAD of pruning.`);
+                        'Injecting delegation hint INSTEAD of pruning.');
                     delegationInjectedPrePrune = true;
                 }
             }
@@ -806,6 +1001,7 @@ class StandardGraph extends Graph {
                 });
             }
             if (agentContext.pruneMessages && !delegationInjectedPrePrune) {
+                console.info(`[Graph:ContextMgmt] Pruning messages | inputCount=${messages.length} | maxTokens=${agentContext.maxContextTokens}`);
                 const { context, indexTokenCountMap, messagesToRefine } = agentContext.pruneMessages({
                     messages,
                     usageMetadata: agentContext.currentUsage,
@@ -813,11 +1009,14 @@ class StandardGraph extends Graph {
                 });
                 agentContext.indexTokenCountMap = indexTokenCountMap;
                 messagesToUse = context;
+                console.info(`[Graph:ContextMgmt] Pruned | kept=${context.length} | discarded=${messagesToRefine.length} | originalCount=${messages.length}`);
                 // Summarize discarded messages if callback provided
-                if (messagesToRefine && messagesToRefine.length > 0 && agentContext.summarizeCallback) {
+                if (messagesToRefine.length > 0 && agentContext.summarizeCallback) {
+                    console.info(`[Graph:ContextMgmt] Summarizing ${messagesToRefine.length} discarded messages`);
                     try {
                         const summary = await agentContext.summarizeCallback(messagesToRefine);
-                        if (summary) {
+                        console.info(`[Graph:ContextMgmt] Summary received | len=${summary?.length ?? 0} | hasContent=${summary != null && summary !== ''}`);
+                        if (summary != null && summary !== '') {
                             const summaryMsg = new SystemMessage(`[Conversation Summary]\n${summary}`);
                             // Insert after system message (if present), before conversation messages
                             const systemIdx = messagesToUse[0]?.getType() === 'system' ? 1 : 0;
@@ -826,6 +1025,7 @@ class StandardGraph extends Graph {
                                 summaryMsg,
                                 ...messagesToUse.slice(systemIdx),
                             ];
+                            console.info(`[Graph:ContextMgmt] Summary injected at index ${systemIdx} | finalMsgCount=${messagesToUse.length}`);
                         }
                     }
                     catch (err) {
@@ -924,10 +1124,10 @@ class StandardGraph extends Graph {
             }
             // Get model info for analytics
             const bedrockOpts = agentContext.clientOptions;
-            const modelId = bedrockOpts?.model ||
+            const modelId = bedrockOpts?.model ??
                 agentContext.clientOptions
                     ?.modelName;
-            const thinkingConfig = bedrockOpts?.additionalModelRequestFields?.['thinking'] ||
+            const thinkingConfig = bedrockOpts?.additionalModelRequestFields?.['thinking'] ??
                 agentContext.clientOptions
                     ?.thinking;
             // Build and emit context analytics for traces
@@ -966,7 +1166,7 @@ class StandardGraph extends Graph {
                     : '';
                 return toolName === 'task';
             });
-            if (hasTaskToolInContext &&
+            if (hasTaskToolInContext === true &&
                 contextAnalytics.utilizationPercent != null &&
                 contextAnalytics.maxContextTokens != null) {
                 const utilization = contextAnalytics.utilizationPercent;
@@ -983,10 +1183,12 @@ class StandardGraph extends Graph {
                     const content = typeof msg.content === 'string'
                         ? msg.content
                         : Array.isArray(msg.content)
-                            ? msg.content.map((p) => {
+                            ? msg.content
+                                .map((p) => {
                                 const part = p;
-                                return String(part.text || part.content || '');
-                            }).join(' ')
+                                return String(part.text ?? part.content ?? '');
+                            })
+                                .join(' ')
                             : '';
                     // Pattern 1: # "filename" headers in attached document blocks
                     const docMatches = content.match(/# "([^"]+)"/g);
@@ -1002,7 +1204,10 @@ class StandardGraph extends Graph {
                     // Pattern 2: "The user has attached: **file1, file2**" (embedded files)
                     const attachedMatch = content.match(/user has attached:\s*\*\*([^*]+)\*\*/i);
                     if (attachedMatch) {
-                        const names = attachedMatch[1].split(',').map((n) => n.trim()).filter(Boolean);
+                        const names = attachedMatch[1]
+                            .split(',')
+                            .map((n) => n.trim())
+                            .filter(Boolean);
                         for (const name of names) {
                             if (!documentNames.includes(name)) {
                                 documentNames.push(name);
@@ -1017,16 +1222,16 @@ class StandardGraph extends Graph {
                     `hasTaskTool: true | messages: ${finalMessages.length} | docs: ${documentCount}`);
                 // TRIGGER 1: Multi-document delegation (3+ documents detected)
                 // Only inject on first iteration (no AI messages yet = agent hasn't responded)
-                const hasAiResponse = finalMessages.some((m) => m._getType?.() === 'ai' || m._getType?.() === 'tool');
+                const hasAiResponse = finalMessages.some((m) => m._getType() === 'ai' || m._getType() === 'tool');
                 if (documentCount >= 3 && !hasAiResponse) {
                     const pressureMsg = new HumanMessage({
                         content: `[MULTI-DOCUMENT PROCESSING — ${documentCount} documents detected]\n` +
                             `Documents: ${documentNames.join(', ')}\n\n` +
                             `You have ${documentCount} documents attached. For thorough analysis, use the "task" tool ` +
-                            `to delegate each document (or group of related documents) to a sub-agent.\n` +
-                            `Each sub-agent has its own fresh context window and can use file_search to retrieve the full document content.\n` +
-                            `After all sub-agents complete, synthesize their results into a comprehensive response.\n\n` +
-                            `This approach ensures each document gets full attention without context limitations.`,
+                            'to delegate each document (or group of related documents) to a sub-agent.\n' +
+                            'Each sub-agent has its own fresh context window and can use file_search to retrieve the full document content.\n' +
+                            'After all sub-agents complete, synthesize their results into a comprehensive response.\n\n' +
+                            'This approach ensures each document gets full attention without context limitations.',
                     });
                     finalMessages = [...finalMessages, pressureMsg];
                     console.info(`[Graph] Multi-document delegation hint injected for ${documentCount} documents: ` +
@@ -1034,14 +1239,15 @@ class StandardGraph extends Graph {
                 }
                 // TRIGGER 2: Token utilization thresholds (mid-chain safety net)
                 // Also fires when we skipped pruning due to delegationInjectedPrePrune
-                if (utilization > 85 || (delegationInjectedPrePrune && utilization > 50)) {
+                if (utilization > 85 ||
+                    (delegationInjectedPrePrune && utilization > 50)) {
                     // CRITICAL: Context is high — MANDATE delegation
                     const pressureMsg = new HumanMessage({
                         content: `[CONTEXT BUDGET CRITICAL — ${utilization.toFixed(0)}% used]\n` +
                             `You have used ${totalTokens} of ${maxTokens} tokens (${remainingTokens} remaining).\n` +
-                            `Your context is very large. You MUST use the "task" tool to delegate work to sub-agents.\n` +
-                            `Each sub-agent runs in its own fresh context window and can use file_search to access documents.\n` +
-                            `Do NOT attempt to process documents directly — delegate each document to a sub-agent, then synthesize results.`,
+                            'Your context is very large. You MUST use the "task" tool to delegate work to sub-agents.\n' +
+                            'Each sub-agent runs in its own fresh context window and can use file_search to access documents.\n' +
+                            'Do NOT attempt to process documents directly — delegate each document to a sub-agent, then synthesize results.',
                     });
                     finalMessages = [...finalMessages, pressureMsg];
                     console.warn(`[Graph] Context pressure CRITICAL (${utilization.toFixed(0)}%): ` +
@@ -1053,8 +1259,8 @@ class StandardGraph extends Graph {
                     const pressureMsg = new HumanMessage({
                         content: `[CONTEXT BUDGET WARNING — ${utilization.toFixed(0)}% used]\n` +
                             `You have used ${totalTokens} of ${maxTokens} tokens (${remainingTokens} remaining).\n` +
-                            `Your context is filling up. Consider using the "task" tool to delegate complex operations to sub-agents.\n` +
-                            `Sub-agents run in fresh context windows and won't consume your remaining budget.`,
+                            'Your context is filling up. Consider using the "task" tool to delegate complex operations to sub-agents.\n' +
+                            "Sub-agents run in fresh context windows and won't consume your remaining budget.",
                     });
                     finalMessages = [...finalMessages, pressureMsg];
                     console.info(`[Graph] Context pressure WARNING (${utilization.toFixed(0)}%): ` +
@@ -1093,7 +1299,7 @@ class StandardGraph extends Graph {
             }
             catch (primaryError) {
                 // Check if this is a "input too long" error from Bedrock/Anthropic
-                const errorMessage = primaryError.message.toLowerCase() ?? '';
+                const errorMessage = primaryError.message.toLowerCase();
                 const isInputTooLongError = errorMessage.includes('too long') ||
                     errorMessage.includes('input is too long') ||
                     errorMessage.includes('context length') ||
@@ -1113,7 +1319,9 @@ class StandardGraph extends Graph {
                 }
                 // If input too long and we have pruning capability OR tokenCounter, retry with progressively more aggressive pruning
                 // Note: We can create emergency pruneMessages dynamically if we have tokenCounter and maxContextTokens
-                const canPrune = agentContext.tokenCounter && agentContext.maxContextTokens;
+                const canPrune = agentContext.tokenCounter != null &&
+                    agentContext.maxContextTokens != null &&
+                    agentContext.maxContextTokens > 0;
                 if (isInputTooLongError && canPrune) {
                     // Progressive reduction: 50% -> 25% -> 10% of original context
                     const reductionLevels = [0.5, 0.25, 0.1];
@@ -1201,7 +1409,7 @@ If I seem to be missing something we discussed earlier, just give me a quick rem
                             console.info(`[Graph] ✅ Retry successful at ${reductionFactor * 100}% with ${reducedMessages.length} messages (reduced from ${finalMessages.length})`);
                         }
                         catch (retryError) {
-                            const retryErrorMsg = retryError.message.toLowerCase() ?? '';
+                            const retryErrorMsg = retryError.message.toLowerCase();
                             const stillTooLong = retryErrorMsg.includes('too long') ||
                                 retryErrorMsg.includes('context length') ||
                                 retryErrorMsg.includes('validationexception');
@@ -1250,6 +1458,101 @@ If I seem to be missing something we discussed earlier, just give me a quick rem
             if (!result) {
                 throw new Error('No result after model invocation');
             }
+            /**
+             * Fallback: populate toolCallStepIds in the graph execution context.
+             *
+             * When model.stream() is available (the common case), attemptInvoke
+             * processes all chunks through a local ChatModelStreamHandler which
+             * creates run steps and populates toolCallStepIds before returning.
+             * The code below is a fallback for the rare case where model.stream
+             * is unavailable and model.invoke() was used instead.
+             *
+             * Text content is dispatched FIRST so that MESSAGE_CREATION is the
+             * current step when handleToolCalls runs. handleToolCalls then creates
+             * TOOL_CALLS on top of it. The dedup in getMessageId and
+             * toolCallStepIds.has makes this safe when attemptInvoke already
+             * handled everything — both paths become no-ops.
+             */
+            const responseMessage = result.messages?.[0];
+            const toolCalls = responseMessage
+                ?.tool_calls;
+            const hasToolCalls = Array.isArray(toolCalls) && toolCalls.length > 0;
+            if (hasToolCalls) {
+                const metadata = config.metadata;
+                const stepKey = this.getStepKey(metadata);
+                const content = responseMessage?.content;
+                const hasTextContent = content != null &&
+                    (typeof content === 'string'
+                        ? content !== ''
+                        : Array.isArray(content) && content.length > 0);
+                /**
+                 * Dispatch text content BEFORE creating TOOL_CALLS steps.
+                 * getMessageId returns a new ID only on the first call for a step key;
+                 * if the for-await consumer already claimed it, this is a no-op.
+                 */
+                if (hasTextContent) {
+                    const messageId = getMessageId(stepKey, this) ?? '';
+                    if (messageId) {
+                        await this.dispatchRunStep(stepKey, {
+                            type: StepTypes.MESSAGE_CREATION,
+                            message_creation: { message_id: messageId },
+                        }, metadata);
+                        const stepId = this.getStepIdByKey(stepKey);
+                        if (typeof content === 'string') {
+                            await this.dispatchMessageDelta(stepId, {
+                                content: [{ type: ContentTypes.TEXT, text: content }],
+                            });
+                        }
+                        else if (Array.isArray(content) &&
+                            content.every((c) => typeof c === 'object' &&
+                                'type' in c &&
+                                typeof c.type === 'string' &&
+                                c.type.startsWith('text'))) {
+                            await this.dispatchMessageDelta(stepId, {
+                                content: content,
+                            });
+                        }
+                    }
+                }
+                await handleToolCalls(toolCalls, metadata, this);
+            }
+            /**
+             * When streaming is disabled, on_chat_model_stream events are never
+             * emitted so ChatModelStreamHandler never fires. Dispatch the text
+             * content as MESSAGE_CREATION + MESSAGE_DELTA here.
+             */
+            const disableStreaming = agentContext.clientOptions
+                ?.disableStreaming === true;
+            if (disableStreaming &&
+                !hasToolCalls &&
+                responseMessage != null &&
+                responseMessage.content != null) {
+                const metadata = config.metadata;
+                const stepKey = this.getStepKey(metadata);
+                const messageId = getMessageId(stepKey, this) ?? '';
+                if (messageId) {
+                    await this.dispatchRunStep(stepKey, {
+                        type: StepTypes.MESSAGE_CREATION,
+                        message_creation: { message_id: messageId },
+                    }, metadata);
+                    const stepId = this.getStepIdByKey(stepKey);
+                    const content = responseMessage.content;
+                    if (typeof content === 'string') {
+                        await this.dispatchMessageDelta(stepId, {
+                            content: [{ type: ContentTypes.TEXT, text: content }],
+                        });
+                    }
+                    else if (Array.isArray(content) &&
+                        content.every((c) => typeof c === 'object' &&
+                            'type' in c &&
+                            typeof c.type === 'string' &&
+                            c.type.startsWith('text'))) {
+                        await this.dispatchMessageDelta(stepId, {
+                            content: content,
+                        });
+                    }
+                }
+            }
             agentContext.currentUsage = this.getUsageMetadata(result.messages?.[0]);
             // Extract and normalize the LLM's finish/stop reason for auto-continuation support
             const finalMsg = result.messages?.[0];
@@ -1262,21 +1565,19 @@ If I seem to be missing something we discussed earlier, just give me a quick rem
                         meta.stop_reason ?? // Anthropic direct API
                         meta.stopReason ?? // Bedrock invoke (non-streaming)
                         messageStop?.stopReason ?? // Bedrock streaming
-                        meta.finishReason ?? // VertexAI/Google
-                        undefined;
+                        meta.finishReason; // VertexAI/Google
             }
             this.cleanupSignalListener();
             // DEFERRED STRUCTURED OUTPUT: When the agent has tools AND structured output configured,
             // we let the agent use tools normally via attemptInvoke(). Once the agent's response
             // has NO tool_calls (it's done with tools), we produce the final structured JSON response.
             if (agentContext.isStructuredOutputMode &&
-                agentContext.structuredOutput &&
-                result) {
+                agentContext.structuredOutput != null) {
                 const lastMessage = result.messages?.[0];
-                const resultHasToolCalls = lastMessage &&
+                const resultHasToolCalls = lastMessage != null &&
                     'tool_calls' in lastMessage &&
                     (lastMessage.tool_calls?.length ?? 0) > 0;
-                if (!resultHasToolCalls) {
+                if (resultHasToolCalls !== true) {
                     try {
                         // Build messages for structured output: include the full conversation
                         // plus the agent's text response from attemptInvoke, so the structured
@@ -1358,6 +1659,10 @@ If I seem to be missing something we discussed earlier, just give me a quick rem
                 reducer: (a, b) => {
                     if (!a.length) {
                         this.startIndex = a.length + b.length;
+                        console.info(`[Graph:Reducer] Initial messages | startIndex=${this.startIndex} | inputMsgCount=${b.length}`);
+                    }
+                    else {
+                        console.debug(`[Graph:Reducer] Appending messages | existing=${a.length} | new=${b.length} | startIndex=${this.startIndex}`);
                     }
                     const result = messagesStateReducer(a, b);
                     this.messages = result;