@librechat/agents 3.3.2 → 3.3.4

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

@@ -29,7 +29,7 @@ function createAIMessageWithToolCalls(
 type CompletionEvent = {
   result: {
     id: string;
-    tool_call: { id: string; output: string };
+    tool_call: { id: string; output: string; args?: string };
   };
 };
 
@@ -124,6 +124,153 @@ describe('ToolNode per-call onResult completion emission', () => {
     expect(result.messages.map((m) => m.content)).toEqual(['sunny', '42']);
   });
 
+  it('serializes bigint output before early and batch completion paths', async () => {
+    const completions: CompletionEvent[] = [];
+    const structuredOutput = [{ rowsRead: BigInt(42), status: 'complete' }];
+
+    jest
+      .spyOn(events, 'safeDispatchCustomEvent')
+      .mockImplementation(async (event, data): Promise<void> => {
+        if (event === GraphEvents.ON_RUN_STEP_COMPLETED) {
+          completions.push(data as CompletionEvent);
+          return;
+        }
+        if (event !== GraphEvents.ON_TOOL_EXECUTE) {
+          return;
+        }
+        const batch = data as t.ToolExecuteBatchRequest;
+        batch.onResult?.({
+          toolCallId: 'call_query',
+          status: 'success',
+          content: structuredOutput,
+        });
+        await flushAsync();
+        batch.resolve([
+          {
+            toolCallId: 'call_query',
+            status: 'success',
+            content: structuredOutput,
+          },
+        ]);
+      });
+
+    const toolNode = new ToolNode({
+      tools: [createDummyTool('query')],
+      eventDrivenMode: true,
+      toolCallStepIds: new Map([['call_query', 'step_query']]),
+    });
+    const result = (await toolNode.invoke({
+      messages: [
+        createAIMessageWithToolCalls([
+          { id: 'call_query', name: 'query', args: {} },
+        ]),
+      ],
+    })) as { messages: ToolMessage[] };
+
+    const serialized = '[{"rowsRead":"42","status":"complete"}]';
+    expect(completions).toHaveLength(1);
+    expect(completions[0].result.tool_call.output).toBe(serialized);
+    expect(result.messages[0].content).toBe(serialized);
+  });
+
+  it('omits native computer screenshots from completion events', async () => {
+    const completions: CompletionEvent[] = [];
+    const screenshot = `data:image/png;base64,${'A'.repeat(2_000)}`;
+    const computerOutput = new ToolMessage({
+      content: screenshot,
+      tool_call_id: 'call_computer',
+      additional_kwargs: { type: 'computer_call_output' },
+    });
+    const computer = createDummyTool('computer_use');
+    (
+      computer as unknown as {
+        invoke: () => Promise<ToolMessage>;
+      }
+    ).invoke = async () => computerOutput;
+    jest
+      .spyOn(events, 'safeDispatchCustomEvent')
+      .mockImplementation(async (event, data): Promise<void> => {
+        if (event === GraphEvents.ON_RUN_STEP_COMPLETED) {
+          completions.push(data as CompletionEvent);
+        }
+      });
+    const toolNode = new ToolNode({
+      tools: [computer],
+      eventDrivenMode: true,
+      directToolNames: new Set(['computer_use']),
+      toolCallStepIds: new Map([['call_computer', 'step_computer']]),
+      maxToolResultChars: 80,
+    });
+
+    const result = (await toolNode.invoke({
+      messages: [
+        createAIMessageWithToolCalls([
+          { id: 'call_computer', name: 'computer_use', args: {} },
+        ]),
+      ],
+    })) as { messages: ToolMessage[] };
+
+    expect(result.messages[0]).toBe(computerOutput);
+    expect(result.messages[0].content).toBe(screenshot);
+    expect(completions).toHaveLength(1);
+    expect(completions[0].result.tool_call.output).toContain(
+      'Computer screenshot omitted'
+    );
+    expect(completions[0].result.tool_call.output.length).toBeLessThanOrEqual(
+      80
+    );
+  });
+
+  it('bounds cyclic tool args without losing the completion event', async () => {
+    const completions: CompletionEvent[] = [];
+    const cyclicArgs: Record<string, unknown> = { city: 'NYC' };
+    cyclicArgs.self = cyclicArgs;
+
+    jest
+      .spyOn(events, 'safeDispatchCustomEvent')
+      .mockImplementation(async (event, data): Promise<void> => {
+        if (event === GraphEvents.ON_RUN_STEP_COMPLETED) {
+          completions.push(data as CompletionEvent);
+          return;
+        }
+        if (event !== GraphEvents.ON_TOOL_EXECUTE) {
+          return;
+        }
+        const batch = data as t.ToolExecuteBatchRequest;
+        batch.onResult?.({
+          toolCallId: 'call_weather',
+          status: 'success',
+          content: 'sunny',
+        });
+        await flushAsync();
+        batch.resolve([
+          {
+            toolCallId: 'call_weather',
+            status: 'success',
+            content: 'sunny',
+          },
+        ]);
+      });
+
+    const toolNode = new ToolNode({
+      tools: [createDummyTool('weather')],
+      eventDrivenMode: true,
+      toolCallStepIds: new Map([['call_weather', 'step_weather']]),
+    });
+
+    await toolNode.invoke({
+      messages: [
+        createAIMessageWithToolCalls([
+          { id: 'call_weather', name: 'weather', args: cyclicArgs },
+        ]),
+      ],
+    });
+
+    expect(completions).toHaveLength(1);
+    expect(completions[0].result.tool_call.args).toContain('[Circular]');
+    expect(completions[0].result.tool_call.output).toBe('sunny');
+  });
+
   it('ignores duplicate and unknown onResult reports', async () => {
     const completions: CompletionEvent[] = [];
 

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

@@ -113,6 +113,54 @@ describe('ToolNode tool output references', () => {
 
       expect(capturedArgs).toEqual(['raw {{tool0turn0}}']);
     });
+
+    it('bounds structured ToolMessage output before its first model call', async () => {
+      const structuredTool = tool(
+        async () =>
+          new ToolMessage({
+            status: 'success',
+            content: [
+              {
+                type: 'json',
+                rows: Array.from({ length: 20 }, (_, index) => ({
+                  id: index,
+                  value: `${'x'.repeat(100)}-${index}`,
+                })),
+              },
+            ],
+            artifact: { source: 'clickhouse' },
+            metadata: { requestId: 'request-1' },
+            name: 'run_select_query',
+            tool_call_id: 'c1',
+          }),
+        {
+          name: 'run_select_query',
+          description: 'returns structured rows',
+          schema: z.object({ command: z.string() }),
+        }
+      ) as unknown as StructuredToolInterface;
+      const node = new ToolNode({
+        tools: [structuredTool],
+        maxToolResultChars: 200,
+      });
+
+      const [msg] = await invokeBatch(node, [
+        {
+          id: 'c1',
+          name: 'run_select_query',
+          command: 'SELECT * FROM events',
+        },
+      ]);
+
+      expect(typeof msg.content).toBe('string');
+      expect(msg.content).toContain('truncated');
+      expect((msg.content as string).length).toBeLessThanOrEqual(200);
+      expect(msg.tool_call_id).toBe('c1');
+      expect(msg.name).toBe('run_select_query');
+      expect(msg.status).toBe('success');
+      expect(msg.artifact).toEqual({ source: 'clickhouse' });
+      expect(msg.metadata).toEqual({ requestId: 'request-1' });
+    });
   });
 
   describe('enabled', () => {
@@ -364,6 +412,67 @@ describe('ToolNode tool output references', () => {
       ).toBe(raw);
     });
 
+    it('preserves structured output exactly up to the registry limit', async () => {
+      const structured = {
+        rows: Array.from({ length: 10 }, (_, index) => ({
+          id: index,
+          value: `row-${index}-${'x'.repeat(100)}`,
+        })),
+      };
+      const exact = JSON.stringify(structured);
+      const capturedArgs: string[] = [];
+      let callCount = 0;
+      const structuredTool = createEchoTool({
+        capturedArgs: [],
+        outputs: ['unused'],
+        name: 'structured',
+      });
+      (
+        structuredTool as unknown as {
+          invoke: (input: {
+            args: { command: string };
+          }) => Promise<typeof structured | string>;
+        }
+      ).invoke = async (input) => {
+        capturedArgs.push(input.args.command);
+        return callCount++ === 0 ? structured : 'done';
+      };
+      const node = new ToolNode({
+        tools: [structuredTool],
+        maxToolResultChars: 100,
+        toolOutputReferences: {
+          enabled: true,
+          maxOutputSize: exact.length,
+        },
+      });
+
+      const [first] = await invokeBatch(
+        node,
+        [{ id: 'c1', name: 'structured', command: 'first' }],
+        'structured-raw-preservation'
+      );
+      await invokeBatch(
+        node,
+        [
+          {
+            id: 'c2',
+            name: 'structured',
+            command: '{{tool0turn0}}',
+          },
+        ],
+        'structured-raw-preservation'
+      );
+
+      expect((first.content as string).length).toBeLessThanOrEqual(100);
+      expect(first.content).toContain('truncated');
+      expect(capturedArgs[1]).toBe(exact);
+      expect(
+        node
+          ._unsafeGetToolOutputRegistry()!
+          .get('structured-raw-preservation', 'tool0turn0')
+      ).toBe(exact);
+    });
+
     it('uses each batch\'s own turn when ToolNode is invoked concurrently within a run', async () => {
       const gates: Record<string, () => void> = {};
       const slowTool = tool(
@@ -823,7 +932,7 @@ describe('ToolNode tool output references', () => {
       expect(JSON.parse(stepCompletedArgs[1]).command).toBe('echo STORED');
     });
 
-    it('records unresolved refs as metadata on non-string ToolMessage content (content untouched)', async () => {
+    it('records unresolved refs on multipart ToolMessage content within the cap', async () => {
       const complexTool = tool(
         async () =>
           new ToolMessage({
@@ -855,8 +964,8 @@ describe('ToolNode tool output references', () => {
 
       expect(Array.isArray(msg.content)).toBe(true);
       const blocks = msg.content as Array<{ type: string; text?: string }>;
-      // Multi-part content is untouched at storage time — the lazy
-      // transform handles the unresolved-refs warning at request time.
+      // In-budget multi-part content stays intact; the lazy transform handles
+      // the unresolved-refs warning at request time.
       expect(blocks).toHaveLength(2);
       expect(blocks[0].type).toBe('text');
       expect(blocks[0].text).toBe('data');

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

@@ -90,6 +90,38 @@ describe('annotateMessagesForLLM', () => {
     expect(out[0]).not.toBe(tm);
   });
 
+  it('does not annotate native computer screenshot strings', () => {
+    const registry = new ToolOutputReferenceRegistry();
+    registry.set('r1', 'tool0turn0', 'stored-raw');
+    const screenshot = `data:image/png;base64,${'A'.repeat(2_000)}`;
+    const tm = makeToolMessage({
+      content: screenshot,
+      additional_kwargs: {
+        type: 'computer_call_output',
+        _refKey: 'tool0turn0',
+      },
+    });
+
+    const out = annotateMessagesForLLM([tm], registry, 'r1');
+
+    expect(out[0].content).toBe(screenshot);
+    expect((out[0] as ToolMessage).additional_kwargs.type).toBe(
+      'computer_call_output'
+    );
+    expect((out[0] as ToolMessage).additional_kwargs._refKey).toBeUndefined();
+  });
+
+  it('leaves native computer screenshots reference-equal without ref metadata', () => {
+    const registry = new ToolOutputReferenceRegistry();
+    const tm = makeToolMessage({
+      content: 'data:image/png;base64,AAAA',
+      additional_kwargs: { type: 'computer_call_output' },
+    });
+    const messages = [tm];
+
+    expect(annotateMessagesForLLM(messages, registry, 'r1')).toBe(messages);
+  });
+
   it('leaves content untouched but strips framework metadata when _refKey is stale', () => {
     /**
      * Stale `_refKey` (not in registry) doesn't trigger annotation,

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

@@ -20,7 +20,7 @@ import { ToolNode } from '../ToolNode';
  */
 function createDirectTool(
   name: string,
-  impl: (args: Record<string, unknown>) => string | Promise<string>
+  impl: (args: Record<string, unknown>) => unknown | Promise<unknown>
 ): StructuredToolInterface {
   return tool(async (args: Record<string, unknown>) => impl(args), {
     name,
@@ -147,6 +147,217 @@ describe('Direct-path lifecycle hooks (in-process tools)', () => {
     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> = [];
@@ -247,6 +458,37 @@ describe('Direct-path lifecycle hooks (in-process tools)', () => {
     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');
@@ -376,11 +618,16 @@ describe('Direct-path lifecycle hooks (in-process tools)', () => {
 
     // 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 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);
@@ -424,7 +671,8 @@ describe('Direct-path lifecycle hooks (in-process tools)', () => {
       hooks: [
         async (): Promise<PreToolUseHookOutput> => ({
           decision: 'allow',
-          additionalContext: 'POLICY-NOTE: writes here require approval next time',
+          additionalContext:
+            'POLICY-NOTE: writes here require approval next time',
         }),
       ],
     });

package/src/tools/toolOutputReferences.ts

@@ -29,6 +29,7 @@ import {
   HARD_MAX_TOOL_RESULT_CHARS,
   HARD_MAX_TOTAL_TOOL_OUTPUT_SIZE,
 } from '@/utils/truncation';
+import { isComputerCallOutputMessage } from '@/utils/toolContent';
 
 /**
  * Non-global matcher for a single `{{tool<i>turn<n>}}` placeholder.
@@ -656,6 +657,11 @@ export function annotateMessagesForLLM(
     const hasRefScope = '_refScope' in meta;
     const hasUnresolvedField = '_unresolvedRefs' in meta;
     if (!hasRefKey && !hasRefScope && !hasUnresolvedField) continue;
+    if (isComputerCallOutputMessage(m)) {
+      out ??= messages.slice();
+      out[i] = cloneToolMessageWithContent(m as ToolMessage, m.content);
+      continue;
+    }
 
     const refKey = readRefKey(meta);
     const unresolved = readUnresolvedRefs(meta);

package/src/types/stream.ts

@@ -336,7 +336,7 @@ export type ToolCallPart = {
   /** If provided, an identifier associated with the tool call */
   id?: string;
   /** If provided, the output of the tool call */
-  output?: string;
+  output?: ToolResultContent['content'];
   /** Auth URL */
   auth?: string;
   /** Expiration time */

package/src/utils/llm.test.ts

@@ -0,0 +1,18 @@
+import { isAnthropicLike } from './llm';
+import { Providers } from '@/common';
+
+describe('isAnthropicLike', () => {
+  it('treats the default Bedrock model as Claude', () => {
+    expect(isAnthropicLike(Providers.BEDROCK)).toBe(true);
+    expect(
+      isAnthropicLike(Providers.BEDROCK, {
+        model: 'anthropic.claude-sonnet-4-5',
+      })
+    ).toBe(true);
+    expect(
+      isAnthropicLike(Providers.BEDROCK, {
+        model: 'amazon.nova-pro-v1:0',
+      })
+    ).toBe(false);
+  });
+});