@librechat/agents 3.1.56 → 3.1.60

package/dist/cjs/graphs/Graph.cjs

@@ -1,11 +1,8 @@
 'use strict';
 
 var nanoid = require('nanoid');
-var stream$1 = require('@langchain/core/utils/stream');
-var googleVertexai = require('@langchain/google-vertexai');
-var langgraph = require('@langchain/langgraph');
-var runnables = require('@langchain/core/runnables');
 var messages = require('@langchain/core/messages');
+var langgraph = require('@langchain/langgraph');
 var core = require('../messages/core.cjs');
 var ids = require('../messages/ids.cjs');
 var prune = require('../messages/prune.cjs');
@@ -13,25 +10,29 @@ var format = require('../messages/format.cjs');
 var cache = require('../messages/cache.cjs');
 var content = require('../messages/content.cjs');
 var tools = require('../messages/tools.cjs');
+var reducer = require('../messages/reducer.cjs');
 var _enum = require('../common/enum.cjs');
 var graph = require('../utils/graph.cjs');
 var llm = require('../utils/llm.cjs');
-var stream = require('../stream.cjs');
 var handlers = require('../tools/handlers.cjs');
 var run = require('../utils/run.cjs');
 require('ai-tokenizer');
 require('zod-to-json-schema');
-var providers = require('../llm/providers.cjs');
 var ToolNode = require('../tools/ToolNode.cjs');
-var index = require('../llm/openai/index.cjs');
 var events = require('../utils/events.cjs');
+var invoke = require('../llm/invoke.cjs');
+var index = require('../summarization/index.cjs');
+var node = require('../summarization/node.cjs');
 var schema = require('../tools/schema.cjs');
 var AgentContext = require('../agents/AgentContext.cjs');
 var fake = require('../llm/fake.cjs');
+var request = require('../llm/request.cjs');
+var init = require('../llm/init.cjs');
 
 /* eslint-disable no-console */
-// src/graphs/Graph.ts
-const { AGENT, TOOLS } = _enum.GraphNodeKeys;
+const { AGENT, TOOLS, SUMMARIZE } = _enum.GraphNodeKeys;
+/** Minimum relative variance before calibrated toolSchemaTokens overrides current value. */
+const CALIBRATION_VARIANCE_THRESHOLD = 0.15;
 class Graph {
     messageStepHasToolCalls = new Map();
     messageIdsByStepKey = new Map();
@@ -41,6 +42,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;
@@ -76,16 +83,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;
@@ -94,6 +108,9 @@ class StandardGraph extends Graph {
         }
         for (const agentConfig of agents) {
             const agentContext = 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;
@@ -101,6 +118,7 @@ class StandardGraph extends Graph {
     /* Init */
     resetValues(keepContent) {
         this.messages = [];
+        this.cachedRunMessages = undefined;
         this.config = graph.resetIfNotEmpty(this.config, undefined);
         if (keepContent !== true) {
             this.contentData = graph.resetIfNotEmpty(this.contentData, []);
@@ -114,6 +132,7 @@ class StandardGraph extends Graph {
          * a stale reference on 2nd+ processStream calls.
          */
         this.toolCallStepIds.clear();
+        this.handlerDispatchedStepIds = graph.resetIfNotEmpty(this.handlerDispatchedStepIds, new Set());
         this.messageIdsByStepKey = graph.resetIfNotEmpty(this.messageIdsByStepKey, new Map());
         this.messageStepHasToolCalls = graph.resetIfNotEmpty(this.messageStepHasToolCalls, new Map());
         this.prelimMessageIdsByStepKey = graph.resetIfNotEmpty(this.prelimMessageIdsByStepKey, new Map());
@@ -123,6 +142,7 @@ class StandardGraph extends Graph {
         }
     }
     clearHeavyState() {
+        this.cachedRunMessages = this.messages.slice(this.startIndex);
         super.clearHeavyState();
         this.messages = [];
         this.overrideModel = undefined;
@@ -153,6 +173,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}`);
@@ -222,11 +245,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 core.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
      */
@@ -278,35 +316,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 === _enum.Providers.ANTHROPIC &&
-            clientOptions.promptCache === true) {
-            finalInstructions = {
-                content: [
-                    {
-                        type: 'text',
-                        text: instructions,
-                        cache_control: { type: 'ephemeral' },
-                    },
-                ],
-            };
-        }
-        if (finalInstructions != null && finalInstructions !== '') {
-            const systemMessage = new messages.SystemMessage(finalInstructions);
-            return runnables.RunnableLambda.from((messages) => {
-                return [systemMessage, ...messages];
-            }).withConfig({ runName: 'prompt' });
-        }
-    }
     initializeTools({ currentTools, currentToolMap, agentContext, }) {
         const toolDefinitions = agentContext?.toolDefinitions;
         const eventDrivenMode = toolDefinitions != null && toolDefinitions.length > 0;
@@ -336,6 +345,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),
             });
         }
@@ -359,42 +370,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 = providers.getChatModelClass(provider);
-        const model = new ChatModelClass(clientOptions ?? {});
-        if (llm.isOpenAILike(provider) &&
-            (model instanceof index.ChatOpenAI || model instanceof index.AzureChatOpenAI)) {
-            model.temperature = clientOptions
-                .temperature;
-            model.topP = clientOptions.topP;
-            model.frequencyPenalty = clientOptions
-                .frequencyPenalty;
-            model.presencePenalty = clientOptions
-                .presencePenalty;
-            model.n = clientOptions.n;
-        }
-        else if (provider === _enum.Providers.VERTEXAI &&
-            model instanceof googleVertexai.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 = fake.createFakeStreamingLLM({
             responses,
@@ -402,10 +381,6 @@ class StandardGraph extends Graph {
             toolCalls,
         });
     }
-    getNewModel({ provider, clientOptions, }) {
-        const ChatModelClass = providers.getChatModelClass(provider);
-        return new ChatModelClass(clientOptions ?? {});
-    }
     getUsageMetadata(finalMessage) {
         if (finalMessage &&
             'usage_metadata' in finalMessage &&
@@ -413,58 +388,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 stream.ChatModelStreamHandler();
-            const stream$2 = await model.stream(finalMessages, config);
-            let finalChunk;
-            for await (const chunk of stream$2) {
-                await streamHandler.handle(_enum.GraphEvents.CHAT_MODEL_STREAM, { chunk }, metadata, this);
-                finalChunk = finalChunk ? stream$1.concat(finalChunk, chunk) : chunk;
-            }
-            if (providers.manualToolStreamProviders.has(provider)) {
-                finalChunk = core.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;
@@ -482,9 +405,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}`);
@@ -493,14 +413,13 @@ class StandardGraph extends Graph {
                 throw new Error('No config provided');
             }
             const { messages: messages$1 } = state;
-            // Extract tool discoveries from current turn only (similar to formatArtifactPayload pattern)
             const discoveredNames = tools.extractToolDiscoveries(messages$1);
             if (discoveredNames.length > 0) {
                 agentContext.markToolsAsDiscovered(discoveredNames);
             }
             const toolsForBinding = agentContext.getToolsForBinding();
             let model = this.overrideModel ??
-                this.initializeModel({
+                init.initializeModel({
                     tools: toolsForBinding,
                     provider: agentContext.provider,
                     clientOptions: agentContext.clientOptions,
@@ -518,34 +437,97 @@ class StandardGraph extends Graph {
             let messagesToUse = messages$1;
             if (!agentContext.pruneMessages &&
                 agentContext.tokenCounter &&
-                agentContext.maxContextTokens != null &&
-                agentContext.indexTokenCountMap[0] != null) {
-                const isAnthropicWithThinking = (agentContext.provider === _enum.Providers.ANTHROPIC &&
-                    agentContext.clientOptions.thinking !=
-                        null) ||
-                    (agentContext.provider === _enum.Providers.BEDROCK &&
-                        agentContext.clientOptions
-                            .additionalModelRequestFields?.['thinking'] != null) ||
-                    (agentContext.provider === _enum.Providers.OPENAI &&
-                        agentContext.clientOptions.modelKwargs
-                            ?.thinking?.type === 'enabled');
+                agentContext.maxContextTokens != null) {
                 agentContext.pruneMessages = prune.createPruneMessages({
-                    startIndex: this.startIndex,
+                    startIndex: agentContext.indexTokenCountMap[0] != null ? this.startIndex : 0,
                     provider: agentContext.provider,
                     tokenCounter: agentContext.tokenCounter,
                     maxTokens: agentContext.maxContextTokens,
-                    thinkingEnabled: isAnthropicWithThinking,
+                    thinkingEnabled: request.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) => {
+                        events.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: messages$1,
                     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$1.length);
+                    const triggerResult = !shouldSkip &&
+                        index.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;
+                        }
+                        events.emitAgentLog(config, 'info', 'graph', 'Summarization triggered', undefined, { runId: this.runId, agentId });
+                        events.emitAgentLog(config, 'debug', 'graph', 'Summarization trigger details', {
+                            totalMessages: messages$1.length,
+                            remainingContextTokens: remainingContextTokens ?? 0,
+                            summaryVersion: agentContext.summaryVersion + 1,
+                            toolSchemaTokens: agentContext.toolSchemaTokens,
+                            instructionTokens: agentContext.instructionTokens,
+                            systemMessageTokens: agentContext.systemMessageTokens,
+                        }, { runId: this.runId, agentId });
+                        agentContext.markSummarizationTriggered(messages$1.length);
+                        return {
+                            summarizationRequest: {
+                                remainingContextTokens: remainingContextTokens ?? 0,
+                                agentId: agentId || agentContext.agentId,
+                            },
+                        };
+                    }
+                    if (shouldSkip) {
+                        events.emitAgentLog(config, 'debug', 'graph', 'Summarization skipped — no new messages or per-run cap reached', {
+                            messageCount: messages$1.length,
+                            messagesToRefineCount: messagesToRefine.length,
+                            contextLength: context.length,
+                        }, { runId: this.runId, agentId });
+                    }
+                }
             }
             let finalMessages = messagesToUse;
             if (agentContext.useLegacyContent) {
@@ -557,26 +539,29 @@ class StandardGraph extends Graph {
             const lastMessageY = finalMessages.length >= 1
                 ? finalMessages[finalMessages.length - 1]
                 : null;
+            const anthropicLike = llm.isAnthropicLike(agentContext.provider, agentContext.clientOptions);
             if (agentContext.provider === _enum.Providers.BEDROCK &&
                 lastMessageX instanceof messages.AIMessageChunk &&
                 lastMessageY instanceof messages.ToolMessage &&
                 typeof lastMessageX.content === 'string') {
-                finalMessages[finalMessages.length - 2].content = '';
+                const trimmed = lastMessageX.content.trim();
+                finalMessages[finalMessages.length - 2].content =
+                    trimmed.length > 0 ? [{ type: 'text', text: trimmed }] : '';
             }
-            const isLatestToolMessage = lastMessageY instanceof messages.ToolMessage;
-            if (isLatestToolMessage &&
-                agentContext.provider === _enum.Providers.ANTHROPIC) {
-                core.formatAnthropicArtifactContent(finalMessages);
-            }
-            else if (isLatestToolMessage &&
-                ((llm.isOpenAILike(agentContext.provider) &&
+            if (lastMessageY instanceof messages.ToolMessage) {
+                if (anthropicLike) {
+                    core.formatAnthropicArtifactContent(finalMessages);
+                }
+                else if ((llm.isOpenAILike(agentContext.provider) &&
                     agentContext.provider !== _enum.Providers.DEEPSEEK) ||
-                    llm.isGoogleLike(agentContext.provider))) {
-                core.formatArtifactPayload(finalMessages);
+                    llm.isGoogleLike(agentContext.provider)) {
+                    core.formatArtifactPayload(finalMessages);
+                }
             }
             if (agentContext.provider === _enum.Providers.ANTHROPIC) {
                 const anthropicOptions = agentContext.clientOptions;
-                if (anthropicOptions?.promptCache === true) {
+                if (anthropicOptions?.promptCache === true &&
+                    !agentContext.systemRunnable) {
                     finalMessages = cache.addCacheControl(finalMessages);
                 }
             }
@@ -586,19 +571,25 @@ class StandardGraph extends Graph {
                     finalMessages = cache.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 === _enum.Providers.ANTHROPIC &&
-                agentContext.clientOptions.thinking !=
-                    null) ||
-                (agentContext.provider === _enum.Providers.BEDROCK &&
-                    agentContext.clientOptions
-                        .additionalModelRequestFields?.['thinking'] != null);
-            if (isAnthropicWithThinking) {
-                finalMessages = format.ensureThinkingBlockInMessages(finalMessages, agentContext.provider);
+            if (request.isThinkingEnabled(agentContext.provider, agentContext.clientOptions)) {
+                finalMessages = format.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 = prune.sanitizeOrphanToolBlocks(finalMessages);
+                if (finalMessages.length !== beforeSanitize) {
+                    events.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) {
@@ -610,52 +601,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$1);
+                const breakdown = agentContext.formatTokenBudgetBreakdown(messages$1);
+                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.';
+                }
+                events.emitAgentLog(config, 'error', 'graph', 'Empty messages after pruning', {
+                    messageCount: messages$1.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 };
+            events.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 invoke.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 invoke.tryFallbackProviders({
+                    fallbacks,
+                    tools: agentContext.tools,
+                    messages: finalMessages,
+                    config,
+                    primaryError,
+                    context: this,
+                });
             }
             if (!result) {
                 throw new Error('No result after model invocation');
@@ -755,27 +762,53 @@ 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);
+                events.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 {
+                events.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 ToolNode.toolsCondition(state, toolNode, this.invokedToolIds);
         };
         const StateAnnotation = langgraph.Annotation.Root({
             messages: langgraph.Annotation({
-                reducer: langgraph.messagesStateReducer,
+                reducer: reducer.messagesStateReducer,
                 default: () => [],
             }),
+            summarizationRequest: langgraph.Annotation({
+                reducer: (_, b) => b,
+                default: () => undefined,
+            }),
         });
         const workflow = new langgraph.StateGraph(StateAnnotation)
             .addNode(agentNode, this.createCallModel(agentId))
@@ -783,15 +816,54 @@ class StandardGraph extends Graph {
             currentTools: agentContext.tools,
             currentToolMap: agentContext.toolMap,
             agentContext,
+        }))
+            .addNode(summarizeNode, node.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(_enum.GraphEvents.ON_RUN_STEP);
+                    if (handler) {
+                        await handler.handle(_enum.GraphEvents.ON_RUN_STEP, runStep, resolvedConfig?.configurable, this);
+                        this.handlerDispatchedStepIds.add(runStep.id);
+                    }
+                    if (resolvedConfig) {
+                        await events.safeDispatchCustomEvent(_enum.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(_enum.GraphEvents.ON_RUN_STEP_COMPLETED);
+                    if (handler) {
+                        await handler.handle(_enum.GraphEvents.ON_RUN_STEP_COMPLETED, {
+                            result: {
+                                ...result,
+                                id: stepId,
+                                index: runStep?.index ?? 0,
+                            },
+                        }, resolvedConfig?.configurable, this);
+                    }
+                },
+            },
+            generateStepId: (stepKey) => this.generateStepId(stepKey),
         }))
             .addEdge(langgraph.START, agentNode)
             .addConditionalEdges(agentNode, routeMessage)
+            .addEdge(summarizeNode, agentNode)
             .addEdge(toolNode, agentContext.toolEnd ? langgraph.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 = langgraph.Annotation.Root({
             messages: langgraph.Annotation({
@@ -799,7 +871,7 @@ class StandardGraph extends Graph {
                     if (!a.length) {
                         this.startIndex = a.length + b.length;
                     }
-                    const result = langgraph.messagesStateReducer(a, b);
+                    const result = reducer.messagesStateReducer(a, b);
                     this.messages = result;
                     return result;
                 },
@@ -809,7 +881,8 @@ class StandardGraph extends Graph {
         const workflow = new langgraph.StateGraph(StateAnnotation)
             .addNode(this.defaultAgentId, agentNode, { ends: [langgraph.END] })
             .addEdge(langgraph.START, this.defaultAgentId)
-            .compile();
+            // LangGraph compile() types are overly strict for opt-in options
+            .compile(this.compileOptions);
         return workflow;
     }
     /**
@@ -860,18 +933,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;
@@ -884,6 +950,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(_enum.GraphEvents.ON_RUN_STEP);
+        if (handler) {
+            await handler.handle(_enum.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 events.safeDispatchCustomEvent(_enum.GraphEvents.ON_RUN_STEP, runStep, this.config);
         return stepId;
     }