@librechat/agents 3.1.57 → 3.1.61

package/src/agents/__tests__/AgentContext.test.ts

@@ -383,7 +383,7 @@ describe('AgentContext', () => {
 
       ctx.markToolsAsDiscovered(['tool1']);
       void ctx.systemRunnable;
-      ctx.instructionTokens = 100;
+      ctx.systemMessageTokens = 100;
       ctx.indexTokenCountMap = { '0': 50 };
       ctx.currentUsage = { input_tokens: 100 };
 
@@ -395,6 +395,70 @@ describe('AgentContext', () => {
       expect(ctx.currentUsage).toBeUndefined();
     });
 
+    it('preserves summarization settings across resets', () => {
+      const ctx = createBasicContext({
+        agentConfig: {
+          summarizationEnabled: true,
+          summarizationConfig: {
+            provider: Providers.ANTHROPIC,
+            model: 'claude-sonnet-4-5',
+            prompt: 'Keep decisions and next steps concise.',
+            trigger: {
+              type: 'token_ratio',
+              value: 0.8,
+            },
+          },
+        },
+      });
+
+      ctx.reset();
+
+      expect(ctx.summarizationEnabled).toBe(true);
+      expect(ctx.summarizationConfig).toEqual({
+        provider: 'anthropic',
+        model: 'claude-sonnet-4-5',
+        prompt: 'Keep decisions and next steps concise.',
+        trigger: {
+          type: 'token_ratio',
+          value: 0.8,
+        },
+      });
+    });
+
+    it('shouldSkipSummarization returns true when message count unchanged', () => {
+      const ctx = createBasicContext({
+        agentConfig: { summarizationEnabled: true },
+      });
+      ctx.markSummarizationTriggered(10);
+      expect(ctx.shouldSkipSummarization(10)).toBe(true);
+    });
+
+    it('shouldSkipSummarization returns false with any new messages', () => {
+      const ctx = createBasicContext({
+        agentConfig: { summarizationEnabled: true },
+      });
+      ctx.markSummarizationTriggered(10);
+      expect(ctx.shouldSkipSummarization(11)).toBe(false);
+    });
+
+    it('shouldSkipSummarization returns false when no prior summarization', () => {
+      const ctx = createBasicContext({
+        agentConfig: { summarizationEnabled: true },
+      });
+      expect(ctx.shouldSkipSummarization(5)).toBe(false);
+    });
+
+    it('shouldSkipSummarization allows unlimited summarizations per run', () => {
+      const ctx = createBasicContext({
+        agentConfig: { summarizationEnabled: true },
+      });
+      for (let i = 0; i < 10; i++) {
+        ctx.markSummarizationTriggered(i * 5);
+      }
+      // Even after 10 summarizations, new messages allow another
+      expect(ctx.shouldSkipSummarization(50)).toBe(false);
+    });
+
     it('rebuilds indexTokenCountMap from base map after reset', async () => {
       const tokenCounter = jest.fn(() => 5);
       const ctx = createBasicContext({
@@ -611,7 +675,7 @@ describe('AgentContext', () => {
 
       // Simulate token map update (as done in fromConfig flow)
       ctx.updateTokenMapWithInstructions({ '0': 10, '1': 20 });
-      expect(ctx.indexTokenCountMap['0']).toBe(10 + turn1Tokens);
+      expect(ctx.indexTokenCountMap['0']).toBe(10);
       expect(ctx.indexTokenCountMap['1']).toBe(20);
 
       // ========== TURN 2: Tool search results come back ==========
@@ -674,8 +738,8 @@ describe('AgentContext', () => {
       const messageTokenCounts = { '0': 50, '1': 100, '2': 75 };
       ctx.updateTokenMapWithInstructions(messageTokenCounts);
 
-      // Verify token map: first message gets instruction tokens added
-      expect(ctx.indexTokenCountMap['0']).toBe(50 + initialSystemTokens);
+      // Verify token map: first message keeps its real token count (no inflation)
+      expect(ctx.indexTokenCountMap['0']).toBe(50);
       expect(ctx.indexTokenCountMap['1']).toBe(100);
       expect(ctx.indexTokenCountMap['2']).toBe(75);
 
@@ -708,7 +772,7 @@ describe('AgentContext', () => {
       const newMessageTokenCounts = { '0': 60, '1': 110 };
       ctx.updateTokenMapWithInstructions(newMessageTokenCounts);
 
-      expect(ctx.indexTokenCountMap['0']).toBe(60 + newSystemTokens);
+      expect(ctx.indexTokenCountMap['0']).toBe(60);
       expect(ctx.indexTokenCountMap['1']).toBe(110);
     });
 
@@ -823,4 +887,200 @@ describe('AgentContext', () => {
       expect(ctx.instructionTokens).toBe(run1Tokens);
     });
   });
+
+  describe('Summary Token Accounting', () => {
+    const charTokenCounter: t.TokenCounter = (msg) => {
+      const raw = msg.content;
+      if (typeof raw === 'string') return raw.length;
+      if (Array.isArray(raw)) {
+        let total = 0;
+        for (let i = 0; i < raw.length; i++) {
+          const item = raw[i] as unknown;
+          if (typeof item === 'string') {
+            total += item.length;
+          } else if (
+            typeof item === 'object' &&
+            item != null &&
+            'text' in item
+          ) {
+            const text = (item as Record<string, unknown>).text;
+            if (typeof text === 'string') total += text.length;
+          }
+        }
+        return total;
+      }
+      return 0;
+    };
+
+    it('mid-run setSummary increases instructionTokens by the summary token count', () => {
+      const ctx = createBasicContext({
+        agentConfig: { instructions: 'Be helpful.' },
+        tokenCounter: charTokenCounter,
+      });
+
+      void ctx.systemRunnable;
+      const baseInstructionTokens = ctx.instructionTokens;
+      expect(baseInstructionTokens).toBeGreaterThan(0);
+
+      // Mid-run summary is injected as HumanMessage but still counts as
+      // instruction overhead so the pruner reserves budget for it.
+      ctx.setSummary('User asked about math. Key results: 2+2=4, 3*5=15.', 50);
+      expect(ctx.hasSummary()).toBe(true);
+
+      void ctx.systemRunnable;
+      expect(ctx.instructionTokens).toBe(baseInstructionTokens + 50);
+    });
+
+    it('summary text appears in rebuilt system message', () => {
+      const ctx = createBasicContext({
+        agentConfig: { instructions: 'Be helpful.' },
+        tokenCounter: charTokenCounter,
+      });
+
+      void ctx.systemRunnable;
+      ctx.setSummary('Prior context: user computed factorials.', 40);
+
+      const runnable = ctx.systemRunnable;
+      expect(runnable).toBeDefined();
+    });
+
+    it('clearSummary removes summary overhead from instructionTokens', () => {
+      const ctx = createBasicContext({
+        agentConfig: { instructions: 'Be helpful.' },
+        tokenCounter: charTokenCounter,
+      });
+
+      void ctx.systemRunnable;
+      const baseTokens = ctx.instructionTokens;
+
+      ctx.setSummary('Summary of the conversation so far.', 35);
+      void ctx.systemRunnable;
+      expect(ctx.instructionTokens).toBe(baseTokens + 35);
+
+      ctx.clearSummary();
+      void ctx.systemRunnable;
+      expect(ctx.instructionTokens).toBe(baseTokens);
+    });
+
+    it('reset preserves durable summary and maintains token counts', () => {
+      const ctx = createBasicContext({
+        agentConfig: { instructions: 'Be helpful.' },
+        tokenCounter: charTokenCounter,
+        indexTokenCountMap: { '0': 10, '1': 20 },
+      });
+
+      void ctx.systemRunnable;
+      ctx.setSummary('Summary text.', 15);
+      void ctx.systemRunnable;
+      expect(ctx.hasSummary()).toBe(true);
+      const tokensWithSummary = ctx.instructionTokens;
+
+      ctx.reset();
+      // Summary should survive reset (durable cross-run state)
+      expect(ctx.hasSummary()).toBe(true);
+      expect(ctx.getSummaryText()).toBe('Summary text.');
+
+      void ctx.systemRunnable;
+      const postResetTokens = ctx.instructionTokens;
+      expect(postResetTokens).toBeGreaterThan(0);
+      // Token count should be the same since summary is preserved
+      expect(postResetTokens).toBe(tokensWithSummary);
+    });
+
+    it('updateTokenMapWithInstructions copies base map without inflating index 0', () => {
+      const ctx = createBasicContext({
+        agentConfig: { instructions: 'Be helpful.' },
+        tokenCounter: charTokenCounter,
+      });
+
+      void ctx.systemRunnable;
+      ctx.setSummary('Summary of prior context with key facts.', 40);
+      void ctx.systemRunnable;
+
+      const instructionTokens = ctx.instructionTokens;
+      expect(instructionTokens).toBeGreaterThan(0);
+
+      const baseMap: Record<string, number> = { '0': 5, '1': 10 };
+      ctx.updateTokenMapWithInstructions(baseMap);
+
+      // Index 0 should contain the real message token count, NOT inflated
+      // with instruction tokens.  Instruction overhead is now handled by
+      // getInstructionTokens() in the pruning factory.
+      expect(ctx.indexTokenCountMap['0']).toBe(5);
+      expect(ctx.indexTokenCountMap['1']).toBe(10);
+    });
+
+    it('hasSummary returns false before setSummary and true after', () => {
+      const ctx = createBasicContext({
+        agentConfig: { instructions: 'Be helpful.' },
+      });
+
+      expect(ctx.hasSummary()).toBe(false);
+      ctx.setSummary('Some summary.', 10);
+      expect(ctx.hasSummary()).toBe(true);
+      ctx.clearSummary();
+      expect(ctx.hasSummary()).toBe(false);
+    });
+  });
+
+  describe('shouldSkipSummarization — re-trigger after summary', () => {
+    it('allows re-summarization after rebuildTokenMapAfterSummarization resets baseline', () => {
+      const ctx = createBasicContext();
+
+      expect(ctx.shouldSkipSummarization(25)).toBe(false);
+      ctx.markSummarizationTriggered(25);
+
+      // Same count — skip
+      expect(ctx.shouldSkipSummarization(25)).toBe(true);
+
+      ctx.setSummary('Summary of conversation', 100);
+      // Full compaction: empty state, baseline resets to 0
+      ctx.rebuildTokenMapAfterSummarization({});
+
+      // Baseline is 0 after full compaction. Guard `_lastSummarizationMsgCount > 0`
+      // is false, so all counts are allowed.
+      expect(ctx.shouldSkipSummarization(0)).toBe(false);
+      expect(ctx.shouldSkipSummarization(1)).toBe(false);
+    });
+
+    it('allows summarization after full compaction resets to empty state', () => {
+      const ctx = createBasicContext();
+
+      ctx.markSummarizationTriggered(20);
+      ctx.setSummary('Summary', 50);
+      ctx.rebuildTokenMapAfterSummarization({});
+
+      // Baseline is 0 after full compaction. The guard `_lastSummarizationMsgCount > 0`
+      // is false, so summarization is always allowed — the model starts fresh.
+      expect(ctx.shouldSkipSummarization(0)).toBe(false);
+      expect(ctx.shouldSkipSummarization(1)).toBe(false);
+    });
+  });
+
+  describe('updateLastCallUsage', () => {
+    it('records usage without modifying toolSchemaTokens', () => {
+      const ctx = createBasicContext();
+      ctx.toolSchemaTokens = 200;
+
+      ctx.updateLastCallUsage({ input_tokens: 500, output_tokens: 30 });
+
+      expect(ctx.lastCallUsage).toBeDefined();
+      expect(ctx.lastCallUsage!.inputTokens).toBe(500);
+      expect(ctx.lastCallUsage!.outputTokens).toBe(30);
+      expect(ctx.toolSchemaTokens).toBe(200);
+    });
+
+    it('handles additive cache tokens', () => {
+      const ctx = createBasicContext();
+
+      ctx.updateLastCallUsage({
+        input_tokens: 5,
+        output_tokens: 100,
+        input_token_details: { cache_creation: 8000, cache_read: 0 },
+      });
+
+      // cache_creation (8000) > input_tokens (5) → additive
+      expect(ctx.lastCallUsage!.inputTokens).toBe(8005);
+    });
+  });
 });

package/src/common/enum.ts

@@ -21,6 +21,14 @@ export enum GraphEvents {
   ON_REASONING_DELTA = 'on_reasoning_delta',
   /** [Custom] Request to execute tools - dispatched by ToolNode, handled by host */
   ON_TOOL_EXECUTE = 'on_tool_execute',
+  /** [Custom] Emitted when the summarize node begins generating a summary */
+  ON_SUMMARIZE_START = 'on_summarize_start',
+  /** [Custom] Delta event carrying the completed summary content */
+  ON_SUMMARIZE_DELTA = 'on_summarize_delta',
+  /** [Custom] Emitted when the summarize node completes with the final summary */
+  ON_SUMMARIZE_COMPLETE = 'on_summarize_complete',
+  /** [Custom] Diagnostic logging event for context management observability */
+  ON_AGENT_LOG = 'on_agent_log',
 
   /* Official Events */
 
@@ -90,6 +98,7 @@ export enum Providers {
 export enum GraphNodeKeys {
   TOOLS = 'tools=',
   AGENT = 'agent=',
+  SUMMARIZE = 'summarize=',
   ROUTER = 'router',
   PRE_TOOLS = 'pre_tools',
   POST_TOOLS = 'post_tools',
@@ -123,6 +132,8 @@ export enum ContentTypes {
   REASONING = 'reasoning',
   /** Multi-Agent Switch */
   AGENT_UPDATE = 'agent_update',
+  /** Framework-level conversation summary block */
+  SUMMARY = 'summary',
   /** Bedrock */
   REASONING_CONTENT = 'reasoning_content',
 }
@@ -169,6 +180,8 @@ export enum Constants {
   LC_TRANSFER_TO_ = 'lc_transfer_to_',
   /** Delimiter for MCP tools: toolName_mcp_serverName */
   MCP_DELIMITER = '_mcp_',
+  /** Anthropic server tool ID prefix (web_search, code_execution, etc.) */
+  ANTHROPIC_SERVER_TOOL_PREFIX = 'srvtoolu_',
 }
 
 export enum TitleMethod {

package/src/events.ts

@@ -7,8 +7,7 @@ import type {
 import type { MultiAgentGraph, StandardGraph } from '@/graphs';
 import type { Logger } from 'winston';
 import type * as t from '@/types';
-import { handleToolCalls } from '@/tools/handlers';
-import { Constants, Providers } from '@/common';
+import { Constants } from '@/common';
 
 export class HandlerRegistry {
   private handlers: Map<string, t.EventHandler> = new Map();
@@ -46,29 +45,6 @@ export class ModelEndHandler implements t.EventHandler {
     if (usage != null && this.collectedUsage != null) {
       this.collectedUsage.push(usage);
     }
-
-    if (metadata.ls_provider === 'FakeListChatModel') {
-      return handleToolCalls(data?.output?.tool_calls, metadata, graph);
-    }
-
-    console.log(`====== ${event.toUpperCase()} ======`);
-    console.dir(
-      {
-        usage,
-      },
-      { depth: null }
-    );
-
-    const agentContext = graph.getAgentContext(metadata);
-
-    if (
-      agentContext.provider !== Providers.GOOGLE &&
-      agentContext.provider !== Providers.BEDROCK
-    ) {
-      return;
-    }
-
-    await handleToolCalls(data?.output?.tool_calls, metadata, graph);
   }
 }
 
@@ -138,10 +114,8 @@ export class TestLLMStreamHandler implements t.EventHandler {
     const msg = isMessageChunk ? chunk.message : undefined;
     if (msg && msg.tool_call_chunks && msg.tool_call_chunks.length > 0) {
       console.log(msg.tool_call_chunks);
-    } else if (msg && msg.content) {
-      if (typeof msg.content === 'string') {
-        process.stdout.write(msg.content);
-      }
+    } else if (msg && typeof msg.content === 'string') {
+      process.stdout.write(msg.content);
     }
   }
 }
@@ -150,12 +124,12 @@ export class TestChatStreamHandler implements t.EventHandler {
   handle(event: string, data: t.StreamEventData | undefined): void {
     const chunk = data?.chunk;
     const isContentChunk = !!(chunk && 'content' in chunk);
-    const content = isContentChunk && chunk.content;
-
-    if (!content || !isContentChunk) {
+    if (!isContentChunk) {
       return;
     }
 
+    const content = chunk.content;
+
     if (chunk.tool_call_chunks && chunk.tool_call_chunks.length > 0) {
       console.dir(chunk.tool_call_chunks, { depth: null });
     }
@@ -176,18 +150,14 @@ export class LLMStreamHandler implements t.EventHandler {
   ): void {
     const chunk = data?.chunk;
     const isMessageChunk = !!(chunk && 'message' in chunk);
-    const msg = isMessageChunk && chunk.message;
+    const msg = isMessageChunk ? chunk.message : undefined;
     if (metadata) {
       console.log(metadata);
     }
     if (msg && msg.tool_call_chunks && msg.tool_call_chunks.length > 0) {
       console.log(msg.tool_call_chunks);
-    } else if (msg && msg.content) {
-      if (typeof msg.content === 'string') {
-        // const text_delta = msg.content;
-        // dispatchCustomEvent(GraphEvents.CHAT_MODEL_STREAM, { chunk }, config);
-        process.stdout.write(msg.content);
-      }
+    } else if (msg && typeof msg.content === 'string') {
+      process.stdout.write(msg.content);
     }
   }
 }