@librechat/agents 3.2.38 → 3.2.41

package/src/messages/cache.ts

@@ -20,6 +20,65 @@ type MessageContentWithCacheControl = MessageContentComplex & {
   cache_control?: unknown;
 };
 
+/**
+ * Prompt-cache breakpoint TTL.
+ *
+ * Both Anthropic (`cache_control.ttl`) and Bedrock (`cachePoint.ttl`) accept
+ * `'5m'` (the legacy provider default) and `'1h'` (the extended cache). When
+ * prompt caching is enabled the SDK now defaults to the 1-hour extended cache
+ * (see {@link DEFAULT_PROMPT_CACHE_TTL}); pass `'5m'` to opt back into the
+ * legacy 5-minute behavior.
+ */
+export type PromptCacheTtl = '5m' | '1h';
+
+/**
+ * Default TTL applied wherever a prompt-cache breakpoint is added. The 1-hour
+ * extended cache keeps prefixes warm across longer gaps between turns, at the
+ * cost of a higher one-time cache-write multiplier (2x vs 1.25x for 5m).
+ */
+export const DEFAULT_PROMPT_CACHE_TTL: PromptCacheTtl = '1h';
+
+/**
+ * Resolve an optionally-configured TTL to a concrete value, defaulting to the
+ * 1-hour extended cache. Used at the Anthropic/Bedrock prompt-cache call sites.
+ */
+export function resolvePromptCacheTtl(
+  ttl: PromptCacheTtl | undefined
+): PromptCacheTtl {
+  return ttl ?? DEFAULT_PROMPT_CACHE_TTL;
+}
+
+/** Anthropic `cache_control` shape (the SDK accepts an optional `ttl`). */
+type AnthropicCacheControl = { type: 'ephemeral'; ttl?: '1h' };
+
+/**
+ * Build an Anthropic `cache_control` breakpoint for the given TTL. `'5m'` (or
+ * `undefined`) omits the `ttl` field — that is the provider default, so the
+ * payload stays byte-identical to the legacy 5-minute marker. `'1h'` adds the
+ * explicit extended-cache `ttl`.
+ */
+export function buildAnthropicCacheControl(
+  ttl?: PromptCacheTtl
+): AnthropicCacheControl {
+  return ttl === '1h'
+    ? { type: 'ephemeral', ttl: '1h' }
+    : { type: 'ephemeral' };
+}
+
+/** Bedrock `cachePoint` shape (the SDK accepts an optional `ttl`). */
+type BedrockCachePoint = { type: 'default'; ttl?: '1h' };
+
+/**
+ * Build a Bedrock `cachePoint` for the given TTL. Mirrors
+ * {@link buildAnthropicCacheControl}: `'5m'`/`undefined` omits `ttl` (the
+ * legacy default), `'1h'` adds the extended-cache `ttl`.
+ */
+export function buildBedrockCachePoint(
+  ttl?: PromptCacheTtl
+): BedrockCachePoint {
+  return ttl === '1h' ? { type: 'default', ttl: '1h' } : { type: 'default' };
+}
+
 /**
  * Deep clones a message's content to prevent mutation of the original.
  */
@@ -119,38 +178,53 @@ export function cloneMessage<T extends MessageWithContent>(
   return cloned;
 }
 
-function stripAnthropicCacheControlFromBlocks(
-  content: MessageContentComplex[]
-): { content: MessageContentComplex[]; modified: boolean } {
-  let modified = false;
-  const strippedContent = content.map((block) => {
-    if (!('cache_control' in block)) {
-      return block;
-    }
-
-    const cloned: MessageContentWithCacheControl = { ...block };
-    delete cloned.cache_control;
-    modified = true;
-    return cloned;
-  });
-
-  return { content: strippedContent, modified };
-}
-
+/**
+ * Sanitize a Bedrock system message: strip Anthropic `cache_control` (Bedrock
+ * conversion can't use it) and normalize any existing `cachePoint` to the
+ * resolved TTL. The normalization matters because Bedrock requires longer-TTL
+ * checkpoints to appear before shorter ones — a stale 5-minute system cachePoint
+ * (host-supplied or carried over from a 5m config) left ahead of a 1-hour
+ * message tail would make the request invalid. System messages are never
+ * anchored as the tail breakpoint; this only fixes markers already present.
+ */
 function sanitizeBedrockSystemMessage<T extends MessageWithContent>(
-  message: T
+  message: T,
+  ttl?: PromptCacheTtl
 ): T {
   const content = message.content;
   if (!Array.isArray(content)) {
     return message;
   }
 
-  const stripped = stripAnthropicCacheControlFromBlocks(content);
-  if (!stripped.modified) {
+  const sanitized: MessageContentComplex[] = [];
+  let modified = false;
+  for (const block of content) {
+    if (isCachePoint(block)) {
+      const existing = (block as { cachePoint?: { ttl?: unknown } }).cachePoint;
+      const desired = buildBedrockCachePoint(ttl);
+      if (existing?.ttl !== desired.ttl) {
+        modified = true;
+        sanitized.push({ cachePoint: desired } as MessageContentComplex);
+      } else {
+        sanitized.push(block);
+      }
+      continue;
+    }
+    if ('cache_control' in block) {
+      const cloned: MessageContentWithCacheControl = { ...block };
+      delete cloned.cache_control;
+      modified = true;
+      sanitized.push(cloned);
+      continue;
+    }
+    sanitized.push(block);
+  }
+
+  if (!modified) {
     return message;
   }
 
-  return cloneMessage(message, stripped.content);
+  return cloneMessage(message, sanitized);
 }
 
 /**
@@ -163,7 +237,8 @@ function sanitizeBedrockSystemMessage<T extends MessageWithContent>(
  * @returns - A new array of message objects with cache control added.
  */
 export function addCacheControl<T extends AnthropicMessage | BaseMessage>(
-  messages: T[]
+  messages: T[],
+  ttl?: PromptCacheTtl
 ): T[] {
   if (!Array.isArray(messages) || messages.length < 2) {
     return messages;
@@ -224,14 +299,16 @@ export function addCacheControl<T extends AnthropicMessage | BaseMessage>(
       if (needsCacheAdd && lastTextIndex >= 0) {
         (
           workingContent[lastTextIndex] as Anthropic.TextBlockParam
-        ).cache_control = {
-          type: 'ephemeral',
-        };
+        ).cache_control = buildAnthropicCacheControl(ttl);
         userMessagesModified++;
       }
     } else if (typeof content === 'string' && needsCacheAdd) {
       workingContent = [
-        { type: 'text', text: content, cache_control: { type: 'ephemeral' } },
+        {
+          type: 'text',
+          text: content,
+          cache_control: buildAnthropicCacheControl(ttl),
+        },
       ] as unknown as MessageContentComplex[];
       userMessagesModified++;
     } else {
@@ -318,7 +395,8 @@ function isTailCacheableBlock(block: MessageContentComplex): boolean {
  * Returns a new array; only messages that require modification are cloned.
  */
 export function addTailCacheControl<T extends AnthropicMessage | BaseMessage>(
-  messages: T[]
+  messages: T[],
+  ttl?: PromptCacheTtl
 ): T[] {
   if (!Array.isArray(messages) || messages.length === 0) {
     return messages;
@@ -368,9 +446,7 @@ export function addTailCacheControl<T extends AnthropicMessage | BaseMessage>(
 
       if (canPlaceMarker && tailIndex >= 0) {
         (workingContent[tailIndex] as Anthropic.TextBlockParam).cache_control =
-          {
-            type: 'ephemeral',
-          };
+          buildAnthropicCacheControl(ttl);
         markerPlaced = true;
         modified = true;
       }
@@ -384,7 +460,11 @@ export function addTailCacheControl<T extends AnthropicMessage | BaseMessage>(
       content.trim() !== ''
     ) {
       workingContent = [
-        { type: 'text', text: content, cache_control: { type: 'ephemeral' } },
+        {
+          type: 'text',
+          text: content,
+          cache_control: buildAnthropicCacheControl(ttl),
+        },
       ] as unknown as MessageContentComplex[];
       markerPlaced = true;
     } else {
@@ -454,7 +534,8 @@ function addCacheControlToRecentMessages<
 >(
   messages: T[],
   maxCachePoints: number,
-  canUseMessage: (message: MessageWithContent) => boolean
+  canUseMessage: (message: MessageWithContent) => boolean,
+  ttl?: PromptCacheTtl
 ): T[] {
   if (
     !Array.isArray(messages) ||
@@ -513,9 +594,7 @@ function addCacheControlToRecentMessages<
       if (canAddCache && lastNonEmptyTextIndex >= 0) {
         (
           workingContent[lastNonEmptyTextIndex] as Anthropic.TextBlockParam
-        ).cache_control = {
-          type: 'ephemeral',
-        };
+        ).cache_control = buildAnthropicCacheControl(ttl);
         cachePointsAdded++;
         modified = true;
       }
@@ -529,7 +608,11 @@ function addCacheControlToRecentMessages<
       canAddCache
     ) {
       workingContent = [
-        { type: 'text', text: content, cache_control: { type: 'ephemeral' } },
+        {
+          type: 'text',
+          text: content,
+          cache_control: buildAnthropicCacheControl(ttl),
+        },
       ] as unknown as MessageContentComplex[];
       cachePointsAdded++;
     } else {
@@ -547,11 +630,12 @@ function addCacheControlToRecentMessages<
 
 export function addCacheControlToStablePrefixMessages<
   T extends AnthropicMessage | BaseMessage,
->(messages: T[], maxCachePoints: number): T[] {
+>(messages: T[], maxCachePoints: number, ttl?: PromptCacheTtl): T[] {
   const assistantMarked = addCacheControlToRecentMessages(
     messages,
     maxCachePoints,
-    isAssistantConversationMessage
+    isAssistantConversationMessage,
+    ttl
   );
 
   if (assistantMarked.some(hasCacheMarker)) {
@@ -561,7 +645,8 @@ export function addCacheControlToStablePrefixMessages<
   return addCacheControlToRecentMessages(
     messages,
     maxCachePoints,
-    isCacheableConversationMessage
+    isCacheableConversationMessage,
+    ttl
   );
 }
 
@@ -664,7 +749,7 @@ export function stripBedrockCacheControl<T extends MessageWithContent>(
  */
 export function addBedrockCacheControl<
   T extends MessageWithContent & { getType?: () => string; role?: string },
->(messages: T[]): T[] {
+>(messages: T[], ttl?: PromptCacheTtl): T[] {
   if (!Array.isArray(messages) || messages.length === 0) {
     return messages;
   }
@@ -687,7 +772,7 @@ export function addBedrockCacheControl<
     const isSystemMessage =
       messageType === 'system' || messageRole === 'system';
     if (isSystemMessage) {
-      updatedMessages[i] = sanitizeBedrockSystemMessage(originalMessage);
+      updatedMessages[i] = sanitizeBedrockSystemMessage(originalMessage, ttl);
       continue;
     }
 
@@ -750,14 +835,14 @@ export function addBedrockCacheControl<
       // Skip if no cacheable text content exists (whitespace-only messages).
       if (needsCacheAdd && lastNonEmptyTextIndex >= 0) {
         workingContent.splice(lastNonEmptyTextIndex + 1, 0, {
-          cachePoint: { type: 'default' },
+          cachePoint: buildBedrockCachePoint(ttl),
         } as MessageContentComplex);
         cachePointsAdded++;
       }
     } else if (typeof content === 'string' && needsCacheAdd) {
       workingContent = [
         { type: ContentTypes.TEXT, text: content },
-        { cachePoint: { type: 'default' } } as MessageContentComplex,
+        { cachePoint: buildBedrockCachePoint(ttl) } as MessageContentComplex,
       ];
       cachePointsAdded++;
     } else if (typeof content === 'string' && hasSerializationProps) {
@@ -791,7 +876,7 @@ export function addBedrockCacheControl<
  */
 export function addBedrockTailCacheControl<
   T extends MessageWithContent & { getType?: () => string; role?: string },
->(messages: T[]): T[] {
+>(messages: T[], ttl?: PromptCacheTtl): T[] {
   if (!Array.isArray(messages) || messages.length === 0) {
     return messages;
   }
@@ -814,7 +899,7 @@ export function addBedrockTailCacheControl<
     const isSystemMessage =
       messageType === 'system' || messageRole === 'system';
     if (isSystemMessage) {
-      updatedMessages[i] = sanitizeBedrockSystemMessage(originalMessage);
+      updatedMessages[i] = sanitizeBedrockSystemMessage(originalMessage, ttl);
       continue;
     }
 
@@ -869,7 +954,7 @@ export function addBedrockTailCacheControl<
 
       if (canPlaceCachePoint && lastNonEmptyTextIndex >= 0) {
         workingContent.splice(lastNonEmptyTextIndex + 1, 0, {
-          cachePoint: { type: 'default' },
+          cachePoint: buildBedrockCachePoint(ttl),
         } as MessageContentComplex);
         cachePointPlaced = true;
         modified = true;
@@ -877,7 +962,7 @@ export function addBedrockTailCacheControl<
     } else if (typeof content === 'string' && canPlaceCachePoint) {
       workingContent = [
         { type: ContentTypes.TEXT, text: content },
-        { cachePoint: { type: 'default' } } as MessageContentComplex,
+        { cachePoint: buildBedrockCachePoint(ttl) } as MessageContentComplex,
       ];
       cachePointPlaced = true;
     } else if (typeof content === 'string' && hasSerializationProps) {

package/src/summarization/node.ts

@@ -10,6 +10,11 @@ import type { AgentContext } from '@/agents/AgentContext';
 import type { HookRegistry } from '@/hooks';
 import type { OnChunk } from '@/llm/invoke';
 import type * as t from '@/types';
+import {
+  addTailCacheControl,
+  resolvePromptCacheTtl,
+  type PromptCacheTtl,
+} from '@/messages/cache';
 import {
   Constants,
   ContentTypes,
@@ -22,7 +27,6 @@ import { attemptInvoke, tryFallbackProviders } from '@/llm/invoke';
 import { createRemoveAllMessage } from '@/messages/reducer';
 import { splitAtRecencyBoundary } from '@/messages/recency';
 import { getMaxOutputTokensKey } from '@/llm/request';
-import { addTailCacheControl } from '@/messages/cache';
 import { initializeModel } from '@/llm/init';
 import { getChunkContent } from '@/stream';
 import { executeHooks } from '@/hooks';
@@ -552,6 +556,17 @@ async function executeSummarizationWithFallback(params: {
       provider: clientConfig.provider as Providers,
       reasoningKey: agentContext.reasoningKey,
       usePromptCache,
+      promptCacheTtl:
+        (clientConfig.provider as Providers) === Providers.ANTHROPIC ||
+        (clientConfig.provider as Providers) === Providers.OPENROUTER
+          ? resolvePromptCacheTtl(
+            (
+                clientConfig.clientOptions as {
+                  promptCacheTtl?: PromptCacheTtl;
+                }
+            ).promptCacheTtl
+          )
+          : undefined,
       log,
     });
     summaryText = result.text;
@@ -1205,6 +1220,7 @@ async function summarizeWithCacheHit({
   provider,
   reasoningKey,
   usePromptCache,
+  promptCacheTtl,
   log,
 }: {
   model: t.ChatModel;
@@ -1217,6 +1233,7 @@ async function summarizeWithCacheHit({
   provider: Providers;
   reasoningKey?: 'reasoning_content' | 'reasoning';
   usePromptCache?: boolean;
+  promptCacheTtl?: PromptCacheTtl;
   log?: LogFn;
 }): Promise<{ text: string; usage?: Partial<UsageMetadata> }> {
   const instruction = buildSummarizationInstruction(
@@ -1227,7 +1244,9 @@ async function summarizeWithCacheHit({
 
   const fullMessages = [...messages, new HumanMessage(instruction)];
   const invokeMessages =
-    usePromptCache === true ? addTailCacheControl(fullMessages) : fullMessages;
+    usePromptCache === true
+      ? addTailCacheControl(fullMessages, promptCacheTtl)
+      : fullMessages;
 
   const result = await attemptInvoke(
     {

package/src/tools/ReadFile.ts

@@ -22,13 +22,13 @@ CONSTRAINTS:
 export const ReadFileToolSchema = {
   type: 'object',
   properties: {
-    file_path: {
+    path: {
       type: 'string',
       description:
         'Path to the file. For skill files: "{skillName}/{path}" (e.g. "pdf-analyzer/src/utils.py"). For code execution output: the path as returned by the execution tool.',
     },
   },
-  required: ['file_path'],
+  required: ['path'],
 } as const;
 
 export const ReadFileToolDefinition = {

package/src/tools/__tests__/LocalExecutionTools.test.ts

@@ -175,8 +175,8 @@ describe('local execution tools', () => {
         aiMessageWithToolCall(Constants.PROGRAMMATIC_TOOL_CALLING, {
           lang: 'py',
           code: [
-            'await write_file(file_path="ptc.txt", content="from local ptc")',
-            'contents = await read_file(file_path="ptc.txt")',
+            'await write_file(path="ptc.txt", content="from local ptc")',
+            'contents = await read_file(path="ptc.txt")',
             'print(contents)',
           ].join('\n'),
         }),
@@ -205,8 +205,8 @@ describe('local execution tools', () => {
       messages: [
         aiMessageWithToolCall(Constants.PROGRAMMATIC_TOOL_CALLING, {
           code: [
-            'write_file \'{"file_path":"bash-ptc.txt","content":"from bash ptc"}\'',
-            'read_file \'{"file_path":"bash-ptc.txt"}\'',
+            'write_file \'{"path":"bash-ptc.txt","content":"from bash ptc"}\'',
+            'read_file \'{"path":"bash-ptc.txt"}\'',
           ].join('\n'),
         }),
       ],
@@ -335,8 +335,8 @@ describe('LocalFileCheckpointer', () => {
 
     const writeTool = bundle.tools.find((tool_) => tool_.name === 'write_file');
     expect(writeTool).toBeDefined();
-    await writeTool!.invoke({ file_path: 'cp.txt', content: 'first' });
-    await writeTool!.invoke({ file_path: 'cp.txt', content: 'second' });
+    await writeTool!.invoke({ path: 'cp.txt', content: 'first' });
+    await writeTool!.invoke({ path: 'cp.txt', content: 'second' });
 
     const restored = await bundle.checkpointer!.rewind();
     expect(restored).toBe(1);
@@ -352,7 +352,7 @@ describe('local read tool guards', () => {
 
     const bundle = createLocalCodingToolBundle({ cwd });
     const readTool = bundle.tools.find((t_) => t_.name === Constants.READ_FILE);
-    const result = await readTool!.invoke({ file_path: 'binary.bin' });
+    const result = await readTool!.invoke({ path: 'binary.bin' });
     expect(String(result)).toContain('binary file');
   });
 
@@ -366,7 +366,7 @@ describe('local read tool guards', () => {
       maxReadBytes: 1024,
     });
     const readTool = bundle.tools.find((t_) => t_.name === Constants.READ_FILE);
-    const result = await readTool!.invoke({ file_path: 'big.txt' });
+    const result = await readTool!.invoke({ path: 'big.txt' });
     expect(String(result)).toContain('exceeds the 1024-byte read cap');
   });
 
@@ -380,7 +380,7 @@ describe('local read tool guards', () => {
     const bundle = createLocalCodingToolBundle({ cwd });
     const readTool = bundle.tools.find((t_) => t_.name === Constants.READ_FILE);
     await expect(
-      readTool!.invoke({ file_path: 'escape/secret.txt' })
+      readTool!.invoke({ path: 'escape/secret.txt' })
     ).rejects.toThrow(/symlink escape/);
   });
 });
@@ -406,7 +406,7 @@ describe('local programmatic bridge auth', () => {
           code: [
             'import os, json, urllib.request, urllib.error',
             'url = os.environ["BRIDGE_PROBE_URL"] if "BRIDGE_PROBE_URL" in os.environ else __LIBRECHAT_TOOL_BRIDGE',
-            'body = json.dumps({"name":"read_file","input":{"file_path":"x"}}).encode("utf-8")',
+            'body = json.dumps({"name":"read_file","input":{"path":"x"}}).encode("utf-8")',
             'try:',
             '  req = urllib.request.Request(url, data=body, headers={"Content-Type":"application/json"}, method="POST")',
             '  urllib.request.urlopen(req, timeout=5)',
@@ -438,7 +438,7 @@ describe('local edit fuzzy matching', () => {
     const bundle = createLocalCodingToolBundle({ cwd });
     const editTool = bundle.tools.find((tt) => tt.name === 'edit_file');
     const result = await editTool!.invoke({
-      file_path: 'a.ts',
+      path: 'a.ts',
       // LLM emits a trailing-whitespace-stripped version.
       old_text:
         'function greet(name: string) {\n  return `Hello, ${name}!`;\n}',
@@ -461,7 +461,7 @@ describe('local edit fuzzy matching', () => {
     const bundle = createLocalCodingToolBundle({ cwd });
     const editTool = bundle.tools.find((tt) => tt.name === 'edit_file');
     const result = await editTool!.invoke({
-      file_path: 'a.ts',
+      path: 'a.ts',
       // LLM stripped the 4-space indent
       old_text: 'method() {\n    return 1;\n}',
       new_text: 'method() {\n    return 42;\n}',
@@ -480,7 +480,7 @@ describe('local edit fuzzy matching', () => {
     const bundle = createLocalCodingToolBundle({ cwd });
     const editTool = bundle.tools.find((tt) => tt.name === 'edit_file');
     const result = await editTool!.invoke({
-      file_path: 'a.txt',
+      path: 'a.txt',
       old_text: 'second',
       new_text: 'SECOND',
     });
@@ -497,7 +497,7 @@ describe('local edit fuzzy matching', () => {
     const bundle = createLocalCodingToolBundle({ cwd });
     const editTool = bundle.tools.find((tt) => tt.name === 'edit_file');
     await editTool!.invoke({
-      file_path: 'a.txt',
+      path: 'a.txt',
       old_text: 'two',
       new_text: 'TWO',
     });
@@ -512,7 +512,7 @@ describe('local edit fuzzy matching', () => {
     await fsWriteFile(file, BOM + 'hello\n', 'utf8');
     const bundle = createLocalCodingToolBundle({ cwd });
     const writeTool = bundle.tools.find((tt) => tt.name === 'write_file');
-    await writeTool!.invoke({ file_path: 'a.txt', content: 'goodbye\n' });
+    await writeTool!.invoke({ path: 'a.txt', content: 'goodbye\n' });
     const raw = await fsReadFile(file, 'utf8');
     expect(raw.startsWith(BOM)).toBe(true);
     expect(raw.slice(1)).toBe('goodbye\n');
@@ -532,7 +532,7 @@ describe('local read attachments', () => {
     await fsWriteFile(file, tinyPng);
     const bundle = createLocalCodingToolBundle({ cwd });
     const readTool = bundle.tools.find((tt) => tt.name === Constants.READ_FILE);
-    const result = await readTool!.invoke({ file_path: 'tiny.png' });
+    const result = await readTool!.invoke({ path: 'tiny.png' });
     expect(String(result)).toContain('binary file');
   });
 
@@ -552,7 +552,7 @@ describe('local read attachments', () => {
     const message = (await readTool!.invoke({
       id: 'call_image',
       name: Constants.READ_FILE,
-      args: { file_path: 'tiny.png' },
+      args: { path: 'tiny.png' },
       type: 'tool_call',
     })) as { content: unknown; artifact: unknown };
     expect(Array.isArray(message.content)).toBe(true);
@@ -589,7 +589,7 @@ describe('local read attachments', () => {
       maxAttachmentBytes: 100,
     });
     const readTool = bundle.tools.find((tt) => tt.name === Constants.READ_FILE);
-    const result = await readTool!.invoke({ file_path: 'big.png' });
+    const result = await readTool!.invoke({ path: 'big.png' });
     expect(String(result)).toMatch(/Refusing to embed/);
   });
 
@@ -602,7 +602,7 @@ describe('local read attachments', () => {
       attachReadAttachments: 'images-only',
     });
     const readTool = bundle.tools.find((tt) => tt.name === Constants.READ_FILE);
-    const result = await readTool!.invoke({ file_path: 'a.txt' });
+    const result = await readTool!.invoke({ path: 'a.txt' });
     expect(String(result)).toContain('hello world');
   });
 });
@@ -662,7 +662,7 @@ describe('post-edit syntax check', () => {
     const message = (await writeTool!.invoke({
       id: 'call_w',
       name: 'write_file',
-      args: { file_path: 'broken.js', content: 'function (\n' },
+      args: { path: 'broken.js', content: 'function (\n' },
       type: 'tool_call',
     })) as { content: string; artifact: { syntax_error?: string } };
     expect(message.content).toContain('[syntax-check warning');
@@ -680,7 +680,7 @@ describe('post-edit syntax check', () => {
       writeTool!.invoke({
         id: 'call_w',
         name: 'write_file',
-        args: { file_path: 'broken.js', content: 'function (\n' },
+        args: { path: 'broken.js', content: 'function (\n' },
         type: 'tool_call',
       })
     ).rejects.toThrow(/syntax check failed/);
@@ -850,7 +850,7 @@ describe('codex review fixes', () => {
       const result = await readTool!.invoke({
         id: 'c',
         name: Constants.READ_FILE,
-        args: { file_path: join(parent, 'shared/lib.ts') },
+        args: { path: join(parent, 'shared/lib.ts') },
         type: 'tool_call',
       });
       expect(JSON.stringify(result)).toContain('X');
@@ -2253,7 +2253,7 @@ describe('comprehensive review (round 14) — Codex P1 #37 + P2 #38/#40/#41', ()
         writeTool!.invoke({
           id: 'wf-strict',
           name: Constants.WRITE_FILE,
-          args: { file_path: file, content: 'function broken( {\n' },
+          args: { path: file, content: 'function broken( {\n' },
           type: 'tool_call',
         })
       ).rejects.toThrow(/syntax check failed.*reverted/i);
@@ -2281,7 +2281,7 @@ describe('comprehensive review (round 14) — Codex P1 #37 + P2 #38/#40/#41', ()
         writeTool!.invoke({
           id: 'wf-strict-new',
           name: Constants.WRITE_FILE,
-          args: { file_path: file, content: 'function broken( {\n' },
+          args: { path: file, content: 'function broken( {\n' },
           type: 'tool_call',
         })
       ).rejects.toThrow(/syntax check failed.*reverted/i);
@@ -2308,7 +2308,7 @@ describe('comprehensive review (round 14) — Codex P1 #37 + P2 #38/#40/#41', ()
           id: 'ef-strict',
           name: Constants.EDIT_FILE,
           args: {
-            file_path: file,
+            path: file,
             old_text: 'return 1;',
             new_text: 'return broken(',
           },

package/src/tools/__tests__/ProgrammaticToolCalling.test.ts

@@ -1503,10 +1503,10 @@ for member in team:
         { registry, runId: 'r1' },
         'read_file',
         'call_1',
-        { file_path: '/tmp/x' }
+        { path: '/tmp/x' }
       );
       expect(gate.denyReason).toBeUndefined();
-      expect(gate.input).toEqual({ file_path: '/tmp/x' });
+      expect(gate.input).toEqual({ path: '/tmp/x' });
     });
 
     it('applies updatedInput to the inner tool args', async () => {
@@ -1520,7 +1520,7 @@ for member in team:
           // eslint-disable-next-line @typescript-eslint/explicit-function-return-type
           async () => ({
             decision: 'allow',
-            updatedInput: { file_path: '/tmp/rewritten' },
+            updatedInput: { path: '/tmp/rewritten' },
           }),
         ],
       });
@@ -1529,10 +1529,10 @@ for member in team:
         { registry, runId: 'r1' },
         'read_file',
         'call_1',
-        { file_path: '/tmp/original' }
+        { path: '/tmp/original' }
       );
       expect(gate.denyReason).toBeUndefined();
-      expect(gate.input).toEqual({ file_path: '/tmp/rewritten' });
+      expect(gate.input).toEqual({ path: '/tmp/rewritten' });
     });
 
     it('treats `ask` as fail-closed deny (HITL not reachable from bridge)', async () => {

package/src/tools/__tests__/ReadFile.test.ts

@@ -9,9 +9,9 @@ import { Constants } from '@/common';
 
 describe('ReadFile', () => {
   describe('schema structure', () => {
-    it('has file_path as required string property', () => {
-      expect(ReadFileToolSchema.properties.file_path.type).toBe('string');
-      expect(ReadFileToolSchema.required).toContain('file_path');
+    it('has path as required string property', () => {
+      expect(ReadFileToolSchema.properties.path.type).toBe('string');
+      expect(ReadFileToolSchema.required).toContain('path');
     });
 
     it('is an object type schema', () => {

package/src/tools/__tests__/ToolNode.session.test.ts

@@ -1021,7 +1021,7 @@ describe('ToolNode code execution session management', () => {
           {
             id: 'call_rf',
             name: Constants.READ_FILE,
-            args: { file_path: '/mnt/data/data.csv' },
+            args: { path: '/mnt/data/data.csv' },
           },
         ],
       });
@@ -1062,7 +1062,7 @@ describe('ToolNode code execution session management', () => {
           {
             id: 'call_rf2',
             name: Constants.READ_FILE,
-            args: { file_path: 'some-skill/notes.md' },
+            args: { path: 'some-skill/notes.md' },
           },
         ],
       });