@librechat/agents 3.4.6 → 3.5.0

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

@@ -1,700 +0,0 @@
-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>) => unknown | Promise<unknown>
-): 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('serializes bigint values in direct structured tool output', async () => {
-    const query = createDirectTool('query', () => 'unused');
-    (
-      query as unknown as {
-        invoke: () => Promise<Array<Record<string, unknown>>>;
-      }
-    ).invoke = async () => [{ rowsRead: BigInt(42), status: 'complete' }];
-    const node = new ToolNode({
-      tools: [query],
-      eventDrivenMode: true,
-      directToolNames: new Set(['query']),
-    });
-
-    const result = await node.invoke({
-      messages: [aiCall('call_bigint', 'query', {})],
-    });
-    const [message] = toolMessages(result);
-
-    expect(message.status).toBe('success');
-    expect(message.content).toBe('[{"rowsRead":"42","status":"complete"}]');
-  });
-
-  it('bounds a large structured result without invoking toJSON', async () => {
-    let toJSONCalls = 0;
-    const structuredOutput = {
-      rows: [{ value: 'x'.repeat(20_000) }],
-      toJSON() {
-        toJSONCalls++;
-        return 'y'.repeat(100_000);
-      },
-    };
-    const query = createDirectTool('large_query', () => 'unused');
-    (
-      query as unknown as {
-        invoke: () => Promise<typeof structuredOutput>;
-      }
-    ).invoke = async () => structuredOutput;
-    const node = new ToolNode({
-      tools: [query],
-      eventDrivenMode: true,
-      directToolNames: new Set(['large_query']),
-      maxToolResultChars: 200,
-    });
-
-    const result = await node.invoke({
-      messages: [aiCall('call_large', 'large_query', {})],
-    });
-    const [message] = toolMessages(result);
-
-    expect(toJSONCalls).toBe(0);
-    expect(typeof message.content).toBe('string');
-    expect((message.content as string).length).toBeLessThanOrEqual(200);
-    expect(message.content).toContain('truncated');
-  });
-
-  it('keeps native computer screenshots intact despite the generic result cap', async () => {
-    const screenshot = `data:image/png;base64,${'A'.repeat(2_000)}`;
-    const contents: ToolMessage['content'][] = [
-      screenshot,
-      [{ type: 'computer_screenshot', image_url: screenshot }],
-    ];
-
-    for (let i = 0; i < contents.length; i++) {
-      const name = `computer_output_${i}`;
-      const computerOutput = new ToolMessage({
-        content: contents[i],
-        tool_call_id: `computer-call-${i}`,
-        additional_kwargs: { type: 'computer_call_output' },
-      });
-      const computer = createDirectTool(name, () => 'unused');
-      (
-        computer as unknown as {
-          invoke: () => Promise<ToolMessage>;
-        }
-      ).invoke = async () => computerOutput;
-      const node = new ToolNode({
-        tools: [computer],
-        eventDrivenMode: true,
-        directToolNames: new Set([name]),
-        maxToolResultChars: 80,
-      });
-
-      const result = await node.invoke({
-        messages: [aiCall(`computer-call-${i}`, name, {})],
-      });
-      const [message] = toolMessages(result);
-
-      expect(message).toBe(computerOutput);
-      expect(message.content).toBe(contents[i]);
-      expect(message.additional_kwargs.type).toBe('computer_call_output');
-    }
-  });
-
-  it('preserves a valid PostToolUse computer screenshot replacement', async () => {
-    const original = `data:image/png;base64,${'A'.repeat(2_000)}`;
-    const replacement = `data:image/png;base64,${'B'.repeat(2_000)}`;
-    const computerOutput = new ToolMessage({
-      content: original,
-      tool_call_id: 'computer-hook-valid',
-      additional_kwargs: { type: 'computer_call_output' },
-    });
-    const computer = createDirectTool('computer_hook_valid', () => 'unused');
-    (
-      computer as unknown as {
-        invoke: () => Promise<ToolMessage>;
-      }
-    ).invoke = async () => computerOutput;
-    const registry = new HookRegistry();
-    registry.register('PostToolUse', {
-      hooks: [
-        async (): Promise<PostToolUseHookOutput> => ({
-          updatedOutput: replacement,
-        }),
-      ],
-    });
-    const node = new ToolNode({
-      tools: [computer],
-      eventDrivenMode: true,
-      hookRegistry: registry,
-      directToolNames: new Set(['computer_hook_valid']),
-      maxToolResultChars: 80,
-    });
-
-    const result = await node.invoke({
-      messages: [aiCall('computer-hook-valid', 'computer_hook_valid', {})],
-    });
-    const [message] = toolMessages(result);
-
-    expect(message.content).toBe(replacement);
-    expect(message.additional_kwargs.type).toBe('computer_call_output');
-  });
-
-  it('rejects an invalid PostToolUse computer output replacement', async () => {
-    const screenshot = `data:image/png;base64,${'A'.repeat(2_000)}`;
-    const computerOutput = new ToolMessage({
-      content: screenshot,
-      tool_call_id: 'computer-hook-invalid',
-      additional_kwargs: { type: 'computer_call_output' },
-    });
-    const computer = createDirectTool('computer_hook_invalid', () => 'unused');
-    (
-      computer as unknown as {
-        invoke: () => Promise<ToolMessage>;
-      }
-    ).invoke = async () => computerOutput;
-    const registry = new HookRegistry();
-    registry.register('PostToolUse', {
-      hooks: [
-        async (): Promise<PostToolUseHookOutput> => ({
-          updatedOutput: 'redacted screenshot',
-        }),
-      ],
-    });
-    const node = new ToolNode({
-      tools: [computer],
-      eventDrivenMode: true,
-      hookRegistry: registry,
-      directToolNames: new Set(['computer_hook_invalid']),
-      maxToolResultChars: 80,
-    });
-
-    await expect(
-      node.invoke({
-        messages: [
-          aiCall('computer-hook-invalid', 'computer_hook_invalid', {}),
-        ],
-      })
-    ).rejects.toThrow(
-      'PostToolUse updatedOutput for a computer call must be a valid screenshot'
-    );
-  });
-
-  it('caps returned and thrown direct-tool errors before storing them', async () => {
-    const returnedError = createDirectTool(
-      'returned_error',
-      () =>
-        new ToolMessage({
-          status: 'error',
-          content: `returned:${'x'.repeat(2_000)}`,
-          tool_call_id: 'returned',
-        })
-    );
-    const thrownError = createDirectTool('thrown_error', () => {
-      throw new Error(`thrown:${'y'.repeat(2_000)}`);
-    });
-    const node = new ToolNode({
-      tools: [returnedError, thrownError],
-      eventDrivenMode: true,
-      directToolNames: new Set(['returned_error', 'thrown_error']),
-      maxToolResultChars: 200,
-    });
-
-    const returned = toolMessages(
-      await node.invoke({
-        messages: [aiCall('returned', 'returned_error', {})],
-      })
-    )[0];
-    const thrown = toolMessages(
-      await node.invoke({
-        messages: [aiCall('thrown', 'thrown_error', {})],
-      })
-    )[0];
-
-    expect(returned.status).toBe('error');
-    expect(String(returned.content).length).toBeLessThanOrEqual(200);
-    expect(returned.content).toContain('[truncated:');
-    expect(thrown.status).toBe('error');
-    expect(String(thrown.content).length).toBeLessThanOrEqual(200);
-    expect(thrown.content).toContain('[truncated:');
-  });
-
-  it('executingAgentId defaults to agentId for direct callers, and an explicit value wins', async () => {
-    const echo = createDirectTool('echo', (args) => `ran:${args.command}`);
-    const captured: Array<string | undefined> = [];
-    const registry = new HookRegistry();
-    registry.register('PreToolUse', {
-      hooks: [
-        async (input): Promise<PreToolUseHookOutput> => {
-          captured.push(input.executingAgentId);
-          return { decision: 'allow' };
-        },
-      ],
-    });
-
-    // Only the existing `agentId` option is passed → executingAgentId defaults to it.
-    const defaulted = new ToolNode({
-      tools: [echo],
-      eventDrivenMode: true,
-      hookRegistry: registry,
-      directToolNames: new Set(['echo']),
-      agentId: 'solo-agent',
-    });
-    await defaulted.invoke({
-      messages: [aiCall('call_def', 'echo', { command: 'a' })],
-    });
-
-    // An explicit executingAgentId overrides the agentId default.
-    const explicit = new ToolNode({
-      tools: [echo],
-      eventDrivenMode: true,
-      hookRegistry: registry,
-      directToolNames: new Set(['echo']),
-      agentId: 'solo-agent',
-      executingAgentId: 'owner-agent',
-    });
-    await explicit.invoke({
-      messages: [aiCall('call_exp', 'echo', { command: 'b' })],
-    });
-
-    expect(captured).toEqual(['solo-agent', 'owner-agent']);
-  });
-
-  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('caps PostToolUse updatedOutput after the hook rewrite', async () => {
-    const echo = createDirectTool('echo', () => 'ORIGINAL');
-    const replacement = 'R'.repeat(500);
-
-    const registry = new HookRegistry();
-    registry.register('PostToolUse', {
-      hooks: [
-        async (): Promise<PostToolUseHookOutput> => ({
-          updatedOutput: replacement,
-        }),
-      ],
-    });
-
-    const node = new ToolNode({
-      tools: [echo],
-      eventDrivenMode: true,
-      hookRegistry: registry,
-      directToolNames: new Set(['echo']),
-      maxToolResultChars: 50,
-    });
-
-    const result = await node.invoke({
-      messages: [aiCall('call_5_capped', 'echo', { command: 'x' })],
-    });
-    const [message] = toolMessages(result);
-
-    expect(typeof message.content).toBe('string');
-    expect((message.content as string).length).toBeLessThanOrEqual(50);
-    expect(message.content).not.toBe(replacement);
-  });
-
-  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();
-  });
-});