@librechat/agents 3.1.57 → 3.1.61

package/src/messages/cache.ts

@@ -101,19 +101,6 @@ function cloneMessage<T extends MessageWithContent>(
   return cloned;
 }
 
-/**
- * Checks if a message's content needs cache control stripping.
- * Returns true if content has cachePoint blocks or cache_control fields.
- */
-function needsCacheStripping(content: MessageContentComplex[]): boolean {
-  for (let i = 0; i < content.length; i++) {
-    const block = content[i];
-    if (isCachePoint(block)) return true;
-    if ('cache_control' in block) return true;
-  }
-  return false;
-}
-
 /**
  * Anthropic API: Adds cache control to the appropriate user messages in the payload.
  * Strips ALL existing cache control (both Anthropic and Bedrock formats) from all messages,
@@ -139,58 +126,63 @@ export function addCacheControl<T extends AnthropicMessage | BaseMessage>(
     const isUserMessage =
       ('getType' in originalMessage && originalMessage.getType() === 'human') ||
       ('role' in originalMessage && originalMessage.role === 'user');
-
     const hasArrayContent = Array.isArray(content);
-    const needsStripping =
-      hasArrayContent &&
-      needsCacheStripping(content as MessageContentComplex[]);
     const needsCacheAdd =
       userMessagesModified < 2 &&
       isUserMessage &&
       (typeof content === 'string' || hasArrayContent);
 
-    if (!needsStripping && !needsCacheAdd) {
+    // Skip messages that don't need any work
+    if (!needsCacheAdd && !hasArrayContent) {
       continue;
     }
 
     let workingContent: MessageContentComplex[];
+    let modified = false;
 
     if (hasArrayContent) {
-      workingContent = deepCloneContent(
-        content as MessageContentComplex[]
-      ).filter((block) => !isCachePoint(block as MessageContentComplex));
-
-      for (let j = 0; j < workingContent.length; j++) {
-        const block = workingContent[j] as Record<string, unknown>;
-        if ('cache_control' in block) {
-          delete block.cache_control;
+      // Single pass: clone blocks, strip cache markers and cache points,
+      // find last text block index for cache insertion — all at once.
+      const src = content as MessageContentComplex[];
+      workingContent = [];
+      let lastTextIndex = -1;
+      for (let j = 0; j < src.length; j++) {
+        const block = src[j];
+        if (isCachePoint(block)) {
+          modified = true;
+          continue; // skip cache point blocks
         }
+        const cloned = { ...block };
+        if ('cache_control' in cloned) {
+          delete (cloned as Record<string, unknown>).cache_control;
+          modified = true;
+        }
+        if ('type' in cloned && cloned.type === 'text') {
+          lastTextIndex = workingContent.length;
+        }
+        workingContent.push(cloned as MessageContentComplex);
       }
-    } else if (typeof content === 'string') {
-      workingContent = [
-        { type: 'text', text: content },
-      ] as MessageContentComplex[];
-    } else {
-      workingContent = [];
-    }
 
-    if (userMessagesModified >= 2 || !isUserMessage) {
-      updatedMessages[i] = cloneMessage(
-        originalMessage as MessageWithContent,
-        workingContent
-      ) as T;
-      continue;
-    }
+      if (!modified && !needsCacheAdd) {
+        continue; // nothing to strip and no cache to add
+      }
 
-    for (let j = workingContent.length - 1; j >= 0; j--) {
-      const contentPart = workingContent[j];
-      if ('type' in contentPart && contentPart.type === 'text') {
-        (contentPart as Anthropic.TextBlockParam).cache_control = {
+      // Add cache control to the last text block for user messages
+      if (needsCacheAdd && lastTextIndex >= 0) {
+        (
+          workingContent[lastTextIndex] as Anthropic.TextBlockParam
+        ).cache_control = {
           type: 'ephemeral',
         };
         userMessagesModified++;
-        break;
       }
+    } else if (typeof content === 'string' && needsCacheAdd) {
+      workingContent = [
+        { type: 'text', text: content, cache_control: { type: 'ephemeral' } },
+      ] as unknown as MessageContentComplex[];
+      userMessagesModified++;
+    } else {
+      continue;
     }
 
     updatedMessages[i] = cloneMessage(
@@ -325,9 +317,6 @@ export function addBedrockCacheControl<
 
     const content = originalMessage.content;
     const hasArrayContent = Array.isArray(content);
-    const needsStripping =
-      hasArrayContent &&
-      needsCacheStripping(content as MessageContentComplex[]);
     const isEmptyString = typeof content === 'string' && content === '';
     const needsCacheAdd =
       messagesModified < 2 &&
@@ -335,77 +324,63 @@ export function addBedrockCacheControl<
       !isEmptyString &&
       (typeof content === 'string' || hasArrayContent);
 
-    if (!needsStripping && !needsCacheAdd) {
+    if (!needsCacheAdd && !hasArrayContent) {
       continue;
     }
 
     let workingContent: MessageContentComplex[];
+    let modified = false;
 
     if (hasArrayContent) {
-      workingContent = deepCloneContent(
-        content as MessageContentComplex[]
-      ).filter((block) => !isCachePoint(block));
-
-      for (let j = 0; j < workingContent.length; j++) {
-        const block = workingContent[j] as Record<string, unknown>;
-        if ('cache_control' in block) {
-          delete block.cache_control;
-        }
-      }
-    } else if (typeof content === 'string') {
-      workingContent = [{ type: ContentTypes.TEXT, text: content }];
-    } else {
+      // Single pass: clone blocks, strip cache markers, find last
+      // non-empty text block for cache point insertion — all at once.
+      const src = content as MessageContentComplex[];
       workingContent = [];
-    }
-
-    if (messagesModified >= 2 || isToolMessage || isEmptyString) {
-      updatedMessages[i] = cloneMessage(originalMessage, workingContent);
-      continue;
-    }
-
-    if (workingContent.length === 0) {
-      continue;
-    }
-
-    let hasCacheableContent = false;
-    for (const block of workingContent) {
-      if (block.type === ContentTypes.TEXT) {
-        if (typeof block.text === 'string' && block.text.trim() !== '') {
-          hasCacheableContent = true;
-          break;
+      let lastNonEmptyTextIndex = -1;
+      for (let j = 0; j < src.length; j++) {
+        const block = src[j];
+        if (isCachePoint(block)) {
+          modified = true;
+          continue;
+        }
+        const cloned = { ...block };
+        if ('cache_control' in cloned) {
+          delete (cloned as Record<string, unknown>).cache_control;
+          modified = true;
         }
+        const type = (cloned as { type?: string }).type;
+        if (type === ContentTypes.TEXT || type === 'text') {
+          const text = (cloned as { text?: string }).text;
+          if (text != null && text.trim() !== '') {
+            lastNonEmptyTextIndex = workingContent.length;
+          }
+        }
+        workingContent.push(cloned as MessageContentComplex);
       }
-    }
 
-    if (!hasCacheableContent) {
-      updatedMessages[i] = cloneMessage(originalMessage, workingContent);
-      continue;
-    }
+      if (!modified && !needsCacheAdd) {
+        continue;
+      }
 
-    let inserted = false;
-    for (let j = workingContent.length - 1; j >= 0; j--) {
-      const block = workingContent[j] as MessageContentComplex;
-      const type = (block as { type?: string }).type;
-      if (type === ContentTypes.TEXT || type === 'text') {
-        const text = (block as { text?: string }).text;
-        if (text === '' || text === undefined || text.trim() === '') {
-          continue;
-        }
-        workingContent.splice(j + 1, 0, {
+      // Insert cache point after the last non-empty text block.
+      // Skip if no cacheable text content exists (whitespace-only messages).
+      if (needsCacheAdd && lastNonEmptyTextIndex >= 0) {
+        workingContent.splice(lastNonEmptyTextIndex + 1, 0, {
           cachePoint: { type: 'default' },
         } as MessageContentComplex);
-        inserted = true;
-        break;
+        messagesModified++;
       }
-    }
-    if (!inserted) {
-      workingContent.push({
-        cachePoint: { type: 'default' },
-      } as MessageContentComplex);
+    } else if (typeof content === 'string' && needsCacheAdd) {
+      workingContent = [
+        { type: ContentTypes.TEXT, text: content },
+        { cachePoint: { type: 'default' } } as MessageContentComplex,
+      ];
+      messagesModified++;
+    } else {
+      continue;
     }
 
     updatedMessages[i] = cloneMessage(originalMessage, workingContent);
-    messagesModified++;
   }
 
   return updatedMessages;

package/src/messages/contextPruning.ts

@@ -0,0 +1,191 @@
+/**
+ * Position-based context pruning for tool results.
+ *
+ * Uses position-based age: the distance of a message
+ * from the conversation end as a fraction of total messages.
+ *
+ * Two degradation levels:
+ * - Soft-trim: Keep head + tail of tool result content, drop middle.
+ * - Hard-clear: Replace entire content with a placeholder.
+ *
+ * Messages in the "protected zone" (recent assistant turns, system/pre-first-human
+ * messages, and messages with image content) are never pruned.
+ */
+
+import { ToolMessage, type BaseMessage } from '@langchain/core/messages';
+import type { ContextPruningConfig } from '@/types/graph';
+import type { TokenCounter } from '@/types/run';
+import type { ContextPruningSettings } from './contextPruningSettings';
+import { resolveContextPruningSettings } from './contextPruningSettings';
+
+/**
+ * Checks if a message contains image content blocks.
+ * Messages with images are skipped by position-based content degradation
+ * because images cannot be meaningfully soft-trimmed or replaced with placeholders.
+ */
+function hasImageContent(message: BaseMessage): boolean {
+  if (!Array.isArray(message.content)) {
+    return false;
+  }
+  return message.content.some(
+    (block) =>
+      typeof block === 'object' &&
+      'type' in block &&
+      (block.type === 'image_url' || block.type === 'image')
+  );
+}
+
+/**
+ * Applies head+tail soft-trim to tool result content.
+ */
+function softTrimContent(
+  content: string,
+  settings: ContextPruningSettings['softTrim']
+): string {
+  const { headChars, tailChars } = settings;
+  const indicator = `\n\n… [soft-trimmed: ${content.length} chars → ${headChars + tailChars} chars, middle removed] …\n\n`;
+  return content.slice(0, headChars) + indicator + content.slice(-tailChars);
+}
+
+export interface ContextPruningResult {
+  /** Number of messages that were soft-trimmed. */
+  softTrimmed: number;
+  /** Number of messages that were hard-cleared. */
+  hardCleared: number;
+}
+
+/**
+ * Applies position-based context pruning to tool result messages.
+ *
+ * Modifies messages in-place and updates indexTokenCountMap with recounted
+ * token values for modified messages.
+ *
+ * @param params.messages - The full message array (modified in-place).
+ * @param params.indexTokenCountMap - Token count map (updated in-place).
+ * @param params.tokenCounter - Function to recount tokens after modification.
+ * @param params.config - Partial context pruning config (merged with defaults).
+ * @returns Counts of soft-trimmed and hard-cleared messages.
+ */
+export function applyContextPruning(params: {
+  messages: BaseMessage[];
+  indexTokenCountMap: Record<string, number | undefined>;
+  tokenCounter: TokenCounter;
+  config?: ContextPruningConfig;
+  resolvedSettings?: ContextPruningSettings;
+}): ContextPruningResult {
+  const {
+    messages,
+    indexTokenCountMap,
+    tokenCounter,
+    config,
+    resolvedSettings,
+  } = params;
+  const settings = resolvedSettings ?? resolveContextPruningSettings(config);
+
+  if (!settings.enabled || messages.length === 0) {
+    return { softTrimmed: 0, hardCleared: 0 };
+  }
+
+  const totalMessages = messages.length;
+  let softTrimmed = 0;
+  let hardCleared = 0;
+
+  // Find the protected zone: last N assistant turns from the end.
+  // An "assistant turn" is a contiguous sequence of AI + Tool messages.
+  const protectedIndices = new Set<number>();
+
+  // Always protect the system message (index 0 if present)
+  if (messages[0]?.getType() === 'system') {
+    protectedIndices.add(0);
+  }
+
+  // Protect messages before the first human message
+  for (let i = 0; i < totalMessages; i++) {
+    if (messages[i].getType() === 'human') {
+      break;
+    }
+    protectedIndices.add(i);
+  }
+
+  // Protect the last N assistant turns (walking backwards)
+  let assistantTurnsFound = 0;
+  let inAssistantSequence = false;
+  for (let i = totalMessages - 1; i >= 0; i--) {
+    const type = messages[i].getType();
+    if (type === 'ai' || type === 'tool') {
+      protectedIndices.add(i);
+      if (!inAssistantSequence) {
+        inAssistantSequence = true;
+      }
+    } else {
+      if (inAssistantSequence) {
+        assistantTurnsFound++;
+        inAssistantSequence = false;
+        if (assistantTurnsFound >= settings.keepLastAssistants) {
+          break;
+        }
+      }
+      // Protect the human message between assistant turns in the protected zone
+      if (assistantTurnsFound < settings.keepLastAssistants) {
+        protectedIndices.add(i);
+      }
+    }
+  }
+
+  // Process each tool message outside the protected zone
+  for (let i = 0; i < totalMessages; i++) {
+    const message = messages[i];
+    if (message.getType() !== 'tool') {
+      continue;
+    }
+    if (protectedIndices.has(i)) {
+      continue;
+    }
+    if (hasImageContent(message)) {
+      continue;
+    }
+
+    const content = message.content;
+    if (typeof content !== 'string') {
+      continue;
+    }
+    if (content.length < settings.minPrunableToolChars) {
+      continue;
+    }
+
+    // Compute age ratio: how far back from the end (0 = latest, 1 = oldest)
+    const ageRatio = (totalMessages - i) / totalMessages;
+
+    if (ageRatio >= settings.hardClearRatio && settings.hardClear.enabled) {
+      // Hard-clear: replace with placeholder
+      const cloned = new ToolMessage({
+        content: settings.hardClear.placeholder,
+        tool_call_id: (message as ToolMessage).tool_call_id,
+        name: message.name,
+        id: message.id,
+        additional_kwargs: message.additional_kwargs,
+        response_metadata: message.response_metadata,
+      });
+      messages[i] = cloned;
+      indexTokenCountMap[i] = tokenCounter(cloned);
+      hardCleared++;
+    } else if (ageRatio >= settings.softTrimRatio) {
+      // Soft-trim: keep head + tail
+      if (content.length > settings.softTrim.maxChars) {
+        const cloned = new ToolMessage({
+          content: softTrimContent(content, settings.softTrim),
+          tool_call_id: (message as ToolMessage).tool_call_id,
+          name: message.name,
+          id: message.id,
+          additional_kwargs: message.additional_kwargs,
+          response_metadata: message.response_metadata,
+        });
+        messages[i] = cloned;
+        indexTokenCountMap[i] = tokenCounter(cloned);
+        softTrimmed++;
+      }
+    }
+  }
+
+  return { softTrimmed, hardCleared };
+}

package/src/messages/contextPruningSettings.ts

@@ -0,0 +1,90 @@
+/**
+ * Default settings for position-based context pruning.
+ *
+ * These are merged with user-provided overrides so any subset can be customized.
+ */
+
+export interface ContextPruningSettings {
+  /** Whether position-based pruning is enabled. Default: false (opt-in). */
+  enabled: boolean;
+  /** Number of recent assistant turns to protect from pruning. Default: 3 */
+  keepLastAssistants: number;
+  /** Age ratio (0-1) at which soft-trim fires. Default: 0.3 */
+  softTrimRatio: number;
+  /** Age ratio (0-1) at which hard-clear fires. Default: 0.5 */
+  hardClearRatio: number;
+  /** Minimum tool result size (chars) before pruning applies. Default: 50000 */
+  minPrunableToolChars: number;
+  softTrim: {
+    /** Maximum total chars after soft-trim. Default: 4000 */
+    maxChars: number;
+    /** Head portion to keep. Default: 1500 */
+    headChars: number;
+    /** Tail portion to keep. Default: 1500 */
+    tailChars: number;
+  };
+  hardClear: {
+    /** Whether hard-clear is enabled. Default: true */
+    enabled: boolean;
+    /** Placeholder text for hard-cleared content. */
+    placeholder: string;
+  };
+}
+
+export const DEFAULT_CONTEXT_PRUNING_SETTINGS: ContextPruningSettings = {
+  enabled: false,
+  keepLastAssistants: 3,
+  softTrimRatio: 0.3,
+  hardClearRatio: 0.5,
+  minPrunableToolChars: 50_000,
+  softTrim: {
+    maxChars: 4_000,
+    headChars: 1_500,
+    tailChars: 1_500,
+  },
+  hardClear: {
+    enabled: true,
+    placeholder: '[Old tool result content cleared]',
+  },
+};
+
+/**
+ * Merges user-provided partial overrides with the defaults.
+ */
+export function resolveContextPruningSettings(
+  overrides?: Partial<{
+    enabled?: boolean;
+    keepLastAssistants?: number;
+    softTrimRatio?: number;
+    hardClearRatio?: number;
+    minPrunableToolChars?: number;
+    softTrim?: Partial<ContextPruningSettings['softTrim']>;
+    hardClear?: Partial<ContextPruningSettings['hardClear']>;
+  }>
+): ContextPruningSettings {
+  if (!overrides) {
+    return { ...DEFAULT_CONTEXT_PRUNING_SETTINGS };
+  }
+  return {
+    enabled: overrides.enabled ?? DEFAULT_CONTEXT_PRUNING_SETTINGS.enabled,
+    keepLastAssistants:
+      overrides.keepLastAssistants ??
+      DEFAULT_CONTEXT_PRUNING_SETTINGS.keepLastAssistants,
+    softTrimRatio:
+      overrides.softTrimRatio ?? DEFAULT_CONTEXT_PRUNING_SETTINGS.softTrimRatio,
+    hardClearRatio:
+      overrides.hardClearRatio ??
+      DEFAULT_CONTEXT_PRUNING_SETTINGS.hardClearRatio,
+    minPrunableToolChars:
+      overrides.minPrunableToolChars ??
+      DEFAULT_CONTEXT_PRUNING_SETTINGS.minPrunableToolChars,
+    softTrim: {
+      ...DEFAULT_CONTEXT_PRUNING_SETTINGS.softTrim,
+      ...overrides.softTrim,
+    },
+    hardClear: {
+      ...DEFAULT_CONTEXT_PRUNING_SETTINGS.hardClear,
+      ...overrides.hardClear,
+    },
+  };
+}

package/src/messages/core.ts

@@ -1,10 +1,10 @@
 // src/messages.ts
 import {
-  AIMessageChunk,
-  HumanMessage,
-  ToolMessage,
   AIMessage,
   BaseMessage,
+  ToolMessage,
+  HumanMessage,
+  AIMessageChunk,
 } from '@langchain/core/messages';
 import type { ToolCall } from '@langchain/core/messages/tool';
 import type * as t from '@/types';
@@ -54,10 +54,10 @@ const modifyContent = ({
   provider: Providers;
   messageType: string;
   content: t.ExtendedMessageContent[];
-}): t.ExtendedMessageContent[] => {
+}): (t.ExtendedMessageContent | null)[] => {
   const allowedTypes =
     allowedTypesByProvider[provider] ?? allowedTypesByProvider.default;
-  return content.map((item) => {
+  return content.map((item: t.ExtendedMessageContent | null) => {
     if (
       item &&
       typeof item === 'object' &&
@@ -153,7 +153,7 @@ export function modifyDeltaProperties(
       provider,
       messageType,
       content: obj.content,
-    });
+    }) as t.MessageContentComplex[];
   }
   if (
     (obj as Partial<AIMessageChunk>).lc_kwargs &&
@@ -365,31 +365,29 @@ export function formatAnthropicArtifactContent(messages: BaseMessage[]): void {
 
   if (latestAIParentIndex === -1) return;
 
-  // Check if any tool message after the AI message has array artifact content
-  const hasArtifactContent = messages.some(
-    (msg, i) =>
-      i > latestAIParentIndex &&
-      msg instanceof ToolMessage &&
-      msg.artifact != null &&
-      msg.artifact?.content != null &&
-      Array.isArray(msg.artifact.content)
-  );
-
-  if (!hasArtifactContent) return;
-
+  // Build tool call ID set and merge artifact content in a single forward pass.
   const message = messages[latestAIParentIndex] as AIMessageChunk;
-  const toolCallIds = message.tool_calls?.map((tc) => tc.id) ?? [];
+  const toolCallIdSet = new Set<string>();
+  if (message.tool_calls) {
+    for (const tc of message.tool_calls) {
+      if (tc.id != null) {
+        toolCallIdSet.add(tc.id);
+      }
+    }
+  }
 
   for (let j = latestAIParentIndex + 1; j < messages.length; j++) {
     const msg = messages[j];
     if (
       msg instanceof ToolMessage &&
-      toolCallIds.includes(msg.tool_call_id) &&
+      toolCallIdSet.has(msg.tool_call_id) &&
       msg.artifact != null &&
-      Array.isArray(msg.artifact?.content) &&
-      Array.isArray(msg.content)
+      Array.isArray(msg.artifact?.content)
     ) {
-      msg.content = msg.content.concat(msg.artifact.content);
+      const base = Array.isArray(msg.content)
+        ? msg.content
+        : [{ type: 'text' as const, text: String(msg.content ?? '') }];
+      msg.content = base.concat(msg.artifact.content);
     }
   }
 }
@@ -410,46 +408,27 @@ export function formatArtifactPayload(messages: BaseMessage[]): void {
 
   if (latestAIParentIndex === -1) return;
 
-  // Check if any tool message after the AI message has array artifact content
-  const hasArtifactContent = messages.some(
-    (msg, i) =>
-      i > latestAIParentIndex &&
-      msg instanceof ToolMessage &&
-      msg.artifact != null &&
-      msg.artifact?.content != null &&
-      Array.isArray(msg.artifact.content)
-  );
-
-  if (!hasArtifactContent) return;
-
-  // Collect all relevant tool messages and their artifacts
-  const relevantMessages = messages
-    .slice(latestAIParentIndex + 1)
-    .filter((msg) => msg instanceof ToolMessage) as ToolMessage[];
-
-  // Aggregate all content and artifacts
+  // Single pass: collect relevant tool messages with artifacts and aggregate
   const aggregatedContent: t.MessageContentComplex[] = [];
 
-  relevantMessages.forEach((msg) => {
-    if (!Array.isArray(msg.artifact?.content)) {
-      return;
+  for (let i = latestAIParentIndex + 1; i < messages.length; i++) {
+    const msg = messages[i];
+    if (
+      !(msg instanceof ToolMessage) ||
+      !Array.isArray(msg.artifact?.content)
+    ) {
+      continue;
     }
     let currentContent = msg.content;
     if (!Array.isArray(currentContent)) {
-      currentContent = [
-        {
-          type: 'text',
-          text: msg.content,
-        },
-      ];
+      currentContent = [{ type: 'text', text: msg.content }];
     }
-    aggregatedContent.push(...currentContent);
+    aggregatedContent.push(...(currentContent as t.MessageContentComplex[]));
     msg.content =
       'Tool response is included in the next message as a Human message';
     aggregatedContent.push(...msg.artifact.content);
-  });
+  }
 
-  // Add single HumanMessage with all aggregated content
   if (aggregatedContent.length > 0) {
     messages.push(new HumanMessage({ content: aggregatedContent }));
   }