@librechat/agents 3.1.57 → 3.1.61

package/dist/esm/agents/AgentContext.mjs

@@ -1,11 +1,29 @@
-import { SystemMessage } from '@langchain/core/messages';
+import { SystemMessage, HumanMessage } from '@langchain/core/messages';
 import { RunnableLambda } from '@langchain/core/runnables';
 import { createSchemaOnlyTools } from '../tools/schema.mjs';
+import { addCacheControl } from '../messages/cache.mjs';
 import { ContentTypes, Providers } from '../common/enum.mjs';
+import '../messages/core.mjs';
+import 'nanoid';
+import { DEFAULT_RESERVE_RATIO } from '../messages/prune.mjs';
+import '@langchain/core/callbacks/dispatch';
+import 'uuid';
 import { toJsonSchema } from '../utils/schema.mjs';
 
 /* eslint-disable no-console */
-// src/agents/AgentContext.ts
+/**
+ * Anthropic direct API tool schema overhead multiplier.
+ * Empirically calibrated against real MCP tool sets (29 tools).
+ * Accounts for Anthropic's internal XML-like tool encoding plus
+ * a ~300-token hidden tool-system preamble.
+ */
+const ANTHROPIC_TOOL_TOKEN_MULTIPLIER = 2.6;
+/**
+ * Default tool schema overhead multiplier for all non-Anthropic providers.
+ * Covers OpenAI function-calling format, Bedrock, and other providers.
+ * Empirically calibrated at ~1.4× the raw JSON token count.
+ */
+const DEFAULT_TOOL_TOKEN_MULTIPLIER = 1.4;
 /**
  * Encapsulates agent-specific state that can vary between agents in a multi-agent system
  */
@@ -14,7 +32,7 @@ class AgentContext {
      * Create an AgentContext from configuration with token accounting initialization
      */
     static fromConfig(agentConfig, tokenCounter, indexTokenCountMap) {
-        const { agentId, name, provider, clientOptions, tools, toolMap, toolEnd, toolRegistry, toolDefinitions, instructions, additional_instructions, streamBuffer, maxContextTokens, reasoningKey, useLegacyContent, discoveredTools, } = agentConfig;
+        const { agentId, name, provider, clientOptions, tools, toolMap, toolEnd, toolRegistry, toolDefinitions, instructions, additional_instructions, streamBuffer, maxContextTokens, reasoningKey, useLegacyContent, discoveredTools, summarizationEnabled, summarizationConfig, initialSummary, contextPruningConfig, maxToolResultChars, } = agentConfig;
         const agentContext = new AgentContext({
             agentId,
             name: name ?? agentId,
@@ -34,11 +52,15 @@ class AgentContext {
             tokenCounter,
             useLegacyContent,
             discoveredTools,
+            summarizationEnabled,
+            summarizationConfig,
+            contextPruningConfig,
+            maxToolResultChars,
         });
+        if (initialSummary?.text != null && initialSummary.text !== '') {
+            agentContext.setInitialSummary(initialSummary.text, initialSummary.tokenCount);
+        }
         if (tokenCounter) {
-            // Initialize system runnable BEFORE async tool token calculation
-            // This ensures system message tokens are in instructionTokens before
-            // updateTokenMapWithInstructions is called
             agentContext.initializeSystemRunnable();
             const tokenMap = indexTokenCountMap || {};
             agentContext.baseIndexTokenCountMap = { ...tokenMap };
@@ -46,7 +68,6 @@ class AgentContext {
             agentContext.tokenCalculationPromise = agentContext
                 .calculateInstructionTokens(tokenCounter)
                 .then(() => {
-                // Update token map with instruction tokens (includes system + tool tokens)
                 agentContext.updateTokenMapWithInstructions(tokenMap);
             })
                 .catch((err) => {
@@ -75,12 +96,39 @@ class AgentContext {
     maxContextTokens;
     /** Current usage metadata for this agent */
     currentUsage;
+    /**
+     * Usage from the most recent LLM call only (not accumulated).
+     * Used for accurate provider calibration in pruning.
+     */
+    lastCallUsage;
+    /**
+     * Whether totalTokens data is fresh (set true when provider usage arrives,
+     * false at the start of each turn before the LLM responds).
+     * Prevents stale token data from driving pruning/trigger decisions.
+     */
+    totalTokensFresh = false;
+    /** Context pruning configuration. */
+    contextPruningConfig;
+    maxToolResultChars;
     /** Prune messages function configured for this agent */
     pruneMessages;
     /** Token counter function for this agent */
     tokenCounter;
-    /** Instructions/system message token count */
-    instructionTokens = 0;
+    /** Token count for the system message (instructions text). */
+    systemMessageTokens = 0;
+    /** Token count for tool schemas only. */
+    toolSchemaTokens = 0;
+    /** Running calibration ratio from the pruner — persisted across runs via contextMeta. */
+    calibrationRatio = 1;
+    /** Provider-observed instruction overhead from the pruner's best-variance turn. */
+    resolvedInstructionOverhead;
+    /** Pre-masking tool content keyed by message index, consumed by the summarize node. */
+    pendingOriginalToolContent;
+    /** Total instruction overhead: system message + tool schemas + pending summary. */
+    get instructionTokens() {
+        const summaryOverhead = this._summaryLocation === 'user_message' ? this.summaryTokenCount : 0;
+        return this.systemMessageTokens + this.toolSchemaTokens + summaryOverhead;
+    }
     /** The amount of time that should pass before another consecutive API call */
     streamBuffer;
     /** Last stream call timestamp for rate limiting */
@@ -123,18 +171,47 @@ class AgentContext {
     cachedSystemRunnable;
     /** Whether system runnable needs rebuild (set when discovered tools change) */
     systemRunnableStale = true;
-    /** Cached system message token count (separate from tool tokens) */
-    systemMessageTokens = 0;
     /** Promise for token calculation initialization */
     tokenCalculationPromise;
     /** Format content blocks as strings (for legacy compatibility) */
     useLegacyContent = false;
+    /** Enables graph-level summarization for this agent */
+    summarizationEnabled;
+    /** Summarization runtime settings used by graph pruning hooks */
+    summarizationConfig;
+    /** Current summary text produced by the summarize node, integrated into system message */
+    summaryText;
+    /** Token count of the current summary (tracked for token accounting) */
+    summaryTokenCount = 0;
+    /**
+     * Where the summary should be injected:
+     * - `'system_prompt'`: cross-run summary, included in `buildInstructionsString`
+     * - `'user_message'`: mid-run compaction, injected as HumanMessage on clean slate
+     * - `'none'`: no summary present
+     */
+    _summaryLocation = 'none';
+    /**
+     * Durable summary that survives reset() calls. Set from initialSummary
+     * during fromConfig() and updated by setSummary() so that the latest
+     * summary (whether cross-run or intra-run) is always restored after
+     * processStream's resetValues() cycle.
+     */
+    _durableSummaryText;
+    _durableSummaryTokenCount = 0;
+    /** Number of summarization cycles that have occurred for this agent context */
+    _summaryVersion = 0;
+    /**
+     * Message count at the time summarization was last triggered.
+     * Used to prevent re-summarizing the same unchanged message set.
+     * Summarization is allowed to fire again only when new messages appear.
+     */
+    _lastSummarizationMsgCount = 0;
     /**
      * Handoff context when this agent receives control via handoff.
      * Contains source and parallel execution info for system message context.
      */
     handoffContext;
-    constructor({ agentId, name, provider, clientOptions, maxContextTokens, streamBuffer, tokenCounter, tools, toolMap, toolRegistry, toolDefinitions, instructions, additionalInstructions, reasoningKey, toolEnd, instructionTokens, useLegacyContent, discoveredTools, }) {
+    constructor({ agentId, name, provider, clientOptions, maxContextTokens, streamBuffer, tokenCounter, tools, toolMap, toolRegistry, toolDefinitions, instructions, additionalInstructions, reasoningKey, toolEnd, instructionTokens, useLegacyContent, discoveredTools, summarizationEnabled, summarizationConfig, contextPruningConfig, maxToolResultChars, }) {
         this.agentId = agentId;
         this.name = name;
         this.provider = provider;
@@ -155,9 +232,13 @@ class AgentContext {
             this.toolEnd = toolEnd;
         }
         if (instructionTokens !== undefined) {
-            this.instructionTokens = instructionTokens;
+            this.systemMessageTokens = instructionTokens;
         }
         this.useLegacyContent = useLegacyContent ?? false;
+        this.summarizationEnabled = summarizationEnabled;
+        this.summarizationConfig = summarizationConfig;
+        this.contextPruningConfig = contextPruningConfig;
+        this.maxToolResultChars = maxToolResultChars;
         if (discoveredTools && discoveredTools.length > 0) {
             for (const toolName of discoveredTools) {
                 this.discoveredToolNames.add(toolName);
@@ -183,7 +264,6 @@ class AgentContext {
                 !allowedCallers.includes('direct');
             if (!isCodeExecutionOnly)
                 continue;
-            // Include if: not deferred OR deferred but discovered
             const isDeferred = toolDef.defer_loading === true;
             const isDiscovered = this.discoveredToolNames.has(name);
             if (!isDeferred || isDiscovered) {
@@ -215,11 +295,9 @@ class AgentContext {
      * Only rebuilds when marked stale (via markToolsAsDiscovered).
      */
     get systemRunnable() {
-        // Return cached if not stale
         if (!this.systemRunnableStale && this.cachedSystemRunnable !== undefined) {
             return this.cachedSystemRunnable;
         }
-        // Stale or first access - rebuild
         const instructionsString = this.buildInstructionsString();
         this.cachedSystemRunnable = this.buildSystemRunnable(instructionsString);
         this.systemRunnableStale = false;
@@ -242,25 +320,29 @@ class AgentContext {
      */
     buildInstructionsString() {
         const parts = [];
-        /** Build agent identity and handoff context preamble */
         const identityPreamble = this.buildIdentityPreamble();
         if (identityPreamble) {
             parts.push(identityPreamble);
         }
-        /** Add main instructions */
         if (this.instructions != null && this.instructions !== '') {
             parts.push(this.instructions);
         }
-        /** Add additional instructions */
         if (this.additionalInstructions != null &&
             this.additionalInstructions !== '') {
             parts.push(this.additionalInstructions);
         }
-        /** Add programmatic tools documentation */
         const programmaticToolsDoc = this.buildProgrammaticOnlyToolsInstructions();
         if (programmaticToolsDoc) {
             parts.push(programmaticToolsDoc);
         }
+        // Cross-run summary: include in system prompt so the model has context
+        // from the prior run.  Mid-run summaries are injected as a HumanMessage
+        // on the post-compaction clean slate instead (see buildSystemRunnable).
+        if (this._summaryLocation === 'system_prompt' &&
+            this.summaryText != null &&
+            this.summaryText !== '') {
+            parts.push('## Conversation Summary\n\n' + this.summaryText);
+        }
         return parts.join('\n\n');
     }
     /**
@@ -287,17 +369,19 @@ class AgentContext {
      * Only called when content has actually changed.
      */
     buildSystemRunnable(instructionsString) {
-        if (!instructionsString) {
-            // Remove previous tokens if we had a system message before
-            this.instructionTokens -= this.systemMessageTokens;
+        const hasMidRunSummary = this._summaryLocation === 'user_message' &&
+            this.summaryText != null &&
+            this.summaryText !== '';
+        if (!instructionsString && !hasMidRunSummary) {
             this.systemMessageTokens = 0;
             return undefined;
         }
         let finalInstructions = instructionsString;
-        // Handle Anthropic prompt caching
+        let usePromptCache = false;
         if (this.provider === Providers.ANTHROPIC) {
             const anthropicOptions = this.clientOptions;
             if (anthropicOptions?.promptCache === true) {
+                usePromptCache = true;
                 finalInstructions = {
                     content: [
                         {
@@ -309,23 +393,56 @@ class AgentContext {
                 };
             }
         }
-        const systemMessage = new SystemMessage(finalInstructions);
-        // Update token counts (subtract old, add new)
+        const systemMessage = instructionsString
+            ? new SystemMessage(finalInstructions)
+            : undefined;
         if (this.tokenCounter) {
-            this.instructionTokens -= this.systemMessageTokens;
-            this.systemMessageTokens = this.tokenCounter(systemMessage);
-            this.instructionTokens += this.systemMessageTokens;
+            this.systemMessageTokens = systemMessage
+                ? this.tokenCounter(systemMessage)
+                : 0;
         }
         return RunnableLambda.from((messages) => {
-            return [systemMessage, ...messages];
+            const prefix = systemMessage ? [systemMessage] : [];
+            // Build the non-system portion (summary + conversation), then apply
+            // cache markers separately so addCacheControl doesn't strip the
+            // SystemMessage's own cache_control breakpoint set above.
+            const hasSummaryBody = this._summaryLocation === 'user_message' &&
+                this.summaryText != null &&
+                this.summaryText !== '';
+            let body;
+            if (hasSummaryBody) {
+                const wrappedSummary = '<summary>\n' +
+                    this.summaryText +
+                    '\n</summary>\n\n' +
+                    'This is your own checkpoint: you wrote it to preserve context after compaction. Pick up where you left off based on the summary above. Do not repeat prior tasks, information or acknowledge this checkpoint message directly.';
+                const summaryMsg = usePromptCache
+                    ? new HumanMessage({
+                        content: [
+                            {
+                                type: 'text',
+                                text: wrappedSummary,
+                                cache_control: { type: 'ephemeral' },
+                            },
+                        ],
+                    })
+                    : new HumanMessage(wrappedSummary);
+                body = [summaryMsg, ...messages];
+            }
+            else {
+                body = messages;
+            }
+            if (usePromptCache && body.length >= 2) {
+                body = addCacheControl(body);
+            }
+            return [...prefix, ...body];
         }).withConfig({ runName: 'prompt' });
     }
     /**
      * Reset context for a new run
      */
     reset() {
-        this.instructionTokens = 0;
         this.systemMessageTokens = 0;
+        this.toolSchemaTokens = 0;
         this.cachedSystemRunnable = undefined;
         this.systemRunnableStale = true;
         this.lastToken = undefined;
@@ -338,6 +455,11 @@ class AgentContext {
         this.currentTokenType = ContentTypes.TEXT;
         this.discoveredToolNames.clear();
         this.handoffContext = undefined;
+        this.summaryText = this._durableSummaryText;
+        this.summaryTokenCount = this._durableSummaryTokenCount;
+        this._lastSummarizationMsgCount = 0;
+        this.lastCallUsage = undefined;
+        this.totalTokensFresh = false;
         if (this.tokenCounter) {
             this.initializeSystemRunnable();
             const baseTokenMap = { ...this.baseIndexTokenCountMap };
@@ -355,24 +477,21 @@ class AgentContext {
         }
     }
     /**
-     * Update the token count map with instruction tokens
+     * Update the token count map from a base map.
+     *
+     * Previously this inflated index 0 with instructionTokens to indirectly
+     * reserve budget for the system prompt.  That approach was imprecise: with
+     * large tool-schema overhead (e.g. 26 MCP tools ~5 000 tokens) the first
+     * conversation message appeared enormous and was always pruned, while the
+     * real available budget was never explicitly computed.
+     *
+     * Now instruction tokens are passed to getMessagesWithinTokenLimit via
+     * the `getInstructionTokens` factory param so the pruner subtracts them
+     * from the budget directly.  The token map contains only real per-message
+     * token counts.
      */
     updateTokenMapWithInstructions(baseTokenMap) {
-        if (this.instructionTokens > 0) {
-            // Shift all indices by the instruction token count
-            const shiftedMap = {};
-            for (const [key, value] of Object.entries(baseTokenMap)) {
-                const index = parseInt(key, 10);
-                if (!isNaN(index)) {
-                    shiftedMap[String(index)] =
-                        value + (index === 0 ? this.instructionTokens : 0);
-                }
-            }
-            this.indexTokenCountMap = shiftedMap;
-        }
-        else {
-            this.indexTokenCountMap = { ...baseTokenMap };
-        }
+        this.indexTokenCountMap = { ...baseTokenMap };
     }
     /**
      * Calculate tool tokens and add to instruction tokens
@@ -380,11 +499,7 @@ class AgentContext {
      */
     async calculateInstructionTokens(tokenCounter) {
         let toolTokens = 0;
-        // Track names to avoid double-counting when a tool appears in both
-        // this.tools (bound StructuredTool instances) and this.toolDefinitions
-        // (MCP / event-driven schemas).
         const countedToolNames = new Set();
-        // Count tokens for bound tools (StructuredTool instances with .schema)
         if (this.tools && this.tools.length > 0) {
             for (const tool of this.tools) {
                 const genericTool = tool;
@@ -399,23 +514,29 @@ class AgentContext {
                 }
             }
         }
-        // Count tokens for tool definitions (MCP / event-driven tools).
-        // These are sent to the provider API as tool schemas alongside bound tools.
-        // Both can be populated simultaneously (graph tools + MCP tools).
         if (this.toolDefinitions && this.toolDefinitions.length > 0) {
             for (const def of this.toolDefinitions) {
                 if (countedToolNames.has(def.name)) {
-                    continue; // Already counted via this.tools
+                    continue;
                 }
                 const schema = {
-                    name: def.name,
-                    description: def.description ?? '',
-                    parameters: def.parameters ?? {},
+                    type: 'function',
+                    function: {
+                        name: def.name,
+                        description: def.description ?? '',
+                        parameters: def.parameters ?? {},
+                    },
                 };
                 toolTokens += tokenCounter(new SystemMessage(JSON.stringify(schema)));
             }
         }
-        this.instructionTokens += toolTokens;
+        const isAnthropic = this.provider !== Providers.BEDROCK &&
+            (this.provider === Providers.ANTHROPIC ||
+                /anthropic|claude/i.test(String(this.clientOptions?.model ?? '')));
+        const toolTokenMultiplier = isAnthropic
+            ? ANTHROPIC_TOOL_TOKEN_MULTIPLIER
+            : DEFAULT_TOOL_TOKEN_MULTIPLIER;
+        this.toolSchemaTokens = Math.ceil(toolTokens * toolTokenMultiplier);
     }
     /**
      * Gets the tool registry for deferred tools (for tool search).
@@ -455,6 +576,151 @@ class AgentContext {
             this.systemRunnableStale = true;
         }
     }
+    setSummary(text, tokenCount) {
+        this.summaryText = text;
+        this.summaryTokenCount = tokenCount;
+        this._summaryLocation = 'user_message';
+        this._durableSummaryText = text;
+        this._durableSummaryTokenCount = tokenCount;
+        this._summaryVersion += 1;
+        this.systemRunnableStale = true;
+        this.pruneMessages = undefined;
+    }
+    /** Sets a cross-run summary that is injected into the system prompt. */
+    setInitialSummary(text, tokenCount) {
+        this.summaryText = text;
+        this.summaryTokenCount = tokenCount;
+        this._summaryLocation = 'system_prompt';
+        this._durableSummaryText = text;
+        this._durableSummaryTokenCount = tokenCount;
+        this._summaryVersion += 1;
+        this.systemRunnableStale = true;
+    }
+    /**
+     * Replaces the indexTokenCountMap with a fresh map keyed to the surviving
+     * context messages after summarization.  Called by the summarize node after
+     * it emits RemoveMessage operations that shift message indices.
+     */
+    rebuildTokenMapAfterSummarization(newTokenMap) {
+        this.indexTokenCountMap = newTokenMap;
+        this.baseIndexTokenCountMap = { ...newTokenMap };
+        this._lastSummarizationMsgCount = Object.keys(newTokenMap).length;
+        this.currentUsage = undefined;
+        this.lastCallUsage = undefined;
+        this.totalTokensFresh = false;
+    }
+    hasSummary() {
+        return this.summaryText != null && this.summaryText !== '';
+    }
+    /** True when a mid-run compaction summary is ready to be injected as a HumanMessage. */
+    hasPendingCompactionSummary() {
+        return this._summaryLocation === 'user_message' && this.hasSummary();
+    }
+    getSummaryText() {
+        return this.summaryText;
+    }
+    get summaryVersion() {
+        return this._summaryVersion;
+    }
+    /**
+     * Returns true when the message count hasn't changed since the last
+     * summarization — re-summarizing would produce an identical result.
+     * Oversized individual messages are handled by fit-to-budget truncation
+     * in the pruner, which keeps them in context without triggering overflow.
+     */
+    shouldSkipSummarization(currentMsgCount) {
+        return (this._lastSummarizationMsgCount > 0 &&
+            currentMsgCount <= this._lastSummarizationMsgCount);
+    }
+    /**
+     * Records the message count at which summarization was triggered,
+     * so subsequent calls with the same count are suppressed.
+     */
+    markSummarizationTriggered(msgCount) {
+        this._lastSummarizationMsgCount = msgCount;
+    }
+    clearSummary() {
+        if (this.summaryText != null) {
+            this.summaryText = undefined;
+            this.summaryTokenCount = 0;
+            this._durableSummaryText = undefined;
+            this._durableSummaryTokenCount = 0;
+            this._summaryLocation = 'none';
+            this.systemRunnableStale = true;
+        }
+    }
+    /**
+     * Returns a structured breakdown of how the context token budget is consumed.
+     * Useful for diagnostics when context overflow or pruning issues occur.
+     */
+    getTokenBudgetBreakdown(messages) {
+        const maxContextTokens = this.maxContextTokens ?? 0;
+        const toolCount = (this.tools?.length ?? 0) + (this.toolDefinitions?.length ?? 0);
+        const messageCount = messages?.length ?? 0;
+        let messageTokens = 0;
+        if (messages != null) {
+            for (let i = 0; i < messages.length; i++) {
+                messageTokens +=
+                    this.indexTokenCountMap[i] ?? 0;
+            }
+        }
+        const reserveTokens = Math.round(maxContextTokens * DEFAULT_RESERVE_RATIO);
+        const availableForMessages = Math.max(0, maxContextTokens - reserveTokens - this.instructionTokens);
+        return {
+            maxContextTokens,
+            instructionTokens: this.instructionTokens,
+            systemMessageTokens: this.systemMessageTokens,
+            toolSchemaTokens: this.toolSchemaTokens,
+            summaryTokens: this.summaryTokenCount,
+            toolCount,
+            messageCount,
+            messageTokens,
+            availableForMessages,
+        };
+    }
+    /**
+     * Returns a human-readable string of the token budget breakdown
+     * for inclusion in error messages and diagnostics.
+     */
+    formatTokenBudgetBreakdown(messages) {
+        const b = this.getTokenBudgetBreakdown(messages);
+        const lines = [
+            'Token budget breakdown:',
+            `  maxContextTokens:    ${b.maxContextTokens}`,
+            `  instructionTokens:   ${b.instructionTokens} (system: ${b.systemMessageTokens}, tools: ${b.toolSchemaTokens} [${b.toolCount} tools])`,
+            `  summaryTokens:       ${b.summaryTokens}`,
+            `  messageTokens:       ${b.messageTokens} (${b.messageCount} messages)`,
+            `  availableForMessages: ${b.availableForMessages}`,
+        ];
+        return lines.join('\n');
+    }
+    /**
+     * Updates the last-call usage with data from the most recent LLM response.
+     * Unlike `currentUsage` which accumulates, this captures only the single call.
+     */
+    updateLastCallUsage(usage) {
+        const baseInputTokens = Number(usage.input_tokens) || 0;
+        const cacheCreation = Number(usage.input_token_details?.cache_creation) || 0;
+        const cacheRead = Number(usage.input_token_details?.cache_read) || 0;
+        const outputTokens = Number(usage.output_tokens) || 0;
+        const cacheSum = cacheCreation + cacheRead;
+        const cacheIsAdditive = cacheSum > 0 && cacheSum > baseInputTokens;
+        const totalInputTokens = cacheIsAdditive
+            ? baseInputTokens + cacheSum
+            : baseInputTokens;
+        this.lastCallUsage = {
+            inputTokens: totalInputTokens,
+            outputTokens,
+            totalTokens: totalInputTokens + outputTokens,
+            cacheRead: cacheRead || undefined,
+            cacheCreation: cacheCreation || undefined,
+        };
+        this.totalTokensFresh = true;
+    }
+    /** Marks token data as stale before a new LLM call. */
+    markTokensStale() {
+        this.totalTokensFresh = false;
+    }
     /**
      * Marks tools as discovered via tool search.
      * Discovered tools will be included in the next model binding.
@@ -484,11 +750,9 @@ class AgentContext {
      * @returns Array of tools to bind to model
      */
     getToolsForBinding() {
-        /** Event-driven mode: create schema-only tools from definitions */
         if (this.toolDefinitions && this.toolDefinitions.length > 0) {
             return this.getEventDrivenToolsForBinding();
         }
-        /** Traditional mode: filter actual tool instances */
         const filtered = !this.tools || !this.toolRegistry
             ? this.tools
             : this.filterToolsForBinding(this.tools);