@librechat/agents 3.1.52 → 3.1.54

package/src/llm/bedrock/llm.spec.ts

@@ -5,16 +5,24 @@ config();
 import { expect, test, describe, jest } from '@jest/globals';
 import {
   AIMessage,
-  AIMessageChunk,
+  ToolMessage,
   HumanMessage,
   SystemMessage,
-  ToolMessage,
+  AIMessageChunk,
 } from '@langchain/core/messages';
 import { concat } from '@langchain/core/utils/stream';
 import { ChatGenerationChunk } from '@langchain/core/outputs';
-import { BedrockRuntimeClient } from '@aws-sdk/client-bedrock-runtime';
+import {
+  BedrockRuntimeClient,
+  ConverseCommand,
+} from '@aws-sdk/client-bedrock-runtime';
+import type { ConverseResponse } from '@aws-sdk/client-bedrock-runtime';
+import {
+  convertConverseMessageToLangChainMessage,
+  handleConverseStreamMetadata,
+  convertToConverseMessages,
+} from './utils';
 import { CustomChatBedrockConverse, ServiceTierType } from './index';
-import { convertToConverseMessages } from './utils';
 
 jest.setTimeout(120000);
 
@@ -429,6 +437,164 @@ describe('CustomChatBedrockConverse', () => {
   });
 });
 
+describe('handleConverseStreamMetadata - cache token extraction', () => {
+  test('should extract cacheReadInputTokens and cacheWriteInputTokens into input_token_details', () => {
+    const metadata = {
+      usage: {
+        inputTokens: 13,
+        outputTokens: 5,
+        totalTokens: 10849,
+        cacheReadInputTokens: 10831,
+        cacheWriteInputTokens: 0,
+      },
+      metrics: { latencyMs: 1000 },
+    };
+
+    const chunk = handleConverseStreamMetadata(metadata, {
+      streamUsage: true,
+    });
+    const msg = chunk.message as AIMessageChunk;
+
+    expect(msg.usage_metadata).toEqual({
+      input_tokens: 13,
+      output_tokens: 5,
+      total_tokens: 10849,
+      input_token_details: {
+        cache_read: 10831,
+        cache_creation: 0,
+      },
+    });
+  });
+
+  test('should not include input_token_details when no cache tokens present', () => {
+    const metadata = {
+      usage: {
+        inputTokens: 100,
+        outputTokens: 50,
+        totalTokens: 150,
+      },
+      metrics: { latencyMs: 500 },
+    };
+
+    const chunk = handleConverseStreamMetadata(metadata, {
+      streamUsage: true,
+    });
+    const msg = chunk.message as AIMessageChunk;
+
+    expect(msg.usage_metadata).toEqual({
+      input_tokens: 100,
+      output_tokens: 50,
+      total_tokens: 150,
+    });
+    expect(msg.usage_metadata?.input_token_details).toBeUndefined();
+  });
+
+  test('should include input_token_details when only cacheWriteInputTokens is present', () => {
+    const metadata = {
+      usage: {
+        inputTokens: 50,
+        outputTokens: 10,
+        totalTokens: 10060,
+        cacheWriteInputTokens: 10000,
+      },
+      metrics: { latencyMs: 800 },
+    };
+
+    const chunk = handleConverseStreamMetadata(metadata, {
+      streamUsage: true,
+    });
+    const msg = chunk.message as AIMessageChunk;
+
+    expect(msg.usage_metadata?.input_token_details).toEqual({
+      cache_read: 0,
+      cache_creation: 10000,
+    });
+  });
+
+  test('should return undefined usage_metadata when streamUsage is false', () => {
+    const metadata = {
+      usage: {
+        inputTokens: 13,
+        outputTokens: 5,
+        totalTokens: 10849,
+        cacheReadInputTokens: 10831,
+        cacheWriteInputTokens: 0,
+      },
+      metrics: { latencyMs: 1000 },
+    };
+
+    const chunk = handleConverseStreamMetadata(metadata, {
+      streamUsage: false,
+    });
+    const msg = chunk.message as AIMessageChunk;
+
+    expect(msg.usage_metadata).toBeUndefined();
+  });
+});
+
+describe('convertConverseMessageToLangChainMessage - cache token extraction', () => {
+  const makeResponseMetadata = (
+    usage: Record<string, number>
+  ): Omit<ConverseResponse, 'output'> =>
+    ({
+      usage,
+      stopReason: 'end_turn',
+      metrics: undefined,
+      $metadata: { requestId: 'test-id' },
+    }) as unknown as Omit<ConverseResponse, 'output'>;
+
+  test('should extract cache tokens in non-streaming response', () => {
+    const message = {
+      role: 'assistant' as const,
+      content: [{ text: 'Hello!' }],
+    };
+
+    const result = convertConverseMessageToLangChainMessage(
+      message,
+      makeResponseMetadata({
+        inputTokens: 20,
+        outputTokens: 5,
+        totalTokens: 10856,
+        cacheReadInputTokens: 10831,
+        cacheWriteInputTokens: 0,
+      })
+    );
+
+    expect(result.usage_metadata).toEqual({
+      input_tokens: 20,
+      output_tokens: 5,
+      total_tokens: 10856,
+      input_token_details: {
+        cache_read: 10831,
+        cache_creation: 0,
+      },
+    });
+  });
+
+  test('should not include input_token_details when no cache tokens in non-streaming response', () => {
+    const message = {
+      role: 'assistant' as const,
+      content: [{ text: 'Hello!' }],
+    };
+
+    const result = convertConverseMessageToLangChainMessage(
+      message,
+      makeResponseMetadata({
+        inputTokens: 100,
+        outputTokens: 50,
+        totalTokens: 150,
+      })
+    );
+
+    expect(result.usage_metadata).toEqual({
+      input_tokens: 100,
+      output_tokens: 50,
+      total_tokens: 150,
+    });
+    expect(result.usage_metadata?.input_token_details).toBeUndefined();
+  });
+});
+
 describe('convertToConverseMessages', () => {
   test('should convert basic messages', () => {
     const { converseMessages, converseSystem } = convertToConverseMessages([
@@ -647,4 +813,67 @@ describe.skip('Integration tests', () => {
       expect(reasoningBlocks.length).toBeGreaterThanOrEqual(0);
     }
   });
+
+  test('cache tokens should populate input_token_details', async () => {
+    const client = new BedrockRuntimeClient({
+      region: integrationArgs.region,
+      credentials: integrationArgs.credentials,
+    });
+
+    // Large system prompt (>1024 tokens) to meet Bedrock's minimum cache threshold
+    const largeSystemPrompt = [
+      'You are an expert assistant.',
+      ...Array(200).fill(
+        'This is padding content to exceed the minimum token threshold for Bedrock prompt caching. '
+      ),
+      'When answering, be brief and direct.',
+    ].join(' ');
+
+    const systemBlocks = [
+      { text: largeSystemPrompt },
+      { cachePoint: { type: 'default' as const } },
+    ];
+
+    const converseArgs = {
+      modelId: 'us.anthropic.claude-sonnet-4-5-20250929-v1:0',
+      system: systemBlocks,
+      inferenceConfig: { maxTokens: 50 },
+    };
+
+    // Call 1: populate the cache (may be a write or read if already warm)
+    await client.send(
+      new ConverseCommand({
+        ...converseArgs,
+        messages: [{ role: 'user', content: [{ text: 'Say hello.' }] }],
+      })
+    );
+
+    // Call 2: should read from cache — this is the one we assert on
+    const response = await client.send(
+      new ConverseCommand({
+        ...converseArgs,
+        messages: [
+          { role: 'user', content: [{ text: 'Say hello.' }] },
+          { role: 'assistant', content: [{ text: 'Hello!' }] },
+          { role: 'user', content: [{ text: 'Say goodbye.' }] },
+        ],
+      })
+    );
+
+    // Feed raw response through convertConverseMessageToLangChainMessage
+    const result = convertConverseMessageToLangChainMessage(
+      response.output!.message!,
+      response
+    );
+
+    expect(result.usage_metadata).toBeDefined();
+    expect(result.usage_metadata!.input_tokens).toBeGreaterThan(0);
+    expect(result.usage_metadata!.output_tokens).toBeGreaterThan(0);
+
+    // Cache should have been populated by call 1, so call 2 should show cache reads
+    expect(result.usage_metadata!.input_token_details).toBeDefined();
+    expect(
+      result.usage_metadata!.input_token_details!.cache_read
+    ).toBeGreaterThan(0);
+  });
 });

package/src/llm/bedrock/utils/message_outputs.ts

@@ -2,8 +2,9 @@
  * Utility functions for converting Bedrock Converse responses to LangChain messages.
  * Ported from @langchain/aws common.js
  */
-import { AIMessage, AIMessageChunk } from '@langchain/core/messages';
 import { ChatGenerationChunk } from '@langchain/core/outputs';
+import { AIMessage, AIMessageChunk } from '@langchain/core/messages';
+import type { UsageMetadata } from '@langchain/core/messages';
 import type {
   BedrockMessage,
   ConverseResponse,
@@ -107,17 +108,38 @@ export function convertConverseMessageToLangChainMessage(
   }
 
   let tokenUsage:
-    | { input_tokens: number; output_tokens: number; total_tokens: number }
+    | {
+        input_tokens: number;
+        output_tokens: number;
+        total_tokens: number;
+        input_token_details?: {
+          cache_read: number;
+          cache_creation: number;
+        };
+      }
     | undefined;
   if (responseMetadata.usage != null) {
-    const input_tokens = responseMetadata.usage.inputTokens ?? 0;
-    const output_tokens = responseMetadata.usage.outputTokens ?? 0;
+    const usage = responseMetadata.usage as NonNullable<
+      typeof responseMetadata.usage
+    > & {
+      cacheReadInputTokens?: number;
+      cacheWriteInputTokens?: number;
+    };
+    const input_tokens = usage.inputTokens ?? 0;
+    const output_tokens = usage.outputTokens ?? 0;
+    const cacheRead = usage.cacheReadInputTokens;
+    const cacheWrite = usage.cacheWriteInputTokens;
     tokenUsage = {
       input_tokens,
       output_tokens,
-      total_tokens:
-        responseMetadata.usage.totalTokens ?? input_tokens + output_tokens,
+      total_tokens: usage.totalTokens ?? input_tokens + output_tokens,
     };
+    if (cacheRead != null || cacheWrite != null) {
+      tokenUsage.input_token_details = {
+        cache_read: cacheRead ?? 0,
+        cache_creation: cacheWrite ?? 0,
+      };
+    }
   }
 
   if (
@@ -285,19 +307,37 @@ export function handleConverseStreamMetadata(
   metadata: ConverseStreamMetadataEvent,
   extra: { streamUsage: boolean }
 ): ChatGenerationChunk {
-  const inputTokens = metadata.usage?.inputTokens ?? 0;
-  const outputTokens = metadata.usage?.outputTokens ?? 0;
-  const usage_metadata = {
+  const usage = metadata.usage as
+    | (NonNullable<ConverseStreamMetadataEvent['usage']> & {
+        cacheReadInputTokens?: number;
+        cacheWriteInputTokens?: number;
+      })
+    | undefined;
+  const inputTokens = usage?.inputTokens ?? 0;
+  const outputTokens = usage?.outputTokens ?? 0;
+  const cacheRead = usage?.cacheReadInputTokens;
+  const cacheWrite = usage?.cacheWriteInputTokens;
+
+  const usage_metadata: Record<string, unknown> = {
     input_tokens: inputTokens,
     output_tokens: outputTokens,
-    total_tokens: metadata.usage?.totalTokens ?? inputTokens + outputTokens,
+    total_tokens: usage?.totalTokens ?? inputTokens + outputTokens,
   };
 
+  if (cacheRead != null || cacheWrite != null) {
+    usage_metadata.input_token_details = {
+      cache_read: cacheRead ?? 0,
+      cache_creation: cacheWrite ?? 0,
+    };
+  }
+
   return new ChatGenerationChunk({
     text: '',
     message: new AIMessageChunk({
       content: '',
-      usage_metadata: extra.streamUsage ? usage_metadata : undefined,
+      usage_metadata: extra.streamUsage
+        ? (usage_metadata as UsageMetadata)
+        : undefined,
       response_metadata: {
         // Use the same key as returned from the Converse API
         metadata,

package/src/llm/google/index.ts

@@ -10,9 +10,8 @@ import type {
 } from '@google/generative-ai';
 import type { CallbackManagerForLLMRun } from '@langchain/core/callbacks/manager';
 import type { BaseMessage, UsageMetadata } from '@langchain/core/messages';
-import type { GeminiGenerationConfig } from '@langchain/google-common';
 import type { GeminiApiUsageMetadata, InputTokenDetails } from './types';
-import type { GoogleClientOptions } from '@/types';
+import type { GoogleClientOptions, GoogleThinkingConfig } from '@/types';
 import {
   convertResponseContentToChatGenerationChunk,
   convertBaseMessagesToContent,
@@ -20,7 +19,7 @@ import {
 } from './utils/common';
 
 export class CustomChatGoogleGenerativeAI extends ChatGoogleGenerativeAI {
-  thinkingConfig?: GeminiGenerationConfig['thinkingConfig'];
+  thinkingConfig?: GoogleThinkingConfig;
 
   /**
    * Override to add gemini-3 model support for multimodal and function calling thought signatures

package/src/llm/openrouter/index.ts

@@ -29,24 +29,135 @@ type OpenAIRoleEnum =
   | 'function'
   | 'tool';
 
-export interface ChatOpenRouterCallOptions extends ChatOpenAICallOptions {
+export type OpenRouterReasoningEffort =
+  | 'xhigh'
+  | 'high'
+  | 'medium'
+  | 'low'
+  | 'minimal'
+  | 'none';
+
+export interface OpenRouterReasoning {
+  effort?: OpenRouterReasoningEffort;
+  max_tokens?: number;
+  exclude?: boolean;
+  enabled?: boolean;
+}
+
+export interface ChatOpenRouterCallOptions
+  extends Omit<ChatOpenAICallOptions, 'reasoning'> {
+  /** @deprecated Use `reasoning` object instead */
   include_reasoning?: boolean;
+  reasoning?: OpenRouterReasoning;
   modelKwargs?: OpenAIChatInput['modelKwargs'];
 }
+
+/** invocationParams return type extended with OpenRouter reasoning */
+export type OpenRouterInvocationParams = Omit<
+  OpenAIClient.Chat.ChatCompletionCreateParams,
+  'messages'
+> & {
+  reasoning?: OpenRouterReasoning;
+};
 export class ChatOpenRouter extends ChatOpenAI {
+  private openRouterReasoning?: OpenRouterReasoning;
+  /** @deprecated Use `reasoning` object instead */
+  private includeReasoning?: boolean;
+
   constructor(_fields: Partial<ChatOpenRouterCallOptions>) {
-    const { include_reasoning, modelKwargs = {}, ...fields } = _fields;
+    const {
+      include_reasoning,
+      reasoning: openRouterReasoning,
+      modelKwargs = {},
+      ...fields
+    } = _fields;
+
+    // Extract reasoning from modelKwargs if provided there (e.g., from LLMConfig)
+    const { reasoning: mkReasoning, ...restModelKwargs } = modelKwargs as {
+      reasoning?: OpenRouterReasoning;
+    } & Record<string, unknown>;
+
     super({
       ...fields,
-      modelKwargs: {
-        ...modelKwargs,
-        include_reasoning,
-      },
+      modelKwargs: restModelKwargs,
     });
+
+    // Merge reasoning config: modelKwargs.reasoning < constructor reasoning
+    if (mkReasoning != null || openRouterReasoning != null) {
+      this.openRouterReasoning = {
+        ...mkReasoning,
+        ...openRouterReasoning,
+      };
+    }
+
+    this.includeReasoning = include_reasoning;
   }
   static lc_name(): 'LibreChatOpenRouter' {
     return 'LibreChatOpenRouter';
   }
+
+  // @ts-expect-error - OpenRouter reasoning extends OpenAI Reasoning with additional
+  // effort levels ('xhigh' | 'none' | 'minimal') not in ReasoningEffort.
+  // The parent's generic conditional return type cannot be widened in an override.
+  override invocationParams(
+    options?: this['ParsedCallOptions'],
+    extra?: { streaming?: boolean }
+  ): OpenRouterInvocationParams {
+    type MutableParams = Omit<
+      OpenAIClient.Chat.ChatCompletionCreateParams,
+      'messages'
+    > & { reasoning_effort?: string; reasoning?: OpenRouterReasoning };
+
+    const params = super.invocationParams(options, extra) as MutableParams;
+
+    // Remove the OpenAI-native reasoning_effort that the parent sets;
+    // OpenRouter uses a `reasoning` object instead
+    delete params.reasoning_effort;
+
+    // Build the OpenRouter reasoning config
+    const reasoning = this.buildOpenRouterReasoning(options);
+    if (reasoning != null) {
+      params.reasoning = reasoning;
+    } else {
+      delete params.reasoning;
+    }
+
+    return params;
+  }
+
+  private buildOpenRouterReasoning(
+    options?: this['ParsedCallOptions']
+  ): OpenRouterReasoning | undefined {
+    let reasoning: OpenRouterReasoning | undefined;
+
+    // 1. Instance-level reasoning config (from constructor)
+    if (this.openRouterReasoning != null) {
+      reasoning = { ...this.openRouterReasoning };
+    }
+
+    // 2. LangChain-style reasoning params (from parent's `this.reasoning`)
+    const lcReasoning = this.getReasoningParams(options);
+    if (lcReasoning?.effort != null) {
+      reasoning = {
+        ...reasoning,
+        effort: lcReasoning.effort as OpenRouterReasoningEffort,
+      };
+    }
+
+    // 3. Call-level reasoning override
+    const callReasoning = (options as ChatOpenRouterCallOptions | undefined)
+      ?.reasoning;
+    if (callReasoning != null) {
+      reasoning = { ...reasoning, ...callReasoning };
+    }
+
+    // 4. Legacy include_reasoning backward compatibility
+    if (reasoning == null && this.includeReasoning === true) {
+      reasoning = { enabled: true };
+    }
+
+    return reasoning;
+  }
   protected override _convertOpenAIDeltaToBaseMessageChunk(
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     delta: Record<string, any>,