@librechat/agents 3.3.10 → 3.3.12

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

@@ -24,9 +24,9 @@ describe('buildBashExecutionToolDescription', () => {
     expect(BashExecutionToolDescription).toContain('heredoc/printf');
     expect(BashExecutionToolDescription).toContain('not bare Python');
     expect(BashExecutionToolDescription).toContain(
-      'failed executions do not register new files'
+      'Failed executions register nothing'
     );
-    expect(BashExecutionToolDescription).toContain('not later-call storage');
+    expect(BashExecutionToolDescription).toContain('`/tmp` never survives the call');
   });
 
   it('appends the tool-output references guide when enabled', () => {

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

@@ -51,10 +51,8 @@ describe('ProgrammaticToolCalling', () => {
       expect(description).toContain('raw=$(tool');
       expect(description).toContain('direct tool > file may be empty');
       expect(description).toContain('/mnt/data/sf.json');
-      expect(description).toContain(
-        'failed executions do not register new files'
-      );
-      expect(description).toContain('not later-call storage');
+      expect(description).toContain('Failed executions register nothing');
+      expect(description).toContain('`/tmp` never survives the call');
     });
   });
 

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

@@ -20,6 +20,7 @@ import {
 } from '../subagent';
 import { sanitizeForwardedSubagentUpdateData } from '../subagent/SubagentExecutor';
 import { Constants, Providers, GraphEvents, StepTypes } from '@/common';
+import { StreamLimitExceededError } from '@/llm/streamLimits';
 import { AgentContext } from '@/agents/AgentContext';
 import { HookRegistry } from '@/hooks/HookRegistry';
 import { HandlerRegistry } from '@/events';
@@ -451,6 +452,131 @@ describe('SubagentExecutor', () => {
     expect(result.messages).toEqual([]);
   });
 
+  it('rethrows a child stream-limit trip instead of converting it to a tool result', async () => {
+    const executor = createExecutor({
+      createChildGraph: (): StandardGraph =>
+        ({
+          createWorkflow: (): { invoke: jest.Mock } => ({
+            invoke: jest.fn().mockRejectedValue(
+              new StreamLimitExceededError({
+                kind: 'tool_call_args',
+                limit: 10,
+                observed: 11,
+                toolName: 'db_query',
+              })
+            ),
+          }),
+          clearHeavyState: jest.fn(),
+        }) as unknown as StandardGraph,
+    });
+    await expect(
+      executor.execute({ description: 'Do something', subagentType: 'researcher' })
+    ).rejects.toBeInstanceOf(StreamLimitExceededError);
+  });
+
+  it('binds the child to the batch-captured controller, not the live scope', async () => {
+    const batchBreaker = new AbortController();
+    const liveBreaker = new AbortController();
+    const executor = createExecutor({
+      breakerScope: { controller: () => liveBreaker },
+      createChildGraph: (): StandardGraph =>
+        ({
+          createWorkflow: (): { invoke: jest.Mock } => ({
+            invoke: jest.fn().mockRejectedValue(
+              new StreamLimitExceededError({
+                kind: 'tool_call_args',
+                limit: 10,
+                observed: 11,
+                toolName: 'db_query',
+              })
+            ),
+          }),
+          clearHeavyState: jest.fn(),
+        }) as unknown as StandardGraph,
+    });
+
+    /** `breaker` is the controller the parent TOOL BATCH captured before
+     * PreToolUse hooks; a reset during those hooks replaced the live
+     * scope, and the child must not revive on — or trip — the new run's
+     * controller. */
+    await expect(
+      executor.execute({
+        description: 'Do something',
+        subagentType: 'researcher',
+        breaker: batchBreaker,
+      })
+    ).rejects.toBeInstanceOf(StreamLimitExceededError);
+    expect(batchBreaker.signal.aborted).toBe(true);
+    expect(liveBreaker.signal.aborted).toBe(false);
+  });
+
+  it('trips the breaker controller captured at execution start, not the current one', async () => {
+    const oldRun = new AbortController();
+    const newRun = new AbortController();
+    let current = oldRun;
+    let releaseChild: (() => void) | undefined;
+    const executor = createExecutor({
+      breakerScope: { controller: () => current },
+      createChildGraph: (): StandardGraph =>
+        ({
+          createWorkflow: (): { invoke: jest.Mock } => ({
+            invoke: jest.fn().mockImplementation(
+              () =>
+                new Promise((_resolve, reject) => {
+                  releaseChild = (): void =>
+                    reject(
+                      new StreamLimitExceededError({
+                        kind: 'tool_call_args',
+                        limit: 10,
+                        observed: 11,
+                        toolName: 'db_query',
+                      })
+                    );
+                })
+            ),
+          }),
+          clearHeavyState: jest.fn(),
+        }) as unknown as StandardGraph,
+    });
+
+    const pending = executor.execute({
+      description: 'Do something',
+      subagentType: 'researcher',
+    });
+    while (releaseChild == null) {
+      await new Promise((resolve) => setTimeout(resolve, 0));
+    }
+    /** The failed run's reset installs a fresh controller while the child
+     * is still settling; the straggler's trip must land on the controller
+     * captured when its execution started. */
+    current = newRun;
+    releaseChild();
+    await expect(pending).rejects.toBeInstanceOf(StreamLimitExceededError);
+    expect(oldRun.signal.aborted).toBe(true);
+    expect(newRun.signal.aborted).toBe(false);
+  });
+
+  it('threads run-level streamLimits into every child graph input', async () => {
+    const childGraphInputs: StandardGraphInput[] = [];
+    const noopFactory = makeNoopGraphFactory();
+    const executor = createExecutor({
+      streamLimits: { maxToolCallArgBytes: 1234, maxDeltaEventsPerTurn: 9 },
+      createChildGraph: (input: StandardGraphInput): StandardGraph => {
+        childGraphInputs.push(input);
+        return noopFactory();
+      },
+    });
+    await executor.execute({
+      description: 'Do something',
+      subagentType: 'researcher',
+    });
+    expect(childGraphInputs).toHaveLength(1);
+    expect(childGraphInputs[0].streamLimits).toEqual({
+      maxToolCallArgBytes: 1234,
+      maxDeltaEventsPerTurn: 9,
+    });
+  });
+
   it('executes child graph and returns filtered content', async () => {
     const { factory, clearHeavyState } = makeStubGraphFactory({
       messages: [

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];