@librechat/agents 3.1.77-dev.1 → 3.1.78-dev.0

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

@@ -0,0 +1,411 @@
+import { z } from 'zod';
+import { tool } from '@langchain/core/tools';
+import { AIMessage, ToolMessage } from '@langchain/core/messages';
+import { describe, it, expect, jest, afterEach } from '@jest/globals';
+import type { StructuredToolInterface } from '@langchain/core/tools';
+import type {
+  PreToolUseHookOutput,
+  PostToolUseHookOutput,
+  PostToolUseFailureHookOutput,
+  PermissionDeniedHookOutput,
+} from '@/hooks';
+import { HookRegistry } from '@/hooks';
+import { ToolNode } from '../ToolNode';
+
+/**
+ * Direct-tool helper: returns a real `StructuredToolInterface` whose
+ * `func` runs in-process. Once registered as a graphTool, the ToolNode
+ * marks it `direct` (skipping the host event-dispatch path) — the path
+ * we are testing fires lifecycle hooks around.
+ */
+function createDirectTool(
+  name: string,
+  impl: (args: Record<string, unknown>) => string | Promise<string>
+): StructuredToolInterface {
+  return tool(async (args: Record<string, unknown>) => impl(args), {
+    name,
+    description: `direct in-process tool ${name}`,
+    schema: z.object({ command: z.string().optional() }).passthrough(),
+  }) as unknown as StructuredToolInterface;
+}
+
+function aiCall(
+  callId: string,
+  name: string,
+  args: Record<string, unknown>
+): AIMessage {
+  return new AIMessage({
+    content: '',
+    tool_calls: [{ id: callId, name, args }],
+  });
+}
+
+function toolMessages(result: unknown): ToolMessage[] {
+  if (Array.isArray(result)) {
+    return result as ToolMessage[];
+  }
+  const obj = result as { messages: ToolMessage[] };
+  return obj.messages;
+}
+
+describe('Direct-path lifecycle hooks (in-process tools)', () => {
+  afterEach(() => {
+    jest.restoreAllMocks();
+  });
+
+  it('PreToolUse decision: deny replaces the tool result with a Blocked ToolMessage and fires PermissionDenied', async () => {
+    const echo = createDirectTool('echo', () => 'EXECUTED');
+
+    const registry = new HookRegistry();
+    registry.register('PreToolUse', {
+      hooks: [
+        async (): Promise<PreToolUseHookOutput> => ({
+          decision: 'deny',
+          reason: 'policy-deny',
+        }),
+      ],
+    });
+    const permissionDenied = jest.fn(
+      async (): Promise<PermissionDeniedHookOutput> => ({})
+    );
+    registry.register('PermissionDenied', { hooks: [permissionDenied] });
+
+    const node = new ToolNode({
+      tools: [echo],
+      eventDrivenMode: true,
+      hookRegistry: registry,
+      directToolNames: new Set(['echo']),
+    });
+
+    const result = await node.invoke({
+      messages: [aiCall('call_1', 'echo', { command: 'rm -rf /' })],
+    });
+    const [message] = toolMessages(result);
+
+    expect(message.status).toBe('error');
+    expect(String(message.content)).toContain('Blocked: policy-deny');
+    expect(String(message.content)).not.toContain('EXECUTED');
+
+    // Event handlers can be async — flush the microtask queue once.
+    await Promise.resolve();
+    expect(permissionDenied).toHaveBeenCalledTimes(1);
+  });
+
+  it('PreToolUse decision: ask is fail-closed when humanInTheLoop is disabled', async () => {
+    const echo = createDirectTool('echo', () => 'EXECUTED');
+
+    const registry = new HookRegistry();
+    registry.register('PreToolUse', {
+      hooks: [
+        async (): Promise<PreToolUseHookOutput> => ({
+          decision: 'ask',
+          reason: 'needs-review',
+        }),
+      ],
+    });
+
+    const node = new ToolNode({
+      tools: [echo],
+      eventDrivenMode: true,
+      hookRegistry: registry,
+      directToolNames: new Set(['echo']),
+      // humanInTheLoop intentionally not set — fail-closed.
+    });
+
+    const result = await node.invoke({
+      messages: [aiCall('call_2', 'echo', { command: 'whoami' })],
+    });
+    const [message] = toolMessages(result);
+
+    expect(message.status).toBe('error');
+    expect(String(message.content)).toContain('Blocked: needs-review');
+    expect(String(message.content)).not.toContain('EXECUTED');
+  });
+
+  it('PreToolUse decision: allow runs the tool unchanged', async () => {
+    const echo = createDirectTool('echo', (args) => `ran:${args.command}`);
+
+    const registry = new HookRegistry();
+    registry.register('PreToolUse', {
+      hooks: [
+        async (): Promise<PreToolUseHookOutput> => ({ decision: 'allow' }),
+      ],
+    });
+
+    const node = new ToolNode({
+      tools: [echo],
+      eventDrivenMode: true,
+      hookRegistry: registry,
+      directToolNames: new Set(['echo']),
+    });
+
+    const result = await node.invoke({
+      messages: [aiCall('call_3', 'echo', { command: 'ls' })],
+    });
+    const [message] = toolMessages(result);
+    expect(message.status).toBe('success');
+    expect(String(message.content)).toBe('ran:ls');
+  });
+
+  it('PreToolUse updatedInput rewrites the args before runTool sees them', async () => {
+    const seen: Record<string, unknown>[] = [];
+    const echo = createDirectTool('echo', (args) => {
+      seen.push(args);
+      return `ran:${String(args.command)}`;
+    });
+
+    const registry = new HookRegistry();
+    registry.register('PreToolUse', {
+      hooks: [
+        async (): Promise<PreToolUseHookOutput> => ({
+          decision: 'allow',
+          updatedInput: { command: 'redacted' },
+        }),
+      ],
+    });
+
+    const node = new ToolNode({
+      tools: [echo],
+      eventDrivenMode: true,
+      hookRegistry: registry,
+      directToolNames: new Set(['echo']),
+    });
+
+    const result = await node.invoke({
+      messages: [aiCall('call_4', 'echo', { command: 'secret' })],
+    });
+    const [message] = toolMessages(result);
+    expect(String(message.content)).toBe('ran:redacted');
+    expect(seen[0]).toMatchObject({ command: 'redacted' });
+  });
+
+  it('PostToolUse updatedOutput replaces the tool message content', async () => {
+    const echo = createDirectTool('echo', () => 'ORIGINAL');
+
+    const registry = new HookRegistry();
+    registry.register('PostToolUse', {
+      hooks: [
+        async (): Promise<PostToolUseHookOutput> => ({
+          updatedOutput: 'REPLACED',
+        }),
+      ],
+    });
+
+    const node = new ToolNode({
+      tools: [echo],
+      eventDrivenMode: true,
+      hookRegistry: registry,
+      directToolNames: new Set(['echo']),
+    });
+
+    const result = await node.invoke({
+      messages: [aiCall('call_5', 'echo', { command: 'x' })],
+    });
+    const [message] = toolMessages(result);
+    expect(String(message.content)).toBe('REPLACED');
+    expect(message.status).toBe('success');
+  });
+
+  it('PostToolUseFailure observes errors thrown by the tool', async () => {
+    const failing = createDirectTool('boom', () => {
+      throw new Error('kaboom');
+    });
+
+    const failure = jest.fn(
+      async (): Promise<PostToolUseFailureHookOutput> => ({})
+    );
+    const registry = new HookRegistry();
+    registry.register('PostToolUseFailure', { hooks: [failure] });
+
+    const node = new ToolNode({
+      tools: [failing],
+      eventDrivenMode: true,
+      hookRegistry: registry,
+      directToolNames: new Set(['boom']),
+    });
+
+    const result = await node.invoke({
+      messages: [aiCall('call_6', 'boom', { command: 'x' })],
+    });
+    const [message] = toolMessages(result);
+    expect(message.status).toBe('error');
+    expect(String(message.content)).toContain('kaboom');
+
+    await Promise.resolve();
+    expect(failure).toHaveBeenCalledTimes(1);
+  });
+
+  it('no-hooks fast path: when no relevant hooks registered, runs runTool directly without overhead', async () => {
+    const echo = createDirectTool('echo', () => 'fast-path');
+
+    const registry = new HookRegistry();
+    // Only register an unrelated event so hasHookFor returns false for
+    // PreToolUse / PostToolUse / PostToolUseFailure.
+    registry.register('RunStart', {
+      hooks: [async (): Promise<Record<string, never>> => ({})],
+    });
+
+    const node = new ToolNode({
+      tools: [echo],
+      eventDrivenMode: true,
+      hookRegistry: registry,
+      directToolNames: new Set(['echo']),
+    });
+
+    const result = await node.invoke({
+      messages: [aiCall('call_7', 'echo', { command: 'x' })],
+    });
+    const [message] = toolMessages(result);
+    expect(String(message.content)).toBe('fast-path');
+  });
+
+  it('mixed batch: PreToolUse deny on a direct tool runs the surviving tool only', async () => {
+    const allowed = createDirectTool('allowed', () => 'allowed-ran');
+    const denied = createDirectTool('denied', () => 'should-not-run');
+
+    const registry = new HookRegistry();
+    registry.register('PreToolUse', {
+      hooks: [
+        async ({ toolName }): Promise<PreToolUseHookOutput> =>
+          toolName === 'denied'
+            ? { decision: 'deny', reason: 'no-no' }
+            : { decision: 'allow' },
+      ],
+    });
+
+    const node = new ToolNode({
+      tools: [allowed, denied],
+      eventDrivenMode: true,
+      hookRegistry: registry,
+      directToolNames: new Set(['allowed', 'denied']),
+    });
+
+    const result = await node.invoke({
+      messages: [
+        new AIMessage({
+          content: '',
+          tool_calls: [
+            { id: 'call_a', name: 'allowed', args: { command: 'a' } },
+            { id: 'call_b', name: 'denied', args: { command: 'b' } },
+          ],
+        }),
+      ],
+    });
+    const messages = toolMessages(result);
+    expect(messages).toHaveLength(2);
+    const byId = new Map(messages.map((m) => [m.tool_call_id, m]));
+    expect(String(byId.get('call_a')?.content)).toBe('allowed-ran');
+    expect(String(byId.get('call_b')?.content)).toContain('Blocked: no-no');
+  });
+
+  it('PreToolUse `turn` matches the per-tool index the body actually executes under (Codex P2 #27)', async () => {
+    // Three parallel direct calls of the same tool. Pre-fix: each
+    // hook read `turn = toolUsageCount.get('echo') ?? 0` BEFORE any
+    // await, so all three saw 0; runTool then incremented inside its
+    // own scope and the bodies ran as 0/1/2. Hook → tool got
+    // misaligned, breaking host policies that key on
+    // (toolName, turn). With the fix, the increment is hoisted into
+    // runDirectToolWithLifecycleHooks (sync, before any await) and
+    // threaded into runTool via batchContext so both observe the
+    // same value.
+    const hookTurns: number[] = [];
+    const bodyTurns: number[] = [];
+    let bodyCount = 0;
+    const echo = createDirectTool('echo', () => {
+      bodyCount += 1;
+      return 'EXECUTED';
+    });
+
+    const registry = new HookRegistry();
+    registry.register('PreToolUse', {
+      hooks: [
+        async (input): Promise<PreToolUseHookOutput> => {
+          if (typeof input.turn === 'number') hookTurns.push(input.turn);
+          return { decision: 'allow' };
+        },
+      ],
+    });
+
+    const node = new ToolNode({
+      tools: [echo],
+      eventDrivenMode: true,
+      hookRegistry: registry,
+      directToolNames: new Set(['echo']),
+    });
+
+    // Patch the tool's `func` to record the turn the body sees via the
+    // standard LangChain config.toolCall.turn channel.
+    const originalFunc = (echo as unknown as { func: (input: unknown, config: unknown) => Promise<string> }).func;
+    (echo as unknown as { func: (input: unknown, config: unknown) => Promise<string> }).func = async (
+      input,
+      config
+    ): Promise<string> => {
+      const t = (config as { toolCall?: { turn?: number } } | undefined)
+        ?.toolCall?.turn;
+      if (typeof t === 'number') bodyTurns.push(t);
+      return originalFunc(input, config);
+    };
+
+    const aiMsg = new AIMessage({
+      content: '',
+      tool_calls: [
+        { id: 'c0', name: 'echo', args: { command: 'a' } },
+        { id: 'c1', name: 'echo', args: { command: 'b' } },
+        { id: 'c2', name: 'echo', args: { command: 'c' } },
+      ],
+    });
+    await node.invoke({ messages: [aiMsg] });
+
+    // Sanity: tool ran 3 times, hook fired 3 times.
+    expect(bodyCount).toBe(3);
+    expect(hookTurns.length).toBe(3);
+    // Post-fix: each hook observes a unique turn (one of 0, 1, 2)
+    // — the SAME turn the body executes under. Pre-fix they all
+    // saw 0, so the dedupe-to-3 assertion would fail.
+    expect(new Set(hookTurns).size).toBe(3);
+    expect([...hookTurns].sort()).toEqual([0, 1, 2]);
+    // The body-side `config.toolCall.turn` should also align (when
+    // visible — LangChain may not propagate config in every test
+    // shape; assert weakly).
+    if (bodyTurns.length === 3) {
+      expect([...bodyTurns].sort()).toEqual([0, 1, 2]);
+    }
+  });
+
+  it('PreToolUse `additionalContext` is materialized as a HumanMessage in the direct path (Codex P2 #39)', async () => {
+    // Pre-fix the direct path called executeHooks but discarded
+    // additionalContexts — silently broke the documented hook API
+    // for hosts using policy/recovery guidance with local tools.
+    const echo = createDirectTool('echo', () => 'EXECUTED');
+
+    const registry = new HookRegistry();
+    registry.register('PreToolUse', {
+      hooks: [
+        async (): Promise<PreToolUseHookOutput> => ({
+          decision: 'allow',
+          additionalContext: 'POLICY-NOTE: writes here require approval next time',
+        }),
+      ],
+    });
+
+    const node = new ToolNode({
+      tools: [echo],
+      eventDrivenMode: true,
+      hookRegistry: registry,
+      directToolNames: new Set(['echo']),
+    });
+
+    const result = await node.invoke({
+      messages: [aiCall('call_ctx', 'echo', { command: 'hi' })],
+    });
+    const messages = toolMessages(result);
+    // ToolMessage for the echo call AND the materialized
+    // HumanMessage carrying the additionalContext.
+    const human = (messages as unknown as { content: unknown }[]).find(
+      (m) =>
+        typeof (m as { content: unknown }).content === 'string' &&
+        String((m as { content: string }).content).includes('POLICY-NOTE')
+    );
+    expect(human).toBeDefined();
+  });
+});

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

@@ -0,0 +1,73 @@
+import { describe, it, expect } from '@jest/globals';
+import {
+  Constants,
+  LOCAL_CODING_BUNDLE_NAMES,
+  LOCAL_CODING_TOOL_NAMES,
+} from '@/common';
+import {
+  createLocalCodingTools,
+  createLocalCodingToolDefinitions,
+  LocalEditFileToolName,
+  LocalGlobSearchToolName,
+  LocalGrepSearchToolName,
+  LocalListDirectoryToolName,
+  LocalWriteFileToolName,
+} from '../local/LocalCodingTools';
+import { CompileCheckToolName } from '../local/CompileCheckTool';
+
+/**
+ * Pins the tool name surface so a typo upstream — in factories,
+ * registry definitions, the policy hook, or LibreChat's icon map —
+ * gets caught at build time. The wire-level strings have to match
+ * what consumer UIs already special-case (`bash_tool`, `read_file`,
+ * `execute_code`, `run_tools_with_code`) and what they may add icons
+ * for next (write_file, edit_file, grep_search, glob_search,
+ * list_directory, compile_check).
+ */
+describe('local coding tool names', () => {
+  it('the per-file Local*ToolName aliases point at canonical Constants', () => {
+    expect(LocalWriteFileToolName).toBe(Constants.WRITE_FILE);
+    expect(LocalEditFileToolName).toBe(Constants.EDIT_FILE);
+    expect(LocalGrepSearchToolName).toBe(Constants.GREP_SEARCH);
+    expect(LocalGlobSearchToolName).toBe(Constants.GLOB_SEARCH);
+    expect(LocalListDirectoryToolName).toBe(Constants.LIST_DIRECTORY);
+    expect(CompileCheckToolName).toBe(Constants.COMPILE_CHECK);
+  });
+
+  it('canonical strings match what consumer UIs (e.g. LibreChat icon map) recognise', () => {
+    expect(Constants.READ_FILE).toBe('read_file');
+    expect(Constants.WRITE_FILE).toBe('write_file');
+    expect(Constants.EDIT_FILE).toBe('edit_file');
+    expect(Constants.GREP_SEARCH).toBe('grep_search');
+    expect(Constants.GLOB_SEARCH).toBe('glob_search');
+    expect(Constants.LIST_DIRECTORY).toBe('list_directory');
+    expect(Constants.COMPILE_CHECK).toBe('compile_check');
+    expect(Constants.BASH_TOOL).toBe('bash_tool');
+    expect(Constants.EXECUTE_CODE).toBe('execute_code');
+    expect(Constants.PROGRAMMATIC_TOOL_CALLING).toBe('run_tools_with_code');
+    expect(Constants.BASH_PROGRAMMATIC_TOOL_CALLING).toBe('run_tools_with_bash');
+  });
+
+  it('LOCAL_CODING_BUNDLE_NAMES matches every name the bundle ships', () => {
+    const tools = createLocalCodingTools();
+    const bundleNames = tools.map((t) => t.name).sort();
+    const advertisedNames = [...LOCAL_CODING_BUNDLE_NAMES].sort();
+    expect(bundleNames).toEqual(advertisedNames);
+  });
+
+  it('LOCAL_CODING_TOOL_NAMES matches the registry-definitions list (local-only tools)', () => {
+    const defs = createLocalCodingToolDefinitions();
+    const defNames = defs.map((d) => d.name).sort();
+    const advertisedNames = [...LOCAL_CODING_TOOL_NAMES].sort();
+    expect(defNames).toEqual(advertisedNames);
+  });
+
+  it('LOCAL_CODING_BUNDLE_NAMES is a strict superset of LOCAL_CODING_TOOL_NAMES', () => {
+    for (const name of LOCAL_CODING_TOOL_NAMES) {
+      expect(LOCAL_CODING_BUNDLE_NAMES).toContain(name);
+    }
+    expect(LOCAL_CODING_BUNDLE_NAMES.length).toBeGreaterThan(
+      LOCAL_CODING_TOOL_NAMES.length
+    );
+  });
+});

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

@@ -0,0 +1,134 @@
+import { tmpdir } from 'os';
+import { join } from 'path';
+import { mkdtemp, rm, writeFile } from 'fs/promises';
+import { describe, it, expect, beforeEach, afterEach, jest } from '@jest/globals';
+import { Constants } from '@/common';
+import { createLocalCodingToolBundle } from '../local/LocalCodingTools';
+import {
+  resolveWorkspacePathSafe,
+  getWorkspaceFS,
+} from '../local/LocalExecutionEngine';
+import { nodeWorkspaceFS } from '../local/workspaceFS';
+import type { WorkspaceFS } from '../local/workspaceFS';
+
+describe('workspace seam', () => {
+  let workspace: string;
+  let extra: string;
+
+  beforeEach(async () => {
+    workspace = await mkdtemp(join(tmpdir(), 'lc-ws-'));
+    extra = await mkdtemp(join(tmpdir(), 'lc-ws-extra-'));
+  });
+
+  afterEach(async () => {
+    await rm(workspace, { recursive: true, force: true });
+    await rm(extra, { recursive: true, force: true });
+  });
+
+  describe('additionalRoots', () => {
+    it('lets read tools touch paths inside an additional root', async () => {
+      await writeFile(join(extra, 'foo.txt'), 'extra contents\n', 'utf8');
+      const path = await resolveWorkspacePathSafe(
+        join(extra, 'foo.txt'),
+        { workspace: { root: workspace, additionalRoots: [extra] } },
+        'read'
+      );
+      expect(path).toBe(join(extra, 'foo.txt'));
+    });
+
+    it('still rejects truly outside paths', async () => {
+      await expect(
+        resolveWorkspacePathSafe(
+          '/etc/passwd',
+          { workspace: { root: workspace, additionalRoots: [extra] } },
+          'read'
+        )
+      ).rejects.toThrow(/outside the local workspace/);
+    });
+
+    it('honours allowReadOutside split from allowWriteOutside', async () => {
+      const cfg = {
+        workspace: {
+          root: workspace,
+          allowReadOutside: true,
+          allowWriteOutside: false,
+        },
+      };
+      const readPath = await resolveWorkspacePathSafe(
+        '/tmp/whatever.txt',
+        cfg,
+        'read'
+      );
+      expect(readPath).toBe('/tmp/whatever.txt');
+      await expect(
+        resolveWorkspacePathSafe('/tmp/whatever.txt', cfg, 'write')
+      ).rejects.toThrow(/outside the local workspace/);
+    });
+
+    it('legacy `cwd` + `allowOutsideWorkspace` still works', async () => {
+      const cfg = { cwd: workspace, allowOutsideWorkspace: true };
+      const p = await resolveWorkspacePathSafe('/tmp/x.txt', cfg, 'write');
+      expect(p).toBe('/tmp/x.txt');
+    });
+
+    it('legacy `cwd` is honoured when `workspace.root` is absent', async () => {
+      const cfg = { cwd: workspace };
+      await expect(
+        resolveWorkspacePathSafe('/tmp/x.txt', cfg, 'write')
+      ).rejects.toThrow(/outside the local workspace/);
+      const p = await resolveWorkspacePathSafe(
+        join(workspace, 'a.txt'),
+        cfg,
+        'write'
+      );
+      expect(p).toBe(join(workspace, 'a.txt'));
+    });
+  });
+
+  describe('WorkspaceFS seam', () => {
+    it('defaults to the Node host fs when nothing is supplied', () => {
+      expect(getWorkspaceFS({ workspace: { root: workspace } })).toBe(
+        nodeWorkspaceFS
+      );
+    });
+
+    it('routes file tool calls through a custom WorkspaceFS', async () => {
+      // Spy: every read/write/etc. routes through `tracked`. We delegate to
+      // the real Node impl so the tool actually completes; the spy just
+      // proves the seam.
+      const tracked: WorkspaceFS = {
+        readFile: jest.fn(nodeWorkspaceFS.readFile) as unknown as WorkspaceFS['readFile'],
+        writeFile: jest.fn(nodeWorkspaceFS.writeFile),
+        stat: jest.fn(nodeWorkspaceFS.stat),
+        readdir: jest.fn(nodeWorkspaceFS.readdir) as unknown as WorkspaceFS['readdir'],
+        mkdir: jest.fn(nodeWorkspaceFS.mkdir),
+        realpath: jest.fn(nodeWorkspaceFS.realpath),
+        unlink: jest.fn(nodeWorkspaceFS.unlink),
+        open: jest.fn(nodeWorkspaceFS.open),
+      };
+      const bundle = createLocalCodingToolBundle({
+        workspace: { root: workspace },
+        exec: { fs: tracked },
+      });
+      const writeTool = bundle.tools.find((t) => t.name === 'write_file')!;
+      await writeTool.invoke({
+        id: 'c1',
+        name: 'write_file',
+        args: { file_path: 'note.md', content: 'hi\n' },
+        type: 'tool_call',
+      });
+      expect(tracked.writeFile).toHaveBeenCalled();
+      expect(tracked.mkdir).toHaveBeenCalled();
+
+      const readTool = bundle.tools.find((t) => t.name === Constants.READ_FILE)!;
+      await readTool.invoke({
+        id: 'c2',
+        name: Constants.READ_FILE,
+        args: { file_path: 'note.md' },
+        type: 'tool_call',
+      });
+      expect(tracked.stat).toHaveBeenCalled();
+      expect(tracked.readFile).toHaveBeenCalled();
+    });
+  });
+});