refactor: rename read/write/edit file_path param to path (LibreChat-AI#250)

* feat(coding-tools)!: rename read/write/edit `file_path` param to `path`

Models intermittently emit the very common `path` instead of `file_path` for
read_file/write_file/edit_file, which fails Zod validation ("Received tool input
did not match expected schema") and derails the agent run — the model then retries
or returns empty. Observed reliably with Kimi K2 via Fireworks/ClickHouse Inference
(the investigator dies right after the first tool call).

Rather than coerce the alias at every execution path, align the schema with what
models actually emit — and with the sibling search tools (grep_search /
glob_search / list_directory), which already use `path`. Now every built-in coding
tool takes its file/dir target in `path`.

- ReadFileToolSchema + Local{Read,Write,Edit}FileToolSchema: `file_path` -> `path`
- handlers read `input.path`
- workspace-policy extractors collapse to a single `path` extractor for all tools
- tests updated

BREAKING CHANGE: the read_file/write_file/edit_file parameter is now `path`
(was `file_path`). Consumers that construct or read these tool-call args must update.

Verified end-to-end against ClickHouse Inference (kimi-k2p7-code): a real investigator
loop goes 4/10 -> 10/10 with no coercion. Tool + hook suites green (the one failing
suite, directToolHITLResumeScope, fails identically on clean main — pre-existing).

* fix(cloudflare-ptc): rename generated read/write/edit helpers to `path`

Codex (LibreChat-AI#250): the Cloudflare Sandbox programmatic runners generate in-sandbox
read_file/write_file/edit_file helpers that still took `file_path` (Python defs +
the JS `payload.file_path` reads), so `write_file(path=...)` failed only in the
Cloudflare programmatic path after the schema switched to `path`. Rename the tool
wrappers' param to `path` (the internal `_resolve`/`_is_within_workspace` utils and
the code-execution temp-file locals keep `file_path` — unrelated).

Author: danny-avila

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');
     });

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) =>

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 = {

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(',
           },

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 () => {

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', () => {