@librechat/agents 3.8.0 → 3.8.2

package/src/summarization/node.ts

@@ -14,6 +14,7 @@ import {
   buildSummaryCarrierText,
   separateSummarizationParameters,
   buildSummarizationInstruction,
+  ManualSummarizationSkippedError,
 } from './shared';
 import {
   addTailCacheControl,
@@ -1026,6 +1027,14 @@ function findStreamLimitAbortReason(
   return undefined;
 }
 
+/** Wording for the history-preserved log and completion, by request reason. */
+const PRESERVATION_REASONS: Partial<
+  Record<NonNullable<t.SummarizationNodeInput['reason']>, string>
+> = {
+  overflow: 'overflow recovery',
+  manual: 'manual compaction',
+};
+
 export function createSummarizeNode({
   agentContext,
   graph: adapterGraph,
@@ -1037,7 +1046,11 @@ export function createSummarizeNode({
       summarizationRequest?: t.SummarizationNodeInput;
     },
     config?: RunnableConfig
-  ): Promise<{ summarizationRequest: undefined; messages?: BaseMessage[] }> => {
+  ): Promise<{
+    summarizationRequest: undefined;
+    messages?: BaseMessage[];
+    manualSummary?: string;
+  }> => {
     /** The breaker signal is captured at node ENTRY, before dispatchRunStep,
      * ON_SUMMARIZE_START, or PreCompact awaits: a sibling's trip plus a
      * prompt next run can reset the controller during one of those awaits,
@@ -1114,6 +1127,12 @@ export function createSummarizeNode({
      * its recursion budget dispatching empty summary steps.
      */
     if (agentContext.summarizationExhausted) {
+      if (request.reason === 'manual') {
+        throw new ManualSummarizationSkippedError(
+          'exhausted',
+          'Compaction skipped: consecutive summarization attempts produced no usable summary'
+        );
+      }
       emitAgentLog(
         config,
         'warn',
@@ -1131,6 +1150,12 @@ export function createSummarizeNode({
 
     const maxCtx = agentContext.maxContextTokens ?? 0;
     if (maxCtx > 0 && agentContext.instructionTokens >= maxCtx) {
+      if (request.reason === 'manual') {
+        throw new ManualSummarizationSkippedError(
+          'instructions_exceed_budget',
+          'Compaction skipped: instructions and tool definitions exceed the context budget'
+        );
+      }
       emitAgentLog(
         config,
         'warn',
@@ -1167,6 +1192,16 @@ export function createSummarizeNode({
     const runnableConfig = config ?? graph.config;
 
     const retainRecent = agentContext.summarizationConfig?.retainRecent;
+    /**
+     * A manual summary is the user asking for the whole history to become a
+     * checkpoint, so the default recency window does not apply to it. A
+     * `retainRecent` the host configured explicitly still keeps its tail,
+     * with the ordinary turn default when it only sets a token cap.
+     */
+    const retainTurns =
+      request.reason === 'manual' && retainRecent == null
+        ? 0
+        : (retainRecent?.turns ?? DEFAULT_RETAIN_RECENT_TURNS);
     const recencyTokenCounter =
       agentContext.contextPressureTokenCounts?.count ??
       agentContext.tokenCounter;
@@ -1175,7 +1210,8 @@ export function createSummarizeNode({
       tailStartIndex,
       usedIntraTurnFallback,
     } = splitAtRecencyBoundary(restoredMessages, {
-      turns: retainRecent?.turns ?? DEFAULT_RETAIN_RECENT_TURNS,
+      provider: agentContext.provider,
+      turns: retainTurns,
       tokens: retainRecent?.tokens,
       tokenCounter: recencyTokenCounter,
       intraTurnTokens: resolveIntraTurnRetainTokens({
@@ -1198,6 +1234,12 @@ export function createSummarizeNode({
     const messagesToRetain = state.messages.slice(tailStartIndex);
 
     if (messagesToRefine.length === 0) {
+      if (request.reason === 'manual') {
+        throw new ManualSummarizationSkippedError(
+          'nothing_to_summarize',
+          'Nothing to compact: the retained recent turns cover the whole conversation'
+        );
+      }
       /**
        * Recency window covers the entire conversation — there is no
        * older content to summarize.  Skipping prevents the model from
@@ -1213,7 +1255,7 @@ export function createSummarizeNode({
         'Summarization skipped — recency window retains all messages',
         {
           messagesRetained: messagesToRetain.length,
-          retainTurns: retainRecent?.turns ?? DEFAULT_RETAIN_RECENT_TURNS,
+          retainTurns,
         },
         { runId: graph.runId, agentId: request.agentId }
       );
@@ -1290,7 +1332,10 @@ export function createSummarizeNode({
           threadId,
           agentId: request.agentId,
           messagesBeforeCount: messagesToRefine.length,
-          trigger: agentContext.summarizationConfig?.trigger?.type ?? 'default',
+          trigger:
+            request.reason === 'manual'
+              ? 'manual'
+              : (agentContext.summarizationConfig?.trigger?.type ?? 'default'),
         },
         sessionId,
       }).catch(() => {
@@ -1340,7 +1385,7 @@ export function createSummarizeNode({
           compaction_semantic_index_entries: semanticIndex.entryCount,
           compaction_semantic_index_chars: semanticIndex.charCount,
           compaction_semantic_index_omitted_entries:
-            semanticIndex.omittedEntryCount,
+              semanticIndex.omittedEntryCount,
           /**
              * Per-call model attribution for usage consumers (the subagent
              * usage-capture handler): the summarizer's model can differ from
@@ -1398,19 +1443,21 @@ export function createSummarizeNode({
     /**
      * The metadata stub describes the history rather than summarizing it, so
      * committing it means removing the head and keeping nothing of what it
-     * said. That trade is never worth making to paper over an overflow: the
-     * recovery would "succeed" only by destroying the conversation it was
-     * supposed to preserve. Leave state untouched and let the provider error
-     * surface instead.
+     * said. That trade is never worth making to paper over an overflow, and
+     * never for a manual compaction, which would replace the whole history
+     * with a message count: the recovery would "succeed" only by destroying
+     * the conversation it was supposed to preserve. Leave state untouched
+     * and let the provider error surface instead.
      */
     if (
       usedMetadataStub === true &&
-      (request.reason === 'overflow' || usedIntraTurnFallback)
+      (request.reason === 'overflow' ||
+        request.reason === 'manual' ||
+        usedIntraTurnFallback)
     ) {
       const preservationReason =
-        request.reason === 'overflow'
-          ? 'overflow recovery'
-          : 'intra-turn compaction';
+        PRESERVATION_REASONS[request.reason ?? 'trigger'] ??
+        'intra-turn compaction';
       log(
         'warn',
         `Summarization failed during ${preservationReason}; keeping history rather than replacing it with a metadata stub`
@@ -1570,6 +1617,8 @@ export function createSummarizeNode({
         messagesToRetain.length > 0
           ? [createRemoveAllMessage(), ...messagesToRetain]
           : [createRemoveAllMessage()],
+      /** The run's result, for trace roots that otherwise see no reply. */
+      ...(request.reason === 'manual' ? { manualSummary: summaryText } : {}),
     };
   };
 }

package/src/summarization/shared.ts

@@ -128,3 +128,26 @@ export function buildSummarizationInstruction(
   }
   return parts.join('');
 }
+
+/** Why a summarize-only run could not attempt its summary. */
+export type ManualSummarizationSkipReason =
+  | 'disabled'
+  | 'exhausted'
+  | 'instructions_exceed_budget'
+  | 'nothing_to_summarize';
+
+/**
+ * A summarize-only run asked for a summary the graph could not attempt.
+ * Thrown rather than ending the run quietly: the summary is the whole result
+ * of such a run, so a host left with neither a summary nor an error would
+ * have nothing to show the user.
+ */
+export class ManualSummarizationSkippedError extends Error {
+  readonly reason: ManualSummarizationSkipReason;
+
+  constructor(reason: ManualSummarizationSkipReason, message: string) {
+    super(message);
+    this.name = 'ManualSummarizationSkippedError';
+    this.reason = reason;
+  }
+}