@librechat/agents 3.1.88 → 3.1.90

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

@@ -117,6 +117,276 @@ describe('ToolNode eager event tool execution', () => {
     expect(result.messages[0].content).toBe('eager result');
   });
 
+  it('uses a prestarted event result when final args are canonically equivalent', async () => {
+    const { toolExecuteCalls } = installToolExecuteResponder('redispatched');
+    const eagerExecutions = new Map<string, t.EagerEventToolExecution>();
+    const request: t.ToolCallRequest = {
+      id: 'call_weather',
+      name: 'weather',
+      args: { city: 'NYC', units: 'metric' },
+      stepId: 'step_weather',
+      turn: 0,
+    };
+    eagerExecutions.set('call_weather', {
+      toolCallId: 'call_weather',
+      toolName: 'weather',
+      args: { city: 'NYC', units: 'metric' },
+      request,
+      promise: Promise.resolve({
+        results: [
+          {
+            toolCallId: 'call_weather',
+            status: 'success',
+            content: 'eager result',
+          },
+        ],
+      }),
+    });
+
+    const toolNode = new ToolNode({
+      tools: [createDummyTool('weather')],
+      eventDrivenMode: true,
+      eagerEventToolExecution: { enabled: true },
+      eagerEventToolExecutions: eagerExecutions,
+      toolCallStepIds: new Map([['call_weather', 'step_weather']]),
+    });
+
+    const result = (await toolNode.invoke({
+      messages: [
+        createAIMessage('call_weather', 'weather', {
+          units: 'metric',
+          city: 'NYC',
+        }),
+      ],
+    })) as { messages: ToolMessage[] };
+
+    expect(toolExecuteCalls).toHaveLength(0);
+    expect(eagerExecutions.has('call_weather')).toBe(false);
+    expect(result.messages).toHaveLength(1);
+    expect(result.messages[0].content).toBe('eager result');
+  });
+
+  it('uses a prestarted event result when only final planning turn differs', async () => {
+    const { toolExecuteCalls } = installToolExecuteResponder('redispatched');
+    const eagerExecutions = new Map<string, t.EagerEventToolExecution>();
+    const eagerUsageCount = new Map<string, number>([['weather', 1]]);
+    const request: t.ToolCallRequest = {
+      id: 'call_weather',
+      name: 'weather',
+      args: { city: 'NYC' },
+      stepId: 'step_weather',
+      turn: 7,
+    };
+    eagerExecutions.set('call_weather', {
+      toolCallId: 'call_weather',
+      toolName: 'weather',
+      args: { city: 'NYC' },
+      request,
+      promise: Promise.resolve({
+        results: [
+          {
+            toolCallId: 'call_weather',
+            status: 'success',
+            content: 'eager result',
+          },
+        ],
+      }),
+    });
+
+    const toolNode = new ToolNode({
+      tools: [createDummyTool('weather')],
+      eventDrivenMode: true,
+      eagerEventToolExecution: { enabled: true },
+      eagerEventToolExecutions: eagerExecutions,
+      eagerEventToolUsageCount: eagerUsageCount,
+      toolCallStepIds: new Map([['call_weather', 'step_weather']]),
+    });
+
+    const result = (await toolNode.invoke({
+      messages: [createAIMessage('call_weather', 'weather', { city: 'NYC' })],
+    })) as { messages: ToolMessage[] };
+
+    expect(toolExecuteCalls).toHaveLength(0);
+    expect(eagerExecutions.has('call_weather')).toBe(false);
+    expect(eagerUsageCount.get('weather')).toBe(1);
+    expect(result.messages).toHaveLength(1);
+    expect(result.messages[0].status).toBe('success');
+    expect(result.messages[0].content).toBe('eager result');
+  });
+
+  it('redispatches completion when a prestarted event result used a stale turn', async () => {
+    const stepCompletions: Array<{
+      result?: { index?: number; tool_call?: { output?: string } };
+    }> = [];
+    jest
+      .spyOn(events, 'safeDispatchCustomEvent')
+      .mockImplementation(async (event, data): Promise<boolean | void> => {
+        if (event === GraphEvents.ON_RUN_STEP_COMPLETED) {
+          stepCompletions.push(data as (typeof stepCompletions)[number]);
+          return true;
+        }
+        if (event === GraphEvents.ON_TOOL_EXECUTE) {
+          throw new Error('tool should not redispatch');
+        }
+      });
+
+    const eagerExecutions = new Map<string, t.EagerEventToolExecution>();
+    const eagerUsageCount = new Map<string, number>([['weather', 1]]);
+    const request: t.ToolCallRequest = {
+      id: 'call_weather',
+      name: 'weather',
+      args: { city: 'NYC' },
+      stepId: 'step_weather',
+      turn: 7,
+    };
+    eagerExecutions.set('call_weather', {
+      toolCallId: 'call_weather',
+      toolName: 'weather',
+      args: { city: 'NYC' },
+      request,
+      completionDispatched: true,
+      promise: Promise.resolve({
+        results: [
+          {
+            toolCallId: 'call_weather',
+            status: 'success',
+            content: 'eager result',
+          },
+        ],
+      }),
+    });
+
+    const toolNode = new ToolNode({
+      tools: [createDummyTool('weather')],
+      eventDrivenMode: true,
+      eagerEventToolExecution: { enabled: true },
+      eagerEventToolExecutions: eagerExecutions,
+      eagerEventToolUsageCount: eagerUsageCount,
+      toolCallStepIds: new Map([['call_weather', 'step_weather']]),
+    });
+
+    const result = (await toolNode.invoke({
+      messages: [createAIMessage('call_weather', 'weather', { city: 'NYC' })],
+    })) as { messages: ToolMessage[] };
+
+    expect(stepCompletions).toHaveLength(1);
+    expect(stepCompletions[0].result?.index).toBe(0);
+    expect(stepCompletions[0].result?.tool_call?.output).toBe('eager result');
+    expect(result.messages).toHaveLength(1);
+    expect(result.messages[0].content).toBe('eager result');
+  });
+
+  it('uses a matching prestarted event result when output references are enabled', async () => {
+    const { toolExecuteCalls } = installToolExecuteResponder('redispatched');
+    const eagerExecutions = new Map<string, t.EagerEventToolExecution>();
+    const eagerUsageCount = new Map<string, number>([['weather', 1]]);
+    const request: t.ToolCallRequest = {
+      id: 'call_weather',
+      name: 'weather',
+      args: { city: 'NYC' },
+      stepId: 'step_weather',
+      turn: 0,
+    };
+    eagerExecutions.set('call_weather', {
+      toolCallId: 'call_weather',
+      toolName: 'weather',
+      args: { city: 'NYC' },
+      request,
+      promise: Promise.resolve({
+        results: [
+          {
+            toolCallId: 'call_weather',
+            status: 'success',
+            content: 'eager result',
+          },
+        ],
+      }),
+    });
+
+    const toolNode = new ToolNode({
+      tools: [createDummyTool('weather')],
+      eventDrivenMode: true,
+      eagerEventToolExecution: { enabled: true },
+      eagerEventToolExecutions: eagerExecutions,
+      eagerEventToolUsageCount: eagerUsageCount,
+      toolCallStepIds: new Map([['call_weather', 'step_weather']]),
+      toolOutputReferences: { enabled: true },
+    });
+
+    const result = (await toolNode.invoke(
+      {
+        messages: [createAIMessage('call_weather', 'weather', { city: 'NYC' })],
+      },
+      { configurable: { run_id: 'run_1' } }
+    )) as { messages: ToolMessage[] };
+
+    expect(toolExecuteCalls).toHaveLength(0);
+    expect(eagerExecutions.has('call_weather')).toBe(false);
+    expect(result.messages).toHaveLength(1);
+    expect(result.messages[0].content).toBe('eager result');
+    expect(result.messages[0].additional_kwargs._refKey).toBe('tool0turn0');
+    expect(result.messages[0].additional_kwargs._refScope).toBe('run_1');
+  });
+
+  it('does not redispatch completion when eager path already emitted it', async () => {
+    const completedEvents: Array<{ result: t.ToolEndEvent }> = [];
+    const toolExecuteCalls: t.ToolExecuteBatchRequest[] = [];
+    jest
+      .spyOn(events, 'safeDispatchCustomEvent')
+      .mockImplementation(async (event, data): Promise<void> => {
+        if (event === GraphEvents.ON_RUN_STEP_COMPLETED) {
+          completedEvents.push(data as { result: t.ToolEndEvent });
+          return;
+        }
+        if (event !== GraphEvents.ON_TOOL_EXECUTE) {
+          return;
+        }
+        toolExecuteCalls.push(data as t.ToolExecuteBatchRequest);
+      });
+
+    const eagerExecutions = new Map<string, t.EagerEventToolExecution>();
+    const request: t.ToolCallRequest = {
+      id: 'call_weather',
+      name: 'weather',
+      args: { city: 'NYC' },
+      stepId: 'step_weather',
+      turn: 0,
+    };
+    eagerExecutions.set('call_weather', {
+      toolCallId: 'call_weather',
+      toolName: 'weather',
+      args: { city: 'NYC' },
+      request,
+      completionDispatched: true,
+      promise: Promise.resolve({
+        results: [
+          {
+            toolCallId: 'call_weather',
+            status: 'success',
+            content: 'eager result',
+          },
+        ],
+      }),
+    });
+
+    const toolNode = new ToolNode({
+      tools: [createDummyTool('weather')],
+      eventDrivenMode: true,
+      eagerEventToolExecution: { enabled: true },
+      eagerEventToolExecutions: eagerExecutions,
+      eagerEventToolUsageCount: new Map([['weather', 1]]),
+      toolCallStepIds: new Map([['call_weather', 'step_weather']]),
+    });
+
+    const result = (await toolNode.invoke({
+      messages: [createAIMessage('call_weather', 'weather', { city: 'NYC' })],
+    })) as { messages: ToolMessage[] };
+
+    expect(toolExecuteCalls).toHaveLength(0);
+    expect(completedEvents).toHaveLength(0);
+    expect(result.messages[0].content).toBe('eager result');
+  });
+
   it('fails closed without redispatching when final args differ from the prestarted call', async () => {
     const { toolExecuteCalls } = installToolExecuteResponder('fresh result');
     const eagerExecutions = new Map<string, t.EagerEventToolExecution>();
@@ -196,7 +466,7 @@ describe('ToolNode eager event tool execution', () => {
     const { toolExecuteCalls } = installToolExecuteResponder('normal result');
     const eagerExecutions = new Map<string, t.EagerEventToolExecution>();
     const eagerUsageCount = new Map<string, number>([['weather', 1]]);
-    const staleRequest: t.ToolCallRequest = {
+    const prestartedRequest: t.ToolCallRequest = {
       id: 'call_weather_2',
       name: 'weather',
       args: { city: 'Boston' },
@@ -207,13 +477,13 @@ describe('ToolNode eager event tool execution', () => {
       toolCallId: 'call_weather_2',
       toolName: 'weather',
       args: { city: 'Boston' },
-      request: staleRequest,
+      request: prestartedRequest,
       promise: Promise.resolve({
         results: [
           {
             toolCallId: 'call_weather_2',
             status: 'success',
-            content: 'stale eager result',
+            content: 'prestarted eager result',
           },
         ],
       }),
@@ -263,8 +533,8 @@ describe('ToolNode eager event tool execution', () => {
       'call_weather_2',
     ]);
     expect(result.messages[0].status).toBe('success');
-    expect(result.messages[1].status).toBe('error');
-    expect(result.messages[1].content).toContain('refusing to re-run');
+    expect(result.messages[1].status).toBe('success');
+    expect(result.messages[1].content).toBe('prestarted eager result');
   });
 
   it('returns a per-call error for malformed event tool args without aborting the batch', async () => {
@@ -314,9 +584,7 @@ describe('ToolNode eager event tool execution', () => {
       'call_weather_good',
     ]);
     expect(result.messages[0].status).toBe('error');
-    expect(result.messages[0].content).toContain(
-      'Invalid tool call arguments'
-    );
+    expect(result.messages[0].content).toContain('Invalid tool call arguments');
     expect(result.messages[1].status).toBe('success');
     expect(result.messages[1].content).toBe('normal result');
   });
@@ -328,9 +596,7 @@ describe('ToolNode eager event tool execution', () => {
     const hookRegistry = new HookRegistry();
     hookRegistry.register('PreToolUse', {
       hooks: [
-        async (
-          input: PreToolUseHookInput
-        ): Promise<PreToolUseHookOutput> => {
+        async (input: PreToolUseHookInput): Promise<PreToolUseHookOutput> => {
           preToolTurns.push(input.turn);
           return { decision: 'allow' };
         },
@@ -351,9 +617,7 @@ describe('ToolNode eager event tool execution', () => {
     });
 
     await toolNode.invoke({
-      messages: [
-        createAIMessage('call_weather_1', 'weather', { city: 'NYC' }),
-      ],
+      messages: [createAIMessage('call_weather_1', 'weather', { city: 'NYC' })],
     });
 
     eagerUsageCount.clear();

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

@@ -204,6 +204,58 @@ describe('ToolNode tool output references', () => {
       expect(capturedArgs).toEqual(['first', 'echo raw-payload']);
     });
 
+    it('keeps generated-file summaries out of registered outputs', async () => {
+      const rawOutput = [
+        'stdout:',
+        '{"ok":true}',
+        '',
+        'Generated files:',
+        'Session files: 1 persisted file(s) are available in /mnt/data, including 0 image(s). Use known /mnt/data paths directly in later code-tool calls. The app displays files/images automatically; do not invent download links or wrap generated images in Markdown.',
+      ].join('\n');
+      const cleanOutput = 'stdout:\n{"ok":true}';
+      const capturedArgs: string[] = [];
+      const filesTool = tool(
+        async () =>
+          new ToolMessage({
+            status: 'success',
+            content: rawOutput,
+            name: 'files',
+            tool_call_id: 'c1',
+          }),
+        {
+          name: 'files',
+          description: 'returns generated-file summary output',
+          schema: z.object({ command: z.string() }),
+        }
+      ) as unknown as StructuredToolInterface;
+      const echo = createEchoTool({
+        capturedArgs,
+        outputs: ['resolved'],
+      });
+      const node = new ToolNode({
+        tools: [filesTool, echo],
+        toolOutputReferences: { enabled: true },
+      });
+
+      const [msg] = await invokeBatch(node, [
+        { id: 'c1', name: 'files', command: 'first' },
+      ]);
+      await invokeBatch(node, [
+        {
+          id: 'c2',
+          name: 'echo',
+          command: 'echo {{tool0turn0}}',
+        },
+      ]);
+
+      expect(msg.content).toBe(rawOutput);
+      expect(getRefKey(msg)).toBe('tool0turn0');
+      expect(
+        node._unsafeGetToolOutputRegistry()!.get('test-run', 'tool0turn0')
+      ).toBe(cleanOutput);
+      expect(capturedArgs).toEqual([`echo ${cleanOutput}`]);
+    });
+
     it('increments the turn counter per ToolNode batch', async () => {
       const capturedArgs: string[] = [];
       const t1 = createEchoTool({

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

@@ -4,6 +4,9 @@ import type { ToolCall } from '@langchain/core/messages/tool';
 import type * as t from '@/types';
 import type {
   HookCallback,
+  PermissionDeniedHookOutput,
+  PostToolUseHookOutput,
+  PreToolUseHookOutput,
   SubagentStartHookInput,
   SubagentStartHookOutput,
   SubagentStopHookInput,
@@ -11,6 +14,7 @@ import type {
 } from '@/hooks/types';
 import { HookRegistry } from '@/hooks/HookRegistry';
 import { Run } from '@/run';
+import { FakeChatModel } from '@/llm/fake';
 import {
   Constants,
   GraphEvents,
@@ -22,6 +26,18 @@ import * as providers from '@/llm/providers';
 
 const CHILD_RESPONSE = 'Hook test child response.';
 
+const calculatorDef: t.LCTool = {
+  name: 'calculator',
+  description: 'Evaluate a math expression.',
+  parameters: {
+    type: 'object',
+    properties: {
+      expression: { type: 'string' },
+    },
+    required: ['expression'],
+  },
+};
+
 const callerConfig = {
   configurable: { thread_id: 'hook-test-thread' },
   streamMode: 'values' as const,
@@ -66,6 +82,40 @@ function createParentAgent(): t.AgentInputs {
   };
 }
 
+function createParentAgentWithChildTool(): t.AgentInputs {
+  return {
+    agentId: 'hook-parent',
+    provider: Providers.OPENAI,
+    clientOptions: { modelName: 'gpt-4o-mini', apiKey: 'test-key' },
+    instructions: 'Delegate research tasks to subagents.',
+    maxContextTokens: 8000,
+    subagentConfigs: [
+      {
+        type: 'researcher',
+        name: 'Researcher',
+        description: 'Researches topics',
+        agentInputs: {
+          agentId: 'researcher-child',
+          provider: Providers.OPENAI,
+          clientOptions: { modelName: 'gpt-4o-mini', apiKey: 'test-key' },
+          instructions: 'Use calculator for arithmetic, then answer concisely.',
+          maxContextTokens: 8000,
+          toolDefinitions: [calculatorDef],
+        },
+      },
+    ],
+  };
+}
+
+function createCalculatorToolCall(): ToolCall {
+  return {
+    name: 'calculator',
+    args: { expression: '21 * 2' },
+    id: 'call_child_calculator',
+    type: 'tool_call',
+  };
+}
+
 async function createSubagentRun(
   hooks: HookRegistry,
   runId = `subagent-hook-${Date.now()}`
@@ -212,4 +262,191 @@ describe('Subagent hook integration (end-to-end via Run)', () => {
       'Blocked: policy violation'
     );
   });
+
+  it('PreToolUse and PostToolUse fire for event-driven tools inside subagents', async () => {
+    getChatModelClassSpy.mockImplementation(((provider: Providers) => {
+      if (provider === Providers.OPENAI) {
+        return class extends FakeChatModel {
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any
+          constructor(_options: any) {
+            super({
+              responses: ['Using calculator.', CHILD_RESPONSE],
+              sleep: 1,
+              toolCalls: [createCalculatorToolCall()],
+            });
+          }
+          bindTools(
+            tools: unknown
+          ): ReturnType<FakeChatModel['withConfig']> {
+            const config = {
+              tools,
+            } as Parameters<FakeChatModel['withConfig']>[0];
+            return this.withConfig(config);
+          }
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        } as any;
+      }
+      return originalGetChatModelClass(provider);
+    }) as typeof providers.getChatModelClass);
+
+    const registry = new HookRegistry();
+    const preToolEvents: string[] = [];
+    const postToolEvents: string[] = [];
+
+    const preHook: HookCallback<'PreToolUse'> = async (
+      input
+    ): Promise<PreToolUseHookOutput> => {
+      preToolEvents.push(`${input.agentId ?? '-'}:${input.toolName}`);
+      return { decision: 'allow' };
+    };
+    registry.register('PreToolUse', { hooks: [preHook] });
+
+    const postHook: HookCallback<'PostToolUse'> = async (
+      input
+    ): Promise<PostToolUseHookOutput> => {
+      postToolEvents.push(`${input.agentId ?? '-'}:${input.toolName}`);
+      return {};
+    };
+    registry.register('PostToolUse', { hooks: [postHook] });
+
+    const customHandlers: Record<string, t.EventHandler> = {
+      [GraphEvents.TOOL_END]: new ToolEndHandler(),
+      [GraphEvents.CHAT_MODEL_END]: new ModelEndHandler(),
+      [GraphEvents.ON_TOOL_EXECUTE]: {
+        handle: (_event, rawData): void => {
+          const request = rawData as t.ToolExecuteBatchRequest;
+          const results: t.ToolExecuteResult[] = request.toolCalls.map(
+            (call) => ({
+              toolCallId: call.id,
+              status: 'success',
+              content: '42',
+            })
+          );
+          request.resolve(results);
+        },
+      },
+    };
+
+    const run = await Run.create<t.IState>({
+      runId: `subagent-tool-hook-${Date.now()}`,
+      graphConfig: {
+        type: 'standard',
+        agents: [createParentAgentWithChildTool()],
+      },
+      returnContent: true,
+      skipCleanup: true,
+      customHandlers,
+      hooks: registry,
+    });
+
+    const tc = makeSubagentToolCall();
+    run.Graph!.overrideTestModel(['Delegating...', 'Final answer.'], 5, [tc]);
+
+    await run.processStream(
+      { messages: [new HumanMessage('calculate something')] },
+      callerConfig
+    );
+
+    expect(preToolEvents).toContain('-:subagent');
+    expect(preToolEvents).toContain('researcher-child:calculator');
+    expect(postToolEvents).toContain('-:subagent');
+    expect(postToolEvents).toContain('researcher-child:calculator');
+  });
+
+  it('child subagent tool ask hooks fail closed instead of starting unsupported nested HITL', async () => {
+    getChatModelClassSpy.mockImplementation(((provider: Providers) => {
+      if (provider === Providers.OPENAI) {
+        return class extends FakeChatModel {
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any
+          constructor(_options: any) {
+            super({
+              responses: ['Using calculator.', CHILD_RESPONSE],
+              sleep: 1,
+              toolCalls: [createCalculatorToolCall()],
+            });
+          }
+          bindTools(
+            tools: unknown
+          ): ReturnType<FakeChatModel['withConfig']> {
+            const config = {
+              tools,
+            } as Parameters<FakeChatModel['withConfig']>[0];
+            return this.withConfig(config);
+          }
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        } as any;
+      }
+      return originalGetChatModelClass(provider);
+    }) as typeof providers.getChatModelClass);
+
+    const registry = new HookRegistry();
+    const deniedTools: string[] = [];
+    const executedTools: string[] = [];
+
+    const preHook: HookCallback<'PreToolUse'> = async (
+      input
+    ): Promise<PreToolUseHookOutput> => {
+      if (input.toolName === 'calculator') {
+        return { decision: 'ask', reason: 'review calculator' };
+      }
+      return { decision: 'allow' };
+    };
+    registry.register('PreToolUse', { hooks: [preHook] });
+
+    const deniedHook: HookCallback<'PermissionDenied'> = async (
+      input
+    ): Promise<PermissionDeniedHookOutput> => {
+      deniedTools.push(
+        `${input.agentId ?? '-'}:${input.toolName}:${input.reason}`
+      );
+      return {};
+    };
+    registry.register('PermissionDenied', { hooks: [deniedHook] });
+
+    const customHandlers: Record<string, t.EventHandler> = {
+      [GraphEvents.TOOL_END]: new ToolEndHandler(),
+      [GraphEvents.CHAT_MODEL_END]: new ModelEndHandler(),
+      [GraphEvents.ON_TOOL_EXECUTE]: {
+        handle: (_event, rawData): void => {
+          const request = rawData as t.ToolExecuteBatchRequest;
+          executedTools.push(...request.toolCalls.map((call) => call.name));
+          const results: t.ToolExecuteResult[] = request.toolCalls.map(
+            (call) => ({
+              toolCallId: call.id,
+              status: 'success',
+              content: '42',
+            })
+          );
+          request.resolve(results);
+        },
+      },
+    };
+
+    const run = await Run.create<t.IState>({
+      runId: `subagent-tool-ask-${Date.now()}`,
+      graphConfig: {
+        type: 'standard',
+        agents: [createParentAgentWithChildTool()],
+      },
+      returnContent: true,
+      skipCleanup: true,
+      customHandlers,
+      hooks: registry,
+      humanInTheLoop: { enabled: true },
+    });
+
+    const tc = makeSubagentToolCall();
+    run.Graph!.overrideTestModel(['Delegating...', 'Final answer.'], 5, [tc]);
+
+    await run.processStream(
+      { messages: [new HumanMessage('calculate something')] },
+      callerConfig
+    );
+
+    expect(run.getInterrupt()).toBeUndefined();
+    expect(deniedTools).toContain(
+      'researcher-child:calculator:review calculator'
+    );
+    expect(executedTools).not.toContain('calculator');
+  });
 });