@librechat/agents 3.1.77 → 3.1.78

package/src/summarization/node.ts

@@ -14,6 +14,7 @@ import { ContentTypes, GraphEvents, StepTypes, Providers } from '@/common';
 import { safeDispatchCustomEvent, emitAgentLog } from '@/utils/events';
 import { attemptInvoke, tryFallbackProviders } from '@/llm/invoke';
 import { createRemoveAllMessage } from '@/messages/reducer';
+import { splitAtRecencyBoundary } from '@/messages/recency';
 import { getMaxOutputTokensKey } from '@/llm/request';
 import { addCacheControl } from '@/messages/cache';
 import { initializeModel } from '@/llm/init';
@@ -22,6 +23,18 @@ import { executeHooks } from '@/hooks';
 
 const SUMMARIZATION_PARAM_KEYS = new Set(['maxSummaryTokens']);
 
+/**
+ * Default number of recent user-led turns preserved verbatim during
+ * compaction.  A turn begins at a HumanMessage and includes every
+ * following AIMessage and ToolMessage up to the next HumanMessage.
+ * The most recent turn is always retained regardless of this value;
+ * the default of `2` additionally keeps the prior exchange so the
+ * model has fresh context on what just happened.  Setting
+ * `retainRecent.turns` to `0` reverts to the legacy "summarize every
+ * message" behavior.
+ */
+const DEFAULT_RETAIN_RECENT_TURNS = 2;
+
 /**
  * Token overhead of the XML wrapper + instruction text added around the
  * summary at injection time in AgentContext.buildSystemRunnable:
@@ -616,6 +629,13 @@ async function dispatchCompletionEvents(params: {
   runStep: t.RunStep;
   summaryUsage?: Partial<UsageMetadata>;
   agentId: string;
+  /**
+   * Number of messages preserved verbatim by the recency window after
+   * compaction.  Reported via the PostCompact hook payload so observers
+   * (metrics, cleanup) see the true post-compaction message count
+   * instead of always-zero.
+   */
+  messagesAfterCount: number;
 }): Promise<void> {
   const {
     graph,
@@ -626,6 +646,7 @@ async function dispatchCompletionEvents(params: {
     runStep,
     summaryUsage,
     agentId,
+    messagesAfterCount,
   } = params;
 
   runStep.summary = summaryBlock;
@@ -678,7 +699,7 @@ async function dispatchCompletionEvents(params: {
         threadId,
         agentId,
         summary: summaryText,
-        messagesAfterCount: 0,
+        messagesAfterCount,
       },
       sessionId,
     }).catch(() => {
@@ -749,19 +770,77 @@ export function createSummarizeNode({
       return { summarizationRequest: undefined };
     }
 
-    const messagesToRefine = restoreOriginalToolContent(
+    /**
+     * Capture the original-tool-content map locally before doing the
+     * split.  We need it in three places: to restore the head for
+     * summarizer quality, to leave intact on the skip path (state is
+     * unchanged), and — critically — to carry forward the tail-relevant
+     * entries on the summarize-fired path.  Clearing it eagerly here
+     * would lose the originals for masked tool messages that the
+     * recency window keeps in the tail; a future summarization could
+     * then only summarize the masked stub instead of the full payload.
+     */
+    const originalPending = agentContext.pendingOriginalToolContent;
+
+    const restoredMessages = restoreOriginalToolContent(
       state.messages,
-      agentContext.pendingOriginalToolContent
+      originalPending
     );
-    agentContext.pendingOriginalToolContent = undefined;
+
+    const runnableConfig = config ?? graph.config;
+
+    const retainRecent = agentContext.summarizationConfig?.retainRecent;
+    const { head: messagesToRefine, tailStartIndex } = splitAtRecencyBoundary(
+      restoredMessages,
+      {
+        turns: retainRecent?.turns ?? DEFAULT_RETAIN_RECENT_TURNS,
+        tokens: retainRecent?.tokens,
+        tokenCounter: agentContext.tokenCounter,
+      }
+    );
+    /**
+     * Use the *masked* messages for the retained tail so that any
+     * truncation prune applied to oversized ToolMessage content stays
+     * truncated in live state.  The summarizer above reads the restored
+     * (full-content) head for summary quality, but reinjecting restored
+     * tool payloads into state would defeat masking and bloat the
+     * checkpoint, forcing more expensive re-pruning on later turns.
+     * `restoreOriginalToolContent` returns an array with identical
+     * length and structure to `state.messages` (replacements only at
+     * specific indices), so the same tailStartIndex slices both arrays
+     * at the same turn boundary.
+     */
+    const messagesToRetain = state.messages.slice(tailStartIndex);
+
+    if (messagesToRefine.length === 0) {
+      /**
+       * Recency window covers the entire conversation — there is no
+       * older content to summarize.  Skipping prevents the model from
+       * destroying the user's most recent message (e.g. a large pasted
+       * payload on the first turn) by replacing it with a generic
+       * checkpoint summary.  Mark the trigger so the same unchanged
+       * state is not re-evaluated on the next prune cycle.
+       */
+      emitAgentLog(
+        config,
+        'debug',
+        'summarize',
+        'Summarization skipped — recency window retains all messages',
+        {
+          messagesRetained: messagesToRetain.length,
+          retainTurns: retainRecent?.turns ?? DEFAULT_RETAIN_RECENT_TURNS,
+        },
+        { runId: graph.runId, agentId: request.agentId }
+      );
+      agentContext.markSummarizationTriggered(state.messages.length);
+      return { summarizationRequest: undefined };
+    }
 
     const clientConfig = buildSummarizationClientConfig(
       agentContext,
       agentContext.summarizationConfig
     );
 
-    const runnableConfig = config ?? graph.config;
-
     const stepKey = `summarize-${request.agentId}`;
     const [stepId, stepIndex] = generateStepId(stepKey);
 
@@ -935,11 +1014,49 @@ export function createSummarizeNode({
       runStep,
       summaryUsage,
       agentId: request.agentId,
+      messagesAfterCount: messagesToRetain.length,
     });
 
+    /**
+     * `dispatchCompletionEvents` calls `rebuildTokenMapAfterSummarization({})`
+     * which resets the dedupe baseline to 0 — correct under the legacy
+     * "remove-all only" shape where no messages survived, but stale once
+     * the recency window keeps a tail.  Realign the baseline to the
+     * surviving tail length so a subsequent prune cycle on the unchanged
+     * tail short-circuits via `shouldSkipSummarization` instead of
+     * looping back into another summarize call.
+     */
+    agentContext.markSummarizationTriggered(messagesToRetain.length);
+
+    /**
+     * Carry forward the original-content entries that correspond to the
+     * retained tail, reindexed for the post-removeAll state where tail
+     * messages start at index 0.  Without this, a future summarization
+     * that pulls these tail messages into its head would only see the
+     * masked stubs (since `setSummary` clears `pruneMessages`, and the
+     * fresh pruner at the next turn has no record of prior masks).
+     * Entries for indices < `tailStartIndex` belong to messages we just
+     * summarized — they are no longer reachable so they are dropped.
+     */
+    if (originalPending != null && originalPending.size > 0) {
+      const tailPending = new Map<number, string>();
+      for (const [idx, content] of originalPending) {
+        if (idx >= tailStartIndex) {
+          tailPending.set(idx - tailStartIndex, content);
+        }
+      }
+      agentContext.pendingOriginalToolContent =
+        tailPending.size > 0 ? tailPending : undefined;
+    } else {
+      agentContext.pendingOriginalToolContent = undefined;
+    }
+
     return {
       summarizationRequest: undefined,
-      messages: [createRemoveAllMessage()],
+      messages:
+        messagesToRetain.length > 0
+          ? [createRemoveAllMessage(), ...messagesToRetain]
+          : [createRemoveAllMessage()],
     };
   };
 }