@librechat/agents 3.3.6 → 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/tools/__tests__/intentArg.test.ts

@@ -4,6 +4,8 @@ import {
   INTENT_ARG,
   INTENT_PROPERTY,
   INTENT_DESCRIPTION,
+  INTENT_LABEL_MARKER,
+  withoutIntent,
   withIntent,
   readIntent,
   stripIntent,
@@ -11,6 +13,7 @@ import {
   readOutcomeFields,
   resolveToolOutcome,
 } from '../intentArg';
+import { ReadFileToolSchema } from '../ReadFile';
 
 describe('withIntent', () => {
   const base: JsonSchemaType = {
@@ -72,7 +75,83 @@ describe('withIntent', () => {
   it('carries the model-facing instruction', () => {
     expect(INTENT_PROPERTY.description).toBe(INTENT_DESCRIPTION);
     expect(INTENT_DESCRIPTION).toContain('FIRST');
-    expect(INTENT_DESCRIPTION).toContain('distinguish that call from its siblings');
+    /** Sibling differentiation is the headline case; models emit identical
+     *  labels for parallel calls without it. */
+    expect(INTENT_DESCRIPTION).toContain('Sibling calls to one tool must differ');
+  });
+
+  it('opens with the exported marker so host strip passes can key on it', () => {
+    expect(INTENT_DESCRIPTION.startsWith(INTENT_LABEL_MARKER)).toBe(true);
+  });
+
+  it('stays terse — it is repeated per tool, per request', () => {
+    expect(INTENT_DESCRIPTION.length).toBeLessThanOrEqual(300);
+  });
+});
+
+describe('withoutIntent', () => {
+  it('removes the injected label — the opt-out for embedders that render none', () => {
+    const withLabel = withIntent({
+      type: 'object',
+      properties: { query: { type: 'string' } },
+      required: ['query'],
+    });
+    const stripped = withoutIntent(withLabel);
+    expect(Object.keys(stripped?.properties ?? {})).toEqual(['query']);
+    expect(stripped?.required).toEqual(['query']);
+  });
+
+  it('never removes a tool-owned business `intent` parameter', () => {
+    const business: JsonSchemaType = {
+      type: 'object',
+      properties: { intent: { type: 'string', description: 'CRM intent category' } },
+      required: ['intent'],
+    };
+    expect(withoutIntent(business)).toBe(business);
+  });
+
+  it('is a no-op on schemas without the label', () => {
+    const plain: JsonSchemaType = { type: 'object', properties: { q: { type: 'string' } } };
+    expect(withoutIntent(plain)).toBe(plain);
+    expect(withoutIntent(undefined)).toBeUndefined();
+  });
+
+  it('prunes intent from `required` too, so the schema stays valid', () => {
+    /** Strict-mode normalization lists every property in `required`; leaving
+     *  a dangling entry yields invalid JSON Schema the provider rejects. */
+    const strict: JsonSchemaType = {
+      type: 'object',
+      properties: { intent: { ...INTENT_PROPERTY }, path: { type: 'string' } },
+      required: ['intent', 'path'],
+    };
+    const stripped = withoutIntent(strict);
+    expect(Object.keys(stripped?.properties ?? {})).toEqual(['path']);
+    expect(stripped?.required).toEqual(['path']);
+  });
+
+  it('drops `required` entirely when intent was its only entry', () => {
+    const onlyIntent: JsonSchemaType = {
+      type: 'object',
+      properties: { intent: { ...INTENT_PROPERTY } },
+      required: ['intent'],
+    };
+    const stripped = withoutIntent(onlyIntent);
+    expect(stripped?.required).toBeUndefined();
+    expect(Object.keys(stripped?.properties ?? {})).toEqual([]);
+  });
+
+  it('accepts a readonly `as const` native schema without a cast', () => {
+    /** ReadFileToolSchema is declared `as const`, so `required` is a readonly
+     *  tuple — this call is the compile-time assertion that the advertised
+     *  opt-out is usable on the schemas it exists for. */
+    const stripped = withoutIntent(ReadFileToolSchema);
+    expect(Object.keys(stripped?.properties ?? {})).toEqual(['path']);
+    expect(stripped?.required).toEqual(['path']);
+  });
+
+  it('round-trips with withIntent', () => {
+    const base: JsonSchemaType = { type: 'object', properties: { q: { type: 'string' } } };
+    expect(withoutIntent(withIntent(base))).toEqual(base);
   });
 });
 
@@ -130,7 +209,7 @@ describe('applyOutcome', () => {
   });
 
   it('ignores a blank outcome', () => {
-    expect(applyOutcome(intent, { outcome: '  ' })).toBe('Searched for OAuth handling');
+    expect(applyOutcome(intent, { outcome: '  ' })).toBe(intent);
   });
 
   it('applies outcome_patch to the first occurrence only, case-sensitive', () => {
@@ -141,34 +220,31 @@ describe('applyOutcome', () => {
     ).toBe('Searched for Searching patterns');
     expect(
       applyOutcome(intent, { outcome_patch: { from: 'searching', to: 'searched' } })
-    ).toBe('Searched for OAuth handling');
+    ).toBe(intent);
   });
 
   it('ignores a patch whose from is empty or absent from the intent', () => {
-    expect(applyOutcome(intent, { outcome_patch: { from: '', to: 'x' } })).toBe(
-      'Searched for OAuth handling'
-    );
+    expect(applyOutcome(intent, { outcome_patch: { from: '', to: 'x' } })).toBe(intent);
     expect(applyOutcome(intent, { outcome_patch: { from: 'Grepping', to: 'Grepped' } })).toBe(
-      'Searched for OAuth handling'
+      intent
     );
   });
 
-  it('mechanically transforms the leading verb', () => {
-    expect(applyOutcome('Reading the callback router')).toBe('Read the callback router');
-    expect(applyOutcome('Writing the zod schema')).toBe('Wrote the zod schema');
-    expect(applyOutcome('Delegating the OAuth audit')).toBe('Delegated the OAuth audit');
-  });
-
-  it('preserves a lowercase leading verb', () => {
-    expect(applyOutcome('searching for OAuth handling')).toBe('searched for OAuth handling');
-  });
-
-  it('leaves an unknown leading word unchanged', () => {
-    expect(applyOutcome('Refactoring the zod schema')).toBe('Refactoring the zod schema');
-  });
-
-  it('handles a single-word intent', () => {
-    expect(applyOutcome('Searching')).toBe('Searched');
+  /**
+   * There is no mechanical tense rewrite: a closed English verb list would
+   * never fire for non-English labels, and would fire for some siblings but
+   * not others inside one group. Completion is a UI state, not a tense.
+   */
+  it('returns the intent unchanged when the tool authored no outcome', () => {
+    for (const label of [
+      'Reading the callback router',
+      'Recording the OAuth callback location',
+      'searching for OAuth handling',
+      'Buscando el manejo de OAuth',
+      'Searching',
+    ]) {
+      expect(applyOutcome(label)).toBe(label);
+    }
   });
 
   it('returns undefined with neither intent nor outcome', () => {
@@ -215,7 +291,7 @@ describe('resolveToolOutcome', () => {
     expect(oversized?.length).toBe(256);
     expect(oversized?.endsWith('…')).toBe(true);
     expect(resolveToolOutcome(args, { outcome: ' \n \t ' })).toBe(
-      'Searched for OAuth handling'
+      'Searching for OAuth handling'
     );
   });
 
@@ -240,7 +316,7 @@ describe('resolveToolOutcome', () => {
     ).toBe('Search failed for OAuth handling');
   });
 
-  it('never falls back to the mechanical transform on a failed call', () => {
+  it('never reuses the in-flight intent as a failed call\'s settled label', () => {
     expect(
       resolveToolOutcome(
         args,