@librechat/agents 3.1.57 → 3.1.61

package/dist/esm/graphs/Graph.mjs

@@ -1,35 +1,36 @@
 import { nanoid } from 'nanoid';
-import { concat } from '@langchain/core/utils/stream';
-import { ChatVertexAI } from '@langchain/google-vertexai';
-import { Annotation, messagesStateReducer, StateGraph, START, END } from '@langchain/langgraph';
-import { RunnableLambda } from '@langchain/core/runnables';
-import { SystemMessage, AIMessageChunk, ToolMessage } from '@langchain/core/messages';
-import { convertMessagesToContent, modifyDeltaProperties, formatAnthropicArtifactContent, formatArtifactPayload } from '../messages/core.mjs';
+import { AIMessageChunk, ToolMessage } from '@langchain/core/messages';
+import { Annotation, StateGraph, START, END } from '@langchain/langgraph';
+import { convertMessagesToContent, formatAnthropicArtifactContent, formatArtifactPayload } from '../messages/core.mjs';
 import { getMessageId } from '../messages/ids.mjs';
-import { createPruneMessages } from '../messages/prune.mjs';
+import { createPruneMessages, sanitizeOrphanToolBlocks } 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, ContentTypes, Providers, GraphEvents, StepTypes } from '../common/enum.mjs';
+import { messagesStateReducer } from '../messages/reducer.mjs';
+import { GraphNodeKeys, ContentTypes, Providers, StepTypes, GraphEvents } from '../common/enum.mjs';
 import { resetIfNotEmpty, joinKeys } from '../utils/graph.mjs';
-import { isOpenAILike, isGoogleLike } from '../utils/llm.mjs';
-import { ChatModelStreamHandler } from '../stream.mjs';
+import { isAnthropicLike, isOpenAILike, isGoogleLike } from '../utils/llm.mjs';
 import { handleToolCalls } from '../tools/handlers.mjs';
 import { sleep } from '../utils/run.mjs';
 import 'ai-tokenizer';
 import 'zod-to-json-schema';
-import { getChatModelClass, manualToolStreamProviders } from '../llm/providers.mjs';
 import { ToolNode, toolsCondition } from '../tools/ToolNode.mjs';
-import { ChatOpenAI, AzureChatOpenAI } from '../llm/openai/index.mjs';
-import { safeDispatchCustomEvent } from '../utils/events.mjs';
+import { emitAgentLog, safeDispatchCustomEvent } from '../utils/events.mjs';
+import { attemptInvoke, tryFallbackProviders } from '../llm/invoke.mjs';
+import { shouldTriggerSummarization } from '../summarization/index.mjs';
+import { createSummarizeNode } from '../summarization/node.mjs';
 import { createSchemaOnlyTools } from '../tools/schema.mjs';
 import { AgentContext } from '../agents/AgentContext.mjs';
 import { createFakeStreamingLLM } from '../llm/fake.mjs';
+import { isThinkingEnabled } from '../llm/request.mjs';
+import { initializeModel } from '../llm/init.mjs';
 
 /* eslint-disable no-console */
-// src/graphs/Graph.ts
-const { AGENT, TOOLS } = GraphNodeKeys;
+const { AGENT, TOOLS, SUMMARIZE } = GraphNodeKeys;
+/** Minimum relative variance before calibrated toolSchemaTokens overrides current value. */
+const CALIBRATION_VARIANCE_THRESHOLD = 0.15;
 class Graph {
     messageStepHasToolCalls = new Map();
     messageIdsByStepKey = new Map();
@@ -39,6 +40,12 @@ class Graph {
     stepKeyIds = new Map();
     contentIndexMap = new Map();
     toolCallStepIds = new Map();
+    /**
+     * Step IDs that have been dispatched via handler registry directly
+     * (in dispatchRunStep).  Used by the custom event callback to skip
+     * duplicate dispatch through the LangGraph callback chain.
+     */
+    handlerDispatchedStepIds = new Set();
     signal;
     /** Set of invoked tool call IDs from non-message run steps completed mid-run, if any */
     invokedToolIds;
@@ -74,16 +81,23 @@ class StandardGraph extends Graph {
     /** Optional compile options passed into workflow.compile() */
     compileOptions;
     messages = [];
+    /** Cached run messages preserved before clearHeavyState() so getRunMessages() works after cleanup. */
+    cachedRunMessages;
     runId;
+    /**
+     * Boundary between historical messages (loaded from conversation state)
+     * and messages produced during the current run.  Set once in the state
+     * reducer when messages first arrive.  Used by `getRunMessages()` and
+     * multi-agent message filtering — NOT for pruner token counting (the
+     * pruner maintains its own `lastTurnStartIndex` in its closure).
+     */
     startIndex = 0;
     signal;
     /** Map of agent contexts by agent ID */
     agentContexts = new Map();
     /** Default agent ID to use */
     defaultAgentId;
-    constructor({ 
-    // parent-level graph inputs
-    runId, signal, agents, tokenCounter, indexTokenCountMap, }) {
+    constructor({ runId, signal, agents, tokenCounter, indexTokenCountMap, calibrationRatio, }) {
         super();
         this.runId = runId;
         this.signal = signal;
@@ -92,6 +106,9 @@ class StandardGraph extends Graph {
         }
         for (const agentConfig of agents) {
             const agentContext = AgentContext.fromConfig(agentConfig, tokenCounter, indexTokenCountMap);
+            if (calibrationRatio != null && calibrationRatio > 0) {
+                agentContext.calibrationRatio = calibrationRatio;
+            }
             this.agentContexts.set(agentConfig.agentId, agentContext);
         }
         this.defaultAgentId = agents[0].agentId;
@@ -99,6 +116,7 @@ class StandardGraph extends Graph {
     /* Init */
     resetValues(keepContent) {
         this.messages = [];
+        this.cachedRunMessages = undefined;
         this.config = resetIfNotEmpty(this.config, undefined);
         if (keepContent !== true) {
             this.contentData = resetIfNotEmpty(this.contentData, []);
@@ -112,6 +130,7 @@ class StandardGraph extends Graph {
          * a stale reference on 2nd+ processStream calls.
          */
         this.toolCallStepIds.clear();
+        this.handlerDispatchedStepIds = resetIfNotEmpty(this.handlerDispatchedStepIds, new Set());
         this.messageIdsByStepKey = resetIfNotEmpty(this.messageIdsByStepKey, new Map());
         this.messageStepHasToolCalls = resetIfNotEmpty(this.messageStepHasToolCalls, new Map());
         this.prelimMessageIdsByStepKey = resetIfNotEmpty(this.prelimMessageIdsByStepKey, new Map());
@@ -121,6 +140,7 @@ class StandardGraph extends Graph {
         }
     }
     clearHeavyState() {
+        this.cachedRunMessages = this.messages.slice(this.startIndex);
         super.clearHeavyState();
         this.messages = [];
         this.overrideModel = undefined;
@@ -151,6 +171,9 @@ class StandardGraph extends Graph {
         else if (currentNode.startsWith(TOOLS)) {
             agentId = currentNode.substring(TOOLS.length);
         }
+        else if (currentNode.startsWith(SUMMARIZE)) {
+            agentId = currentNode.substring(SUMMARIZE.length);
+        }
         const agentContext = this.agentContexts.get(agentId ?? '');
         if (!agentContext) {
             throw new Error(`No agent context found for agent ID ${agentId}`);
@@ -220,11 +243,26 @@ class StandardGraph extends Graph {
     }
     /* Misc.*/
     getRunMessages() {
+        if (this.messages.length === 0 && this.cachedRunMessages != null) {
+            return this.cachedRunMessages;
+        }
         return this.messages.slice(this.startIndex);
     }
     getContentParts() {
         return convertMessagesToContent(this.messages.slice(this.startIndex));
     }
+    getCalibrationRatio() {
+        const context = this.agentContexts.get(this.defaultAgentId);
+        return context?.calibrationRatio ?? 1;
+    }
+    getResolvedInstructionOverhead() {
+        const context = this.agentContexts.get(this.defaultAgentId);
+        return context?.resolvedInstructionOverhead;
+    }
+    getToolCount() {
+        const context = this.agentContexts.get(this.defaultAgentId);
+        return ((context?.tools?.length ?? 0) + (context?.toolDefinitions?.length ?? 0));
+    }
     /**
      * Get all run steps, optionally filtered by agent ID
      */
@@ -276,35 +314,6 @@ class StandardGraph extends Graph {
         return contentPartAgentMap;
     }
     /* Graph */
-    createSystemRunnable({ provider, clientOptions, instructions, additional_instructions, }) {
-        let finalInstructions = instructions;
-        if (additional_instructions != null && additional_instructions !== '') {
-            finalInstructions =
-                finalInstructions != null && finalInstructions
-                    ? `${finalInstructions}\n\n${additional_instructions}`
-                    : additional_instructions;
-        }
-        if (finalInstructions != null &&
-            finalInstructions &&
-            provider === Providers.ANTHROPIC &&
-            clientOptions.promptCache === true) {
-            finalInstructions = {
-                content: [
-                    {
-                        type: 'text',
-                        text: instructions,
-                        cache_control: { type: 'ephemeral' },
-                    },
-                ],
-            };
-        }
-        if (finalInstructions != null && finalInstructions !== '') {
-            const systemMessage = new SystemMessage(finalInstructions);
-            return RunnableLambda.from((messages) => {
-                return [systemMessage, ...messages];
-            }).withConfig({ runName: 'prompt' });
-        }
-    }
     initializeTools({ currentTools, currentToolMap, agentContext, }) {
         const toolDefinitions = agentContext?.toolDefinitions;
         const eventDrivenMode = toolDefinitions != null && toolDefinitions.length > 0;
@@ -334,6 +343,8 @@ class StandardGraph extends Graph {
                 toolCallStepIds: this.toolCallStepIds,
                 toolRegistry: agentContext?.toolRegistry,
                 directToolNames: directToolNames.size > 0 ? directToolNames : undefined,
+                maxContextTokens: agentContext?.maxContextTokens,
+                maxToolResultChars: agentContext?.maxToolResultChars,
                 errorHandler: (data, metadata) => StandardGraph.handleToolCallErrorStatic(this, data, metadata),
             });
         }
@@ -357,42 +368,10 @@ class StandardGraph extends Graph {
             errorHandler: (data, metadata) => StandardGraph.handleToolCallErrorStatic(this, data, metadata),
             toolRegistry: agentContext?.toolRegistry,
             sessions: this.sessions,
+            maxContextTokens: agentContext?.maxContextTokens,
+            maxToolResultChars: agentContext?.maxToolResultChars,
         });
     }
-    initializeModel({ provider, tools, clientOptions, }) {
-        const ChatModelClass = getChatModelClass(provider);
-        const model = new ChatModelClass(clientOptions ?? {});
-        if (isOpenAILike(provider) &&
-            (model instanceof ChatOpenAI || model instanceof AzureChatOpenAI)) {
-            model.temperature = clientOptions
-                .temperature;
-            model.topP = clientOptions.topP;
-            model.frequencyPenalty = clientOptions
-                .frequencyPenalty;
-            model.presencePenalty = clientOptions
-                .presencePenalty;
-            model.n = clientOptions.n;
-        }
-        else if (provider === Providers.VERTEXAI &&
-            model instanceof ChatVertexAI) {
-            model.temperature = clientOptions
-                .temperature;
-            model.topP = clientOptions.topP;
-            model.topK = clientOptions.topK;
-            model.topLogprobs = clientOptions
-                .topLogprobs;
-            model.frequencyPenalty = clientOptions
-                .frequencyPenalty;
-            model.presencePenalty = clientOptions
-                .presencePenalty;
-            model.maxOutputTokens = clientOptions
-                .maxOutputTokens;
-        }
-        if (!tools || tools.length === 0) {
-            return model;
-        }
-        return model.bindTools(tools);
-    }
     overrideTestModel(responses, sleep, toolCalls) {
         this.overrideModel = createFakeStreamingLLM({
             responses,
@@ -400,10 +379,6 @@ class StandardGraph extends Graph {
             toolCalls,
         });
     }
-    getNewModel({ provider, clientOptions, }) {
-        const ChatModelClass = getChatModelClass(provider);
-        return new ChatModelClass(clientOptions ?? {});
-    }
     getUsageMetadata(finalMessage) {
         if (finalMessage &&
             'usage_metadata' in finalMessage &&
@@ -411,58 +386,6 @@ class StandardGraph extends Graph {
             return finalMessage.usage_metadata;
         }
     }
-    /** Execute model invocation with streaming support */
-    async attemptInvoke({ currentModel, finalMessages, provider, tools: _tools, }, config) {
-        const model = this.overrideModel ?? currentModel;
-        if (!model) {
-            throw new Error('No model found');
-        }
-        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 streamHandler.handle(GraphEvents.CHAT_MODEL_STREAM, { chunk }, metadata, this);
-                finalChunk = finalChunk ? concat(finalChunk, chunk) : chunk;
-            }
-            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);
-            }
-            return { messages: [finalMessage] };
-        }
-    }
     cleanupSignalListener(currentModel) {
         if (!this.signal) {
             return;
@@ -480,9 +403,6 @@ class StandardGraph extends Graph {
     }
     createCallModel(agentId = 'default') {
         return async (state, config) => {
-            /**
-             * Get agent context - it must exist by this point
-             */
             const agentContext = this.agentContexts.get(agentId);
             if (!agentContext) {
                 throw new Error(`Agent context not found for agentId: ${agentId}`);
@@ -491,14 +411,13 @@ class StandardGraph extends Graph {
                 throw new Error('No config provided');
             }
             const { messages } = state;
-            // Extract tool discoveries from current turn only (similar to formatArtifactPayload pattern)
             const discoveredNames = extractToolDiscoveries(messages);
             if (discoveredNames.length > 0) {
                 agentContext.markToolsAsDiscovered(discoveredNames);
             }
             const toolsForBinding = agentContext.getToolsForBinding();
             let model = this.overrideModel ??
-                this.initializeModel({
+                initializeModel({
                     tools: toolsForBinding,
                     provider: agentContext.provider,
                     clientOptions: agentContext.clientOptions,
@@ -516,34 +435,97 @@ class StandardGraph extends Graph {
             let messagesToUse = messages;
             if (!agentContext.pruneMessages &&
                 agentContext.tokenCounter &&
-                agentContext.maxContextTokens != null &&
-                agentContext.indexTokenCountMap[0] != null) {
-                const isAnthropicWithThinking = (agentContext.provider === Providers.ANTHROPIC &&
-                    agentContext.clientOptions.thinking !=
-                        null) ||
-                    (agentContext.provider === Providers.BEDROCK &&
-                        agentContext.clientOptions
-                            .additionalModelRequestFields?.['thinking'] != null) ||
-                    (agentContext.provider === Providers.OPENAI &&
-                        agentContext.clientOptions.modelKwargs
-                            ?.thinking?.type === 'enabled');
+                agentContext.maxContextTokens != null) {
                 agentContext.pruneMessages = createPruneMessages({
-                    startIndex: this.startIndex,
+                    startIndex: agentContext.indexTokenCountMap[0] != null ? this.startIndex : 0,
                     provider: agentContext.provider,
                     tokenCounter: agentContext.tokenCounter,
                     maxTokens: agentContext.maxContextTokens,
-                    thinkingEnabled: isAnthropicWithThinking,
+                    thinkingEnabled: isThinkingEnabled(agentContext.provider, agentContext.clientOptions),
                     indexTokenCountMap: agentContext.indexTokenCountMap,
+                    contextPruningConfig: agentContext.contextPruningConfig,
+                    summarizationEnabled: agentContext.summarizationEnabled,
+                    reserveRatio: agentContext.summarizationConfig?.reserveRatio,
+                    calibrationRatio: agentContext.calibrationRatio,
+                    getInstructionTokens: () => agentContext.instructionTokens,
+                    log: (level, message, data) => {
+                        emitAgentLog(config, level, 'prune', message, data, {
+                            runId: this.runId,
+                            agentId,
+                        });
+                    },
                 });
             }
             if (agentContext.pruneMessages) {
-                const { context, indexTokenCountMap } = agentContext.pruneMessages({
+                const { context, indexTokenCountMap, messagesToRefine, prePruneContextTokens, remainingContextTokens, originalToolContent, calibrationRatio, resolvedInstructionOverhead, } = agentContext.pruneMessages({
                     messages,
                     usageMetadata: agentContext.currentUsage,
-                    // startOnMessageType: 'human',
+                    lastCallUsage: agentContext.lastCallUsage,
+                    totalTokensFresh: agentContext.totalTokensFresh,
                 });
                 agentContext.indexTokenCountMap = indexTokenCountMap;
+                if (calibrationRatio != null && calibrationRatio > 0) {
+                    agentContext.calibrationRatio = calibrationRatio;
+                }
+                if (resolvedInstructionOverhead != null) {
+                    agentContext.resolvedInstructionOverhead =
+                        resolvedInstructionOverhead;
+                    const nonToolOverhead = agentContext.instructionTokens - agentContext.toolSchemaTokens;
+                    const calibratedToolTokens = Math.max(0, resolvedInstructionOverhead - nonToolOverhead);
+                    const currentToolTokens = agentContext.toolSchemaTokens;
+                    const variance = currentToolTokens > 0
+                        ? Math.abs(calibratedToolTokens - currentToolTokens) /
+                            currentToolTokens
+                        : 1;
+                    if (variance > CALIBRATION_VARIANCE_THRESHOLD) {
+                        agentContext.toolSchemaTokens = calibratedToolTokens;
+                    }
+                }
                 messagesToUse = context;
+                const hasPrunedMessages = agentContext.summarizationEnabled === true &&
+                    Array.isArray(messagesToRefine) &&
+                    messagesToRefine.length > 0;
+                if (hasPrunedMessages) {
+                    const shouldSkip = agentContext.shouldSkipSummarization(messages.length);
+                    const triggerResult = !shouldSkip &&
+                        shouldTriggerSummarization({
+                            trigger: agentContext.summarizationConfig?.trigger,
+                            maxContextTokens: agentContext.maxContextTokens,
+                            prePruneContextTokens: prePruneContextTokens != null
+                                ? prePruneContextTokens + agentContext.instructionTokens
+                                : undefined,
+                            remainingContextTokens,
+                            messagesToRefineCount: messagesToRefine.length,
+                        });
+                    if (triggerResult) {
+                        if (originalToolContent != null && originalToolContent.size > 0) {
+                            agentContext.pendingOriginalToolContent = originalToolContent;
+                        }
+                        emitAgentLog(config, 'info', 'graph', 'Summarization triggered', undefined, { runId: this.runId, agentId });
+                        emitAgentLog(config, 'debug', 'graph', 'Summarization trigger details', {
+                            totalMessages: messages.length,
+                            remainingContextTokens: remainingContextTokens ?? 0,
+                            summaryVersion: agentContext.summaryVersion + 1,
+                            toolSchemaTokens: agentContext.toolSchemaTokens,
+                            instructionTokens: agentContext.instructionTokens,
+                            systemMessageTokens: agentContext.systemMessageTokens,
+                        }, { runId: this.runId, agentId });
+                        agentContext.markSummarizationTriggered(messages.length);
+                        return {
+                            summarizationRequest: {
+                                remainingContextTokens: remainingContextTokens ?? 0,
+                                agentId: agentId || agentContext.agentId,
+                            },
+                        };
+                    }
+                    if (shouldSkip) {
+                        emitAgentLog(config, 'debug', 'graph', 'Summarization skipped — no new messages or per-run cap reached', {
+                            messageCount: messages.length,
+                            messagesToRefineCount: messagesToRefine.length,
+                            contextLength: context.length,
+                        }, { runId: this.runId, agentId });
+                    }
+                }
             }
             let finalMessages = messagesToUse;
             if (agentContext.useLegacyContent) {
@@ -555,26 +537,29 @@ class StandardGraph extends Graph {
             const lastMessageY = finalMessages.length >= 1
                 ? finalMessages[finalMessages.length - 1]
                 : null;
+            const anthropicLike = isAnthropicLike(agentContext.provider, agentContext.clientOptions);
             if (agentContext.provider === Providers.BEDROCK &&
                 lastMessageX instanceof AIMessageChunk &&
                 lastMessageY instanceof ToolMessage &&
                 typeof lastMessageX.content === 'string') {
-                finalMessages[finalMessages.length - 2].content = '';
-            }
-            const isLatestToolMessage = lastMessageY instanceof ToolMessage;
-            if (isLatestToolMessage &&
-                agentContext.provider === Providers.ANTHROPIC) {
-                formatAnthropicArtifactContent(finalMessages);
+                const trimmed = lastMessageX.content.trim();
+                finalMessages[finalMessages.length - 2].content =
+                    trimmed.length > 0 ? [{ type: 'text', text: trimmed }] : '';
             }
-            else if (isLatestToolMessage &&
-                ((isOpenAILike(agentContext.provider) &&
+            if (lastMessageY instanceof ToolMessage) {
+                if (anthropicLike) {
+                    formatAnthropicArtifactContent(finalMessages);
+                }
+                else if ((isOpenAILike(agentContext.provider) &&
                     agentContext.provider !== Providers.DEEPSEEK) ||
-                    isGoogleLike(agentContext.provider))) {
-                formatArtifactPayload(finalMessages);
+                    isGoogleLike(agentContext.provider)) {
+                    formatArtifactPayload(finalMessages);
+                }
             }
             if (agentContext.provider === Providers.ANTHROPIC) {
                 const anthropicOptions = agentContext.clientOptions;
-                if (anthropicOptions?.promptCache === true) {
+                if (anthropicOptions?.promptCache === true &&
+                    !agentContext.systemRunnable) {
                     finalMessages = addCacheControl(finalMessages);
                 }
             }
@@ -584,19 +569,25 @@ class StandardGraph extends Graph {
                     finalMessages = addBedrockCacheControl(finalMessages);
                 }
             }
-            /**
-             * Handle edge case: when switching from a non-thinking agent to a thinking-enabled agent,
-             * convert AI messages with tool calls to HumanMessages to avoid thinking block requirements.
-             * This is required by Anthropic/Bedrock when thinking is enabled.
-             */
-            const isAnthropicWithThinking = (agentContext.provider === Providers.ANTHROPIC &&
-                agentContext.clientOptions.thinking !=
-                    null) ||
-                (agentContext.provider === Providers.BEDROCK &&
-                    agentContext.clientOptions
-                        .additionalModelRequestFields?.['thinking'] != null);
-            if (isAnthropicWithThinking) {
-                finalMessages = ensureThinkingBlockInMessages(finalMessages, agentContext.provider);
+            if (isThinkingEnabled(agentContext.provider, agentContext.clientOptions)) {
+                finalMessages = ensureThinkingBlockInMessages(finalMessages, agentContext.provider, config);
+            }
+            // Intentionally broad: runs when the pruner wasn't used OR any post-pruning
+            // transform (addCacheControl, ensureThinkingBlock, etc.) reassigned finalMessages.
+            // sanitizeOrphanToolBlocks fast-paths to a Set diff check when no orphans exist,
+            // so the cost is negligible and this acts as a safety net for Anthropic/Bedrock.
+            const needsOrphanSanitize = anthropicLike &&
+                (!agentContext.pruneMessages || finalMessages !== messagesToUse);
+            if (needsOrphanSanitize) {
+                const beforeSanitize = finalMessages.length;
+                finalMessages = sanitizeOrphanToolBlocks(finalMessages);
+                if (finalMessages.length !== beforeSanitize) {
+                    emitAgentLog(config, 'warn', 'sanitize', 'Orphan tool blocks removed', {
+                        before: beforeSanitize,
+                        after: finalMessages.length,
+                        dropped: beforeSanitize - finalMessages.length,
+                    }, { runId: this.runId, agentId });
+                }
             }
             if (agentContext.lastStreamCall != null &&
                 agentContext.streamBuffer != null) {
@@ -608,52 +599,68 @@ class StandardGraph extends Graph {
                 }
             }
             agentContext.lastStreamCall = Date.now();
+            agentContext.markTokensStale();
             let result;
             const fallbacks = agentContext.clientOptions?.fallbacks ??
                 [];
-            if (finalMessages.length === 0) {
+            if (finalMessages.length === 0 &&
+                !agentContext.hasPendingCompactionSummary()) {
+                const budgetBreakdown = agentContext.getTokenBudgetBreakdown(messages);
+                const breakdown = agentContext.formatTokenBudgetBreakdown(messages);
+                const instructionsExceedBudget = budgetBreakdown.instructionTokens > budgetBreakdown.maxContextTokens;
+                let guidance;
+                if (instructionsExceedBudget) {
+                    const toolPct = budgetBreakdown.toolSchemaTokens > 0
+                        ? Math.round((budgetBreakdown.toolSchemaTokens /
+                            budgetBreakdown.instructionTokens) *
+                            100)
+                        : 0;
+                    guidance =
+                        toolPct > 50
+                            ? `Tool definitions consume ${budgetBreakdown.toolSchemaTokens} tokens (${toolPct}% of instructions) across ${budgetBreakdown.toolCount} tools, exceeding maxContextTokens (${budgetBreakdown.maxContextTokens}). Reduce the number of tools or increase maxContextTokens.`
+                            : `Instructions (${budgetBreakdown.instructionTokens} tokens) exceed maxContextTokens (${budgetBreakdown.maxContextTokens}). Increase maxContextTokens or shorten the system prompt.`;
+                    if (agentContext.summarizationEnabled === true) {
+                        guidance +=
+                            ' Summarization was skipped because the summary would further increase the instruction overhead.';
+                    }
+                }
+                else {
+                    guidance =
+                        'Please increase the context window size or make your message shorter.';
+                }
+                emitAgentLog(config, 'error', 'graph', 'Empty messages after pruning', {
+                    messageCount: messages.length,
+                    instructionsExceedBudget,
+                    breakdown,
+                }, { runId: this.runId, agentId });
                 throw new Error(JSON.stringify({
                     type: 'empty_messages',
-                    info: 'Message pruning removed all messages as none fit in the context window. Please increase the context window size or make your message shorter.',
+                    info: `Message pruning removed all messages as none fit in the context window. ${guidance}\n${breakdown}`,
                 }));
             }
+            const invokeStart = Date.now();
+            const invokeMeta = { runId: this.runId, agentId };
+            emitAgentLog(config, 'debug', 'graph', 'Invoking LLM', {
+                messageCount: finalMessages.length,
+                provider: agentContext.provider,
+            }, invokeMeta, { force: true });
             try {
-                result = await this.attemptInvoke({
-                    currentModel: model,
-                    finalMessages,
+                result = await attemptInvoke({
+                    model: (this.overrideModel ?? model),
+                    messages: finalMessages,
                     provider: agentContext.provider,
-                    tools: agentContext.tools,
+                    context: this,
                 }, config);
             }
             catch (primaryError) {
-                let lastError = primaryError;
-                for (const fb of fallbacks) {
-                    try {
-                        let model = this.getNewModel({
-                            provider: fb.provider,
-                            clientOptions: fb.clientOptions,
-                        });
-                        const bindableTools = agentContext.tools;
-                        model = (!bindableTools || bindableTools.length === 0
-                            ? model
-                            : model.bindTools(bindableTools));
-                        result = await this.attemptInvoke({
-                            currentModel: model,
-                            finalMessages,
-                            provider: fb.provider,
-                            tools: agentContext.tools,
-                        }, config);
-                        lastError = undefined;
-                        break;
-                    }
-                    catch (e) {
-                        lastError = e;
-                        continue;
-                    }
-                }
-                if (lastError !== undefined) {
-                    throw lastError;
-                }
+                result = await tryFallbackProviders({
+                    fallbacks,
+                    tools: agentContext.tools,
+                    messages: finalMessages,
+                    config,
+                    primaryError,
+                    context: this,
+                });
             }
             if (!result) {
                 throw new Error('No result after model invocation');
@@ -753,20 +760,42 @@ class StandardGraph extends Graph {
                     }
                 }
             }
+            const invokeElapsed = ((Date.now() - invokeStart) / 1000).toFixed(2);
             agentContext.currentUsage = this.getUsageMetadata(result.messages?.[0]);
+            if (agentContext.currentUsage) {
+                agentContext.updateLastCallUsage(agentContext.currentUsage);
+                emitAgentLog(config, 'debug', 'graph', `LLM call complete (${invokeElapsed}s)`, {
+                    ...agentContext.currentUsage,
+                    elapsedSeconds: Number(invokeElapsed),
+                    instructionTokens: agentContext.instructionTokens,
+                    toolSchemaTokens: agentContext.toolSchemaTokens,
+                    messageCount: finalMessages.length,
+                }, invokeMeta, { force: true });
+            }
+            else {
+                emitAgentLog(config, 'debug', 'graph', `LLM call complete (${invokeElapsed}s)`, {
+                    elapsedSeconds: Number(invokeElapsed),
+                    messageCount: finalMessages.length,
+                }, invokeMeta, { force: true });
+            }
             this.cleanupSignalListener();
             return result;
         };
     }
     createAgentNode(agentId) {
+        const getConfig = () => this.config;
         const agentContext = this.agentContexts.get(agentId);
         if (!agentContext) {
             throw new Error(`Agent context not found for agentId: ${agentId}`);
         }
         const agentNode = `${AGENT}${agentId}`;
         const toolNode = `${TOOLS}${agentId}`;
+        const summarizeNode = `${SUMMARIZE}${agentId}`;
         const routeMessage = (state, config) => {
             this.config = config;
+            if (state.summarizationRequest != null) {
+                return summarizeNode;
+            }
             return toolsCondition(state, toolNode, this.invokedToolIds);
         };
         const StateAnnotation = Annotation.Root({
@@ -774,6 +803,10 @@ class StandardGraph extends Graph {
                 reducer: messagesStateReducer,
                 default: () => [],
             }),
+            summarizationRequest: Annotation({
+                reducer: (_, b) => b,
+                default: () => undefined,
+            }),
         });
         const workflow = new StateGraph(StateAnnotation)
             .addNode(agentNode, this.createCallModel(agentId))
@@ -781,15 +814,54 @@ class StandardGraph extends Graph {
             currentTools: agentContext.tools,
             currentToolMap: agentContext.toolMap,
             agentContext,
+        }))
+            .addNode(summarizeNode, createSummarizeNode({
+            agentContext,
+            graph: {
+                contentData: this.contentData,
+                contentIndexMap: this.contentIndexMap,
+                get config() {
+                    return getConfig();
+                },
+                runId: this.runId,
+                isMultiAgent: this.isMultiAgentGraph(),
+                dispatchRunStep: async (runStep, nodeConfig) => {
+                    this.contentData.push(runStep);
+                    this.contentIndexMap.set(runStep.id, runStep.index);
+                    const resolvedConfig = nodeConfig ?? this.config;
+                    const handler = this.handlerRegistry?.getHandler(GraphEvents.ON_RUN_STEP);
+                    if (handler) {
+                        await handler.handle(GraphEvents.ON_RUN_STEP, runStep, resolvedConfig?.configurable, this);
+                        this.handlerDispatchedStepIds.add(runStep.id);
+                    }
+                    if (resolvedConfig) {
+                        await safeDispatchCustomEvent(GraphEvents.ON_RUN_STEP, runStep, resolvedConfig);
+                    }
+                },
+                dispatchRunStepCompleted: async (stepId, result, nodeConfig) => {
+                    const resolvedConfig = nodeConfig ?? this.config;
+                    const runStep = this.contentData.find((s) => s.id === stepId);
+                    const handler = this.handlerRegistry?.getHandler(GraphEvents.ON_RUN_STEP_COMPLETED);
+                    if (handler) {
+                        await handler.handle(GraphEvents.ON_RUN_STEP_COMPLETED, {
+                            result: {
+                                ...result,
+                                id: stepId,
+                                index: runStep?.index ?? 0,
+                            },
+                        }, resolvedConfig?.configurable, this);
+                    }
+                },
+            },
+            generateStepId: (stepKey) => this.generateStepId(stepKey),
         }))
             .addEdge(START, agentNode)
             .addConditionalEdges(agentNode, routeMessage)
+            .addEdge(summarizeNode, agentNode)
             .addEdge(toolNode, agentContext.toolEnd ? END : agentNode);
-        // Cast to unknown to avoid tight coupling to external types; options are opt-in
-        return workflow.compile(this.compileOptions);
+        return workflow.compile();
     }
     createWorkflow() {
-        /** Use the default (first) agent for now */
         const agentNode = this.createAgentNode(this.defaultAgentId);
         const StateAnnotation = Annotation.Root({
             messages: Annotation({
@@ -807,7 +879,8 @@ class StandardGraph extends Graph {
         const workflow = new StateGraph(StateAnnotation)
             .addNode(this.defaultAgentId, agentNode, { ends: [END] })
             .addEdge(START, this.defaultAgentId)
-            .compile();
+            // LangGraph compile() types are overly strict for opt-in options
+            .compile(this.compileOptions);
         return workflow;
     }
     /**
@@ -858,18 +931,11 @@ class StandardGraph extends Graph {
         if (runId) {
             runStep.runId = runId;
         }
-        /**
-         * Extract agentId and parallelGroupId from metadata
-         * Only set agentId for MultiAgentGraph (so frontend knows when to show agent labels)
-         */
         if (metadata) {
             try {
                 const agentContext = this.getAgentContext(metadata);
                 if (this.isMultiAgentGraph() && agentContext.agentId) {
-                    // Only include agentId for MultiAgentGraph - enables frontend to show agent labels
                     runStep.agentId = agentContext.agentId;
-                    // Set group ID if this agent is part of a parallel group
-                    // Group IDs are incrementing numbers (1, 2, 3...) reflecting execution order
                     const groupId = this.getParallelGroupIdForAgent(agentContext.agentId);
                     if (groupId != null) {
                         runStep.groupId = groupId;
@@ -882,6 +948,21 @@ class StandardGraph extends Graph {
         }
         this.contentData.push(runStep);
         this.contentIndexMap.set(stepId, runStep.index);
+        // Primary dispatch: handler registry (reliable, always works).
+        // This mirrors how handleToolCallCompleted dispatches ON_RUN_STEP_COMPLETED
+        // via the handler registry, ensuring the event always reaches the handler
+        // even when LangGraph's callback system drops the custom event.
+        const handler = this.handlerRegistry?.getHandler(GraphEvents.ON_RUN_STEP);
+        if (handler) {
+            await handler.handle(GraphEvents.ON_RUN_STEP, runStep, metadata, this);
+            this.handlerDispatchedStepIds.add(stepId);
+        }
+        // Secondary dispatch: custom event for LangGraph callback chain
+        // (tracing, Langfuse, external consumers).  May be silently dropped
+        // in some scenarios (stale run ID, subgraph callback propagation issues),
+        // but the primary dispatch above guarantees the event reaches the handler.
+        // The customEventCallback in run.ts skips events already dispatched above
+        // to prevent double handling.
         await safeDispatchCustomEvent(GraphEvents.ON_RUN_STEP, runStep, this.config);
         return stepId;
     }