@librechat/agents 3.3.7 → 3.3.8

package/src/summarization/__tests__/node.test.ts

@@ -1,11 +1,13 @@
 import { AIMessage, HumanMessage, ToolMessage } from '@langchain/core/messages';
 import type { RunnableConfig } from '@langchain/core/runnables';
+import type { BaseMessage } from '@langchain/core/messages';
 import type * as t from '@/types';
 import {
   createSummarizeNode,
   DEFAULT_SUMMARIZATION_PROMPT,
   DEFAULT_UPDATE_SUMMARIZATION_PROMPT,
 } from '@/summarization/node';
+import { convertInjectedMessages } from '@/messages/injected';
 import { Constants, GraphEvents, Providers } from '@/common';
 import { AgentContext } from '@/agents/AgentContext';
 import * as providers from '@/llm/providers';
@@ -945,6 +947,192 @@ describe('recency window — first-turn protection', () => {
     expect((result.messages![2] as AIMessage).content).toBe('turn 2 reply');
   });
 
+  describe('summary coverage', () => {
+    const runCompaction = async (
+      messages: BaseMessage[],
+      turns = 1
+    ): Promise<t.SummaryContentBlock | undefined> => {
+      captureEvents();
+      jest.spyOn(providers, 'getChatModelClass').mockReturnValue(
+        class {
+          constructor() {
+            return mockInvokeModel('Summary of older turns');
+          }
+        } as never
+      );
+
+      let summaryBlock: t.SummaryContentBlock | undefined;
+      const graph = mockGraph((_stepId, result) => {
+        if (result.type === 'summary') {
+          summaryBlock = result.summary;
+        }
+      });
+      const summarizeNode = createSummarizeNode({
+        agentContext: createAgentContext({
+          summarizationConfig: { retainRecent: { turns } },
+        } as never),
+        graph: graph as never,
+        generateStepId,
+      });
+
+      await summarizeNode(
+        {
+          messages,
+          summarizationRequest: {
+            remainingContextTokens: 0,
+            agentId: 'agent_0',
+          },
+        },
+        {} as RunnableConfig
+      );
+
+      return summaryBlock;
+    };
+
+    it('records the first retained message as the coverage anchor', async () => {
+      const summaryBlock = await runCompaction([
+        new HumanMessage({ content: 'turn 1 query', id: 'm1' }),
+        new AIMessage({ content: 'turn 1 reply', id: 'm2' }),
+        new HumanMessage({ content: 'turn 2 query', id: 'm3' }),
+        new AIMessage({ content: 'turn 2 reply', id: 'm4' }),
+      ]);
+
+      expect(summaryBlock?.coverage).toEqual({ retainedFromMessageId: 'm3' });
+    });
+
+    it('skips a retained message that carries no source id', async () => {
+      const summaryBlock = await runCompaction([
+        new HumanMessage({ content: 'turn 1 query', id: 'm1' }),
+        new AIMessage({ content: 'turn 1 reply', id: 'm2' }),
+        new HumanMessage({ content: 'turn 2 query' }),
+        new AIMessage({ content: 'turn 2 reply', id: 'm4' }),
+      ]);
+
+      expect(summaryBlock?.coverage).toEqual({ retainedFromMessageId: 'm4' });
+    });
+
+    it('omits coverage when no retained message carries a source id', async () => {
+      const summaryBlock = await runCompaction([
+        new HumanMessage('turn 1 query'),
+        new AIMessage('turn 1 reply'),
+        new HumanMessage('turn 2 query'),
+        new AIMessage('turn 2 reply'),
+      ]);
+
+      expect(summaryBlock?.coverage).toBeUndefined();
+    });
+
+    /** A steer expands one source message into pre-steer, steer, and post-steer
+     *  messages sharing its ID, and the recency split lands on the steer. The
+     *  straddling message is the anchor, so it survives whole. */
+    it('anchors on a source id that straddles the recency boundary', async () => {
+      const summaryBlock = await runCompaction([
+        new HumanMessage({ content: 'turn 1 query', id: 'm1' }),
+        new AIMessage({ content: 'pre-steer reply', id: 'm2' }),
+        new HumanMessage({
+          content: 'steer',
+          id: 'm2',
+          additional_kwargs: { role: 'user', source: 'steer' },
+        }),
+        new AIMessage({ content: 'post-steer reply', id: 'm2' }),
+      ]);
+
+      expect(summaryBlock?.coverage).toEqual({ retainedFromMessageId: 'm2' });
+    });
+
+    /** A steer carries `source: 'steer'` but is replayed from a payload entry
+     *  and stamped with its ID, so it is a valid anchor. When compaction lands
+     *  before any post-steer message exists it is the *only* retained entry —
+     *  treating every marked message as synthetic drops it. */
+    it('anchors on a retained steer with no post-steer message', async () => {
+      const summaryBlock = await runCompaction([
+        new HumanMessage({ content: 'turn 1 query', id: 'm1' }),
+        new AIMessage({ content: 'pre-steer reply', id: 'm2' }),
+        new HumanMessage({
+          content: 'steer',
+          id: 'm2',
+          additional_kwargs: { role: 'user', source: 'steer' },
+        }),
+      ]);
+
+      expect(summaryBlock?.coverage).toEqual({ retainedFromMessageId: 'm2' });
+    });
+
+    /** `formatAgentMessages` reconstructs skill bodies inside its payload loop
+     *  and keeps processing payload entries after, so this unstamped entry — a
+     *  reducer UUID by the time compaction sees it — precedes stamped messages.
+     *  Anchoring on it would resolve to nothing on the next run. */
+    it('skips a reconstructed skill body to reach the stamped message behind it', async () => {
+      const summaryBlock = await runCompaction(
+        [
+          new HumanMessage({ content: 'turn 1 query', id: 'm1' }),
+          new AIMessage({ content: 'turn 1 reply', id: 'm2' }),
+          new HumanMessage({
+            content: 'skill body',
+            id: 'reducer-uuid',
+            additional_kwargs: {
+              role: 'user',
+              isMeta: true,
+              source: 'skill',
+              skillName: 'demo',
+            },
+          }),
+          new HumanMessage({ content: 'turn 2 query', id: 'm3' }),
+          new AIMessage({ content: 'turn 2 reply', id: 'm4' }),
+        ],
+        2
+      );
+
+      expect(summaryBlock?.coverage).toEqual({ retainedFromMessageId: 'm3' });
+    });
+
+    /** `InjectedMessage` leaves both `isMeta` and `source` optional, so a bare
+     *  injected turn carries no marker of its own — and an injected `steer` is
+     *  otherwise indistinguishable from a replayed one. `convertInjectedMessages`
+     *  records `injected` on everything it builds, which decides both. */
+    it.each([
+      ['a bare injected turn', { role: 'user' as const, content: 'injected' }],
+      [
+        'an injected steer',
+        {
+          role: 'user' as const,
+          content: 'injected steer',
+          source: 'steer' as const,
+        },
+      ],
+    ])('skips %s when anchoring', async (_label, injected) => {
+      const [converted] = convertInjectedMessages([injected]);
+      converted.id = 'reducer-uuid';
+
+      const summaryBlock = await runCompaction(
+        [
+          new HumanMessage({ content: 'turn 1 query', id: 'm1' }),
+          new AIMessage({ content: 'turn 1 reply', id: 'm2' }),
+          converted,
+          new HumanMessage({ content: 'turn 2 query', id: 'm3' }),
+          new AIMessage({ content: 'turn 2 reply', id: 'm4' }),
+        ],
+        2
+      );
+
+      expect(summaryBlock?.coverage).toEqual({ retainedFromMessageId: 'm3' });
+    });
+
+    it('anchors on the straddling id when it is the only source', async () => {
+      const summaryBlock = await runCompaction([
+        new AIMessage({ content: 'pre-steer reply', id: 'm1' }),
+        new HumanMessage({
+          content: 'steer',
+          id: 'm1',
+          additional_kwargs: { role: 'user', source: 'steer' },
+        }),
+        new AIMessage({ content: 'post-steer reply', id: 'm1' }),
+      ]);
+
+      expect(summaryBlock?.coverage).toEqual({ retainedFromMessageId: 'm1' });
+    });
+  });
+
   it('keeps the masked tail content (does not re-inject restored tool payloads into state)', async () => {
     captureEvents();
 

package/src/summarization/node.ts

@@ -381,10 +381,75 @@ function computeSummaryTokenCount(
   return 0;
 }
 
+/**
+ * Names the first retained message so the summary declares its own extent
+ * rather than leaving the next run to infer coverage from where the block
+ * happens to sit.
+ *
+ * Anchored to the retained side, not the covered side. One source message can
+ * expand into several messages — a steer splits an assistant entry into
+ * pre-steer, steer, and post-steer entries sharing its ID — and the recency
+ * split lands on any human-type message, including the steer. Naming the last
+ * *covered* message would then name a half-covered ID with no correct reading;
+ * naming the first *retained* message makes that same message the anchor, so it
+ * survives whole and everything before it is unambiguously covered.
+ *
+ * Synthetic entries are skipped, because they can sit *before* a resolvable
+ * one. `formatAgentMessages` reconstructs skill bodies inside its payload loop
+ * (see the `pendingSkillNames` block) and keeps processing payload entries
+ * afterwards, so an unstamped skill body — which `messagesStateReducer` then
+ * gives a UUID no payload entry carries — is followed by stamped messages.
+ * Anchoring on the UUID would look resolvable at write time and degrade to
+ * positional trimming on read, dropping the retained tail. Skipping it reaches
+ * the stamped message behind it.
+ *
+ * `convertInjectedMessages` records `injected` on everything it builds, which is
+ * what makes this decidable: `isMeta` and `source` are both optional on
+ * `InjectedMessage`, so a bare entry carries no marker of its own, and an
+ * injected `source: 'steer'` is otherwise indistinguishable from a replayed one.
+ * The remaining `isMeta`/`source` checks cover the constructors that build
+ * synthetic entries directly instead of going through that funnel — hook context
+ * in `ToolNode` and `StandardGraph`, handoff cues, reconstructed skill bodies.
+ *
+ * `steer` is exempt from the `source` check because a replayed steer *is*
+ * stamped from its payload entry; rejecting every marked `source` once dropped
+ * exactly those retained steers. Injected steers are still caught, by `injected`.
+ *
+ * Known limitation: a payload entry that omits `messageId` is never stamped, so
+ * the reducer's UUID is recorded and cannot resolve on the next run. There is no
+ * write-time fix — such an entry has no stable ID to name in the next payload
+ * either — and the reader's positional fallback is what `main` already does, so
+ * the anchor degrades rather than misleads.
+ */
+function isSyntheticContext(message: BaseMessage): boolean {
+  const { additional_kwargs: kwargs } = message;
+  if (kwargs.injected === true || kwargs.isMeta === true) {
+    return true;
+  }
+  return kwargs.source != null && kwargs.source !== 'steer';
+}
+
+function resolveSummaryCoverage(
+  messagesToRetain: BaseMessage[]
+): t.SummaryCoverage | undefined {
+  for (let i = 0; i < messagesToRetain.length; i++) {
+    const message = messagesToRetain[i];
+    if (isSyntheticContext(message)) {
+      continue;
+    }
+    const id = message.id?.trim();
+    if (id != null && id !== '') {
+      return { retainedFromMessageId: id };
+    }
+  }
+  return undefined;
+}
+
 /** Constructs the SummaryContentBlock persisted in the run step and dispatched to events. */
 function buildSummaryBlock(params: {
   summaryText: string;
   tokenCount: number;
+  coverage?: t.SummaryCoverage;
   stepId: string;
   stepIndex: number;
   modelName?: string;
@@ -400,6 +465,7 @@ function buildSummaryBlock(params: {
       } as t.MessageContentComplex,
     ],
     tokenCount: params.tokenCount,
+    ...(params.coverage != null ? { coverage: params.coverage } : {}),
     summaryVersion: params.summaryVersion,
     boundary: {
       messageId: params.stepId,
@@ -1145,6 +1211,7 @@ export function createSummarizeNode({
     const summaryBlock = buildSummaryBlock({
       summaryText,
       tokenCount,
+      coverage: resolveSummaryCoverage(messagesToRetain),
       stepId,
       stepIndex: runStep.index,
       modelName: clientConfig.modelName,

package/src/types/activityLabel.ts

@@ -38,6 +38,14 @@ export type RunActivityLabelOptions = {
   thinkingExcerpts?: string[];
   /** Assistant's last text before the block (~200 chars), as intent context. */
   lastAssistantText?: string;
+  /**
+   * Headers already committed for earlier batches in this run (run order,
+   * most recent last). Continuity context: the prompt shows them so the new
+   * header extends the run's story instead of restating a line already on
+   * screen. Hosts should pass only COMMITTED labels — a pending slot's text
+   * is empty and a dropped fill never surfaced to the user.
+   */
+  previousLabels?: string[];
   /** Override for the default label system prompt. */
   prompt?: string;
   /** Per-entry serialization cap for the prompt. Default 600. */

package/src/types/stream.ts

@@ -301,10 +301,30 @@ export type SummaryBoundary = {
   contentIndex: number;
 };
 
+/**
+ * Semantic extent of a summary: the first source message compaction retained
+ * verbatim, meaning everything before it is covered. Distinct from `boundary`,
+ * which records where the block was emitted — a retained recency tail sits
+ * *before* the block's own position, so position alone cannot say what the
+ * summary replaced.
+ *
+ * Anchored to the retained side rather than the covered side so that a source
+ * message expanding into several messages (a steer splits an assistant entry
+ * into pre-steer, steer, and post-steer entries sharing one ID) stays whole:
+ * such a message is the retained anchor and survives intact.
+ */
+export type SummaryCoverage = {
+  retainedFromMessageId: string;
+};
+
 export type SummaryContentBlock = {
   type: ContentTypes.SUMMARY;
   content?: MessageContentComplex[];
+  /** Injection budget: provider output-token space when usage was reported, plus
+   *  the wrapper added at injection time. Not comparable with per-message counts
+   *  such as `indexTokenCountMap`, which are in the consumer's own tokenizer. */
   tokenCount?: number;
+  coverage?: SummaryCoverage;
   boundary?: SummaryBoundary;
   summaryVersion?: number;
   model?: string;