@illuma-ai/agents 1.0.90 → 1.0.94

package/src/graphs/Graph.ts

@@ -25,32 +25,35 @@ import {
 } from '@langchain/core/messages';
 import type {
   BaseMessageFields,
+  MessageContent,
   UsageMetadata,
   BaseMessage,
 } from '@langchain/core/messages';
 import type { ToolCall } from '@langchain/core/messages/tool';
 import type * as t from '@/types';
-import {
-  GraphNodeKeys,
-  ContentTypes,
-  GraphEvents,
-  Providers,
-  StepTypes,
-  MessageTypes,
-  Constants,
-} from '@/common';
 import {
   formatAnthropicArtifactContent,
   ensureThinkingBlockInMessages,
   convertMessagesToContent,
   addBedrockCacheControl,
+  extractToolDiscoveries,
   modifyDeltaProperties,
   formatArtifactPayload,
   formatContentStrings,
   createPruneMessages,
   addCacheControl,
-  extractToolDiscoveries,
+  getMessageId,
 } from '@/messages';
+import {
+  GraphNodeKeys,
+  ContentTypes,
+  GraphEvents,
+  Providers,
+  StepTypes,
+  MessageTypes,
+  Constants,
+  TOOL_TURN_THINKING_BUDGET,
+} from '@/common';
 import {
   resetIfNotEmpty,
   isOpenAILike,
@@ -69,9 +72,15 @@ import { safeDispatchCustomEvent } from '@/utils/events';
 import { createSchemaOnlyTools } from '@/tools/schema';
 import { prepareSchemaForProvider } from '@/schemas/validate';
 import { AgentContext } from '@/agents/AgentContext';
-import { StructuredOutputRefusalError, StructuredOutputTruncatedError } from '@/types/graph';
+import {
+  StructuredOutputRefusalError,
+  StructuredOutputTruncatedError,
+} from '@/types/graph';
 import { createFakeStreamingLLM } from '@/llm/fake';
+import { handleToolCalls } from '@/tools/handlers';
+import { ChatModelStreamHandler } from '@/stream';
 import { HandlerRegistry } from '@/events';
+import { StreamingToolCallBuffer } from '@/tools/StreamingToolCallBuffer';
 
 const { AGENT, TOOLS } = GraphNodeKeys;
 
@@ -151,6 +160,34 @@ export abstract class Graph<
    * Currently supports code execution session tracking (session_id, files).
    */
   sessions: t.ToolSessionMap = 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: 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(): void {
+    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();
+  }
 }
 
 export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
@@ -208,7 +245,13 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
       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()
@@ -227,6 +270,107 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
     }
   }
 
+  override clearHeavyState(): void {
+    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: t.ClientOptions,
+    provider: Providers
+  ): t.ClientOptions {
+    if (provider === Providers.ANTHROPIC) {
+      const anthropicOpts = clientOptions as t.AnthropicClientOptions;
+      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 as number) >
+          TOOL_TURN_THINKING_BUDGET
+      ) {
+        return {
+          ...anthropicOpts,
+          thinking: {
+            ...anthropicOpts.thinking,
+            budget_tokens: TOOL_TURN_THINKING_BUDGET,
+          },
+        } as t.AnthropicClientOptions;
+      }
+    }
+
+    if (provider === Providers.BEDROCK) {
+      const bedrockOpts = clientOptions as t.BedrockAnthropicClientOptions;
+      const thinkingField = bedrockOpts.additionalModelRequestFields?.thinking;
+      if (
+        thinkingField != null &&
+        typeof thinkingField === 'object' &&
+        'budget_tokens' in thinkingField &&
+        (thinkingField.budget_tokens as number) > TOOL_TURN_THINKING_BUDGET
+      ) {
+        return {
+          ...bedrockOpts,
+          additionalModelRequestFields: {
+            ...((bedrockOpts.additionalModelRequestFields ?? {}) as Record<
+              string,
+              unknown
+            >),
+            thinking: {
+              ...thinkingField,
+              budget_tokens: TOOL_TURN_THINKING_BUDGET,
+            },
+          },
+        } as t.BedrockAnthropicClientOptions;
+      }
+    }
+
+    if (provider === Providers.VERTEXAI || provider === Providers.GOOGLE) {
+      const googleOpts = clientOptions as t.GoogleClientOptions;
+      if (
+        googleOpts.thinkingConfig?.thinkingBudget != null &&
+        googleOpts.thinkingConfig.thinkingBudget > TOOL_TURN_THINKING_BUDGET
+      ) {
+        return {
+          ...googleOpts,
+          thinkingConfig: {
+            ...googleOpts.thinkingConfig,
+            thinkingBudget: TOOL_TURN_THINKING_BUDGET,
+          },
+        } as t.GoogleClientOptions;
+      }
+    }
+
+    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.
@@ -260,7 +404,7 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
     } else if (messageCount <= 150) {
       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';
     } else {
@@ -366,7 +510,7 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
     ) {
       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) {
@@ -383,7 +527,11 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
   /* Misc.*/
 
   getRunMessages(): BaseMessage[] | undefined {
-    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(): t.MessageContentComplex[] | undefined {
@@ -548,30 +696,91 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
     if (eventDrivenMode) {
       const schemaTools = createSchemaOnlyTools(toolDefinitions);
       const toolDefMap = new Map(toolDefinitions.map((def) => [def.name, def]));
+      const graphTools = agentContext?.graphTools as
+        | t.GenericTool[]
+        | undefined;
+
+      const directToolNames = new Set<string>();
+      const allTools = [...schemaTools] as t.GenericTool[];
+      const allToolMap: t.ToolMap = 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 CustomToolNode<t.BaseGraphState>({
-        tools: schemaTools as t.GenericTool[],
-        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 as t.GenericTool[] | undefined;
+    const baseTools = (currentTools as t.GenericTool[] | undefined) ?? [];
+    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): t is t.GenericTool & { name: string } => 'name' in t)
+              .map((t) => [t.name, t] as [string, t.GenericTool]),
+            ...graphTools
+              .filter((t): t is t.GenericTool & { name: string } => 'name' in t)
+              .map((t) => [t.name, t] as [string, t.GenericTool]),
+          ])
+        : currentToolMap;
+
+    /** Build directToolNames from graph-managed tools (handoff/transfer) so HITL can bypass them */
+    let directToolNames: Set<string> | undefined;
+    if (graphTools && graphTools.length > 0) {
+      directToolNames = new Set<string>();
+      for (const tool of graphTools) {
+        if ('name' in tool) {
+          directToolNames.add(tool.name);
+        }
+      }
+      if (directToolNames.size === 0) {
+        directToolNames = undefined;
+      }
+    }
+
     return new CustomToolNode<t.BaseGraphState>({
-      tools: (currentTools as t.GenericTool[] | undefined) ?? [],
-      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,
     });
   }
@@ -666,7 +875,7 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
       currentModel,
       finalMessages,
       provider,
-      tools,
+      tools: _tools,
     }: {
       currentModel?: t.ChatModel;
       finalMessages: BaseMessage[];
@@ -680,23 +889,54 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
       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 as Record<string, unknown> | undefined;
+      const streamHandler = new ChatModelStreamHandler();
       const stream = await model.stream(finalMessages, config);
       let finalChunk: AIMessageChunk | undefined;
       for await (const chunk of stream) {
-        await safeDispatchCustomEvent(
+        await streamHandler.handle(
           GraphEvents.CHAT_MODEL_STREAM,
-          { chunk, emitted: true },
-          config
+          { 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: ToolCall) => !!tool_call.name
+        );
+      }
+
       return { messages: [finalChunk as AIMessageChunk] };
     } 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(
@@ -739,17 +979,14 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
     rawMessage?: AIMessageChunk;
   }> {
     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 as any).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.`
+        '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.'
       );
     }
 
@@ -766,7 +1003,10 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
       const resolved = agentContext.resolveStructuredOutputMode();
       method = resolved.method;
       if (resolved.warnings.length > 0) {
-        console.warn('[Graph] Structured output mode warnings:', resolved.warnings);
+        console.warn(
+          '[Graph] Structured output mode warnings:',
+          resolved.warnings
+        );
       }
     } else {
       // Legacy fallback: use the old mode-based resolution
@@ -774,7 +1014,8 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
       if (mode === 'tool') {
         method = 'functionCalling';
       } else if (mode === 'provider') {
-        method = provider === Providers.BEDROCK ? 'functionCalling' : 'jsonMode';
+        method =
+          provider === Providers.BEDROCK ? 'functionCalling' : 'jsonMode';
       } else {
         method = undefined;
       }
@@ -782,36 +1023,30 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
 
     // 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,
+        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
     // Always use includeRaw: true internally so we can debug what's returned
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    const structuredModel = (model as any).withStructuredOutput(preparedSchema, {
-      name,
-      method: method === 'native' ? undefined : method,
-      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 as any).model || (model as any).modelId || 'unknown',
-    });
+    const structuredModel = (model as any).withStructuredOutput(
+      preparedSchema,
+      {
+        name,
+        method: method === 'native' ? undefined : method,
+        includeRaw: true, // Always true internally for debugging
+        strict: structuredOutputConfig.strict !== false,
+      }
+    );
 
     let lastError: Error | undefined;
     let attempts = 0;
@@ -822,24 +1057,16 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
         // 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 as AIMessageChunk;
-          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
+            responseMetadata.stop_reason ?? // Anthropic
+            responseMetadata.finish_reason ?? // OpenAI
+            responseMetadata.stopReason; // Bedrock
 
           if (stopReason === 'max_tokens' || stopReason === 'length') {
             throw new StructuredOutputTruncatedError(stopReason);
@@ -847,14 +1074,15 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
 
           // Check for Anthropic refusal (stop_reason won't be 'refusal' but content may indicate it)
           // OpenAI uses message.refusal field
-          const refusal = (rawMsg as AIMessageChunk & { refusal?: string }).refusal;
-          if (refusal) {
+          const refusal = (rawMsg as AIMessageChunk & { refusal?: string })
+            .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 as Record<string, unknown>,
             rawMessage: result.raw as AIMessageChunk,
@@ -952,12 +1180,15 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
     // 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 } as t.ClientOptions;
+    const structuredClientOptions = {
+      ...agentContext.clientOptions,
+    } as t.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();
-    const canStream = resolved.method === 'jsonSchema' || resolved.method === 'jsonMode';
+    const canStream =
+      resolved.method === 'jsonSchema' || resolved.method === 'jsonMode';
     if (!canStream) {
       // Disable streaming for function calling mode (synthetic tool calls break streaming UX)
       // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -972,19 +1203,24 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
     if (needsThinkingDisabled) {
       // Remove thinking configuration for Bedrock
       if (agentContext.provider === Providers.BEDROCK) {
-        const bedrockOpts = structuredClientOptions as t.BedrockAnthropicClientOptions;
-        if (bedrockOpts.additionalModelRequestFields) {
-          // eslint-disable-next-line @typescript-eslint/no-explicit-any
-          const additionalFields = Object.assign({}, bedrockOpts.additionalModelRequestFields) as any;
+        const bedrockOpts =
+          structuredClientOptions as t.BedrockAnthropicClientOptions;
+        if (bedrockOpts.additionalModelRequestFields != null) {
+          const additionalFields = Object.assign(
+            {},
+            bedrockOpts.additionalModelRequestFields
+          ) as Record<string, unknown>;
           delete additionalFields.thinking;
           delete additionalFields.budgetTokens;
-          bedrockOpts.additionalModelRequestFields = additionalFields;
+          bedrockOpts.additionalModelRequestFields =
+            additionalFields as t.BedrockAnthropicInput['additionalModelRequestFields'];
         }
       }
 
       // Remove thinking configuration for Anthropic direct API
       if (agentContext.provider === Providers.ANTHROPIC) {
-        const anthropicOpts = structuredClientOptions as t.AnthropicClientOptions;
+        const anthropicOpts =
+          structuredClientOptions as t.AnthropicClientOptions;
         if (anthropicOpts.thinking) {
           delete anthropicOpts.thinking;
         }
@@ -1064,7 +1300,8 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
       // (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 &&
+        agentContext.dynamicContext != null &&
+        agentContext.dynamicContext !== '' &&
         messages.length > 0 &&
         !messages.some(
           (m) =>
@@ -1090,12 +1327,28 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
       }
 
       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) {
@@ -1120,17 +1373,16 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
       // the content for the LLM to understand what to delegate.
       // ====================================================================
       let delegationInjectedPrePrune = false;
-      const hasTaskToolPrePrune = agentContext.tools?.some(
-        (tool) => {
-          const toolName = typeof tool === 'object' && 'name' in tool
+      const hasTaskToolPrePrune = agentContext.tools?.some((tool) => {
+        const toolName =
+          typeof tool === 'object' && 'name' in tool
             ? (tool as { name: string }).name
             : '';
-          return toolName === 'task';
-        }
-      );
+        return toolName === 'task';
+      });
 
       if (
-        hasTaskToolPrePrune &&
+        hasTaskToolPrePrune === true &&
         agentContext.tokenCounter &&
         agentContext.maxContextTokens != null
       ) {
@@ -1140,15 +1392,16 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
           prePruneTokens += agentContext.tokenCounter(msg);
         }
         // Add instruction tokens (system prompt)
-        prePruneTokens += agentContext.instructionTokens ?? 0;
+        prePruneTokens += agentContext.instructionTokens;
 
-        const prePruneUtilization = (prePruneTokens / agentContext.maxContextTokens) * 100;
+        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.`
+              `(${prePruneTokens}/${agentContext.maxContextTokens} tokens). ` +
+              'Injecting delegation hint INSTEAD of pruning.'
           );
           delegationInjectedPrePrune = true;
         }
@@ -1184,34 +1437,56 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
       }
 
       if (agentContext.pruneMessages && !delegationInjectedPrePrune) {
-        const { context, indexTokenCountMap, messagesToRefine } = agentContext.pruneMessages({
-          messages,
-          usageMetadata: agentContext.currentUsage,
-          // startOnMessageType: 'human',
-        });
+        console.info(
+          `[Graph:ContextMgmt] Pruning messages | inputCount=${messages.length} | maxTokens=${agentContext.maxContextTokens}`
+        );
+        const { context, indexTokenCountMap, messagesToRefine } =
+          agentContext.pruneMessages({
+            messages,
+            usageMetadata: agentContext.currentUsage,
+            // startOnMessageType: 'human',
+          });
         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) {
-              const summaryMsg = new SystemMessage(`[Conversation Summary]\n${summary}`);
+            const summary =
+              await agentContext.summarizeCallback(messagesToRefine);
+            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;
+              const systemIdx =
+                messagesToUse[0]?.getType() === 'system' ? 1 : 0;
               messagesToUse = [
                 ...messagesToUse.slice(0, systemIdx),
                 summaryMsg,
                 ...messagesToUse.slice(systemIdx),
               ];
+              console.info(
+                `[Graph:ContextMgmt] Summary injected at index ${systemIdx} | finalMsgCount=${messagesToUse.length}`
+              );
             }
           } catch (err) {
             console.error('[Graph] Summarization callback failed:', err);
           }
         }
       } else if (delegationInjectedPrePrune) {
-        console.info('[Graph] Skipping pruning — delegation will handle context pressure');
+        console.info(
+          '[Graph] Skipping pruning — delegation will handle context pressure'
+        );
       }
 
       let finalMessages = messagesToUse;
@@ -1338,11 +1613,11 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
         | t.BedrockAnthropicClientOptions
         | undefined;
       const modelId =
-        bedrockOpts?.model ||
+        bedrockOpts?.model ??
         (agentContext.clientOptions as t.AnthropicClientOptions | undefined)
           ?.modelName;
       const thinkingConfig =
-        bedrockOpts?.additionalModelRequestFields?.['thinking'] ||
+        bedrockOpts?.additionalModelRequestFields?.['thinking'] ??
         (agentContext.clientOptions as t.AnthropicClientOptions | undefined)
           ?.thinking;
 
@@ -1383,17 +1658,16 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
       // This runs mid-chain — so even if tool responses push context up
       // after the first LLM call, subsequent iterations get the hint.
       // ====================================================================
-      const hasTaskToolInContext = agentContext.tools?.some(
-        (tool) => {
-          const toolName = typeof tool === 'object' && 'name' in tool
+      const hasTaskToolInContext = agentContext.tools?.some((tool) => {
+        const toolName =
+          typeof tool === 'object' && 'name' in tool
             ? (tool as { name: string }).name
             : '';
-          return toolName === 'task';
-        }
-      );
+        return toolName === 'task';
+      });
 
       if (
-        hasTaskToolInContext &&
+        hasTaskToolInContext === true &&
         contextAnalytics.utilizationPercent != null &&
         contextAnalytics.maxContextTokens != null
       ) {
@@ -1409,14 +1683,17 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
         let documentCount = 0;
         const documentNames: string[] = [];
         for (const msg of finalMessages) {
-          const content = typeof msg.content === 'string'
-            ? msg.content
-            : Array.isArray(msg.content)
-              ? msg.content.map((p: unknown) => {
-                  const part = p as Record<string, unknown>;
-                  return String(part.text || part.content || '');
-                }).join(' ')
-              : '';
+          const content =
+            typeof msg.content === 'string'
+              ? msg.content
+              : Array.isArray(msg.content)
+                ? msg.content
+                    .map((p: unknown) => {
+                      const part = p as Record<string, unknown>;
+                      return String(part.text ?? part.content ?? '');
+                    })
+                    .join(' ')
+                : '';
           // Pattern 1: # "filename" headers in attached document blocks
           const docMatches = content.match(/# "([^"]+)"/g);
           if (docMatches) {
@@ -1429,9 +1706,14 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
             }
           }
           // Pattern 2: "The user has attached: **file1, file2**" (embedded files)
-          const attachedMatch = content.match(/user has attached:\s*\*\*([^*]+)\*\*/i);
+          const attachedMatch = content.match(
+            /user has attached:\s*\*\*([^*]+)\*\*/i
+          );
           if (attachedMatch) {
-            const names = attachedMatch[1].split(',').map((n: string) => n.trim()).filter(Boolean);
+            const names = attachedMatch[1]
+              .split(',')
+              .map((n: string) => n.trim())
+              .filter(Boolean);
             for (const name of names) {
               if (!documentNames.includes(name)) {
                 documentNames.push(name);
@@ -1444,61 +1726,67 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
         // BASELINE LOG: Always fires so we can verify this code path runs
         console.info(
           `[Graph] Context utilization: ${utilization.toFixed(1)}% ` +
-          `(${totalTokens}/${maxTokens} tokens, ${remainingTokens} remaining) | ` +
-          `hasTaskTool: true | messages: ${finalMessages.length} | docs: ${documentCount}`
+            `(${totalTokens}/${maxTokens} tokens, ${remainingTokens} remaining) | ` +
+            `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'
+          (m) => m._getType() === 'ai' || m._getType() === 'tool'
         );
         if (documentCount >= 3 && !hasAiResponse) {
           const pressureMsg = new HumanMessage({
-            content: `[MULTI-DOCUMENT PROCESSING — ${documentCount} documents detected]\n` +
+            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: ` +
-            `${documentNames.join(', ')}`
+              `${documentNames.join(', ')}`
           );
         }
 
         // 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` +
+            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)}%): ` +
-            `Injected mandatory delegation hint. ${remainingTokens} tokens remaining. ` +
-            `prePruneSkipped: ${delegationInjectedPrePrune}`
+              `Injected mandatory delegation hint. ${remainingTokens} tokens remaining. ` +
+              `prePruneSkipped: ${delegationInjectedPrePrune}`
           );
         } else if (utilization > 70) {
           // WARNING: Context filling up — suggest delegation
           const pressureMsg = new HumanMessage({
-            content: `[CONTEXT BUDGET WARNING — ${utilization.toFixed(0)}% used]\n` +
+            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)}%): ` +
-            `Injected delegation suggestion. ${remainingTokens} tokens remaining.`
+              `Injected delegation suggestion. ${remainingTokens} tokens remaining.`
           );
         }
       }
@@ -1541,8 +1829,7 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
         );
       } catch (primaryError) {
         // Check if this is a "input too long" error from Bedrock/Anthropic
-        const errorMessage =
-          (primaryError as Error).message.toLowerCase() ?? '';
+        const errorMessage = (primaryError as Error).message.toLowerCase();
         const isInputTooLongError =
           errorMessage.includes('too long') ||
           errorMessage.includes('input is too long') ||
@@ -1569,7 +1856,9 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
         // 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;
+          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];
@@ -1689,8 +1978,7 @@ If I seem to be missing something we discussed earlier, just give me a quick rem
                 `[Graph] ✅ Retry successful at ${reductionFactor * 100}% with ${reducedMessages.length} messages (reduced from ${finalMessages.length})`
               );
             } catch (retryError) {
-              const retryErrorMsg =
-                (retryError as Error).message.toLowerCase() ?? '';
+              const retryErrorMsg = (retryError as Error).message.toLowerCase();
               const stillTooLong =
                 retryErrorMsg.includes('too long') ||
                 retryErrorMsg.includes('context length') ||
@@ -1752,6 +2040,128 @@ 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 as AIMessageChunk | undefined)
+        ?.tool_calls;
+      const hasToolCalls = Array.isArray(toolCalls) && toolCalls.length > 0;
+
+      if (hasToolCalls) {
+        const metadata = config.metadata as Record<string, unknown>;
+        const stepKey = this.getStepKey(metadata);
+        const content = responseMessage?.content as MessageContent | undefined;
+        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 as t.MessageDelta['content'],
+              });
+            }
+          }
+        }
+
+        await handleToolCalls(toolCalls as ToolCall[], 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 as t.OpenAIClientOptions | undefined)
+          ?.disableStreaming === true;
+
+      if (
+        disableStreaming &&
+        !hasToolCalls &&
+        responseMessage != null &&
+        (responseMessage.content as MessageContent | undefined) != null
+      ) {
+        const metadata = config.metadata as Record<string, unknown>;
+        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 as t.MessageDelta['content'],
+            });
+          }
+        }
+      }
+
       agentContext.currentUsage = this.getUsageMetadata(result.messages?.[0]);
 
       // Extract and normalize the LLM's finish/stop reason for auto-continuation support
@@ -1759,14 +2169,15 @@ If I seem to be missing something we discussed earlier, just give me a quick rem
       if (finalMsg && 'response_metadata' in finalMsg) {
         const meta = finalMsg.response_metadata as Record<string, unknown>;
         // Bedrock streaming nests stopReason inside messageStop: { stopReason: '...' }
-        const messageStop = meta.messageStop as Record<string, unknown> | undefined;
+        const messageStop = meta.messageStop as
+          | Record<string, unknown>
+          | undefined;
         this.lastFinishReason =
-          (meta.finish_reason as string) ??              // OpenAI/Azure
-          (meta.stop_reason as string) ??                // Anthropic direct API
-          (meta.stopReason as string) ??                 // Bedrock invoke (non-streaming)
-          (messageStop?.stopReason as string) ??         // Bedrock streaming
-          (meta.finishReason as string) ??               // VertexAI/Google
-          undefined;
+          (meta.finish_reason as string | undefined) ?? // OpenAI/Azure
+          (meta.stop_reason as string | undefined) ?? // Anthropic direct API
+          (meta.stopReason as string | undefined) ?? // Bedrock invoke (non-streaming)
+          (messageStop?.stopReason as string | undefined) ?? // Bedrock streaming
+          (meta.finishReason as string | undefined); // VertexAI/Google
       }
 
       this.cleanupSignalListener();
@@ -1776,16 +2187,15 @@ If I seem to be missing something we discussed earlier, just give me a quick rem
       // 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 &&
+          lastMessage != null &&
           'tool_calls' in lastMessage &&
           ((lastMessage as AIMessageChunk).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
@@ -1892,6 +2302,13 @@ 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;
@@ -2121,6 +2538,7 @@ If I seem to be missing something we discussed earlier, just give me a quick rem
         this
       );
   }
+
   /**
    * Static version of handleToolCallError to avoid creating strong references
    * that prevent garbage collection