@librechat/agents 3.7.15 → 3.7.17

package/src/graphs/Graph.ts

@@ -54,7 +54,6 @@ import {
   CALIBRATION_RATIO_MAX,
   createPruneMessages,
   projectToolMessagesForProvider,
-  calculateMaxToolCallInputChars,
   syncBudgetDerivedFields,
   addTailCacheControl,
   resolvePromptCacheTtl,
@@ -156,6 +155,7 @@ import { createContextPressureMeter } from '@/llm/contextPressureMeter';
 import { safeDispatchCustomEvent, emitAgentLog } from '@/utils/events';
 import { prepareProviderRequest } from '@/llm/prepareProviderRequest';
 import { createCloudflareCodingToolBundle } from '@/tools/cloudflare';
+import { calculateMaxToolCallInputChars } from '@/utils/truncation';
 import { prepareToolsForPromptCache } from '@/llm/promptCacheTools';
 import { providerRequiresStrictAlternation } from '@/llm/providers';
 import { buildSubagentToolParams } from '@/tools/SubagentTool';
@@ -163,6 +163,7 @@ import { initializeLangfuseTracing } from '@/instrumentation';
 import { shouldTriggerSummarization } from '@/summarization';
 import { isRunStepResumeState } from '@/tools/runStepResume';
 import { resolveLocalToolsForBinding } from '@/tools/local';
+import { isFadingTier, isInformativeFadingTier } from '@/messages/fading';
 import { createSummarizeNode } from '@/summarization/node';
 import { getTruncationStopReason } from '@/llm/truncation';
 import { messagesStateReducer } from '@/messages/reducer';
@@ -1070,6 +1071,13 @@ export abstract class Graph<
     return [...threadIds];
   }
 
+  protected createSubagentFadingResumeState(): Pick<
+    SubagentGraphResumeState,
+    'fadingTier' | 'fadingTiers'
+    > {
+    return {};
+  }
+
   createSubagentResumeState(runId: string): SubagentGraphResumeState {
     return {
       toolCallSteps: [...this.toolCallStepIds].map(([toolCallId, stepId]) => ({
@@ -1107,6 +1115,7 @@ export abstract class Graph<
       ],
       eagerToolSuppressions: [...this.eagerEventToolSuppressions],
       runStepState: this.createRunStepResumeState(),
+      ...this.createSubagentFadingResumeState(),
       ...(this._toolOutputRegistry == null
         ? {}
         : {
@@ -1491,6 +1500,8 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
       tokenCounter,
       indexTokenCountMap,
       calibrationRatio,
+      fadingTier,
+      fadingTiers,
       subagentUsageSink,
       subagentTasks,
       subagentScope,
@@ -1539,6 +1550,21 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
       if (calibrationRatio != null && calibrationRatio > 0) {
         agentContext.calibrationRatio = calibrationRatio;
       }
+      let restoredFadingTier: t.FadingTier | null | undefined;
+      if (
+        fadingTiers != null &&
+        Object.prototype.hasOwnProperty.call(fadingTiers, agentConfig.agentId)
+      ) {
+        restoredFadingTier = fadingTiers[agentConfig.agentId];
+      } else if (agentConfig.agentId === agents[0].agentId) {
+        restoredFadingTier = fadingTier;
+      }
+      /** A supplied tier is assumed to describe the supplied history. Hosts
+       * must clear it when they create a new summary; this also permits tiers
+       * learned on turns after a durable summary to survive subsequent Runs. */
+      if (isFadingTier(restoredFadingTier)) {
+        agentContext.fadingTier = { ...restoredFadingTier };
+      }
 
       this.agentContexts.set(agentConfig.agentId, agentContext);
     }
@@ -2551,6 +2577,57 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
     return context?.calibrationRatio ?? 1;
   }
 
+  /**
+   * Latched context-fading tier for the default agent, or undefined while it
+   * is still fresh. Hosts persist it beside the calibration ratio.
+   */
+  getFadingTier(): t.FadingTier | undefined {
+    const context = this.agentContexts.get(this.defaultAgentId);
+    const tier = context?.fadingTier;
+    return isInformativeFadingTier(tier, context?.maxContextTokens)
+      ? { ...tier }
+      : undefined;
+  }
+
+  /** Latched context-fading tiers keyed by agent ID. */
+  getFadingTiers(): t.FadingTiers {
+    const tiers: Array<[string, t.FadingTier]> = [];
+    for (const [agentId, context] of this.agentContexts) {
+      if (
+        isInformativeFadingTier(context.fadingTier, context.maxContextTokens)
+      ) {
+        tiers.push([agentId, { ...context.fadingTier }]);
+      }
+    }
+    return Object.fromEntries(tiers);
+  }
+
+  /** Agent IDs whose canonical history was compacted during this run. */
+  getFadingTierResetAgentIds(): string[] {
+    return Array.from(this.agentContexts)
+      .filter(([, context]) => context.fadingTierReset)
+      .map(([agentId]) => agentId);
+  }
+
+  /** Whether the default agent compacted canonical history during this run. */
+  didResetFadingTier(): boolean {
+    return (
+      this.agentContexts.get(this.defaultAgentId)?.fadingTierReset === true
+    );
+  }
+
+  protected override createSubagentFadingResumeState(): Pick<
+    SubagentGraphResumeState,
+    'fadingTier' | 'fadingTiers'
+    > {
+    const fadingTier = this.getFadingTier();
+    const fadingTiers = this.getFadingTiers();
+    return {
+      ...(fadingTier == null ? {} : { fadingTier }),
+      ...(Object.keys(fadingTiers).length === 0 ? {} : { fadingTiers }),
+    };
+  }
+
   getResolvedInstructionOverhead(): number | undefined {
     const context = this.agentContexts.get(this.defaultAgentId);
     return context?.resolvedInstructionOverhead;
@@ -3059,6 +3136,12 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
        * same masking record the configured trigger preserves.
        */
       let prunedOriginalToolContent: Map<number, string> | undefined;
+      const canProjectContext =
+        agentContext.tokenCounter != null &&
+        agentContext.maxContextTokens != null;
+      const providerMessages = canProjectContext
+        ? agentContext.getProviderProjectedMessages(messages)
+        : messages;
       if (
         !agentContext.pruneMessages &&
         agentContext.tokenCounter &&
@@ -3080,6 +3163,7 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
           summarizationEnabled: agentContext.summarizationEnabled,
           reserveRatio: agentContext.summarizationConfig?.reserveRatio,
           calibrationRatio: agentContext.calibrationRatio,
+          fadingTier: agentContext.fadingTier,
           getInstructionTokens: () => agentContext.instructionTokens,
           log: (level, message, data) => {
             emitAgentLog(config, level, 'prune', message, data, {
@@ -3098,29 +3182,28 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
           remainingContextTokens,
           newOriginalToolContent,
           calibrationRatio,
+          fadingTier,
           resolvedInstructionOverhead,
           contextBudget,
           effectiveInstructionTokens,
         } = agentContext.pruneMessages({
-          messages,
+          messages: providerMessages,
+          canonicalMessages: messages,
+          canonicalPrefixStable: true,
           usageMetadata: agentContext.currentUsage,
           lastCallUsage: agentContext.lastCallUsage,
           totalTokensFresh: agentContext.totalTokensFresh,
         });
         prunedOriginalToolContent = newOriginalToolContent;
-        /**
-         * Masking rewrites tool content in `state.messages` in place, so this
-         * map is the only surviving copy of the full output. Persist it on
-         * every prune, not just when a summary is about to be written — the
-         * pruner closure that produced it is discarded on the next reset, and
-         * with it any chance of a later summary restoring the real content.
-         * AgentContext bounds what accumulates.
-         */
+        /** Preserve the masking record for the existing overflow/summarization
+         * path. The graph history itself remains canonical; only the provider
+         * projection above is rewritten by fading. */
         agentContext.preserveOriginalToolContent(newOriginalToolContent);
         agentContext.indexTokenCountMap = indexTokenCountMap;
         if (calibrationRatio != null && calibrationRatio > 0) {
           agentContext.calibrationRatio = calibrationRatio;
         }
+        agentContext.fadingTier = fadingTier;
         if (resolvedInstructionOverhead != null) {
           agentContext.resolvedInstructionOverhead =
             resolvedInstructionOverhead;
@@ -5031,7 +5114,10 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
 
     const StateAnnotation = Annotation.Root({
       messages: Annotation<BaseMessage[]>({
-        reducer: messagesStateReducer,
+        reducer: (a, b) => {
+          agentContext.invalidateProviderProjectionForMessageUpdates(b);
+          return messagesStateReducer(a, b);
+        },
         default: () => [],
       }),
       summarizationRequest: Annotation<t.SummarizationNodeInput | undefined>({

package/src/graphs/MultiAgentGraph.ts

@@ -30,7 +30,10 @@ import {
 } from '@/messages/provenance';
 import { serializeToolContentBounded } from '@/utils/toolContent';
 import { Constants, MULTI_AGENT_GRAPH_RUN_NAME } from '@/common';
-import { HARD_MAX_TOOL_RESULT_CHARS } from '@/utils/truncation';
+import {
+  calculateMaxToolResultChars,
+  HARD_MAX_TOOL_RESULT_CHARS,
+} from '@/utils/truncation';
 import { StandardGraph } from './Graph';
 
 /** Pattern to extract instructions from transfer ToolMessage content */
@@ -970,6 +973,29 @@ export class MultiAgentGraph extends StandardGraph {
    * @param agentId - The agent ID to check for handoff reception
    * @returns Object with filtered messages, extracted instructions, source agent, and parallel siblings
    */
+  /**
+   * Character cap for text injected into an agent's context as a routing or
+   * handoff prompt, derived from that agent's remaining message budget. Fading
+   * only shrinks tool content, so a prompt above this cap could overflow the
+   * agent's window or force the routing instruction out of its context.
+   */
+  private async resolveMaxRoutingPromptChars(agentId: string): Promise<number> {
+    const agentContext = this.agentContexts.get(agentId);
+    if (agentContext?.tokenCalculationPromise != null) {
+      await agentContext.tokenCalculationPromise;
+    }
+    const availableMessageTokens =
+      agentContext?.maxContextTokens == null
+        ? undefined
+        : agentContext.getTokenBudgetBreakdown().availableForMessages;
+    if (availableMessageTokens == null) {
+      return HARD_MAX_TOOL_RESULT_CHARS;
+    }
+    return availableMessageTokens <= 0
+      ? 0
+      : calculateMaxToolResultChars(availableMessageTokens);
+  }
+
   private processHandoffReception(
     messages: BaseMessage[],
     agentId: string
@@ -1358,6 +1384,12 @@ export class MultiAgentGraph extends StandardGraph {
            */
           const hasInstructions = instructions !== null && instructions !== '';
           if (hasInstructions) {
+            /** Bounded like a direct-edge routing prompt: a HumanMessage is
+             * not tool content, so fading could never shrink it later. */
+            const boundedInstructions = serializeToolContentBounded(
+              instructions,
+              await this.resolveMaxRoutingPromptChars(agentId)
+            );
             const lastMsg =
               filteredMessages.length > 0
                 ? filteredMessages[filteredMessages.length - 1]
@@ -1371,12 +1403,12 @@ export class MultiAgentGraph extends StandardGraph {
                     `[Processed tool result and transferring to ${agentId}]`
                   )
                 ),
-                buildRoutingPrompt(instructions),
+                buildRoutingPrompt(boundedInstructions),
               ];
             } else {
               messagesForAgent = [
                 ...filteredMessages,
-                buildRoutingPrompt(instructions),
+                buildRoutingPrompt(boundedInstructions),
               ];
             }
           }
@@ -1576,18 +1608,34 @@ export class MultiAgentGraph extends StandardGraph {
         builder.addNode(wrapperNodeId, async (state: t.BaseGraphState) => {
           let promptText: string | undefined;
           let effectiveExcludeResults = excludeResults;
+          const getMaxRoutingPromptChars = (): Promise<number> =>
+            this.resolveMaxRoutingPromptChars(destination);
 
           if (typeof prompt === 'function') {
-            promptText = await prompt(state.messages, this.startIndex);
+            const resolvedPrompt = await prompt(state.messages, this.startIndex);
+            promptText =
+              resolvedPrompt == null
+                ? undefined
+                : serializeToolContentBounded(
+                  resolvedPrompt,
+                  await getMaxRoutingPromptChars()
+                );
           } else if (prompt != null) {
             if (prompt.includes('{results}')) {
               const resultsMessages = state.messages.slice(this.startIndex);
-              const resultsString = getBufferString(resultsMessages);
+              const maxRoutingPromptChars = await getMaxRoutingPromptChars();
+              const resultsString = serializeToolContentBounded(
+                getBufferString(resultsMessages),
+                maxRoutingPromptChars
+              );
               const promptTemplate = PromptTemplate.fromTemplate(prompt);
               const result = await promptTemplate.invoke({
                 results: resultsString,
               });
-              promptText = result.value;
+              promptText = serializeToolContentBounded(
+                result.value,
+                maxRoutingPromptChars
+              );
               effectiveExcludeResults =
                 excludeResults !== false && promptText !== '';
             } else {

package/src/llm/openai/utils/index.ts

@@ -48,11 +48,13 @@ import {
   OPENAI_RESPONSES_STREAMED_TOOL_CALL_ADAPTER,
 } from '@/tools/streamedToolCallSeals';
 import {
+  HARD_MAX_TOOL_RESULT_CHARS,
   calculateMaxToolCallInputChars,
+} from '@/utils/truncation';
+import {
   projectToolCallInputs,
   serializeToolCallInput,
 } from '@/messages/prune';
-import { HARD_MAX_TOOL_RESULT_CHARS } from '@/utils/truncation';
 import { toLangChainContent } from '@/messages/langchain';
 
 export type { OpenAICallOptions, OpenAIChatInput };

package/src/llm/preempt.ts

@@ -5,7 +5,10 @@ import {
   DEFAULT_MAX_SEALS,
   DEFAULT_PREEMPT_RESTART_GRACE_MS,
 } from '@/common';
-import { isReasoningContentBlock } from '@/messages/core';
+import {
+  hasNonEmptyTextContent,
+  isReasoningContentBlock,
+} from '@/messages/core';
 
 /**
  * Normalizes a host-supplied seal budget.
@@ -33,22 +36,6 @@ export function resolveMaxSeals(maxSeals: number | undefined): number {
  * stripped or signed on several providers and cannot stand in for the visible
  * assistant turn a sealed sequence needs.
  */
-function hasNonEmptyTextContent(content: AIMessageChunk['content']): boolean {
-  if (typeof content === 'string') {
-    return content.trim() !== '';
-  }
-  for (const block of content) {
-    if (block.type !== ContentTypes.TEXT) {
-      continue;
-    }
-    const text = block[ContentTypes.TEXT];
-    if (typeof text === 'string' && text.trim() !== '') {
-      return true;
-    }
-  }
-  return false;
-}
-
 /**
  * True while a Gemini server-side tool call is still awaiting its response.
  *

package/src/messages/contextPruning.ts

@@ -60,6 +60,8 @@ export interface ContextPruningResult {
  */
 export function applyContextPruning(params: {
   messages: BaseMessage[];
+  /** Full graph history used only to decide whether a projected result is eligible. */
+  canonicalMessages?: BaseMessage[];
   indexTokenCountMap: Record<string, number | undefined>;
   tokenCounter: TokenCounter;
   config?: ContextPruningConfig;
@@ -138,7 +140,11 @@ export function applyContextPruning(params: {
     }
     const content = message.content;
     const contentLength = getToolContentCharLength(content);
-    if (contentLength < settings.minPrunableToolChars) {
+    const eligibilityContent = params.canonicalMessages?.[i]?.content ?? content;
+    if (
+      getToolContentCharLength(eligibilityContent) <
+      settings.minPrunableToolChars
+    ) {
       continue;
     }
 

package/src/messages/core.ts

@@ -2793,3 +2793,55 @@ export function findLastIndex<T>(
   }
   return -1;
 }
+
+/** Reads an own data property without invoking accessors; `undefined` otherwise. */
+function readOwnDataProperty(target: object, key: PropertyKey): unknown {
+  try {
+    const descriptor = Object.getOwnPropertyDescriptor(target, key);
+    return descriptor != null && 'value' in descriptor ? descriptor.value : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Whether message content carries non-whitespace text in any text block. */
+export function hasNonEmptyTextContent(content: BaseMessage['content']): boolean {
+  if (typeof content === 'string') {
+    return content.trim() !== '';
+  }
+  if (!Array.isArray(content) || isProxy(content)) {
+    return false;
+  }
+  /** Index reads through own data descriptors: `for...of` would invoke a
+   * hostile `Symbol.iterator` or an accessor-backed element before any guard. */
+  const length = readOwnDataProperty(content, 'length');
+  const blockCount = typeof length === 'number' ? length : 0;
+  for (let i = 0; i < blockCount; i++) {
+    const block = readOwnDataProperty(content, i);
+    if (typeof block !== 'object' || block == null || isProxy(block)) {
+      continue;
+    }
+    try {
+      const type = Object.getOwnPropertyDescriptor(block, 'type');
+      if (
+        type == null ||
+        !('value' in type) ||
+        (type.value !== ContentTypes.TEXT && type.value !== 'output_text')
+      ) {
+        continue;
+      }
+      const text = Object.getOwnPropertyDescriptor(block, ContentTypes.TEXT);
+      if (
+        text != null &&
+        'value' in text &&
+        typeof text.value === 'string' &&
+        text.value.trim() !== ''
+      ) {
+        return true;
+      }
+    } catch {
+      continue;
+    }
+  }
+  return false;
+}