@librechat/agents 3.2.38 → 3.2.41

package/src/llm/anthropic/utils/message_inputs.ts

@@ -978,11 +978,16 @@ const NON_CACHEABLE_PAYLOAD_BLOCK_TYPES = new Set([
  * skipped. Returns a new array only when it actually places a marker.
  */
 function reanchorTailCacheControl(
-  messages: AnthropicMessageCreateParams['messages']
+  messages: AnthropicMessageCreateParams['messages'],
+  ttl?: '1h'
 ): AnthropicMessageCreateParams['messages'] {
   if (messages.length === 0) {
     return messages;
   }
+  const cacheControl =
+    ttl === '1h'
+      ? ({ type: 'ephemeral', ttl: '1h' } as const)
+      : ({ type: 'ephemeral' } as const);
   const lastIndex = messages.length - 1;
   const tail = messages[lastIndex];
   const content = tail.content;
@@ -994,9 +999,7 @@ function reanchorTailCacheControl(
     const next = [...messages];
     next[lastIndex] = {
       ...tail,
-      content: [
-        { type: 'text', text: content, cache_control: { type: 'ephemeral' } },
-      ],
+      content: [{ type: 'text', text: content, cache_control: cacheControl }],
     } as (typeof messages)[number];
     return next;
   }
@@ -1027,12 +1030,36 @@ function reanchorTailCacheControl(
   next[lastIndex] = {
     ...tail,
     content: content.map((block, i) =>
-      i === anchor ? { ...block, cache_control: { type: 'ephemeral' } } : block
+      i === anchor ? { ...block, cache_control: cacheControl } : block
     ),
   } as (typeof messages)[number];
   return next;
 }
 
+/**
+ * Find the extended-cache TTL (`'1h'`) carried by an existing `cache_control`
+ * breakpoint, so {@link reanchorTailCacheControl} can re-apply the same TTL the
+ * stripped prefill had. Returns `undefined` for the legacy 5-minute default
+ * (no `ttl`), keeping that path byte-identical to before.
+ */
+function findCacheControlTtl(
+  messages: AnthropicMessageCreateParams['messages']
+): '1h' | undefined {
+  for (const message of messages) {
+    if (!Array.isArray(message.content)) {
+      continue;
+    }
+    for (const block of message.content) {
+      const cacheControl = (block as { cache_control?: { ttl?: unknown } })
+        .cache_control;
+      if (cacheControl?.ttl === '1h') {
+        return '1h';
+      }
+    }
+  }
+  return undefined;
+}
+
 export function stripUnsupportedAssistantPrefill<
   T extends Pick<AnthropicMessageCreateParams, 'messages'> & { model?: string },
 >(request: T): T {
@@ -1065,7 +1092,7 @@ export function stripUnsupportedAssistantPrefill<
   const reanchored =
     messagesHaveCacheControl(messages) &&
     !messagesHaveCacheControl(nextMessages)
-      ? reanchorTailCacheControl(nextMessages)
+      ? reanchorTailCacheControl(nextMessages, findCacheControlTtl(messages))
       : nextMessages;
 
   return {

package/src/llm/bedrock/index.ts

@@ -39,6 +39,7 @@ import {
   handleConverseStreamContentBlockDelta,
   handleConverseStreamMetadata,
 } from './utils';
+import { resolvePromptCacheTtl, type PromptCacheTtl } from '@/messages/cache';
 import { insertBedrockToolCachePoint } from './toolCache';
 
 /**
@@ -63,6 +64,15 @@ export interface CustomChatBedrockConverseInput
    */
   promptCache?: boolean;
 
+  /**
+   * Prompt-cache checkpoint TTL. Defaults to `'1h'` (extended cache) when
+   * `promptCache` is enabled; set `'5m'` for the legacy 5-minute behavior.
+   * Bedrock models that don't support the 1-hour TTL downgrade to 5m
+   * server-side (verified on Sonnet/Opus 4.6), so the default is safe to leave
+   * on; use `'5m'` for any model that rejects it.
+   */
+  promptCacheTtl?: PromptCacheTtl;
+
   /**
    * Guardrail configuration for Converse and ConverseStream invocations.
    * `streamProcessingMode` is only used by ConverseStream.
@@ -109,6 +119,11 @@ export class CustomChatBedrockConverse extends ChatBedrockConverse {
    */
   promptCache?: boolean;
 
+  /**
+   * Prompt-cache checkpoint TTL (`'5m'` legacy or `'1h'` extended cache).
+   */
+  promptCacheTtl?: PromptCacheTtl;
+
   /**
    * Application Inference Profile ARN to use instead of model ID.
    */
@@ -122,6 +137,7 @@ export class CustomChatBedrockConverse extends ChatBedrockConverse {
   constructor(fields?: CustomChatBedrockConverseInput) {
     super(fields);
     this.promptCache = fields?.promptCache;
+    this.promptCacheTtl = fields?.promptCacheTtl;
     this.applicationInferenceProfile = fields?.applicationInferenceProfile;
     this.serviceTier = fields?.serviceTier;
   }
@@ -149,7 +165,11 @@ export class CustomChatBedrockConverse extends ChatBedrockConverse {
     const baseParams = super.invocationParams(options);
     const toolConfig =
       this.promptCache === true
-        ? insertBedrockToolCachePoint(baseParams.toolConfig, true)
+        ? insertBedrockToolCachePoint(
+          baseParams.toolConfig,
+          true,
+          resolvePromptCacheTtl(this.promptCacheTtl)
+        )
         : baseParams.toolConfig;
 
     /** Service tier from options or fall back to class-level setting */

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

@@ -397,6 +397,67 @@ describe('CustomChatBedrockConverse', () => {
       ]);
     });
 
+    test('defaults the tool cache point to the 1h extended TTL', () => {
+      const model = new CustomChatBedrockConverse({
+        ...baseConstructorArgs,
+        promptCache: true,
+      });
+
+      const params = model.invocationParams({
+        tools: [
+          {
+            type: 'function',
+            function: {
+              name: 'direct_tool',
+              description: 'Direct tool',
+              parameters: { type: 'object', properties: {} },
+            },
+          },
+        ],
+      });
+
+      const toolList = (params.toolConfig?.tools ?? []) as unknown as Array<
+        Record<string, unknown>
+      >;
+      const cachePoints = toolList.filter((t) => 'cachePoint' in t);
+      expect(cachePoints).toHaveLength(1);
+      expect((cachePoints[0] as { cachePoint: unknown }).cachePoint).toEqual({
+        type: 'default',
+        ttl: '1h',
+      });
+    });
+
+    test('honors an explicit 5m promptCacheTtl on the tool cache point', () => {
+      const model = new CustomChatBedrockConverse({
+        ...baseConstructorArgs,
+        promptCache: true,
+        promptCacheTtl: '5m',
+      });
+
+      const params = model.invocationParams({
+        tools: [
+          {
+            type: 'function',
+            function: {
+              name: 'direct_tool',
+              description: 'Direct tool',
+              parameters: { type: 'object', properties: {} },
+            },
+          },
+        ],
+      });
+
+      const toolList = (params.toolConfig?.tools ?? []) as unknown as Array<
+        Record<string, unknown>
+      >;
+      const cachePoints = toolList.filter((t) => 'cachePoint' in t);
+      expect(cachePoints).toHaveLength(1);
+      // 5m omits the ttl field (provider default).
+      expect((cachePoints[0] as { cachePoint: unknown }).cachePoint).toEqual({
+        type: 'default',
+      });
+    });
+
     test('adds the Bedrock cache point before deferred tools', () => {
       const model = new CustomChatBedrockConverse({
         ...baseConstructorArgs,

package/src/llm/bedrock/toolCache.test.ts

@@ -167,4 +167,28 @@ describe('partitionAndMarkBedrockToolCache', () => {
       'described_tool description'
     );
   });
+
+  it('normalizes an existing tool cache point to the resolved 1h ttl', () => {
+    const result = insertBedrockToolCachePoint(
+      {
+        tools: [
+          {
+            toolSpec: {
+              name: 'direct_tool',
+              description: 'Direct tool',
+              inputSchema: { json: { type: 'object', properties: {} } },
+            },
+          },
+          { cachePoint: { type: 'default' } },
+        ] as Tool[],
+      },
+      false,
+      '1h'
+    );
+    const cachePoints = (result?.tools ?? []).filter(
+      (t): t is Tool.CachePointMember => 'cachePoint' in t
+    );
+    expect(cachePoints).toHaveLength(1);
+    expect(cachePoints[0].cachePoint).toEqual({ type: 'default', ttl: '1h' });
+  });
 });

package/src/llm/bedrock/toolCache.ts

@@ -3,12 +3,9 @@ import type { Tool, ToolConfiguration } from '@aws-sdk/client-bedrock-runtime';
 import type { OpenAIClient } from '@langchain/openai';
 import type { DocumentType } from '@smithy/types';
 import type { GraphTools } from '@/types';
+import { buildBedrockCachePoint, type PromptCacheTtl } from '@/messages/cache';
 import { _convertToOpenAITool } from '@/llm/openai';
 
-const CACHE_POINT: Tool.CachePointMember = {
-  cachePoint: { type: 'default' },
-};
-
 const BEDROCK_TOOL_CACHE_MARKER = '__lc_bedrock_cache_point_after';
 const BEDROCK_TOOL_CACHE_DISABLED_MARKER = '__lc_bedrock_skip_tool_cache';
 
@@ -148,13 +145,18 @@ export function partitionAndMarkBedrockToolCache(
 
 export function insertBedrockToolCachePoint(
   toolConfig: ToolConfiguration | undefined,
-  fallbackToEnd: boolean
+  fallbackToEnd: boolean,
+  ttl?: PromptCacheTtl
 ): ToolConfiguration | undefined {
   const tools = toolConfig?.tools as BedrockToolWithCacheMarker[] | undefined;
   if (tools == null || tools.length === 0) {
     return toolConfig;
   }
 
+  const cachePoint: Tool.CachePointMember = {
+    cachePoint: buildBedrockCachePoint(ttl),
+  };
+
   let markerIndex = -1;
   let hasCachePoint = false;
   let hasDisabledMarker = false;
@@ -163,8 +165,11 @@ export function insertBedrockToolCachePoint(
   for (let i = 0; i < tools.length; i++) {
     const tool = tools[i];
     if (isBedrockCachePoint(tool)) {
+      // Normalize an existing cache point to the resolved TTL so a stale
+      // 5-minute tool breakpoint never precedes the new 1-hour system/message
+      // breakpoints (Bedrock requires longer-TTL entries to appear first).
       hasCachePoint = true;
-      cleanedTools.push(tool);
+      cleanedTools.push(cachePoint);
       continue;
     }
     if (tool[BEDROCK_TOOL_CACHE_MARKER] === true) {
@@ -189,7 +194,7 @@ export function insertBedrockToolCachePoint(
     ...toolConfig,
     tools: [
       ...cleanedTools.slice(0, insertionIndex + 1),
-      CACHE_POINT,
+      cachePoint,
       ...cleanedTools.slice(insertionIndex + 1),
     ],
   };

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

@@ -427,24 +427,40 @@ const standardContentBlockConverter: StandardContentBlockConverter<{
   },
 };
 
+type BedrockPromptCacheTtl = '5m' | '1h';
+type NormalizedBedrockCachePoint = {
+  type: 'default';
+  ttl?: BedrockPromptCacheTtl;
+};
+
 /**
- * Check if a block has a cache point.
+ * Check if a block has a default cache point and return its normalized form,
+ * preserving an optional extended-TTL `ttl` (`'5m'` | `'1h'`). Returns
+ * `undefined` when the block is not a default cache point.
  */
-function isDefaultCachePoint(block: unknown): boolean {
+function getDefaultCachePoint(
+  block: unknown
+): NormalizedBedrockCachePoint | undefined {
   if (typeof block !== 'object' || block === null) {
-    return false;
+    return undefined;
   }
   if (!('cachePoint' in block)) {
-    return false;
+    return undefined;
   }
   const cachePoint = (block as { cachePoint?: unknown }).cachePoint;
   if (typeof cachePoint !== 'object' || cachePoint === null) {
-    return false;
+    return undefined;
   }
   if (!('type' in cachePoint)) {
-    return false;
+    return undefined;
   }
-  return (cachePoint as { type?: string }).type === 'default';
+  if ((cachePoint as { type?: string }).type !== 'default') {
+    return undefined;
+  }
+  const ttl = (cachePoint as { ttl?: unknown }).ttl;
+  return ttl === '5m' || ttl === '1h'
+    ? { type: 'default', ttl }
+    : { type: 'default' };
 }
 
 /**
@@ -570,11 +586,10 @@ function convertLangChainContentBlockToConverseContentBlock({
     } as BedrockContentBlock;
   }
 
-  if (isDefaultCachePoint(block)) {
+  const cachePoint = getDefaultCachePoint(block);
+  if (cachePoint != null) {
     return {
-      cachePoint: {
-        type: 'default',
-      },
+      cachePoint,
     } as BedrockContentBlock;
   }
 
@@ -604,14 +619,14 @@ function convertSystemMessageToConverseMessage(
         contentBlocks.push({
           text: (block as { text: string }).text,
         });
-      } else if (isDefaultCachePoint(block)) {
+      } else {
+        const cachePoint = getDefaultCachePoint(block);
+        if (cachePoint == null) {
+          break;
+        }
         contentBlocks.push({
-          cachePoint: {
-            type: 'default',
-          },
+          cachePoint,
         } as BedrockSystemContentBlock);
-      } else {
-        break;
       }
     }
     if (msg.content.length === contentBlocks.length) {
@@ -681,28 +696,29 @@ function convertAIMessageToConverseMessage(msg: BaseMessage): BedrockMessage {
           reasoningContent:
             langchainReasoningBlockToBedrockReasoningBlock(reasoningBlock),
         } as BedrockContentBlock);
-      } else if (isDefaultCachePoint(block)) {
-        contentBlocks.push({
-          cachePoint: {
-            type: 'default',
-          },
-        } as BedrockContentBlock);
-      } else if (FOREIGN_REASONING_TYPES.some((t) => t === block.type)) {
-        // Reasoning from another provider (Anthropic `thinking`/
-        // `redacted_thinking`, Google `reasoning`, LibreChat `think`). Bedrock's
-        // native reasoning is `reasoning_content` (handled above); a foreign
-        // block carries a signature Bedrock cannot validate, so drop it on a
-        // cross-provider handoff (e.g. Anthropic → Bedrock) rather than crash.
-        // The Bedrock model produces its own reasoning. Anything else unknown
-        // still throws below — real content must be surfaced, not dropped.
-        return;
       } else {
-        const blockValues = Object.fromEntries(
-          Object.entries(block).filter(([key]) => key !== 'type')
-        );
-        throw new Error(
-          `Unsupported content block type: ${block.type} with content of ${JSON.stringify(blockValues, null, 2)}`
-        );
+        const cachePoint = getDefaultCachePoint(block);
+        if (cachePoint != null) {
+          contentBlocks.push({
+            cachePoint,
+          } as BedrockContentBlock);
+        } else if (FOREIGN_REASONING_TYPES.some((t) => t === block.type)) {
+          // Reasoning from another provider (Anthropic `thinking`/
+          // `redacted_thinking`, Google `reasoning`, LibreChat `think`).
+          // Bedrock's native reasoning is `reasoning_content` (handled above); a
+          // foreign block carries a signature Bedrock cannot validate, so drop
+          // it on a cross-provider handoff (e.g. Anthropic → Bedrock) rather
+          // than crash. The Bedrock model produces its own reasoning. Anything
+          // else unknown still throws below — real content must be surfaced.
+          return;
+        } else {
+          const blockValues = Object.fromEntries(
+            Object.entries(block).filter(([key]) => key !== 'type')
+          );
+          throw new Error(
+            `Unsupported content block type: ${block.type} with content of ${JSON.stringify(blockValues, null, 2)}`
+          );
+        }
       }
     });
 
@@ -864,9 +880,10 @@ function convertToolMessageToConverseMessage(msg: BaseMessage): BedrockMessage {
   const toolResultContent: BedrockContentBlock[] = [];
   const trailingCachePoints: BedrockContentBlock[] = [];
   for (const block of content) {
-    if (isDefaultCachePoint(block)) {
+    const cachePoint = getDefaultCachePoint(block);
+    if (cachePoint != null) {
       trailingCachePoints.push({
-        cachePoint: { type: 'default' },
+        cachePoint,
       } as BedrockContentBlock);
     } else {
       toolResultContent.push(block);

package/src/llm/openrouter/index.ts

@@ -6,6 +6,7 @@ import type {
 import type { CallbackManagerForLLMRun } from '@langchain/core/callbacks/manager';
 import type { ChatGenerationChunk } from '@langchain/core/outputs';
 import type { BaseMessage } from '@langchain/core/messages';
+import type { PromptCacheTtl } from '@/messages/cache';
 import { ChatOpenAI, emitStreamChunkCallback } from '@/llm/openai';
 
 export type OpenRouterReasoningEffort =
@@ -30,6 +31,13 @@ export interface ChatOpenRouterCallOptions
   reasoning?: OpenRouterReasoning;
   modelKwargs?: OpenAIChatInput['modelKwargs'];
   promptCache?: boolean;
+  /**
+   * Prompt-cache breakpoint TTL. Defaults to `'1h'` (extended cache) when
+   * `promptCache` is enabled; set `'5m'` for the legacy 5-minute behavior.
+   * OpenRouter forwards this to Claude upstreams (Anthropic / Bedrock / Vertex),
+   * which downgrade to 5m where the extended TTL isn't supported.
+   */
+  promptCacheTtl?: PromptCacheTtl;
 }
 
 export type ChatOpenRouterInput = Partial<
@@ -107,6 +115,7 @@ export class ChatOpenRouter extends ChatOpenAI {
   constructor(_fields: ChatOpenRouterInput) {
     const fieldsWithoutPromptCache: ChatOpenRouterInput = { ..._fields };
     delete fieldsWithoutPromptCache.promptCache;
+    delete fieldsWithoutPromptCache.promptCacheTtl;
 
     const {
       include_reasoning,

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

@@ -9,7 +9,7 @@ type OpenRouterTool = {
     description?: string;
     parameters?: object;
   };
-  cache_control?: { type: 'ephemeral' };
+  cache_control?: { type: 'ephemeral'; ttl?: '1h' };
   defer_loading?: boolean;
 };
 
@@ -80,4 +80,55 @@ describe('partitionAndMarkOpenRouterToolCache', () => {
     expect(result[0].cache_control).toEqual({ type: 'ephemeral' });
     expect(result[1]).not.toHaveProperty('cache_control');
   });
+
+  it('stamps the resolved 1h ttl on the last static tool', () => {
+    const result = partitionAndMarkOpenRouterToolCache(
+      [
+        createOpenAITool('static_one'),
+        createOpenAITool('static_two'),
+      ] as GraphTools,
+      () => false,
+      '1h'
+    ) as OpenRouterTool[];
+
+    expect(result[1].cache_control).toEqual({ type: 'ephemeral', ttl: '1h' });
+    expect(result[0]).not.toHaveProperty('cache_control');
+  });
+
+  it('omits ttl for the 5m legacy default', () => {
+    const result = partitionAndMarkOpenRouterToolCache(
+      [createOpenAITool('only_static')] as GraphTools,
+      () => false,
+      '5m'
+    ) as OpenRouterTool[];
+
+    expect(result[0].cache_control).toEqual({ type: 'ephemeral' });
+  });
+
+  it('strips a stale marker off an earlier static tool', () => {
+    const earlier = createOpenAITool('static_one');
+    earlier.cache_control = { type: 'ephemeral' };
+    const result = partitionAndMarkOpenRouterToolCache(
+      [earlier, createOpenAITool('static_two')] as GraphTools,
+      () => false,
+      '1h'
+    ) as OpenRouterTool[];
+
+    // No stale 5m marker survives ahead of the resolved 1h breakpoint.
+    expect(result[0]).not.toHaveProperty('cache_control');
+    expect(result[1].cache_control).toEqual({ type: 'ephemeral', ttl: '1h' });
+  });
+
+  it('strips a stale marker off a deferred tool', () => {
+    const deferred = createOpenAITool('deferred_one');
+    deferred.cache_control = { type: 'ephemeral' };
+    const result = partitionAndMarkOpenRouterToolCache(
+      [createOpenAITool('static_one'), deferred] as GraphTools,
+      (name) => name === 'deferred_one',
+      '1h'
+    ) as OpenRouterTool[];
+
+    expect(result[0].cache_control).toEqual({ type: 'ephemeral', ttl: '1h' });
+    expect(result[1]).not.toHaveProperty('cache_control');
+  });
 });

package/src/llm/openrouter/toolCache.ts

@@ -1,12 +1,16 @@
 import type { BindToolsInput } from '@langchain/core/language_models/chat_models';
 import type { OpenAIClient } from '@langchain/openai';
 import type { GraphTools } from '@/types';
+import {
+  buildAnthropicCacheControl,
+  type PromptCacheTtl,
+} from '@/messages/cache';
 import { _convertToOpenAITool } from '@/llm/openai';
 
-const CACHE_CONTROL = { type: 'ephemeral' as const };
+type OpenRouterCacheControl = { type: 'ephemeral'; ttl?: '1h' };
 
 type OpenRouterToolWithCacheControl = OpenAIClient.ChatCompletionTool & {
-  cache_control?: typeof CACHE_CONTROL;
+  cache_control?: OpenRouterCacheControl;
   defer_loading?: boolean;
 };
 
@@ -46,17 +50,35 @@ function toOpenRouterTool(tool: unknown): OpenRouterToolWithCacheControl {
 }
 
 function markCacheControl(
-  tool: OpenRouterToolWithCacheControl
+  tool: OpenRouterToolWithCacheControl,
+  ttl?: PromptCacheTtl
 ): OpenRouterToolWithCacheControl {
   return {
     ...tool,
-    cache_control: CACHE_CONTROL,
+    cache_control: buildAnthropicCacheControl(ttl),
   };
 }
 
+/**
+ * Drop any existing `cache_control` from a tool. Reused/caller-supplied tools
+ * can carry a stale marker (e.g. from a prior `promptCacheTtl: '5m'` run); since
+ * all tools serialize before system/messages, a leftover 5-minute marker ahead
+ * of the resolved breakpoint would violate the longer-TTL-first ordering.
+ */
+function stripCacheControl(
+  tool: OpenRouterToolWithCacheControl
+): OpenRouterToolWithCacheControl {
+  if (tool.cache_control == null) {
+    return tool;
+  }
+  const { cache_control: _omit, ...rest } = tool;
+  return rest;
+}
+
 export function partitionAndMarkOpenRouterToolCache(
   tools: GraphTools | undefined,
-  isDeferred: (toolName: string) => boolean
+  isDeferred: (toolName: string) => boolean,
+  ttl?: PromptCacheTtl
 ): GraphTools | undefined {
   if (tools == null || tools.length === 0) {
     return tools;
@@ -77,12 +99,24 @@ export function partitionAndMarkOpenRouterToolCache(
     staticTools.push(converted);
   }
 
+  // Deferred tools sit after the breakpoint but still before system/messages,
+  // so strip any stale marker off them.
+  for (let i = 0; i < deferredTools.length; i++) {
+    deferredTools[i] = stripCacheControl(deferredTools[i]);
+  }
+
   if (staticTools.length === 0) {
     return [...deferredTools] as GraphTools;
   }
 
+  // Strip stale markers off the earlier static tools, then stamp only the last
+  // static tool with the resolved TTL (markCacheControl overwrites any marker).
+  for (let i = 0; i < staticTools.length - 1; i++) {
+    staticTools[i] = stripCacheControl(staticTools[i]);
+  }
   staticTools[staticTools.length - 1] = markCacheControl(
-    staticTools[staticTools.length - 1]
+    staticTools[staticTools.length - 1],
+    ttl
   );
 
   return [...staticTools, ...deferredTools] as GraphTools;