@librechat/agents 3.2.39 → 3.2.42

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

@@ -2,6 +2,7 @@ import type * as t from '@/types';
 import {
   createCloudflareWorkspaceFS,
   createCloudflareLocalExecutionConfig,
+  execWithClientTimeout,
   executeCloudflareBash,
   executeCloudflareCode,
 } from '../cloudflare/CloudflareSandboxExecutionEngine';
@@ -257,6 +258,136 @@ describe('Cloudflare sandbox execution backend', () => {
     expect(result.timedOut).toBe(true);
   });
 
+  it('rejects with a client-side timeout when sandbox exec stalls (no native cancellation)', async () => {
+    // The native Cloudflare Sandbox DO exec() is uncancellable (ExecOptions has no
+    // signal) and its own `timeout` is not enforced when the container/RPC stalls,
+    // while the in-sandbox `timeout(1)` wrapper only bounds a *running* command.
+    // Without a client-side race a stalled exec hangs until the host's run-level
+    // abort, burning the whole budget on one tool call (issue #251).
+    jest.useFakeTimers();
+    try {
+      let mainExecCalls = 0;
+      const sandbox = createRuntime({
+        exec: (command) => {
+          // Cleanup (`rm -rf`) resolves immediately; the real command stalls,
+          // simulating an unresponsive / cold container exec that never returns.
+          if (command.startsWith('rm -rf')) {
+            return Promise.resolve({ exitCode: 0, stdout: '', stderr: '' });
+          }
+          mainExecCalls += 1;
+          return new Promise<t.CloudflareSandboxExecResult>(() => undefined);
+        },
+      });
+
+      const promise = executeCloudflareCode(
+        { lang: 'py', code: 'print("slow")' },
+        { sandbox, workspaceRoot: '/workspace', timeoutMs: 1000 }
+      );
+      const assertion = expect(promise).rejects.toThrow(/client-side timeout/);
+
+      // Client backstop = outerTimeoutMs(1000) + 5000 = 11000ms; advance past it.
+      await jest.advanceTimersByTimeAsync(11500);
+      await assertion;
+      expect(mainExecCalls).toBe(1);
+    } finally {
+      jest.useRealTimers();
+    }
+  });
+
+  it('aborts signal-aware execs when the client timeout fires', async () => {
+    // For signal-aware transports (e.g. the HTTP bridge), a client timeout should
+    // actually cancel the underlying exec, not just abandon it.
+    jest.useFakeTimers();
+    try {
+      let mainSignal: AbortSignal | undefined;
+      const sandbox = createRuntime({
+        supportsExecSignal: true,
+        exec: (command, options) => {
+          if (command.startsWith('rm -rf')) {
+            return Promise.resolve({ exitCode: 0, stdout: '', stderr: '' });
+          }
+          mainSignal = options?.signal;
+          return new Promise<t.CloudflareSandboxExecResult>(() => undefined);
+        },
+      });
+
+      const promise = executeCloudflareCode(
+        { lang: 'py', code: 'print("slow")' },
+        { sandbox, workspaceRoot: '/workspace', timeoutMs: 1000 }
+      );
+      const assertion = expect(promise).rejects.toThrow(/client-side timeout/);
+      await jest.advanceTimersByTimeAsync(11500);
+      await assertion;
+
+      expect(mainSignal).toBeDefined();
+      expect(mainSignal?.aborted).toBe(true);
+    } finally {
+      jest.useRealTimers();
+    }
+  });
+
+  it('composes a caller abort signal with the timeout instead of clobbering it', async () => {
+    let received: AbortSignal | undefined;
+    const sandbox = createRuntime({
+      supportsExecSignal: true,
+      exec: (_command, options) => {
+        received = options?.signal;
+        return new Promise<t.CloudflareSandboxExecResult>(
+          (_resolve, reject) => {
+            options?.signal?.addEventListener(
+              'abort',
+              () => reject(new Error('aborted')),
+              { once: true }
+            );
+          }
+        );
+      },
+    });
+
+    const caller = new AbortController();
+    const settled = execWithClientTimeout(
+      sandbox,
+      'echo hi',
+      { signal: caller.signal },
+      60000,
+      'test'
+    ).catch((e) => e as Error);
+
+    await Promise.resolve();
+    expect(received).toBeDefined();
+    // The exec gets a composed signal, not the caller's directly.
+    expect(received).not.toBe(caller.signal);
+    expect(received?.aborted).toBe(false);
+
+    // A caller cancellation must reach the exec (not wait for the client timeout).
+    caller.abort();
+    await settled;
+    expect(received?.aborted).toBe(true);
+  });
+
+  it('strips a caller signal for native runtimes that cannot consume it', async () => {
+    let received: t.CloudflareSandboxExecOptions | undefined;
+    const sandbox = createRuntime({
+      // no supportsExecSignal -> native DO, which cannot clone/consume a signal
+      exec: async (_command, options) => {
+        received = options;
+        return { exitCode: 0, stdout: 'ok', stderr: '' };
+      },
+    });
+    const caller = new AbortController();
+
+    await execWithClientTimeout(
+      sandbox,
+      'echo hi',
+      { cwd: '/workspace', signal: caller.signal },
+      60000,
+      'test'
+    );
+
+    expect(received).toBeDefined();
+    expect(received).not.toHaveProperty('signal');
+  });
+
   it('passes call-specific timeouts to the Cloudflare spawn wrapper', async () => {
     let execCommand = '';
     let execTimeout: number | undefined;

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

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

@@ -125,7 +125,7 @@ describe('workspace seam', () => {
       await writeTool.invoke({
         id: 'c1',
         name: 'write_file',
-        args: { file_path: 'note.md', content: 'hi\n' },
+        args: { path: 'note.md', content: 'hi\n' },
         type: 'tool_call',
       });
       expect(tracked.writeFile).toHaveBeenCalled();
@@ -137,7 +137,7 @@ describe('workspace seam', () => {
       await readTool.invoke({
         id: 'c2',
         name: Constants.READ_FILE,
-        args: { file_path: 'note.md' },
+        args: { path: 'note.md' },
         type: 'tool_call',
       });
       expect(tracked.stat).toHaveBeenCalled();

package/src/tools/cloudflare/CloudflareProgrammaticToolCalling.ts

@@ -19,6 +19,8 @@ import {
 } from '@/tools/BashProgrammaticToolCalling';
 import { Constants } from '@/common';
 import {
+  clientExecTimeoutMs,
+  execWithClientTimeout,
   executeCloudflareCode,
   getCloudflareWorkspaceRoot,
   resolveCloudflareSandbox,
@@ -166,13 +168,16 @@ async function executeGeneratedCloudflareBash(
   const workspaceRoot = getCloudflareWorkspaceRoot(config);
   const shell = config.shell ?? 'bash';
   const timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT;
-  const result = await sandbox.exec(
+  const result = await execWithClientTimeout(
+    sandbox,
     withInSandboxTimeout(`${shell} -lc ${quoteShell(command)}`, timeoutMs),
     {
       cwd: workspaceRoot,
       env: config.env,
       timeout: outerTimeoutMs(timeoutMs),
-    }
+    },
+    clientExecTimeoutMs(timeoutMs),
+    'cloudflare bash programmatic exec'
   );
   const maxOutputChars = config.maxOutputChars ?? DEFAULT_MAX_OUTPUT_CHARS;
   return {
@@ -478,30 +483,30 @@ async def execute_code(lang, code, args=None):
     finally:
         shutil.rmtree(temp_dir, ignore_errors=True)
 
-async def read_file(file_path, offset=None, limit=None):
-    resolved = _resolve(file_path)
+async def read_file(path, offset=None, limit=None):
+    resolved = _resolve(path)
     with open(resolved, encoding="utf-8") as handle:
         return _line_window(handle.read(), offset, limit)
 
-async def write_file(file_path, content):
+async def write_file(path, content):
     _assert_writable("write_file")
-    resolved = _resolve(file_path)
+    resolved = _resolve(path)
     os.makedirs(os.path.dirname(resolved), exist_ok=True)
     existed = os.path.exists(resolved)
     with open(resolved, "w", encoding="utf-8") as handle:
         handle.write(content)
     return f"{'Overwrote' if existed else 'Created'} {resolved} ({len(content)} chars)."
 
-async def edit_file(file_path, old_text=None, new_text=None, edits=None):
+async def edit_file(path, old_text=None, new_text=None, edits=None):
     _assert_writable("edit_file")
-    resolved = _resolve(file_path)
+    resolved = _resolve(path)
     edits = edits or [{"old_text": old_text, "new_text": new_text}]
     content = open(resolved, encoding="utf-8").read()
     for edit in edits:
         old = edit.get("old_text") or ""
         new = edit.get("new_text") or ""
         if content.count(old) != 1:
-            raise ValueError(f"Could not locate old_text exactly once in {file_path}")
+            raise ValueError(f"Could not locate old_text exactly once in {path}")
         content = content.replace(old, new, 1)
     open(resolved, "w", encoding="utf-8").write(content)
     return f"Applied {len(edits)} edit(s) to {resolved}."
@@ -881,13 +886,13 @@ async function execute_code(payload) {
 }
 
 async function read_file(payload) {
-  const resolved = resolvePath(payload.file_path);
+  const resolved = resolvePath(payload.path);
   return lineWindow(await fsp.readFile(resolved, "utf8"), payload.offset, payload.limit);
 }
 
 async function write_file(payload) {
   assertWritable("write_file");
-  const resolved = resolvePath(payload.file_path);
+  const resolved = resolvePath(payload.path);
   await fsp.mkdir(path.dirname(resolved), { recursive: true });
   const existed = fs.existsSync(resolved);
   await fsp.writeFile(resolved, payload.content, "utf8");
@@ -896,14 +901,14 @@ async function write_file(payload) {
 
 async function edit_file(payload) {
   assertWritable("edit_file");
-  const resolved = resolvePath(payload.file_path);
+  const resolved = resolvePath(payload.path);
   const edits = payload.edits || [{ old_text: payload.old_text, new_text: payload.new_text }];
   let content = await fsp.readFile(resolved, "utf8");
   for (const edit of edits) {
     const oldText = edit.old_text || "";
     const newText = edit.new_text || "";
     if (oldText === "" || content.split(oldText).length - 1 !== 1) {
-      throw new Error("Could not locate old_text exactly once in " + payload.file_path);
+      throw new Error("Could not locate old_text exactly once in " + payload.path);
     }
     content = content.replace(oldText, newText);
   }