@librechat/agents 3.3.11 → 3.3.12

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

@@ -0,0 +1,389 @@
+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 { RunnableConfig } from '@langchain/core/runnables';
+import type * as t from '@/types';
+import * as events from '@/utils/events';
+import {
+  StreamLimitExceededError,
+  RUN_BREAKER_SCOPE_CONFIG_KEY,
+} from '@/llm/streamLimits';
+import { GraphEvents } from '@/common';
+import { HookRegistry } from '@/hooks';
+import { ToolNode } from '../ToolNode';
+
+function createSignalCaptureTool(name: string): {
+  tool: StructuredToolInterface;
+  observed: () => AbortSignal | undefined;
+} {
+  let signal: AbortSignal | undefined;
+  const captureTool = tool(
+    async (_input, config) => {
+      signal = (config as RunnableConfig | undefined)?.signal;
+      return 'captured';
+    },
+    {
+      name,
+      description: 'captures the abort signal its runtime receives',
+      schema: z.object({}),
+    }
+  ) as unknown as StructuredToolInterface;
+  return { tool: captureTool, observed: () => signal };
+}
+
+function createToolCallMessage(id: string, name: string): AIMessage {
+  return new AIMessage({ content: '', tool_calls: [{ id, name, args: {} }] });
+}
+
+/** A minimal tool whose invoke ignores the abort signal entirely — unlike
+ * langchain `tool()` Runnables, which race the signal and reject with its
+ * reason the moment a trip fires mid-execution. */
+function createSignalBlindTool(
+  name: string,
+  fn: () => Promise<string>
+): StructuredToolInterface {
+  return {
+    name,
+    description: `signal-blind ${name}`,
+    invoke: fn,
+  } as unknown as StructuredToolInterface;
+}
+
+function installToolExecuteResponder(): {
+  toolExecuteCalls: t.ToolExecuteBatchRequest[];
+  } {
+  const toolExecuteCalls: t.ToolExecuteBatchRequest[] = [];
+  jest
+    .spyOn(events, 'safeDispatchCustomEvent')
+    .mockImplementation(async (event, data): Promise<void> => {
+      if (event !== GraphEvents.ON_TOOL_EXECUTE) {
+        return;
+      }
+      const batch = data as t.ToolExecuteBatchRequest;
+      toolExecuteCalls.push(batch);
+      batch.resolve(
+        batch.toolCalls.map((call) => ({
+          toolCallId: call.id,
+          status: 'success' as const,
+          content: `ok ${call.name}`,
+        }))
+      );
+    });
+  return { toolExecuteCalls };
+}
+
+describe('ToolNode breaker signal composition', () => {
+  afterEach(() => {
+    jest.restoreAllMocks();
+  });
+
+  it('exposes the run breaker to direct tool runtimes', async () => {
+    const breaker = new AbortController();
+    const { tool: capture, observed } = createSignalCaptureTool('capture');
+    const node = new ToolNode({
+      tools: [capture],
+      getBreakerSignal: () => breaker.signal,
+    });
+
+    const result = (await node.invoke({
+      messages: [createToolCallMessage('call_1', 'capture')],
+    })) as { messages: ToolMessage[] };
+
+    expect(result.messages[0].content).toBe('captured');
+    const signal = observed();
+    expect(signal).toBeDefined();
+    expect(signal?.aborted).toBe(false);
+
+    breaker.abort(new Error('stream limit breach'));
+    expect(signal?.aborted).toBe(true);
+  });
+
+  it('composes the breaker with the caller signal instead of replacing it', async () => {
+    const breaker = new AbortController();
+    const caller = new AbortController();
+    const { tool: capture, observed } = createSignalCaptureTool('capture');
+    const node = new ToolNode({
+      tools: [capture],
+      getBreakerSignal: () => breaker.signal,
+    });
+
+    await node.invoke(
+      { messages: [createToolCallMessage('call_1', 'capture')] },
+      { signal: caller.signal }
+    );
+
+    const signal = observed();
+    expect(signal).toBeDefined();
+    expect(signal?.aborted).toBe(false);
+
+    caller.abort(new Error('caller cancelled'));
+    expect(signal?.aborted).toBe(true);
+  });
+
+  it('leaves the caller signal untouched when no breaker accessor is set', async () => {
+    const caller = new AbortController();
+    const { tool: capture, observed } = createSignalCaptureTool('capture');
+    const node = new ToolNode({ tools: [capture] });
+
+    await node.invoke(
+      { messages: [createToolCallMessage('call_1', 'capture')] },
+      { signal: caller.signal }
+    );
+
+    expect(observed()).toBe(caller.signal);
+  });
+
+  it('rejects the batch at entry when the breaker has already tripped', async () => {
+    const breaker = new AbortController();
+    const trip = new StreamLimitExceededError({
+      kind: 'tool_call_args',
+      limit: 10,
+      observed: 11,
+      toolName: 'db_query',
+    });
+    breaker.abort(trip);
+    let toolRan = false;
+    const sideEffect = tool(
+      async () => {
+        toolRan = true;
+        return 'ran';
+      },
+      {
+        name: 'side_effect',
+        description: 'must never run on a failed run',
+        schema: z.object({}),
+      }
+    ) as unknown as StructuredToolInterface;
+    const node = new ToolNode({
+      tools: [sideEffect],
+      getBreakerSignal: () => breaker.signal,
+    });
+
+    await expect(
+      node.invoke({
+        messages: [createToolCallMessage('call_1', 'side_effect')],
+      })
+    ).rejects.toBe(trip);
+    expect(toolRan).toBe(false);
+  });
+
+  it('stops regular siblings when an interrupting tool trips the breaker', async () => {
+    const breaker = new AbortController();
+    const trip = new StreamLimitExceededError({
+      kind: 'tool_call_args',
+      limit: 10,
+      observed: 11,
+      toolName: 'db_query',
+    });
+    let sideEffectRan = false;
+    /** Plain tool objects, NOT langchain `tool()`: Runnable invokes race
+     * the composed signal and reject with its reason the instant the trip
+     * fires, which would mask the stage boundary this test targets. The
+     * exposure is exactly tools that ignore cancellation. */
+    const tripper = createSignalBlindTool('ask_question', async () => {
+      breaker.abort(trip);
+      return 'completed normally across the trip';
+    });
+    const sideEffect = createSignalBlindTool('send_email', async () => {
+      sideEffectRan = true;
+      return 'sent';
+    });
+    const node = new ToolNode({
+      tools: [tripper, sideEffect],
+      interruptingToolNames: new Set(['ask_question']),
+      getBreakerSignal: () => breaker.signal,
+    });
+
+    await expect(
+      node.invoke({
+        messages: [
+          new AIMessage({
+            content: '',
+            tool_calls: [
+              { id: 'call_1', name: 'ask_question', args: {} },
+              { id: 'call_2', name: 'send_email', args: {} },
+            ],
+          }),
+        ],
+      })
+    ).rejects.toBe(trip);
+    expect(sideEffectRan).toBe(false);
+  });
+
+  it('stops event dispatch when a direct tool trips the breaker mid-batch', async () => {
+    const breaker = new AbortController();
+    const trip = new StreamLimitExceededError({
+      kind: 'tool_call_args',
+      limit: 10,
+      observed: 11,
+      toolName: 'db_query',
+    });
+    const { toolExecuteCalls } = installToolExecuteResponder();
+    const tripper = createSignalBlindTool('direct_tripper', async () => {
+      breaker.abort(trip);
+      return 'completed normally across the trip';
+    });
+    const node = new ToolNode({
+      tools: [tripper],
+      eventDrivenMode: true,
+      directToolNames: new Set(['direct_tripper']),
+      toolCallStepIds: new Map([
+        ['call_1', 'step_1'],
+        ['call_2', 'step_2'],
+      ]),
+      getBreakerSignal: () => breaker.signal,
+    });
+
+    await expect(
+      node.invoke({
+        messages: [
+          new AIMessage({
+            content: '',
+            tool_calls: [
+              { id: 'call_1', name: 'direct_tripper', args: {} },
+              { id: 'call_2', name: 'remote_tool', args: {} },
+            ],
+          }),
+        ],
+      })
+    ).rejects.toBe(trip);
+    expect(toolExecuteCalls).toHaveLength(0);
+  });
+
+  it('stops a direct tool when the breaker trips during its PreToolUse hook', async () => {
+    const breaker = new AbortController();
+    const trip = new StreamLimitExceededError({
+      kind: 'tool_call_args',
+      limit: 10,
+      observed: 11,
+      toolName: 'db_query',
+    });
+    let toolRan = false;
+    const sideEffect = createSignalBlindTool('send_email', async () => {
+      toolRan = true;
+      return 'sent';
+    });
+    const registry = new HookRegistry();
+    registry.register('PreToolUse', {
+      hooks: [
+        async () => {
+          breaker.abort(trip);
+          return { decision: 'allow' };
+        },
+      ],
+    });
+    const node = new ToolNode({
+      tools: [sideEffect],
+      hookRegistry: registry,
+      getBreakerSignal: () => breaker.signal,
+    });
+
+    await expect(
+      node.invoke({
+        messages: [createToolCallMessage('call_1', 'send_email')],
+      })
+    ).rejects.toBe(trip);
+    expect(toolRan).toBe(false);
+  });
+
+  it('stops the host batch when the breaker trips during approval hooks', async () => {
+    const breaker = new AbortController();
+    const trip = new StreamLimitExceededError({
+      kind: 'tool_call_args',
+      limit: 10,
+      observed: 11,
+      toolName: 'db_query',
+    });
+    const { toolExecuteCalls } = installToolExecuteResponder();
+    const registry = new HookRegistry();
+    registry.register('PreToolUse', {
+      hooks: [
+        async () => {
+          breaker.abort(trip);
+          return { decision: 'allow' };
+        },
+      ],
+    });
+    const node = new ToolNode({
+      tools: [],
+      eventDrivenMode: true,
+      hookRegistry: registry,
+      toolCallStepIds: new Map([['call_1', 'step_1']]),
+      getBreakerSignal: () => breaker.signal,
+    });
+
+    await expect(
+      node.invoke({
+        messages: [createToolCallMessage('call_1', 'remote_tool')],
+      })
+    ).rejects.toBe(trip);
+    expect(toolExecuteCalls).toHaveLength(0);
+  });
+
+  it('stamps the batch-entry run scope into tool configs and strips it from host batches', async () => {
+    const scope = Object.freeze({ epoch: 3, controller: new AbortController() });
+    let seenScope: unknown;
+    const capture = {
+      name: 'capture_scope',
+      description: 'captures the batch scope from its config',
+      invoke: async (
+        _params: unknown,
+        config?: { configurable?: Record<string, unknown> }
+      ): Promise<string> => {
+        seenScope = config?.configurable?.[RUN_BREAKER_SCOPE_CONFIG_KEY];
+        return 'ok';
+      },
+    } as unknown as StructuredToolInterface;
+    const node = new ToolNode({
+      tools: [capture],
+      getRunScope: () => scope,
+    });
+
+    await node.invoke({
+      messages: [createToolCallMessage('call_1', 'capture_scope')],
+    });
+    expect(seenScope).toBe(scope);
+
+    /** Host batch requests spread `configurable` into their own run
+     * configs — the scope must not leak there. */
+    const { toolExecuteCalls } = installToolExecuteResponder();
+    const eventNode = new ToolNode({
+      tools: [],
+      eventDrivenMode: true,
+      toolCallStepIds: new Map([['call_1', 'step_1']]),
+      getRunScope: () => scope,
+    });
+    await eventNode.invoke({
+      messages: [createToolCallMessage('call_1', 'remote_tool')],
+    });
+    expect(toolExecuteCalls).toHaveLength(1);
+    expect(
+      toolExecuteCalls[0].configurable?.[RUN_BREAKER_SCOPE_CONFIG_KEY]
+    ).toBeUndefined();
+  });
+
+  it('sends a breaker-composed signal on ON_TOOL_EXECUTE batch requests', async () => {
+    const breaker = new AbortController();
+    const { toolExecuteCalls } = installToolExecuteResponder();
+    const node = new ToolNode({
+      tools: [],
+      eventDrivenMode: true,
+      toolCallStepIds: new Map([['call_1', 'step_1']]),
+      getBreakerSignal: () => breaker.signal,
+    });
+
+    await node.invoke({
+      messages: [createToolCallMessage('call_1', 'remote_tool')],
+    });
+
+    expect(toolExecuteCalls).toHaveLength(1);
+    const { signal } = toolExecuteCalls[0];
+    expect(signal).toBeDefined();
+    expect(signal?.aborted).toBe(false);
+
+    breaker.abort(new Error('stream limit breach'));
+    expect(signal?.aborted).toBe(true);
+  });
+});

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

@@ -0,0 +1,69 @@
+/**
+ * `StreamLimitExceededError` must pass through ToolNode's tool-error
+ * conversion like a `GraphInterrupt`: a child run (subagent) that trips a
+ * stream circuit breaker is a safety abort, and converting it into an error
+ * ToolMessage would let the parent keep generating after the limit fired.
+ */
+import { z } from 'zod';
+import { tool } from '@langchain/core/tools';
+import { AIMessage } from '@langchain/core/messages';
+import { describe, it, expect } from '@jest/globals';
+import type { StructuredToolInterface } from '@langchain/core/tools';
+import { StreamLimitExceededError } from '@/llm/streamLimits';
+import { ToolNode } from '@/tools/ToolNode';
+
+const stateWith = (name: string): { messages: AIMessage[] } => ({
+  messages: [
+    new AIMessage({
+      content: '',
+      tool_calls: [{ id: 'call_1', name, args: { command: 'x' } }],
+    }),
+  ],
+});
+
+describe('ToolNode stream-limit passthrough', () => {
+  it('rethrows StreamLimitExceededError instead of converting it to a ToolMessage', async () => {
+    const limitBoom = tool(
+      async () => {
+        throw new StreamLimitExceededError({
+          kind: 'tool_call_args',
+          limit: 10,
+          observed: 11,
+          toolName: 'db_query',
+        });
+      },
+      {
+        name: 'limitBoom',
+        description: 'tool that trips a stream limit',
+        schema: z.object({ command: z.string() }),
+      }
+    ) as unknown as StructuredToolInterface;
+
+    const node = new ToolNode({ tools: [limitBoom] });
+    await expect(
+      node.invoke(stateWith('limitBoom'), {
+        configurable: { run_id: 'limit-run' },
+      })
+    ).rejects.toBeInstanceOf(StreamLimitExceededError);
+  });
+
+  it('still converts ordinary tool errors to error ToolMessages', async () => {
+    const plainBoom = tool(
+      async () => {
+        throw new Error('ordinary failure');
+      },
+      {
+        name: 'plainBoom',
+        description: 'tool that throws a normal error',
+        schema: z.object({ command: z.string() }),
+      }
+    ) as unknown as StructuredToolInterface;
+
+    const node = new ToolNode({ tools: [plainBoom] });
+    const result = (await node.invoke(stateWith('plainBoom'), {
+      configurable: { run_id: 'plain-run' },
+    })) as { messages: Array<{ content: unknown; status?: string }> };
+    expect(result.messages).toHaveLength(1);
+    expect(String(result.messages[0].content)).toContain('ordinary failure');
+  });
+});

package/src/tools/search/crw-scraper.ts

@@ -27,6 +27,8 @@ export class CrwScraper implements t.BaseScraper {
   private xpath?: string;
   private proxy?: string;
   private stealth?: boolean;
+  private httpAgent?: t.HttpAgent;
+  private httpsAgent?: t.HttpsAgent;
 
   constructor(config: t.CrwScraperConfig = {}) {
     this.apiKey = config.apiKey ?? process.env.CRW_API_KEY ?? '';
@@ -49,6 +51,8 @@ export class CrwScraper implements t.BaseScraper {
     this.xpath = config.xpath;
     this.proxy = config.proxy;
     this.stealth = config.stealth;
+    this.httpAgent = config.httpAgent;
+    this.httpsAgent = config.httpsAgent;
 
     // Self-host fastCRW may run without auth, so a missing key is only a
     // warning — unlike Firecrawl/Tavily, scrapeUrl does NOT early-return on it.
@@ -96,6 +100,8 @@ export class CrwScraper implements t.BaseScraper {
         {
           headers,
           timeout: payloadTimeout + CRW_TIMEOUT_BUFFER,
+          httpAgent: this.httpAgent,
+          httpsAgent: this.httpsAgent,
         }
       );
 

package/src/tools/search/crw-search.ts

@@ -91,7 +91,12 @@ export const createCrwAPI = (
       const response = await axios.post<t.CrwSearchResponse>(
         config.apiUrl,
         payload,
-        { headers, timeout: config.timeout }
+        {
+          headers,
+          timeout: config.timeout,
+          httpAgent: options?.httpAgent,
+          httpsAgent: options?.httpsAgent,
+        }
       );
 
       const body = response.data;

package/src/tools/search/firecrawl.ts

@@ -29,6 +29,8 @@ export class FirecrawlScraper implements t.BaseScraper {
   private location?: { country?: string; languages?: string[] };
   private onlyMainContent?: boolean;
   private changeTrackingOptions?: object;
+  private httpAgent?: t.HttpAgent;
+  private httpsAgent?: t.HttpsAgent;
 
   constructor(config: t.FirecrawlScraperConfig = {}) {
     this.apiKey = config.apiKey ?? process.env.FIRECRAWL_API_KEY ?? '';
@@ -61,6 +63,8 @@ export class FirecrawlScraper implements t.BaseScraper {
     this.location = config.location;
     this.onlyMainContent = config.onlyMainContent;
     this.changeTrackingOptions = config.changeTrackingOptions;
+    this.httpAgent = config.httpAgent;
+    this.httpsAgent = config.httpsAgent;
 
     if (!this.apiKey) {
       this.logger.warn('FIRECRAWL_API_KEY is not set. Scraping will not work.');
@@ -121,6 +125,8 @@ export class FirecrawlScraper implements t.BaseScraper {
           Authorization: `Bearer ${this.apiKey}`,
         },
         timeout: this.timeout,
+        httpAgent: this.httpAgent,
+        httpsAgent: this.httpsAgent,
       });
 
       return [url, response.data];

package/src/tools/search/http-agent.test.ts

@@ -0,0 +1,133 @@
+import axios from 'axios';
+import { Agent as HttpAgent } from 'http';
+import { Agent as HttpsAgent } from 'https';
+import { createFirecrawlScraper } from './firecrawl';
+import { createReranker } from './rerankers';
+import { createCrwAPI } from './crw-search';
+import { createSearchAPI } from './search';
+
+jest.mock('axios');
+const mockedAxios = axios as jest.Mocked<typeof axios>;
+
+const httpAgent = new HttpAgent();
+const httpsAgent = new HttpsAgent();
+
+describe('injected http(s) agent', () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+  });
+
+  it('passes both agents to the firecrawl scraper request config', async () => {
+    mockedAxios.post.mockResolvedValueOnce({
+      data: { success: true, data: { markdown: 'x' } },
+    });
+
+    const scraper = createFirecrawlScraper({
+      apiKey: 'test-key',
+      httpAgent,
+      httpsAgent,
+    });
+    await scraper.scrapeUrl('https://example.com');
+
+    expect(mockedAxios.post).toHaveBeenCalledWith(
+      expect.any(String),
+      expect.anything(),
+      expect.objectContaining({ httpAgent, httpsAgent })
+    );
+  });
+
+  it('omits agents from the firecrawl request config when none are provided', async () => {
+    mockedAxios.post.mockResolvedValueOnce({
+      data: { success: true, data: { markdown: 'x' } },
+    });
+
+    const scraper = createFirecrawlScraper({ apiKey: 'test-key' });
+    await scraper.scrapeUrl('https://example.com');
+
+    const requestConfig = mockedAxios.post.mock.calls[0][2];
+    expect(requestConfig?.httpAgent).toBeUndefined();
+    expect(requestConfig?.httpsAgent).toBeUndefined();
+  });
+
+  it('passes both agents to the Jina reranker request config', async () => {
+    mockedAxios.post.mockResolvedValueOnce({ data: { results: [] } });
+
+    const reranker = createReranker({
+      rerankerType: 'jina',
+      jinaApiKey: 'test-key',
+      httpAgent,
+      httpsAgent,
+    });
+    await reranker?.rerank('query', ['a', 'b'], 2);
+
+    expect(mockedAxios.post).toHaveBeenCalledWith(
+      expect.any(String),
+      expect.anything(),
+      expect.objectContaining({ httpAgent, httpsAgent })
+    );
+  });
+
+  it('passes agents supplied through the crw search options bag', async () => {
+    mockedAxios.post.mockResolvedValueOnce({
+      data: { success: true, data: { web: [] } },
+    });
+
+    const api = createCrwAPI('test-key', undefined, { httpAgent, httpsAgent });
+    await api.getSources({ query: 'query' });
+
+    expect(mockedAxios.post).toHaveBeenCalledWith(
+      expect.any(String),
+      expect.anything(),
+      expect.objectContaining({ httpAgent, httpsAgent })
+    );
+  });
+
+  it('threads agents from the tool config into the serper search request', async () => {
+    mockedAxios.post.mockResolvedValueOnce({ data: { organic: [] } });
+
+    const api = createSearchAPI({
+      searchProvider: 'serper',
+      serperApiKey: 'test-key',
+      httpAgent,
+      httpsAgent,
+    });
+    await api.getSources({ query: 'query' });
+
+    expect(mockedAxios.post).toHaveBeenCalledWith(
+      expect.any(String),
+      expect.anything(),
+      expect.objectContaining({ httpAgent, httpsAgent })
+    );
+  });
+
+  it('threads agents from the tool config into the searxng search request', async () => {
+    mockedAxios.get.mockResolvedValueOnce({ data: { results: [] } });
+
+    const api = createSearchAPI({
+      searchProvider: 'searxng',
+      searxngInstanceUrl: 'https://searxng.example.com',
+      httpAgent,
+      httpsAgent,
+    });
+    await api.getSources({ query: 'query' });
+
+    expect(mockedAxios.get).toHaveBeenCalledWith(
+      expect.any(String),
+      expect.objectContaining({ httpAgent, httpsAgent })
+    );
+  });
+
+  it('omits agents from the serper search request when none are provided', async () => {
+    mockedAxios.post.mockResolvedValueOnce({ data: { organic: [] } });
+
+    const api = createSearchAPI({
+      searchProvider: 'serper',
+      serperApiKey: 'test-key',
+    });
+    await api.getSources({ query: 'query' });
+
+    const requestConfig = mockedAxios.post.mock.calls[0][2];
+    expect(requestConfig?.httpAgent).toBeUndefined();
+    expect(requestConfig?.httpsAgent).toBeUndefined();
+  });
+});

package/src/tools/search/keenable-scraper.ts

@@ -15,6 +15,8 @@ export class KeenableScraper implements t.BaseScraper {
   private timeout: number;
   private attributionTitle: string;
   private logger: t.Logger;
+  private httpAgent?: t.HttpAgent;
+  private httpsAgent?: t.HttpsAgent;
 
   constructor(config: t.KeenableScraperConfig = {}) {
     const resolvedKey = config.apiKey ?? process.env.KEENABLE_API_KEY;
@@ -28,6 +30,8 @@ export class KeenableScraper implements t.BaseScraper {
         : KEENABLE_FETCH_PUBLIC_URL);
     this.timeout = config.timeout ?? DEFAULT_KEENABLE_SCRAPE_TIMEOUT;
     this.attributionTitle = config.attributionTitle ?? 'LibreChat';
+    this.httpAgent = config.httpAgent;
+    this.httpsAgent = config.httpsAgent;
     this.logger = config.logger || createDefaultLogger();
   }
 
@@ -57,6 +61,8 @@ export class KeenableScraper implements t.BaseScraper {
         params: { url },
         headers: this.buildHeaders(),
         timeout: options.timeout ?? this.timeout,
+        httpAgent: this.httpAgent,
+        httpsAgent: this.httpsAgent,
       });
 
       const data = response.data;

package/src/tools/search/keenable-search.ts

@@ -65,7 +65,12 @@ export const createKeenableAPI = (
       const response = await axios.post<t.KeenableSearchResponse>(
         resolvedUrl,
         payload,
-        { headers, timeout }
+        {
+          headers,
+          timeout,
+          httpAgent: options?.httpAgent,
+          httpsAgent: options?.httpsAgent,
+        }
       );
 
       const maxResults = Math.min(