@librechat/agents 3.2.21 → 3.2.32

package/src/llm/invoke.ts

@@ -5,8 +5,8 @@ import type { ToolCall } from '@langchain/core/messages/tool';
 import type { BaseMessage } from '@langchain/core/messages';
 import type { ToolOutputReferenceRegistry } from '@/tools/toolOutputReferences';
 import type * as t from '@/types';
-import { manualToolStreamProviders } from '@/llm/providers';
 import { annotateMessagesForLLM } from '@/tools/toolOutputReferences';
+import { manualToolStreamProviders } from '@/llm/providers';
 import { modifyDeltaProperties } from '@/messages';
 import { ChatModelStreamHandler } from '@/stream';
 import { GraphEvents, Providers } from '@/common';
@@ -51,6 +51,127 @@ export type InvokeContext = NonNullable<
  */
 export type OnChunk = (chunk: AIMessageChunk) => void | Promise<void>;
 
+function getRegisteredDefaultChatStreamHandler(
+  context?: InvokeContext
+): ChatModelStreamHandler | undefined {
+  const handler = context?.handlerRegistry?.getHandler(
+    GraphEvents.CHAT_MODEL_STREAM
+  );
+  return handler instanceof ChatModelStreamHandler ? handler : undefined;
+}
+
+function hasReasoningDetails(chunk: AIMessageChunk): boolean {
+  const reasoningDetails = chunk.additional_kwargs.reasoning_details;
+  return Array.isArray(reasoningDetails) && reasoningDetails.length > 0;
+}
+
+function removeOpenRouterFinalReasoningReplayContent({
+  current,
+  next,
+  provider,
+}: {
+  current?: AIMessageChunk;
+  next: AIMessageChunk;
+  provider: Providers;
+}): AIMessageChunk {
+  const content = getOpenRouterFinalReasoningContent({
+    current,
+    next,
+    provider,
+  });
+  if (content == null || content === next.content) {
+    return next;
+  }
+
+  return new AIMessageChunk(
+    Object.assign({}, next, {
+      content,
+    })
+  );
+}
+
+function getOpenRouterFinalReasoningContent({
+  current,
+  next,
+  provider,
+}: {
+  current?: AIMessageChunk;
+  next: AIMessageChunk;
+  provider: Providers;
+}): string | undefined {
+  if (
+    provider !== Providers.OPENROUTER ||
+    current == null ||
+    !hasReasoningDetails(next) ||
+    typeof current.content !== 'string' ||
+    current.content === '' ||
+    typeof next.content !== 'string' ||
+    next.content === ''
+  ) {
+    return undefined;
+  }
+  if (!next.content.startsWith(current.content)) {
+    return next.content;
+  }
+  return next.content.slice(current.content.length);
+}
+
+function removeReasoningDetails(
+  additionalKwargs: AIMessageChunk['additional_kwargs']
+): AIMessageChunk['additional_kwargs'] {
+  return Object.fromEntries(
+    Object.entries(additionalKwargs).filter(
+      ([key]) => key !== 'reasoning_details'
+    )
+  );
+}
+
+function getStreamHandlingChunk({
+  current,
+  next,
+  provider,
+}: {
+  current?: AIMessageChunk;
+  next: AIMessageChunk;
+  provider: Providers;
+}): AIMessageChunk | undefined {
+  const content = getOpenRouterFinalReasoningContent({
+    current,
+    next,
+    provider,
+  });
+  if (content == null) {
+    return next;
+  }
+  if (content === '') {
+    return undefined;
+  }
+  return new AIMessageChunk(
+    Object.assign({}, next, {
+      content,
+      additional_kwargs: removeReasoningDetails(next.additional_kwargs),
+    })
+  );
+}
+
+function appendStreamChunk({
+  current,
+  next,
+  provider,
+}: {
+  current?: AIMessageChunk;
+  next: AIMessageChunk;
+  provider: Providers;
+}): AIMessageChunk {
+  if (current == null) {
+    return next;
+  }
+  return concat(
+    current,
+    removeOpenRouterFinalReasoningReplayContent({ current, next, provider })
+  );
+}
+
 /**
  * Invokes a chat model with the given messages, handling both streaming and
  * non-streaming paths.
@@ -90,23 +211,62 @@ export async function attemptInvoke(
   if (model.stream) {
     const stream = await model.stream(messagesForProvider, config);
     let finalChunk: AIMessageChunk | undefined;
+    const registeredStreamHandler =
+      getRegisteredDefaultChatStreamHandler(context);
 
     if (onChunk) {
       for await (const chunk of stream) {
         await onChunk(chunk);
-        finalChunk = finalChunk ? concat(finalChunk, chunk) : chunk;
+        finalChunk = appendStreamChunk({
+          current: finalChunk,
+          next: chunk,
+          provider,
+        });
       }
-    } else {
+    } else if (registeredStreamHandler == null) {
       const metadata = config?.metadata as Record<string, unknown> | undefined;
       const streamHandler = new ChatModelStreamHandler();
       for await (const chunk of stream) {
-        await streamHandler.handle(
-          GraphEvents.CHAT_MODEL_STREAM,
-          { chunk },
-          metadata,
-          context
-        );
-        finalChunk = finalChunk ? concat(finalChunk, chunk) : chunk;
+        const handlingChunk = getStreamHandlingChunk({
+          current: finalChunk,
+          next: chunk,
+          provider,
+        });
+        if (handlingChunk != null) {
+          await streamHandler.handle(
+            GraphEvents.CHAT_MODEL_STREAM,
+            { chunk: handlingChunk },
+            metadata,
+            context
+          );
+        }
+        finalChunk = appendStreamChunk({
+          current: finalChunk,
+          next: chunk,
+          provider,
+        });
+      }
+    } else {
+      const metadata = config?.metadata as Record<string, unknown> | undefined;
+      for await (const chunk of stream) {
+        const handlingChunk = getStreamHandlingChunk({
+          current: finalChunk,
+          next: chunk,
+          provider,
+        });
+        if (handlingChunk != null && handlingChunk !== chunk) {
+          await registeredStreamHandler.handle(
+            GraphEvents.CHAT_MODEL_STREAM,
+            { chunk: handlingChunk },
+            metadata,
+            context
+          );
+        }
+        finalChunk = appendStreamChunk({
+          current: finalChunk,
+          next: chunk,
+          provider,
+        });
       }
     }
 

package/src/llm/openai/index.ts

@@ -1,18 +1,18 @@
 import { AzureOpenAI as AzureOpenAIClient } from 'openai';
 import { ChatXAI as OriginalChatXAI } from '@langchain/xai';
 import { ChatGenerationChunk } from '@langchain/core/outputs';
+import { ToolDefinition } from '@langchain/core/language_models/base';
+import { ChatDeepSeek as OriginalChatDeepSeek } from '@langchain/deepseek';
+import { CallbackManagerForLLMRun } from '@langchain/core/callbacks/manager';
 import {
   AIMessage,
   AIMessageChunk,
   isAIMessage,
 } from '@langchain/core/messages';
-import { ToolDefinition } from '@langchain/core/language_models/base';
 import {
   convertToOpenAITool,
   isLangChainTool,
 } from '@langchain/core/utils/function_calling';
-import { ChatDeepSeek as OriginalChatDeepSeek } from '@langchain/deepseek';
-import { CallbackManagerForLLMRun } from '@langchain/core/callbacks/manager';
 import {
   getEndpoint,
   OpenAIClient,
@@ -24,7 +24,6 @@ import {
   AzureChatOpenAIResponses as OriginalAzureChatOpenAIResponses,
   AzureChatOpenAICompletions as OriginalAzureChatOpenAICompletions,
 } from '@langchain/openai';
-import type { HeaderValue, HeadersLike } from './types';
 import type {
   BaseMessage,
   BaseMessageChunk,
@@ -34,6 +33,7 @@ import type { BindToolsInput } from '@langchain/core/language_models/chat_models
 import type { ChatGeneration, ChatResult } from '@langchain/core/outputs';
 import type { ChatXAIInput } from '@langchain/xai';
 import type * as t from '@langchain/openai';
+import type { HeaderValue, HeadersLike } from './types';
 import { isReasoningModel, _convertMessagesToOpenAIParams } from './utils';
 
 // eslint-disable-next-line @typescript-eslint/explicit-function-return-type

package/src/llm/openai/utils/index.ts

@@ -1,12 +1,12 @@
 /* eslint-disable @typescript-eslint/ban-ts-comment */
 /* eslint-disable @typescript-eslint/explicit-function-return-type */
 import { type OpenAI as OpenAIClient } from 'openai';
-import type {
-  ChatCompletionContentPartText,
-  ChatCompletionContentPartImage,
-  ChatCompletionContentPartInputAudio,
-  ChatCompletionContentPart,
-} from 'openai/resources/chat/completions';
+import { ChatGenerationChunk } from '@langchain/core/outputs';
+import {
+  convertLangChainToolCallToOpenAI,
+  makeInvalidToolCall,
+  parseToolCall,
+} from '@langchain/core/output_parsers/openai_tools';
 import {
   AIMessage,
   AIMessageChunk,
@@ -25,24 +25,24 @@ import {
   convertToProviderContentBlock,
   isDataContentBlock,
 } from '@langchain/core/messages';
-import { ChatGenerationChunk } from '@langchain/core/outputs';
-import {
-  convertLangChainToolCallToOpenAI,
-  makeInvalidToolCall,
-  parseToolCall,
-} from '@langchain/core/output_parsers/openai_tools';
-import type { ToolCall, ToolCallChunk } from '@langchain/core/messages/tool';
+import type {
+  ChatCompletionContentPartText,
+  ChatCompletionContentPartImage,
+  ChatCompletionContentPartInputAudio,
+  ChatCompletionContentPart,
+} from 'openai/resources/chat/completions';
 import type {
   OpenAICallOptions,
   OpenAIChatInput,
   ChatOpenAIReasoningSummary,
 } from '@langchain/openai';
-import { toLangChainContent } from '@/messages/langchain';
+import type { ToolCall, ToolCallChunk } from '@langchain/core/messages/tool';
 import {
   STREAMED_TOOL_CALL_SEAL_METADATA_KEY,
   STREAMED_TOOL_CALL_ADAPTER_METADATA_KEY,
   OPENAI_RESPONSES_STREAMED_TOOL_CALL_ADAPTER,
 } from '@/tools/streamedToolCallSeals';
+import { toLangChainContent } from '@/messages/langchain';
 
 export type { OpenAICallOptions, OpenAIChatInput };
 

package/src/llm/openrouter/index.ts

@@ -1,12 +1,12 @@
-import { ChatOpenAI, emitStreamChunkCallback } from '@/llm/openai';
-import type { BaseMessage } from '@langchain/core/messages';
-import type { ChatGenerationChunk } from '@langchain/core/outputs';
-import type { CallbackManagerForLLMRun } from '@langchain/core/callbacks/manager';
 import type {
   ChatOpenAICallOptions,
   OpenAIChatInput,
   OpenAIClient,
 } from '@langchain/openai';
+import type { CallbackManagerForLLMRun } from '@langchain/core/callbacks/manager';
+import type { ChatGenerationChunk } from '@langchain/core/outputs';
+import type { BaseMessage } from '@langchain/core/messages';
+import { ChatOpenAI, emitStreamChunkCallback } from '@/llm/openai';
 
 export type OpenRouterReasoningEffort =
   | 'xhigh'

package/src/llm/openrouter/reasoning.test.ts

@@ -1,6 +1,6 @@
-import { ChatOpenRouter } from './index';
-import type { OpenRouterReasoning, ChatOpenRouterCallOptions } from './index';
 import type { OpenAIChatInput } from '@langchain/openai';
+import type { OpenRouterReasoning, ChatOpenRouterCallOptions } from './index';
+import { ChatOpenRouter } from './index';
 
 type CreateRouterOptions = Partial<
   ChatOpenRouterCallOptions &

package/src/llm/vertexai/fixThoughtSignatures.test.ts

@@ -1,6 +1,6 @@
 import { expect, test, describe } from '@jest/globals';
-import type { GeminiContent } from '@langchain/google-common';
 import { AIMessage, HumanMessage, ToolMessage } from '@langchain/core/messages';
+import type { GeminiContent } from '@langchain/google-common';
 import { fixThoughtSignatures } from './index';
 
 const SIG_A = 'AY89a1/sigA==';

package/src/llm/vertexai/index.ts

@@ -1,5 +1,6 @@
 import { ChatGoogle } from '@langchain/google-gauth';
 import { ChatConnection } from '@langchain/google-common';
+import { AIMessageChunk, isAIMessage } from '@langchain/core/messages';
 import type {
   GeminiContent,
   GeminiRequest,
@@ -8,7 +9,6 @@ import type {
 } from '@langchain/google-common';
 import type { CallbackManagerForLLMRun } from '@langchain/core/callbacks/manager';
 import type { BaseMessage, UsageMetadata } from '@langchain/core/messages';
-import { AIMessageChunk, isAIMessage } from '@langchain/core/messages';
 import type { ChatGenerationChunk } from '@langchain/core/outputs';
 import type { GoogleThinkingConfig, VertexAIClientOptions } from '@/types';
 

package/src/messages/cache.test.ts

@@ -13,9 +13,11 @@ import {
   stripBedrockCacheControl,
   addBedrockCacheControl,
   addCacheControl,
+  addCacheControlToStablePrefixMessages,
 } from './cache';
 import { _convertMessagesToOpenAIParams } from '@/llm/openai/utils';
 import { toLangChainContent } from './langchain';
+import { formatAgentMessages } from './format';
 import { ContentTypes } from '@/common/enum';
 
 type CacheControlBlock = MessageContentComplex & {
@@ -766,6 +768,127 @@ describe('addBedrockCacheControl (Bedrock cache checkpoints)', () => {
   });
 });
 
+describe('synthetic skill/meta messages are not cache-anchored', () => {
+  const hasAnthropicMarker = (m: BaseMessage): boolean =>
+    Array.isArray(m.content) &&
+    m.content.some((block) => 'cache_control' in block);
+
+  const hasBedrockCachePoint = (m: BaseMessage): boolean =>
+    Array.isArray(m.content) &&
+    m.content.some((block) => 'cachePoint' in block);
+
+  const skillBody = (skillName: string, content = 'SKILL BODY'): HumanMessage =>
+    new HumanMessage({
+      content,
+      additional_kwargs: { isMeta: true, source: 'skill', skillName },
+    });
+
+  it('Anthropic: skips a trailing synthetic skill message; markers land on the real user messages', () => {
+    const messages: BaseMessage[] = [
+      new HumanMessage('First real question'),
+      new AIMessage('Answer'),
+      new HumanMessage('Second real question'),
+      skillBody('pdf-analyzer'),
+    ];
+
+    const result = addCacheControl<BaseMessage>(messages);
+
+    expect(hasAnthropicMarker(result[3])).toBe(false);
+    expect(hasAnthropicMarker(result[2])).toBe(true);
+    expect(hasAnthropicMarker(result[0])).toBe(true);
+  });
+
+  it('Anthropic: strips a stale marker from a synthetic skill message without re-adding one', () => {
+    const stale = new HumanMessage({
+      content: toLangChainContent([
+        {
+          type: 'text',
+          text: 'SKILL BODY',
+          cache_control: { type: 'ephemeral' },
+        } as MessageContentComplex,
+      ]),
+      additional_kwargs: {
+        isMeta: true,
+        source: 'skill',
+        skillName: 'pdf-analyzer',
+      },
+    });
+    const messages: BaseMessage[] = [
+      new HumanMessage('Real question'),
+      new AIMessage('Answer'),
+      stale,
+    ];
+
+    const result = addCacheControl<BaseMessage>(messages);
+
+    expect(hasAnthropicMarker(result[2])).toBe(false);
+    expect(hasAnthropicMarker(result[0])).toBe(true);
+  });
+
+  it('Anthropic: detects skill messages by additional_kwargs.source even without isMeta', () => {
+    const messages: BaseMessage[] = [
+      new HumanMessage('Real question'),
+      new AIMessage('Answer'),
+      new HumanMessage({
+        content: 'SKILL BODY',
+        additional_kwargs: { source: 'skill', skillName: 'pdf-analyzer' },
+      }),
+    ];
+
+    const result = addCacheControl<BaseMessage>(messages);
+
+    expect(hasAnthropicMarker(result[2])).toBe(false);
+    expect(hasAnthropicMarker(result[0])).toBe(true);
+  });
+
+  it('Bedrock: skips a trailing synthetic skill message; cachePoints land on the real user messages', () => {
+    const messages: BaseMessage[] = [
+      new HumanMessage('First real question'),
+      new AIMessage('Answer'),
+      new HumanMessage('Second real question'),
+      skillBody('pdf-analyzer'),
+    ];
+
+    const result = addBedrockCacheControl<BaseMessage>(messages);
+
+    expect(hasBedrockCachePoint(result[3])).toBe(false);
+    expect(hasBedrockCachePoint(result[2])).toBe(true);
+    expect(hasBedrockCachePoint(result[0])).toBe(true);
+  });
+
+  it('stable-prefix fallback: anchors the real user message, not a synthetic skill message', () => {
+    // Mirrors AgentContext's dynamic-tail path: the only assistant message is a
+    // skill-only tool call (no text), so the assistant-only pass adds no marker
+    // and the cacheable fallback runs. It must skip the reconstructed skill
+    // HumanMessage and anchor the real user message instead.
+    const messages: BaseMessage[] = [
+      new HumanMessage('Real stable question'),
+      new AIMessage({
+        content: toLangChainContent([
+          {
+            type: 'tool_use',
+            id: 'call_1',
+            name: 'skill',
+            input: { skillName: 'pdf-analyzer' },
+          } as MessageContentComplex,
+        ]),
+        tool_calls: [
+          { id: 'call_1', name: 'skill', args: { skillName: 'pdf-analyzer' } },
+        ],
+      }),
+      skillBody('pdf-analyzer'),
+    ];
+
+    const result = addCacheControlToStablePrefixMessages<BaseMessage>(
+      messages,
+      2
+    );
+
+    expect(hasAnthropicMarker(result[2])).toBe(false);
+    expect(hasAnthropicMarker(result[0])).toBe(true);
+  });
+});
+
 describe('stripAnthropicCacheControl', () => {
   it('removes cache_control fields from content blocks', () => {
     const messages: TestMsg[] = [
@@ -1474,6 +1597,27 @@ describe('Multi-turn cache cleanup', () => {
 });
 
 describe('LangChain message type preservation', () => {
+  it('preserves direct roles for formatted LangChain messages after addCacheControl', () => {
+    const { messages } = formatAgentMessages([
+      { role: 'user', content: 'Hello' },
+      { role: 'assistant', content: 'Hi there' },
+      { role: 'user', content: 'Thanks' },
+    ]);
+
+    const result = addCacheControl(messages);
+
+    expect(result.map((message) => message.role)).toEqual([
+      'user',
+      'assistant',
+      'user',
+    ]);
+    expect(result[0]).toBeInstanceOf(HumanMessage);
+    expect(result[0]).not.toBe(messages[0]);
+    expect(Object.keys(result[0])).not.toContain('role');
+    expect(result[1]).toBe(messages[1]);
+    expect(result[2]).not.toBe(messages[2]);
+  });
+
   it('should preserve instanceof for LangChain messages after addCacheControl', () => {
     const messages: BaseMessage[] = [
       new HumanMessage({ content: [{ type: 'text', text: 'Hello' }] }),

package/src/messages/cache.ts

@@ -6,10 +6,11 @@ import {
   SystemMessage,
   MessageContentComplex,
 } from '@langchain/core/messages';
-import type { AnthropicMessage } from '@/types/messages';
 import type Anthropic from '@anthropic-ai/sdk';
-import { ContentTypes } from '@/common/enum';
+import type { AnthropicMessage } from '@/types/messages';
 import { toLangChainContent } from './langchain';
+import { ContentTypes } from '@/common/enum';
+import { withMessageRole } from './format';
 
 type MessageWithContent = {
   content?: string | MessageContentComplex[];
@@ -56,19 +57,31 @@ function cloneMessage<T extends MessageWithContent>(
     const msgType = message.getType();
     switch (msgType) {
     case 'ai':
-      return new AIMessage({
-        ...baseParams,
-        tool_calls: (message as unknown as AIMessage).tool_calls,
-      }) as unknown as T;
+      return withMessageRole(
+        new AIMessage({
+          ...baseParams,
+          tool_calls: (message as unknown as AIMessage).tool_calls,
+        }),
+        'assistant'
+      ) as unknown as T;
     case 'human':
-      return new HumanMessage(baseParams) as unknown as T;
+      return withMessageRole(
+        new HumanMessage(baseParams),
+        'user'
+      ) as unknown as T;
     case 'system':
-      return new SystemMessage(baseParams) as unknown as T;
+      return withMessageRole(
+        new SystemMessage(baseParams),
+        'system'
+      ) as unknown as T;
     case 'tool':
-      return new ToolMessage({
-        ...baseParams,
-        tool_call_id: (message as unknown as ToolMessage).tool_call_id,
-      }) as unknown as T;
+      return withMessageRole(
+        new ToolMessage({
+          ...baseParams,
+          tool_call_id: (message as unknown as ToolMessage).tool_call_id,
+        }),
+        'tool'
+      ) as unknown as T;
     default:
       break;
     }
@@ -169,6 +182,7 @@ export function addCacheControl<T extends AnthropicMessage | BaseMessage>(
     const needsCacheAdd =
       userMessagesModified < 2 &&
       isUserMessage &&
+      !isSyntheticMetaMessage(originalMessage) &&
       (typeof content === 'string' || hasArrayContent);
 
     // Skip messages that don't need any work
@@ -250,6 +264,26 @@ function getMessageRole(message: MessageWithContent): string | undefined {
   return undefined;
 }
 
+const SKILL_MESSAGE_SOURCE = 'skill';
+
+/**
+ * Synthetic skill/meta messages (reconstructed skill bodies, primed SKILL.md
+ * instructions) are re-injected every turn and are not stable conversation
+ * turns. They must not anchor a fresh prompt-cache marker — doing so pins the
+ * cache to a volatile/duplicated prefix. Stale markers are still stripped from
+ * them; only the *adding* of new markers is suppressed. Detected via
+ * `additional_kwargs.isMeta === true` or `additional_kwargs.source === 'skill'`.
+ */
+function isSyntheticMetaMessage(message: MessageWithContent): boolean {
+  const { additional_kwargs: kwargs } = message as {
+    additional_kwargs?: { isMeta?: unknown; source?: unknown };
+  };
+  if (kwargs == null) {
+    return false;
+  }
+  return kwargs.isMeta === true || kwargs.source === SKILL_MESSAGE_SOURCE;
+}
+
 function isCacheableConversationMessage(message: MessageWithContent): boolean {
   const role = getMessageRole(message);
   return (
@@ -292,7 +326,9 @@ function addCacheControlToRecentMessages<
     const content = originalMessage.content;
     const hasArrayContent = Array.isArray(content);
     const canAddCache =
-      cachePointsAdded < maxCachePoints && canUseMessage(originalMessage);
+      cachePointsAdded < maxCachePoints &&
+      canUseMessage(originalMessage) &&
+      !isSyntheticMetaMessage(originalMessage);
 
     if (!canAddCache && !hasArrayContent) {
       continue;
@@ -523,6 +559,7 @@ export function addBedrockCacheControl<
       isUserMessage &&
       !isToolMessage &&
       !isEmptyString &&
+      !isSyntheticMetaMessage(originalMessage) &&
       (typeof content === 'string' || hasArrayContent);
 
     if (!needsCacheAdd && !hasArrayContent && !hasSerializationProps) {

package/src/messages/content.ts

@@ -1,5 +1,5 @@
-import { ContentTypes } from '@/common';
 import type { BaseMessage } from '@langchain/core/messages';
+import { ContentTypes } from '@/common';
 
 /**
  * Formats an array of messages for LangChain, making sure all content fields are strings

package/src/messages/contextPruning.ts

@@ -13,9 +13,9 @@
  */
 
 import { ToolMessage, type BaseMessage } from '@langchain/core/messages';
+import type { ContextPruningSettings } from './contextPruningSettings';
 import type { ContextPruningConfig } from '@/types/graph';
 import type { TokenCounter } from '@/types/run';
-import type { ContextPruningSettings } from './contextPruningSettings';
 import { resolveContextPruningSettings } from './contextPruningSettings';
 
 /**