@librechat/agents 3.2.38 → 3.2.39

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;

package/src/messages/__tests__/anthropicToolCache.test.ts

@@ -140,6 +140,174 @@ describe('partitionAndMarkAnthropicToolCache', () => {
     // is returned unchanged (same reference) so we don't churn the array.
     expect(partitionAndMarkAnthropicToolCache(input, () => false)).toBe(input);
   });
+
+  it('stamps the resolved 1h ttl on the last static tool', () => {
+    const out = partitionAndMarkAnthropicToolCache(
+      [fakeTool('a-static'), fakeTool('b-static')] as never,
+      () => false,
+      '1h'
+    ) as Array<{
+      extras?: { cache_control?: { type: string; ttl?: string } };
+    }>;
+    expect(out[1].extras?.cache_control).toEqual({
+      type: 'ephemeral',
+      ttl: '1h',
+    });
+    expect(out[0].extras?.cache_control).toBeUndefined();
+  });
+
+  it('re-stamps a pre-marked 5m tool to 1h so it does not precede a 1h breakpoint', () => {
+    const a = fakeTool('a-static') as {
+      extras?: { cache_control?: { type: string; ttl?: string } };
+    };
+    a.extras = { cache_control: { type: 'ephemeral' } };
+    const out = partitionAndMarkAnthropicToolCache(
+      [a] as never,
+      () => false,
+      '1h'
+    ) as Array<{
+      extras?: { cache_control?: { type: string; ttl?: string } };
+    }>;
+    expect(out[0].extras?.cache_control).toEqual({
+      type: 'ephemeral',
+      ttl: '1h',
+    });
+  });
+
+  it('strips a pre-marked earlier static tool so only the tail carries the 1h marker', () => {
+    const a = fakeTool('a-static') as {
+      extras?: { cache_control?: { type: string; ttl?: string } };
+    };
+    a.extras = { cache_control: { type: 'ephemeral' } };
+    const b = fakeTool('b-static');
+    const out = partitionAndMarkAnthropicToolCache(
+      [a, b] as never,
+      () => false,
+      '1h'
+    ) as Array<{
+      extras?: { cache_control?: { type: string; ttl?: string } };
+    }>;
+    // Earlier tool's stray 5m marker is removed so it can't precede the tail.
+    expect(out[0].extras?.cache_control).toBeUndefined();
+    expect(out[1].extras?.cache_control).toEqual({
+      type: 'ephemeral',
+      ttl: '1h',
+    });
+  });
+
+  it('strips stale markers off deferred tools so they do not precede the system/message breakpoint', () => {
+    const staticTool = fakeTool('a-static');
+    const deferred = fakeTool('b-deferred') as {
+      extras?: { cache_control?: { type: string } };
+    };
+    deferred.extras = { cache_control: { type: 'ephemeral' } };
+    const out = partitionAndMarkAnthropicToolCache(
+      [staticTool, deferred] as never,
+      (name) => name === 'b-deferred',
+      '1h'
+    ) as Array<{
+      extras?: { cache_control?: { type: string; ttl?: string } };
+    }>;
+    expect(out[0].extras?.cache_control).toEqual({
+      type: 'ephemeral',
+      ttl: '1h',
+    });
+    expect(out[1].extras?.cache_control).toBeUndefined();
+  });
+
+  it('strips stale markers in the all-deferred case', () => {
+    const deferred = fakeTool('only-deferred') as {
+      extras?: { cache_control?: { type: string } };
+    };
+    deferred.extras = { cache_control: { type: 'ephemeral' } };
+    const out = partitionAndMarkAnthropicToolCache(
+      [deferred] as never,
+      () => true,
+      '1h'
+    ) as Array<{ extras?: { cache_control?: unknown } }>;
+    expect(out[0].extras?.cache_control).toBeUndefined();
+  });
+
+  it('strips a direct cache_control on an earlier native (non-built-in) tool', () => {
+    const nativeWithMarker = {
+      name: 'native_a',
+      input_schema: { type: 'object', properties: {} },
+      cache_control: { type: 'ephemeral' },
+    };
+    const out = partitionAndMarkAnthropicToolCache(
+      [nativeWithMarker, fakeTool('native_b')] as never,
+      () => false,
+      '1h'
+    ) as Array<{
+      cache_control?: unknown;
+      extras?: { cache_control?: { type: string; ttl?: string } };
+    }>;
+    expect(out[0].cache_control).toBeUndefined();
+    expect(out[1].extras?.cache_control).toEqual({
+      type: 'ephemeral',
+      ttl: '1h',
+    });
+  });
+
+  it('upgrades a raw Anthropic tail tool to a direct 1h marker (not extras)', () => {
+    const nativeTail = {
+      name: 'native_tail',
+      input_schema: { type: 'object', properties: {} },
+      cache_control: { type: 'ephemeral' },
+    };
+    const out = partitionAndMarkAnthropicToolCache(
+      [nativeTail] as never,
+      () => false,
+      '1h'
+    ) as Array<{
+      cache_control?: { type: string; ttl?: string };
+      extras?: { cache_control?: unknown };
+    }>;
+    // Raw Anthropic tools carry cache_control directly (extras is not promoted
+    // for them), so the stale marker is upgraded in place to 1h — not moved.
+    expect(out[0].cache_control).toEqual({ type: 'ephemeral', ttl: '1h' });
+    expect(out[0].extras?.cache_control).toBeUndefined();
+  });
+
+  it('reorders deferred tools after a correctly pre-marked static tool', () => {
+    const deferred = fakeTool('z-deferred');
+    const staticTool = fakeTool('a-static') as {
+      extras?: { cache_control?: { type: string; ttl?: string } };
+    };
+    // Already carries the resolved 1h marker, so nothing is mutated...
+    staticTool.extras = { cache_control: { type: 'ephemeral', ttl: '1h' } };
+    const out = partitionAndMarkAnthropicToolCache(
+      [deferred, staticTool] as never, // deferred precedes static in the input
+      (name) => name === 'z-deferred',
+      '1h'
+    ) as Array<{ name?: string }>;
+    // ...but the static (cached) tool must still be hoisted ahead of the
+    // deferred tool so the breakpoint precedes discovered tools.
+    expect(out.map((t) => t.name)).toEqual(['a-static', 'z-deferred']);
+  });
+
+  it('re-stamps a LangChain tool whose marker sits only on the direct block', () => {
+    // A StructuredTool (custom) pre-marked directly — not under extras — does
+    // not reach the payload, so the breakpoint must be re-stamped under extras.
+    const t = fakeTool('a-static') as {
+      cache_control?: unknown;
+      extras?: { cache_control?: { type: string; ttl?: string } };
+    };
+    t.cache_control = { type: 'ephemeral', ttl: '1h' };
+    const out = partitionAndMarkAnthropicToolCache(
+      [t] as never,
+      () => false,
+      '1h'
+    ) as Array<{
+      cache_control?: unknown;
+      extras?: { cache_control?: { type: string; ttl?: string } };
+    }>;
+    expect(out[0].extras?.cache_control).toEqual({
+      type: 'ephemeral',
+      ttl: '1h',
+    });
+    expect(out[0].cache_control).toBeUndefined();
+  });
 });
 
 describe('makeIsDeferred', () => {