@librechat/agents 3.2.57 → 3.2.58

package/src/specs/langfuse-trace-shaping.test.ts

@@ -0,0 +1,194 @@
+import { LangfuseOtelSpanAttributes } from '@langfuse/tracing';
+import type { ReadableSpan } from '@opentelemetry/sdk-trace-base';
+import {
+  shapeLangfuseSpan,
+  shouldDropLangfuseSpan,
+} from '@/langfuseTraceShaping';
+
+type TestSpan = ReadableSpan & {
+  name: string;
+  attributes: Record<string, unknown>;
+};
+
+function createSpan(
+  name: string,
+  attributes: Record<string, unknown> = {},
+  parentSpanId?: string
+): TestSpan {
+  return {
+    name,
+    attributes,
+    ...(parentSpanId != null ? { parentSpanId } : {}),
+  } as unknown as TestSpan;
+}
+
+const INPUT = LangfuseOtelSpanAttributes.OBSERVATION_INPUT;
+const OUTPUT = LangfuseOtelSpanAttributes.OBSERVATION_OUTPUT;
+const TRACE_INPUT = LangfuseOtelSpanAttributes.TRACE_INPUT;
+const TRACE_OUTPUT = LangfuseOtelSpanAttributes.TRACE_OUTPUT;
+
+describe('shouldDropLangfuseSpan', () => {
+  it('drops langgraph __start__ seed spans', () => {
+    expect(shouldDropLangfuseSpan('__start__')).toBe(true);
+  });
+
+  it('drops anonymous RunnableLambda pass-throughs', () => {
+    expect(shouldDropLangfuseSpan('RunnableLambda')).toBe(true);
+  });
+
+  it('keeps named observations', () => {
+    expect(shouldDropLangfuseSpan('GenerateTitle')).toBe(false);
+    expect(shouldDropLangfuseSpan('agent=openAI__gpt-5.4')).toBe(false);
+    expect(shouldDropLangfuseSpan('ChatOpenAI')).toBe(false);
+  });
+});
+
+describe('shapeLangfuseSpan', () => {
+  it('strips the ephemeral agent id (provider__model) from agent node names', () => {
+    const span = createSpan('agent=openAI__gpt-5.4', {}, 'parent-1');
+    shapeLangfuseSpan(span);
+    expect(span.name).toBe('agent');
+  });
+
+  it('renames tool node spans to the pending tool names and scopes input to args', () => {
+    const messages = [
+      { type: 'human', content: 'hello' },
+      {
+        type: 'ai',
+        content: '',
+        tool_calls: [
+          {
+            name: 'get_service_details',
+            args: { path: 'organizations/1' },
+            id: 'call_1',
+          },
+        ],
+      },
+    ];
+    const span = createSpan(
+      'tools=openAI__gpt-5.4',
+      { [INPUT]: JSON.stringify({ messages }) },
+      'parent-1'
+    );
+    shapeLangfuseSpan(span);
+    expect(span.name).toBe('get_service_details');
+    expect(JSON.parse(span.attributes[INPUT] as string)).toEqual([
+      { name: 'get_service_details', args: { path: 'organizations/1' } },
+    ]);
+  });
+
+  it('joins multiple pending tool names and dedupes repeats', () => {
+    const messages = [
+      {
+        type: 'ai',
+        tool_calls: [
+          { name: 'web_search', args: { q: 'a' }, id: '1' },
+          { name: 'web_search', args: { q: 'b' }, id: '2' },
+          { name: 'execute_code', args: { code: '1+1' }, id: '3' },
+        ],
+      },
+    ];
+    const span = createSpan(
+      'tool_batch',
+      { [INPUT]: JSON.stringify({ messages }) },
+      'parent-1'
+    );
+    shapeLangfuseSpan(span);
+    expect(span.name).toBe('web_search, execute_code');
+  });
+
+  it('reads tool calls from serialized langchain message kwargs', () => {
+    const messages = [
+      {
+        lc: 1,
+        type: 'constructor',
+        id: ['langchain_core', 'messages', 'AIMessage'],
+        kwargs: {
+          content: '',
+          tool_calls: [{ name: 'lookup', args: { id: 7 }, id: 'call_7' }],
+        },
+      },
+    ];
+    const span = createSpan(
+      'tools=agent_abc',
+      { [INPUT]: JSON.stringify({ messages }) },
+      'parent-1'
+    );
+    shapeLangfuseSpan(span);
+    expect(span.name).toBe('lookup');
+  });
+
+  it('leaves tool node spans untouched when no tool calls are found', () => {
+    const original = JSON.stringify({
+      messages: [{ type: 'human', content: 'hi' }],
+    });
+    const span = createSpan(
+      'tools=agent_abc',
+      { [INPUT]: original },
+      'parent-1'
+    );
+    shapeLangfuseSpan(span);
+    expect(span.name).toBe('tools=agent_abc');
+    expect(span.attributes[INPUT]).toBe(original);
+  });
+
+  it('sets root span and trace input/output to the question and answer', () => {
+    const span = createSpan('LibreChat Agent', {
+      [INPUT]: JSON.stringify({
+        messages: [
+          { type: 'system', content: 'You are helpful.' },
+          { type: 'human', content: 'What is ClickHouse?' },
+        ],
+      }),
+      [OUTPUT]: JSON.stringify({
+        messages: [
+          { type: 'human', content: 'What is ClickHouse?' },
+          { type: 'ai', content: 'A columnar OLAP database.' },
+        ],
+      }),
+    });
+    shapeLangfuseSpan(span);
+    expect(span.attributes[INPUT]).toBe('What is ClickHouse?');
+    expect(span.attributes[TRACE_INPUT]).toBe('What is ClickHouse?');
+    expect(span.attributes[OUTPUT]).toBe('A columnar OLAP database.');
+    expect(span.attributes[TRACE_OUTPUT]).toBe('A columnar OLAP database.');
+  });
+
+  it('extracts answer text from content part arrays', () => {
+    const span = createSpan('LibreChat Agent', {
+      [INPUT]: JSON.stringify([{ type: 'human', content: 'hi' }]),
+      [OUTPUT]: JSON.stringify({
+        messages: [
+          {
+            id: ['langchain_core', 'messages', 'AIMessage'],
+            kwargs: {
+              content: [
+                { type: 'text', text: 'Hello ' },
+                { type: 'text', text: 'there.' },
+              ],
+            },
+          },
+        ],
+      }),
+    });
+    shapeLangfuseSpan(span);
+    expect(span.attributes[INPUT]).toBe('hi');
+    expect(span.attributes[OUTPUT]).toBe('Hello there.');
+  });
+
+  it('does not rewrite non-root spans with message payloads', () => {
+    const original = JSON.stringify({
+      messages: [{ type: 'human', content: 'hi' }],
+    });
+    const span = createSpan('ChatOpenAI', { [INPUT]: original }, 'parent-1');
+    shapeLangfuseSpan(span);
+    expect(span.attributes[INPUT]).toBe(original);
+  });
+
+  it('preserves root attributes when extraction finds nothing', () => {
+    const span = createSpan('LibreChat Agent', { [INPUT]: 'plain text' });
+    shapeLangfuseSpan(span);
+    expect(span.attributes[INPUT]).toBe('plain text');
+    expect(span.attributes[TRACE_INPUT]).toBeUndefined();
+  });
+});

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__/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/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 };
+};