@librechat/agents 3.3.3 → 3.3.5

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/search/keenable-scraper.test.ts

@@ -0,0 +1,153 @@
+import axios from 'axios';
+import { createKeenableScraper } from './keenable-scraper';
+
+jest.mock('axios');
+const mockedAxios = axios as jest.Mocked<typeof axios>;
+
+const sampleResponse = {
+  data: {
+    url: 'https://example.com/',
+    title: 'Example Domain',
+    content:
+      '# Example Domain\n\nThis domain is for use in documentation examples.',
+    description: 'An example page.',
+  },
+};
+
+describe('Keenable scraper', () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+    delete process.env.KEENABLE_API_KEY;
+    delete process.env.KEENABLE_FETCH_URL;
+  });
+
+  it('returns an error for empty URLs without calling the API', async () => {
+    const scraper = createKeenableScraper();
+    const [url, response] = await scraper.scrapeUrl('   ');
+
+    expect(url).toBe('   ');
+    expect(response.success).toBe(false);
+    expect(mockedAxios.get).not.toHaveBeenCalled();
+  });
+
+  it('hits the public endpoint and omits the API key header when keyless', async () => {
+    mockedAxios.get.mockResolvedValueOnce(sampleResponse);
+
+    const scraper = createKeenableScraper();
+    const [, response] = await scraper.scrapeUrl('https://example.com');
+
+    expect(mockedAxios.get).toHaveBeenCalledWith(
+      'https://api.keenable.ai/v1/fetch/public',
+      expect.objectContaining({
+        params: { url: 'https://example.com' },
+        headers: expect.objectContaining({ 'X-Keenable-Title': 'LibreChat' }),
+      })
+    );
+    const headers = mockedAxios.get.mock.calls[0][1]?.headers as Record<
+      string,
+      string
+    >;
+    expect(headers['X-API-Key']).toBeUndefined();
+    expect(response.success).toBe(true);
+    expect(response.data?.content).toContain('# Example Domain');
+  });
+
+  it('hits the keyed endpoint and sends the API key header when a key is set', async () => {
+    mockedAxios.get.mockResolvedValueOnce(sampleResponse);
+
+    const scraper = createKeenableScraper({ apiKey: 'secret-key' });
+    await scraper.scrapeUrl('https://example.com');
+
+    expect(mockedAxios.get).toHaveBeenCalledWith(
+      'https://api.keenable.ai/v1/fetch',
+      expect.objectContaining({
+        headers: expect.objectContaining({ 'X-API-Key': 'secret-key' }),
+      })
+    );
+  });
+
+  it('honors a custom attribution title and fetch URL override', async () => {
+    mockedAxios.get.mockResolvedValueOnce(sampleResponse);
+
+    const scraper = createKeenableScraper({
+      apiUrl: 'https://keenable.internal/v1/fetch/public',
+      attributionTitle: 'MyApp',
+    });
+    await scraper.scrapeUrl('https://example.com');
+
+    expect(mockedAxios.get).toHaveBeenCalledWith(
+      'https://keenable.internal/v1/fetch/public',
+      expect.objectContaining({
+        headers: expect.objectContaining({ 'X-Keenable-Title': 'MyApp' }),
+      })
+    );
+  });
+
+  it('reports failure when the API returns no content', async () => {
+    mockedAxios.get.mockResolvedValueOnce({
+      data: { url: 'https://x.test', content: '' },
+    });
+
+    const scraper = createKeenableScraper();
+    const [, response] = await scraper.scrapeUrl('https://x.test');
+
+    expect(response.success).toBe(false);
+    expect(response.error).toMatch(/no content/i);
+  });
+
+  it('reports failure with a message when the request throws', async () => {
+    mockedAxios.get.mockRejectedValueOnce(new Error('network down'));
+
+    const scraper = createKeenableScraper();
+    const [, response] = await scraper.scrapeUrl('https://x.test');
+
+    expect(response.success).toBe(false);
+    expect(response.error).toContain('network down');
+  });
+
+  it('scrapes multiple URLs concurrently', async () => {
+    mockedAxios.get
+      .mockResolvedValueOnce({ data: { content: 'a', url: 'https://a.test' } })
+      .mockResolvedValueOnce({ data: { content: 'b', url: 'https://b.test' } });
+
+    const scraper = createKeenableScraper();
+    const results = await scraper.scrapeUrls([
+      'https://a.test',
+      'https://b.test',
+    ]);
+
+    expect(results).toHaveLength(2);
+    expect(results[0][1].data?.content).toBe('a');
+    expect(results[1][1].data?.content).toBe('b');
+  });
+
+  it('extractContent returns the markdown with no structured references', () => {
+    const scraper = createKeenableScraper();
+    const [content, references] = scraper.extractContent({
+      success: true,
+      data: { content: '# Title\n\nBody' },
+    });
+
+    expect(content).toBe('# Title\n\nBody');
+    expect(references).toBeUndefined();
+  });
+
+  it('extractMetadata surfaces title, description and url', () => {
+    const scraper = createKeenableScraper();
+    const metadata = scraper.extractMetadata({
+      success: true,
+      data: {
+        content: 'x',
+        title: 'Example Domain',
+        description: 'An example page.',
+        url: 'https://example.com/',
+      },
+    });
+
+    expect(metadata).toEqual({
+      title: 'Example Domain',
+      description: 'An example page.',
+      url: 'https://example.com/',
+    });
+  });
+});