@librechat/agents 3.2.57 → 3.2.59

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

@@ -292,6 +292,50 @@ describe('buildChildInputs', () => {
     expect(result.toolDefinitions).toBeUndefined();
   });
 
+  it('scrubs INHERITED graphTools on self-spawn (parent-spread config) but keeps an explicit child config’s own', () => {
+    const askLikeTool = { name: 'ask_user_question' } as unknown as NonNullable<
+      AgentInputs['graphTools']
+    >[number];
+    const inputsWithGraphTools: AgentInputs = {
+      ...parentAgentInputs,
+      graphTools: [askLikeTool],
+    };
+
+    /**
+     * Self-spawn: `resolveSubagentConfigs` fills `agentInputs` as a shallow
+     * spread of the parent's `_sourceInputs`, so the parent-scoped direct
+     * tool would leak into a checkpointer-less child graph and fail with
+     * `No checkpointer set` — must be scrubbed.
+     */
+    const selfConfig: ResolvedSubagentConfig = {
+      type: 'self',
+      name: 'Self',
+      description: 'd',
+      self: true,
+      agentInputs: { ...inputsWithGraphTools },
+    };
+    expect(
+      buildChildInputs(selfConfig, 'child-self', 3).graphTools
+    ).toBeUndefined();
+
+    /**
+     * Explicit child config: a host that deliberately attaches its own
+     * in-process direct tools to a child keeps them (Codex #289 P2 —
+     * interrupt-capable tools still fail in children, but non-interrupting
+     * direct tools are legitimate there).
+     */
+    const explicitConfig: ResolvedSubagentConfig = {
+      type: 'researcher',
+      name: 'R',
+      description: 'd',
+      agentInputs: inputsWithGraphTools,
+    };
+    expect(
+      buildChildInputs(explicitConfig, 'child-explicit', 3).graphTools
+    ).toEqual([askLikeTool]);
+    expect(inputsWithGraphTools.graphTools).toHaveLength(1); // parent untouched
+  });
+
   it('strips parent-run-scoped initialSummary and discoveredTools from child inputs', () => {
     /**
      * Codex P1: a child inheriting `initialSummary` or `discoveredTools` from

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

@@ -1263,4 +1263,90 @@ describe('ToolNode code execution session management', () => {
       );
     });
   });
+
+  describe('stateful runtime session hint injection', () => {
+    it('injects the explicit runtimeSessionHint when statefulSessions is on', async () => {
+      const capturedConfigs: Record<string, unknown>[] = [];
+      const mockTool = createMockCodeTool({ capturedConfigs });
+      const toolNode = new ToolNode({
+        tools: [mockTool],
+        sessions: new Map(),
+        toolExecution: {
+          engine: 'sandbox',
+          sandbox: {
+            statefulSessions: true,
+            runtimeSessionHint: 'conv-explicit',
+          },
+        },
+      });
+
+      await toolNode.invoke({ messages: [createAIMessageWithCodeCall('c1')] });
+
+      expect(capturedConfigs[0]._runtime_session_hint).toBe('conv-explicit');
+    });
+
+    it('falls back to configurable.thread_id when no explicit hint is given', async () => {
+      const capturedConfigs: Record<string, unknown>[] = [];
+      const mockTool = createMockCodeTool({ capturedConfigs });
+      const toolNode = new ToolNode({
+        tools: [mockTool],
+        sessions: new Map(),
+        toolExecution: {
+          engine: 'sandbox',
+          sandbox: { statefulSessions: true },
+        },
+      });
+
+      await toolNode.invoke(
+        { messages: [createAIMessageWithCodeCall('c1')] },
+        { configurable: { thread_id: 'thread-abc' } }
+      );
+
+      expect(capturedConfigs[0]._runtime_session_hint).toBe('thread-abc');
+    });
+
+    it('does not inject a hint when statefulSessions is off', async () => {
+      const capturedConfigs: Record<string, unknown>[] = [];
+      const mockTool = createMockCodeTool({ capturedConfigs });
+      const toolNode = new ToolNode({
+        tools: [mockTool],
+        sessions: new Map(),
+        toolExecution: {
+          engine: 'sandbox',
+          sandbox: { statefulSessions: false },
+        },
+      });
+
+      await toolNode.invoke(
+        { messages: [createAIMessageWithCodeCall('c1')] },
+        { configurable: { thread_id: 'thread-abc' } }
+      );
+
+      expect(capturedConfigs[0]._runtime_session_hint).toBeUndefined();
+    });
+
+    it('injects the hint independently of an existing exec session', async () => {
+      const capturedConfigs: Record<string, unknown>[] = [];
+      const sessions: t.ToolSessionMap = new Map();
+      sessions.set(Constants.EXECUTE_CODE, {
+        session_id: 'exec-1',
+        files: [],
+        lastUpdated: 0,
+      });
+      const mockTool = createMockCodeTool({ capturedConfigs });
+      const toolNode = new ToolNode({
+        tools: [mockTool],
+        sessions,
+        toolExecution: {
+          engine: 'sandbox',
+          sandbox: { statefulSessions: true, runtimeSessionHint: 'conv-1' },
+        },
+      });
+
+      await toolNode.invoke({ messages: [createAIMessageWithCodeCall('c1')] });
+
+      expect(capturedConfigs[0].session_id).toBe('exec-1');
+      expect(capturedConfigs[0]._runtime_session_hint).toBe('conv-1');
+    });
+  });
 });

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

@@ -0,0 +1,92 @@
+import { describe, it, expect } from '@jest/globals';
+import type * as t from '@/types';
+import {
+  buildToolExecutionRequestPlan,
+  resolveRuntimeSessionHint,
+} from '../eagerEventExecution';
+
+describe('buildToolExecutionRequestPlan — runtimeSessionHint', () => {
+  const usageCount = () => new Map<string, number>();
+
+  it('carries runtimeSessionHint onto the built ToolCallRequest', () => {
+    const plan = buildToolExecutionRequestPlan({
+      toolCalls: [
+        {
+          id: 'call_1',
+          name: 'execute_code',
+          args: { lang: 'py', code: 'print(1)' },
+          runtimeSessionHint: 'conv-42',
+        },
+      ],
+      usageCount: usageCount(),
+    });
+    expect(plan?.requests[0].runtimeSessionHint).toBe('conv-42');
+  });
+
+  it('omits the field entirely when the hint is absent or empty', () => {
+    const plan = buildToolExecutionRequestPlan({
+      toolCalls: [{ id: 'c1', name: 'execute_code', args: {} }],
+      usageCount: usageCount(),
+    });
+    expect('runtimeSessionHint' in (plan?.requests[0] as object)).toBe(false);
+
+    const empty = buildToolExecutionRequestPlan({
+      toolCalls: [
+        { id: 'c2', name: 'execute_code', args: {}, runtimeSessionHint: '' },
+      ],
+      usageCount: usageCount(),
+    });
+    expect('runtimeSessionHint' in (empty?.requests[0] as object)).toBe(false);
+  });
+
+  it('carries the hint onto invalid-arg (rejected) requests too', () => {
+    const plan = buildToolExecutionRequestPlan({
+      toolCalls: [
+        {
+          id: 'c1',
+          name: 'execute_code',
+          args: 'not-an-object',
+          runtimeSessionHint: 'conv-9',
+        },
+      ],
+      usageCount: usageCount(),
+      invalidArgsBehavior: 'error-result',
+    });
+    expect(plan?.allRequests[0].runtimeSessionHint).toBe('conv-9');
+    expect(plan?.rejectedResults).toHaveLength(1);
+  });
+});
+
+describe('resolveRuntimeSessionHint', () => {
+  const sandbox = (
+    o: Partial<t.SandboxExecutionConfig>
+  ): t.ToolExecutionConfig => ({
+    sandbox: o,
+  });
+
+  it('returns undefined unless statefulSessions is on', () => {
+    expect(resolveRuntimeSessionHint(undefined, 'thread-1')).toBeUndefined();
+    expect(resolveRuntimeSessionHint(sandbox({}), 'thread-1')).toBeUndefined();
+    expect(
+      resolveRuntimeSessionHint(
+        sandbox({ statefulSessions: false }),
+        'thread-1'
+      )
+    ).toBeUndefined();
+  });
+
+  it('prefers an explicit hint, else falls back to thread_id', () => {
+    expect(
+      resolveRuntimeSessionHint(
+        sandbox({ statefulSessions: true, runtimeSessionHint: 'explicit' }),
+        'thread-1'
+      )
+    ).toBe('explicit');
+    expect(
+      resolveRuntimeSessionHint(sandbox({ statefulSessions: true }), 'thread-1')
+    ).toBe('thread-1');
+    expect(
+      resolveRuntimeSessionHint(sandbox({ statefulSessions: true }), '')
+    ).toBeUndefined();
+  });
+});

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

@@ -3996,6 +3996,91 @@ describe('AskUserQuestion — interrupt + resume', () => {
     expect(resumedAnswer).toBe('production');
   });
 
+  it('a DIRECT tool in event-driven mode can raise ask_user_question from its body and resume with the answer as its ToolMessage', async () => {
+    /**
+     * The production host shape (e.g. LibreChat's `AgentInputs.graphTools`
+     * plumb): the run is event-driven (other tools are schema-only
+     * definitions dispatched to the host), but an interrupt-capable tool is
+     * supplied as a real instance and marked direct so it executes inside
+     * the Pregel task frame. Event dispatch must never see the call — a
+     * host-side handler runs outside the graph, where `interrupt()` throws.
+     */
+    const { askUserQuestion } = await import('@/hitl');
+
+    const dispatchSpy = jest
+      .spyOn(events, 'safeDispatchCustomEvent')
+      .mockImplementation(async () => {});
+
+    let bodyRuns = 0;
+    const askTool = tool(
+      async (input: { question: string }) => {
+        bodyRuns += 1;
+        const resolution = askUserQuestion(input);
+        return resolution.answer;
+      },
+      {
+        name: 'ask_user_question',
+        description: 'Ask the user a clarifying question.',
+        schema: z.object({ question: z.string() }),
+      }
+    ) as unknown as StructuredToolInterface;
+
+    const node = new ToolNode({
+      tools: [createSchemaStub('echo'), askTool],
+      toolMap: new Map([
+        ['echo', createSchemaStub('echo')],
+        ['ask_user_question', askTool],
+      ]),
+      eventDrivenMode: true,
+      agentId: 'agent-ask-direct',
+      toolCallStepIds: new Map([['call_ask_1', 'step_call_ask_1']]),
+      directToolNames: new Set(['ask_user_question']),
+    });
+
+    const graph = buildHITLGraph(node, [
+      {
+        id: 'call_ask_1',
+        name: 'ask_user_question',
+        args: { question: 'Which environment?' },
+      },
+    ]);
+    const config = { configurable: { thread_id: 'thread-ask-direct' } };
+
+    const interrupted = await graph.invoke({ messages: [] }, config);
+    expect(isInterrupted<t.HumanInterruptPayload>(interrupted)).toBe(true);
+    if (!isInterrupted<t.HumanInterruptPayload>(interrupted)) {
+      throw new Error('expected interrupt');
+    }
+    const payload = interrupted.__interrupt__[0].value!;
+    if (payload.type !== 'ask_user_question') {
+      throw new Error('expected ask_user_question payload');
+    }
+    expect(payload.question.question).toBe('Which environment?');
+    expect(bodyRuns).toBe(1);
+
+    /** The interrupt came from the direct path — never dispatched to the host. */
+    const toolExecuteDispatches = dispatchSpy.mock.calls.filter(
+      ([event]) => event === 'on_tool_execute'
+    );
+    expect(toolExecuteDispatches).toHaveLength(0);
+
+    const resumed = (await resumeGraph(
+      graph,
+      interrupted,
+      { answer: 'staging' } satisfies t.AskUserQuestionResolution,
+      config
+    )) as MessagesUpdate;
+
+    expect(bodyRuns).toBe(2); // body re-runs from the top on the resume pass
+    const toolMessage = resumed.messages.find(
+      (m): m is ToolMessage =>
+        m._getType() === 'tool' &&
+        (m as ToolMessage).tool_call_id === 'call_ask_1'
+    );
+    expect(toolMessage).toBeDefined();
+    expect(String(toolMessage!.content)).toBe('staging');
+  });
+
   it('isAskUserQuestionInterrupt narrows the payload union correctly', async () => {
     const { isAskUserQuestionInterrupt, isToolApprovalInterrupt } =
       await import('@/types/hitl');

package/src/tools/eagerEventExecution.ts

@@ -52,8 +52,30 @@ export type ToolExecutionPlanCall = {
   args: unknown;
   stepId?: string;
   codeSessionContext?: t.ToolCallRequest['codeSessionContext'];
+  runtimeSessionHint?: string;
 };
 
+/**
+ * Stateful runtime session hint for the remote sandbox: only when
+ * `toolExecution.sandbox.statefulSessions` is on; explicit host hint else the
+ * conversation `thread_id`. Undefined disables the wire field. Shared by the
+ * direct ToolNode path and both event-driven planners so they stay in lockstep.
+ */
+export function resolveRuntimeSessionHint(
+  toolExecution: t.ToolExecutionConfig | undefined,
+  threadId: string | undefined
+): string | undefined {
+  const sandbox = toolExecution?.sandbox;
+  if (sandbox?.statefulSessions !== true) {
+    return undefined;
+  }
+  const explicit = sandbox.runtimeSessionHint;
+  if (explicit != null && explicit !== '') {
+    return explicit;
+  }
+  return threadId != null && threadId !== '' ? threadId : undefined;
+}
+
 export type ToolExecutionRequestPlan = {
   allRequests: t.ToolCallRequest[];
   requests: t.ToolCallRequest[];
@@ -73,15 +95,12 @@ export function buildToolExecutionRequestPlan(args: {
     args: Record<string, unknown>;
     stepId?: string;
     codeSessionContext?: t.ToolCallRequest['codeSessionContext'];
+    runtimeSessionHint?: string;
     rejectedErrorMessage?: string;
   }> = [];
 
   for (const toolCall of args.toolCalls) {
-    if (
-      toolCall.id == null ||
-      toolCall.id === '' ||
-      toolCall.name === ''
-    ) {
+    if (toolCall.id == null || toolCall.id === '' || toolCall.name === '') {
       return undefined;
     }
     const coercedArgs = coerceRecordArgs(toolCall.args);
@@ -95,6 +114,7 @@ export function buildToolExecutionRequestPlan(args: {
         args: {},
         stepId: toolCall.stepId,
         codeSessionContext: toolCall.codeSessionContext,
+        runtimeSessionHint: toolCall.runtimeSessionHint,
         rejectedErrorMessage:
           'Invalid tool call arguments: expected a JSON object.',
       });
@@ -106,6 +126,7 @@ export function buildToolExecutionRequestPlan(args: {
       args: coercedArgs,
       stepId: toolCall.stepId,
       codeSessionContext: toolCall.codeSessionContext,
+      runtimeSessionHint: toolCall.runtimeSessionHint,
     });
   }
 
@@ -123,6 +144,12 @@ export function buildToolExecutionRequestPlan(args: {
     if (toolCall.codeSessionContext != null) {
       request.codeSessionContext = toolCall.codeSessionContext;
     }
+    if (
+      toolCall.runtimeSessionHint != null &&
+      toolCall.runtimeSessionHint !== ''
+    ) {
+      request.runtimeSessionHint = toolCall.runtimeSessionHint;
+    }
     return request;
   });
   const requests = allRequests.filter(

package/src/tools/search/jina-reranker.test.ts

@@ -150,7 +150,8 @@ describe('JinaReranker', () => {
     });
 
     it('should log compact Axios errors without request internals', async () => {
-      const customUrl = 'https://test-jina-endpoint.com/v1/rerank?api_key=hidden';
+      const customUrl =
+        'https://test-jina-endpoint.com/v1/rerank?api_key=hidden';
       const reranker = new JinaReranker({
         apiKey: 'test-key',
         apiUrl: customUrl,
@@ -201,6 +202,49 @@ describe('JinaReranker', () => {
       expect(serializedMetadata).not.toContain('test-key');
       expect(serializedMetadata.length).toBeLessThan(500);
     });
+
+    it('should bound the rerank request with the default timeout', async () => {
+      const customUrl = 'https://test-jina-endpoint.com/v1/rerank';
+      const reranker = new JinaReranker({
+        apiKey: 'test-key',
+        apiUrl: customUrl,
+        logger: mockLogger,
+      });
+      jest.spyOn(mockLogger, 'debug').mockImplementation(() => mockLogger);
+      const postSpy = jest.spyOn(axios, 'post').mockResolvedValueOnce({
+        data: { results: [{ index: 0, relevance_score: 0.9 }] },
+      });
+
+      await reranker.rerank('test query', ['document1'], 1);
+
+      expect(postSpy).toHaveBeenCalledWith(
+        customUrl,
+        expect.any(Object),
+        expect.objectContaining({ timeout: 10000 })
+      );
+    });
+
+    it('should bound the rerank request with a custom timeout', async () => {
+      const customUrl = 'https://test-jina-endpoint.com/v1/rerank';
+      const reranker = new JinaReranker({
+        apiKey: 'test-key',
+        apiUrl: customUrl,
+        timeout: 2500,
+        logger: mockLogger,
+      });
+      jest.spyOn(mockLogger, 'debug').mockImplementation(() => mockLogger);
+      const postSpy = jest.spyOn(axios, 'post').mockResolvedValueOnce({
+        data: { results: [{ index: 0, relevance_score: 0.9 }] },
+      });
+
+      await reranker.rerank('test query', ['document1'], 1);
+
+      expect(postSpy).toHaveBeenCalledWith(
+        customUrl,
+        expect.any(Object),
+        expect.objectContaining({ timeout: 2500 })
+      );
+    });
   });
 });
 
@@ -234,4 +278,29 @@ describe('createReranker', () => {
     const apiUrl = getApiUrl(reranker);
     expect(apiUrl).toBe('https://api.jina.ai/v1/rerank');
   });
+
+  it('should pass rerankerTimeout through to the rerank request', async () => {
+    const customUrl = 'https://custom-jina-endpoint.com/v1/rerank';
+    const reranker = createReranker({
+      rerankerType: 'jina',
+      jinaApiKey: 'test-key',
+      jinaApiUrl: customUrl,
+      rerankerTimeout: 4000,
+      logger: createDefaultLogger(),
+    });
+    if (!(reranker instanceof JinaReranker)) {
+      throw new Error('Expected createReranker to return a JinaReranker.');
+    }
+    const postSpy = jest.spyOn(axios, 'post').mockResolvedValueOnce({
+      data: { results: [{ index: 0, relevance_score: 0.9 }] },
+    });
+
+    await reranker.rerank('test query', ['document1'], 1);
+
+    expect(postSpy).toHaveBeenCalledWith(
+      customUrl,
+      expect.any(Object),
+      expect.objectContaining({ timeout: 4000 })
+    );
+  });
 });

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

@@ -0,0 +1,98 @@
+import axios from 'axios';
+import type * as t from './types';
+import { DATE_RANGE } from './schema';
+
+const DEFAULT_KEENABLE_TIMEOUT = 15000;
+
+/** Authenticated and keyless endpoints. Keenable works without an API key by
+ * falling back to the public endpoint; a key only lifts rate limits. */
+const KEENABLE_DEFAULT_API_URL = 'https://api.keenable.ai/v1/search';
+const KEENABLE_PUBLIC_API_URL = 'https://api.keenable.ai/v1/search/public';
+const KEENABLE_DATE_RANGES: Record<DATE_RANGE, string> = {
+  [DATE_RANGE.PAST_HOUR]: '1h',
+  [DATE_RANGE.PAST_24_HOURS]: '1d',
+  [DATE_RANGE.PAST_WEEK]: '7d',
+  [DATE_RANGE.PAST_MONTH]: '1mo',
+  [DATE_RANGE.PAST_YEAR]: '1y',
+};
+
+export const createKeenableAPI = (
+  apiKey?: string,
+  apiUrl?: string,
+  options?: t.KeenableSearchOptions
+): {
+  getSources: (params: t.GetSourcesParams) => Promise<t.SearchResult>;
+} => {
+  const resolvedKey = apiKey ?? process.env.KEENABLE_API_KEY;
+  const hasKey = resolvedKey != null && resolvedKey !== '';
+  const timeout = options?.timeout ?? DEFAULT_KEENABLE_TIMEOUT;
+  const resolvedUrl =
+    apiUrl ??
+    process.env.KEENABLE_API_URL ??
+    (hasKey ? KEENABLE_DEFAULT_API_URL : KEENABLE_PUBLIC_API_URL);
+
+  /** Constant for the provider's lifetime. X-Keenable-Title is required for
+   * keyless requests and used for traffic attribution; the API key only lifts
+   * rate limits, so it is sent only when present. */
+  const headers: Record<string, string> = {
+    'Content-Type': 'application/json',
+    'X-Keenable-Title': options?.attributionTitle ?? 'LibreChat',
+  };
+  if (hasKey) {
+    headers['X-API-Key'] = resolvedKey;
+  }
+
+  const getSources = async ({
+    query,
+    date,
+    numResults = 8,
+  }: t.GetSourcesParams): Promise<t.SearchResult> => {
+    if (!query.trim()) {
+      return { success: false, error: 'Query cannot be empty' };
+    }
+
+    try {
+      /** Keenable's endpoint has no result-count parameter; the count is
+       * applied client-side after the response (see slice below). */
+      const payload: t.KeenableSearchPayload = { query };
+      if (options?.site != null && options.site !== '') {
+        payload.site = options.site;
+      }
+      if (date != null) {
+        payload.published_after = KEENABLE_DATE_RANGES[date];
+      }
+
+      const response = await axios.post<t.KeenableSearchResponse>(
+        resolvedUrl,
+        payload,
+        { headers, timeout }
+      );
+
+      const maxResults = Math.min(
+        Math.max(1, options?.maxResults ?? numResults),
+        20
+      );
+      const rawResults = Array.isArray(response.data.results)
+        ? response.data.results.slice(0, maxResults)
+        : [];
+
+      const organic: t.OrganicResult[] = rawResults.map((result) => ({
+        title: result.title ?? '',
+        link: result.url ?? '',
+        snippet: result.description ?? result.snippet ?? '',
+        date: result.published_at,
+      }));
+
+      return { success: true, data: { organic } };
+    } catch (error) {
+      const errorMessage =
+        error instanceof Error ? error.message : String(error);
+      return {
+        success: false,
+        error: `Keenable API request failed: ${errorMessage}`,
+      };
+    }
+  };
+
+  return { getSources };
+};