@librechat/agents 3.2.38 → 3.2.41

package/src/agents/AgentContext.ts

@@ -8,6 +8,15 @@ import type {
 } from '@langchain/core/messages';
 import type { RunnableConfig, Runnable } from '@langchain/core/runnables';
 import type * as t from '@/types';
+import {
+  addTailCacheControl,
+  addCacheControlToStablePrefixMessages,
+  buildAnthropicCacheControl,
+  buildBedrockCachePoint,
+  resolvePromptCacheTtl,
+  cloneMessage,
+  type PromptCacheTtl,
+} from '@/messages/cache';
 import {
   ANTHROPIC_TOOL_TOKEN_MULTIPLIER,
   DEFAULT_TOOL_TOKEN_MULTIPLIER,
@@ -15,30 +24,25 @@ import {
   Constants,
   Providers,
 } from '@/common';
-import {
-  addTailCacheControl,
-  addCacheControlToStablePrefixMessages,
-  cloneMessage,
-} from '@/messages/cache';
-import { createSchemaOnlyTools } from '@/tools/schema';
-import { apportionTokenCounts } from '@/utils/tokens';
 import {
   DEFAULT_RESERVE_RATIO,
   createPruneMessages,
   syncBudgetDerivedFields,
 } from '@/messages';
+import { createSchemaOnlyTools } from '@/tools/schema';
+import { apportionTokenCounts } from '@/utils/tokens';
 import { isThinkingEnabled } from '@/llm/request';
 import { toJsonSchema } from '@/utils/schema';
 
 type AgentSystemTextBlock = {
   type: 'text';
   text: string;
-  cache_control?: { type: 'ephemeral' };
+  cache_control?: { type: 'ephemeral'; ttl?: '1h' };
 };
 
 type AgentSystemContentBlock =
   | AgentSystemTextBlock
-  | { cachePoint: { type: 'default' } };
+  | { cachePoint: { type: 'default'; ttl?: '1h' } };
 
 type PromptCacheProvider = Providers.ANTHROPIC | Providers.OPENROUTER;
 
@@ -689,7 +693,10 @@ export class AgentContext {
         dynamicTail.length === 0 &&
         body.length >= 2
       ) {
-        body = addTailCacheControl(body);
+        body = addTailCacheControl(
+          body,
+          this.getPromptCacheTtl(promptCacheProvider)
+        );
       }
       return [...prefix, ...body];
     }).withConfig({ runName: 'prompt' });
@@ -713,7 +720,9 @@ export class AgentContext {
         {
           type: 'text',
           text: wrappedSummary,
-          cache_control: { type: 'ephemeral' },
+          cache_control: buildAnthropicCacheControl(
+            this.getPromptCacheTtl(Providers.ANTHROPIC)
+          ),
         },
       ],
     });
@@ -760,7 +769,10 @@ export class AgentContext {
     );
     const stablePrefix = messages.slice(0, tailIndex);
     const trailingMessages = messages.slice(tailIndex);
-    const cacheablePrefix = this.addStablePromptCacheMarkers(stablePrefix);
+    const cacheablePrefix = this.addStablePromptCacheMarkers(
+      stablePrefix,
+      this.getPromptCacheTtl(promptCacheProvider)
+    );
 
     return [...cacheablePrefix, ...tail, ...trailingMessages];
   }
@@ -791,14 +803,17 @@ export class AgentContext {
     return messages.length;
   }
 
-  private addStablePromptCacheMarkers(messages: BaseMessage[]): BaseMessage[] {
+  private addStablePromptCacheMarkers(
+    messages: BaseMessage[],
+    ttl?: PromptCacheTtl
+  ): BaseMessage[] {
     if (messages.length <= 1) {
       return messages;
     }
 
     return [
       messages[0],
-      ...addCacheControlToStablePrefixMessages(messages.slice(1), 2),
+      ...addCacheControlToStablePrefixMessages(messages.slice(1), 2, ttl),
     ];
   }
 
@@ -834,6 +849,34 @@ export class AgentContext {
     return bedrockOptions?.promptCache === true;
   }
 
+  /**
+   * Resolved TTL for the active prompt-cache provider (Anthropic or OpenRouter).
+   * Both expose `promptCacheTtl` and use the Anthropic `cache_control` format, so
+   * the configured value resolves the same way (default `'1h'` extended cache).
+   */
+  private getPromptCacheTtl(
+    provider: PromptCacheProvider | undefined
+  ): PromptCacheTtl | undefined {
+    if (provider == null) {
+      return undefined;
+    }
+    return resolvePromptCacheTtl(
+      (this.clientOptions as { promptCacheTtl?: PromptCacheTtl } | undefined)
+        ?.promptCacheTtl
+    );
+  }
+
+  /**
+   * Resolved TTL for Bedrock prompt-cache checkpoints (default `'1h'`).
+   * Models that don't support the 1-hour TTL downgrade to 5m server-side.
+   */
+  private getBedrockPromptCacheTtl(): PromptCacheTtl {
+    const bedrockOptions = this.clientOptions as
+      | t.BedrockAnthropicClientOptions
+      | undefined;
+    return resolvePromptCacheTtl(bedrockOptions?.promptCacheTtl);
+  }
+
   private buildSystemMessage({
     stableInstructions,
     dynamicInstructions,
@@ -855,7 +898,9 @@ export class AgentContext {
         content.push({
           type: 'text',
           text: stableInstructions,
-          cache_control: { type: 'ephemeral' },
+          cache_control: buildAnthropicCacheControl(
+            this.getPromptCacheTtl(promptCacheProvider)
+          ),
         });
       }
       if (dynamicInstructions && !shouldMoveDynamicInstructions) {
@@ -874,7 +919,9 @@ export class AgentContext {
           {
             type: 'text',
             text: stableInstructions,
-            cache_control: { type: 'ephemeral' },
+            cache_control: buildAnthropicCacheControl(
+              this.getPromptCacheTtl(promptCacheProvider)
+            ),
           },
         ],
       } as BaseMessageFields);
@@ -883,7 +930,7 @@ export class AgentContext {
     if (this.hasBedrockPromptCache() && stableInstructions) {
       const content: AgentSystemContentBlock[] = [
         { type: 'text', text: stableInstructions },
-        { cachePoint: { type: 'default' } },
+        { cachePoint: buildBedrockCachePoint(this.getBedrockPromptCacheTtl()) },
       ];
       if (dynamicInstructions) {
         content.push({ type: 'text', text: dynamicInstructions });

package/src/agents/__tests__/AgentContext.anthropic.live.test.ts

@@ -187,7 +187,11 @@ function addLatestUserOnlyAnthropicCacheControl(
       if (!modified) {
         continue;
       }
-    } else if (typeof content === 'string' && content.trim() !== '' && canAddCache) {
+    } else if (
+      typeof content === 'string' &&
+      content.trim() !== '' &&
+      canAddCache
+    ) {
       workingContent = [
         {
           type: 'text',
@@ -348,7 +352,7 @@ describeIfLive('AgentContext Anthropic prompt cache live API', () => {
         {
           type: 'text',
           text: stableInstructions,
-          cache_control: { type: 'ephemeral' },
+          cache_control: { type: 'ephemeral', ttl: '1h' },
         },
       ],
     });

package/src/agents/__tests__/AgentContext.bedrock.live.test.ts

@@ -279,7 +279,11 @@ function addLatestUserOnlyBedrockCacheControl(
       if (!modified) {
         continue;
       }
-    } else if (typeof content === 'string' && content.trim() !== '' && canAddCache) {
+    } else if (
+      typeof content === 'string' &&
+      content.trim() !== '' &&
+      canAddCache
+    ) {
       workingContent = [
         { type: 'text', text: content } as MessageContentComplex,
         cachePointBlock(),
@@ -490,7 +494,7 @@ describeIfLive('AgentContext Bedrock prompt cache live API', () => {
           text: stableInstructions,
         },
         {
-          cachePoint: { type: 'default' },
+          cachePoint: { type: 'default', ttl: '1h' },
         },
         {
           type: 'text',
@@ -643,9 +647,7 @@ describeIfLive('AgentContext Bedrock prompt cache live API', () => {
       })}\n`
     );
 
-    expect(currentSecond.cacheRead).toBeGreaterThan(
-      latestOnlySecond.cacheRead
-    );
+    expect(currentSecond.cacheRead).toBeGreaterThan(latestOnlySecond.cacheRead);
     expect(currentSecond.cacheCreation).toBeLessThan(
       latestOnlySecond.cacheCreation
     );

package/src/agents/__tests__/AgentContext.openrouter.live.test.ts

@@ -93,7 +93,7 @@ describeIfLive('AgentContext OpenRouter prompt cache live API', () => {
         {
           type: 'text',
           text: stableInstructions,
-          cache_control: { type: 'ephemeral' },
+          cache_control: { type: 'ephemeral', ttl: '1h' },
         },
       ],
     });

package/src/agents/__tests__/AgentContext.test.ts

@@ -7,8 +7,12 @@ import { AgentContext } from '../AgentContext';
 
 describe('AgentContext', () => {
   type TestSystemContentBlock =
-    | { type: 'text'; text: string; cache_control?: { type: 'ephemeral' } }
-    | { cachePoint: { type: 'default' } };
+    | {
+        type: 'text';
+        text: string;
+        cache_control?: { type: 'ephemeral'; ttl?: '1h' };
+      }
+    | { cachePoint: { type: 'default'; ttl?: '1h' } };
 
   type ContextOptions = {
     agentConfig?: Partial<t.AgentInputs>;
@@ -98,7 +102,7 @@ describe('AgentContext', () => {
         {
           type: 'text',
           text: 'Stable instructions',
-          cache_control: { type: 'ephemeral' },
+          cache_control: { type: 'ephemeral', ttl: '1h' },
         },
       ]);
       expect(result[1].content).toBe('Hello');
@@ -164,7 +168,7 @@ describe('AgentContext', () => {
         agentConfig: {
           provider: Providers.BEDROCK,
           clientOptions: {
-            model: 'anthropic.claude-3-5-sonnet',
+            model: 'anthropic.claude-sonnet-4-5-20250929-v1:0',
             promptCache: true,
           },
           instructions: 'Stable instructions',
@@ -176,7 +180,7 @@ describe('AgentContext', () => {
       const content = result[0].content as TestSystemContentBlock[];
       expect(content).toEqual([
         { type: 'text', text: 'Stable instructions' },
-        { cachePoint: { type: 'default' } },
+        { cachePoint: { type: 'default', ttl: '1h' } },
         { type: 'text', text: 'Dynamic instructions' },
       ]);
     });
@@ -186,7 +190,7 @@ describe('AgentContext', () => {
         agentConfig: {
           provider: Providers.BEDROCK,
           clientOptions: {
-            model: 'anthropic.claude-3-5-sonnet',
+            model: 'anthropic.claude-sonnet-4-5-20250929-v1:0',
             promptCache: true,
           },
           instructions: undefined,
@@ -240,7 +244,7 @@ describe('AgentContext', () => {
         {
           type: 'text',
           text: 'Stable instructions',
-          cache_control: { type: 'ephemeral' },
+          cache_control: { type: 'ephemeral', ttl: '1h' },
         },
       ]);
       expect(result[1].content).toBe('Hello');
@@ -730,7 +734,7 @@ describe('AgentContext', () => {
         agentConfig: {
           provider: Providers.BEDROCK,
           clientOptions: {
-            model: 'anthropic.claude-3-5-sonnet',
+            model: 'anthropic.claude-sonnet-4-5-20250929-v1:0',
             promptCache: true,
           },
           instructions: 'Stable instructions',
@@ -741,10 +745,12 @@ describe('AgentContext', () => {
       const result = await ctx.systemRunnable!.invoke([
         new HumanMessage('Hello'),
       ]);
-      const finalMessages = addBedrockCacheControl(result);
+      // The graph applies the same resolved TTL it stamped on the system
+      // checkpoint, so the 1h system cachePoint is preserved (normalized to 1h).
+      const finalMessages = addBedrockCacheControl(result, '1h');
       expect(finalMessages[0].content).toEqual([
         { type: 'text', text: 'Stable instructions' },
-        { cachePoint: { type: 'default' } },
+        { cachePoint: { type: 'default', ttl: '1h' } },
         { type: 'text', text: 'Dynamic instructions' },
       ]);
     });
@@ -2154,7 +2160,7 @@ describe('AgentContext', () => {
     const buildBranch = (
       maxContextTokens: number,
       perMessageTokens: number,
-      count: number,
+      count: number
     ): { ctx: AgentContext; messages: AIMessage[] } => {
       const ctx = createBasicContext({ tokenCounter: countByChars });
       ctx.maxContextTokens = maxContextTokens;
@@ -2166,7 +2172,7 @@ describe('AgentContext', () => {
         messages.push(
           i % 2 === 0
             ? (new HumanMessage(content) as unknown as AIMessage)
-            : new AIMessage(content),
+            : new AIMessage(content)
         );
       }
       return { ctx, messages };
@@ -2175,7 +2181,9 @@ describe('AgentContext', () => {
     it('returns null without a tokenizer or a window', () => {
       const noCounter = createBasicContext({});
       noCounter.maxContextTokens = 1000;
-      expect(noCounter.projectContextUsage([new HumanMessage('hi')])).toBeNull();
+      expect(
+        noCounter.projectContextUsage([new HumanMessage('hi')])
+      ).toBeNull();
 
       const noWindow = createBasicContext({ tokenCounter: countByChars });
       noWindow.maxContextTokens = undefined;
@@ -2207,7 +2215,9 @@ describe('AgentContext', () => {
       expect(usage!.remainingContextTokens).toBeGreaterThanOrEqual(0);
 
       const max = usage!.contextBudget ?? usage!.breakdown.maxContextTokens;
-      expect(max - (usage!.remainingContextTokens ?? 0)).toBeLessThanOrEqual(max);
+      expect(max - (usage!.remainingContextTokens ?? 0)).toBeLessThanOrEqual(
+        max
+      );
     });
 
     it('does not mutate the context (local pruner, no field writes)', () => {
@@ -2245,7 +2255,7 @@ describe('AgentContext', () => {
 
       expect(messages[2]).toBe(originalRef);
       expect((messages[2] as unknown as ToolMessage).content).toBe(
-        originalContent,
+        originalContent
       );
     });
 
@@ -2257,7 +2267,9 @@ describe('AgentContext', () => {
       ctx.indexTokenCountMap = {};
       const messages: AIMessage[] = [];
       for (let i = 0; i < 6; i++) {
-        messages.push(new HumanMessage('x'.repeat(1_000)) as unknown as AIMessage);
+        messages.push(
+          new HumanMessage('x'.repeat(1_000)) as unknown as AIMessage
+        );
       }
 
       const usage = ctx.projectContextUsage(messages);
@@ -2285,7 +2297,7 @@ describe('AgentContext', () => {
         const ctx = createBasicContext({ tokenCounter: countByChars });
         ctx.maxContextTokens = 5_000;
         const messages: AIMessage[] = [0, 1, 2].map(
-          () => new HumanMessage('x'.repeat(1_000)) as unknown as AIMessage,
+          () => new HumanMessage('x'.repeat(1_000)) as unknown as AIMessage
         );
         return { ctx, messages };
       };
@@ -2303,7 +2315,7 @@ describe('AgentContext', () => {
       const dirtyUsage = dirty.ctx.projectContextUsage(dirty.messages);
 
       expect(dirtyUsage!.remainingContextTokens).toBe(
-        cleanUsage!.remainingContextTokens,
+        cleanUsage!.remainingContextTokens
       );
       expect(dirtyUsage!.calibrationRatio).toBe(cleanUsage!.calibrationRatio);
     });
@@ -2350,7 +2362,7 @@ describe('AgentContext', () => {
 
       expect(scaledUsage!.calibrationRatio).toBe(3);
       expect(scaledUsage!.remainingContextTokens).not.toBe(
-        baseUsage!.remainingContextTokens,
+        baseUsage!.remainingContextTokens
       );
     });
 

package/src/agents/__tests__/promptCacheLiveHelpers.ts

@@ -15,8 +15,12 @@ type LivePromptCacheProvider =
   | Providers.OPENROUTER;
 
 type PromptCacheExpectedSystemBlock =
-  | { type: 'text'; text: string; cache_control?: { type: 'ephemeral' } }
-  | { cachePoint: { type: 'default' } };
+  | {
+      type: 'text';
+      text: string;
+      cache_control?: { type: 'ephemeral'; ttl?: '1h' };
+    }
+  | { cachePoint: { type: 'default'; ttl?: '1h' } };
 
 type LivePromptCacheClientOptions =
   | t.ClientOptions

package/src/graphs/Graph.ts

@@ -27,6 +27,7 @@ import {
   createPruneMessages,
   syncBudgetDerivedFields,
   addTailCacheControl,
+  resolvePromptCacheTtl,
   getMessageId,
   makeIsDeferred,
   partitionAndMarkAnthropicToolCache,
@@ -1404,7 +1405,14 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
         toolsForBinding =
           partitionAndMarkAnthropicToolCache(
             rawToolsForBinding,
-            makeIsDeferred(agentContext.toolDefinitions)
+            makeIsDeferred(agentContext.toolDefinitions),
+            resolvePromptCacheTtl(
+              (
+                agentContext.clientOptions as
+                  | t.AnthropicClientOptions
+                  | undefined
+              )?.promptCacheTtl
+            )
           ) ?? rawToolsForBinding;
       } else if (
         agentContext.provider === Providers.OPENROUTER &&
@@ -1417,7 +1425,14 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
         toolsForBinding =
           partitionAndMarkOpenRouterToolCache(
             rawToolsForBinding,
-            makeIsDeferred(agentContext.toolDefinitions)
+            makeIsDeferred(agentContext.toolDefinitions),
+            resolvePromptCacheTtl(
+              (
+                agentContext.clientOptions as
+                  | t.ProviderOptionsMap[Providers.OPENROUTER]
+                  | undefined
+              )?.promptCacheTtl
+            )
           ) ?? rawToolsForBinding;
       } else if (
         agentContext.provider === Providers.BEDROCK &&
@@ -1833,9 +1848,30 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
         (anthropicPromptCacheEnabled || openRouterPromptCacheEnabled) &&
         !agentContext.systemRunnable
       ) {
-        finalMessages = addTailCacheControl<BaseMessage>(finalMessages);
+        finalMessages = addTailCacheControl<BaseMessage>(
+          finalMessages,
+          resolvePromptCacheTtl(
+            anthropicPromptCacheEnabled
+              ? (
+                  agentContext.clientOptions as
+                    | t.AnthropicClientOptions
+                    | undefined
+              )?.promptCacheTtl
+              : (
+                  agentContext.clientOptions as
+                    | t.ProviderOptionsMap[Providers.OPENROUTER]
+                    | undefined
+              )?.promptCacheTtl
+          )
+        );
       } else if (bedrockPromptCacheEnabled) {
-        finalMessages = addBedrockTailCacheControl<BaseMessage>(finalMessages);
+        const bedrockOptions = agentContext.clientOptions as
+          | t.BedrockAnthropicClientOptions
+          | undefined;
+        finalMessages = addBedrockTailCacheControl<BaseMessage>(
+          finalMessages,
+          resolvePromptCacheTtl(bedrockOptions?.promptCacheTtl)
+        );
       }
 
       if (

package/src/hooks/__tests__/createWorkspacePolicyHook.test.ts

@@ -51,7 +51,7 @@ describe('createWorkspacePolicyHook', () => {
     const hook = createWorkspacePolicyHook({ root: workspace });
     const out = await call(
       hook,
-      makeInput('read_file', { file_path: 'src/x.ts' })
+      makeInput('read_file', { path: 'src/x.ts' })
     );
     expect(out.decision).toBe('allow');
   });
@@ -60,7 +60,7 @@ describe('createWorkspacePolicyHook', () => {
     const hook = createWorkspacePolicyHook({ root: workspace });
     const out = await call(
       hook,
-      makeInput('read_file', { file_path: join(workspace, 'src/x.ts') })
+      makeInput('read_file', { path: join(workspace, 'src/x.ts') })
     );
     expect(out.decision).toBe('allow');
   });
@@ -72,7 +72,7 @@ describe('createWorkspacePolicyHook', () => {
     });
     const out = await call(
       hook,
-      makeInput('read_file', { file_path: join(extra, 'lib/y.ts') })
+      makeInput('read_file', { path: join(extra, 'lib/y.ts') })
     );
     expect(out.decision).toBe('allow');
   });
@@ -81,7 +81,7 @@ describe('createWorkspacePolicyHook', () => {
     const hook = createWorkspacePolicyHook({ root: workspace });
     const out = await call(
       hook,
-      makeInput('read_file', { file_path: '/etc/passwd' })
+      makeInput('read_file', { path: '/etc/passwd' })
     );
     expect(out.decision).toBe('ask');
     expect(out.reason).toContain('/etc/passwd');
@@ -93,7 +93,7 @@ describe('createWorkspacePolicyHook', () => {
     const out = await call(
       hook,
       makeInput('write_file', {
-        file_path: '/etc/foo',
+        path: '/etc/foo',
         content: 'malicious',
       })
     );
@@ -107,7 +107,7 @@ describe('createWorkspacePolicyHook', () => {
     });
     const out = await call(
       hook,
-      makeInput('read_file', { file_path: '/etc/passwd' })
+      makeInput('read_file', { path: '/etc/passwd' })
     );
     expect(out.decision).toBe('deny');
     expect(out.reason).toContain('/etc/passwd');
@@ -121,7 +121,7 @@ describe('createWorkspacePolicyHook', () => {
     const out = await call(
       hook,
       makeInput('edit_file', {
-        file_path: '/etc/foo',
+        path: '/etc/foo',
         old_text: 'a',
         new_text: 'b',
       })
@@ -136,7 +136,7 @@ describe('createWorkspacePolicyHook', () => {
     });
     const out = await call(
       hook,
-      makeInput('read_file', { file_path: '/etc/passwd' })
+      makeInput('read_file', { path: '/etc/passwd' })
     );
     expect(out.decision).toBe('allow');
   });
@@ -184,7 +184,7 @@ describe('createWorkspacePolicyHook', () => {
     });
     const out = await call(
       hook,
-      makeInput('read_file', { file_path: '/somewhere/else.ts' })
+      makeInput('read_file', { path: '/somewhere/else.ts' })
     );
     expect(out.reason).toBe('read_file blocked from /somewhere/else.ts');
   });
@@ -212,7 +212,7 @@ describe('createWorkspacePolicyHook', () => {
     const hook = createWorkspacePolicyHook({ root: '.' });
     const out = await call(
       hook,
-      makeInput('read_file', { file_path: resolve('.', 'src/x.ts') })
+      makeInput('read_file', { path: resolve('.', 'src/x.ts') })
     );
     expect(out.decision).toBe('allow');
   });
@@ -228,7 +228,7 @@ describe('createWorkspacePolicyHook', () => {
       });
       const out = await call(
         hook,
-        makeInput('read_file', { file_path: 'escape' })
+        makeInput('read_file', { path: 'escape' })
       );
       expect(out.decision).toBe('deny');
       expect(out.reason).toContain('escape');
@@ -245,7 +245,7 @@ describe('createWorkspacePolicyHook', () => {
       });
       const out = await call(
         hook,
-        makeInput('read_file', { file_path: join(altMount, 'file.ts') })
+        makeInput('read_file', { path: join(altMount, 'file.ts') })
       );
       expect(out.decision).toBe('allow');
     });

package/src/hooks/createWorkspacePolicyHook.ts

@@ -166,13 +166,14 @@ function extractCompileCheckPaths(input: Record<string, unknown>): string[] {
   return out;
 }
 
+// All built-in coding tools take their file/dir target in `path`.
+const extractPath: PathExtractor = (i) =>
+  typeof i.path === 'string' && i.path !== '' ? [i.path] : [];
+
 const DEFAULT_EXTRACTORS: Record<string, PathExtractor> = {
-  [Constants.READ_FILE]: (i) =>
-    typeof i.file_path === 'string' ? [i.file_path] : [],
-  [Constants.WRITE_FILE]: (i) =>
-    typeof i.file_path === 'string' ? [i.file_path] : [],
-  [Constants.EDIT_FILE]: (i) =>
-    typeof i.file_path === 'string' ? [i.file_path] : [],
+  [Constants.READ_FILE]: extractPath,
+  [Constants.WRITE_FILE]: extractPath,
+  [Constants.EDIT_FILE]: extractPath,
   [Constants.GREP_SEARCH]: (i) =>
     typeof i.path === 'string' && i.path !== '' ? [i.path] : [],
   [Constants.GLOB_SEARCH]: (i) =>