@librechat/agents 3.1.95 → 3.1.97

package/src/specs/langfuse-config.test.ts

@@ -1,105 +1,104 @@
-import { LangfuseSpanProcessor } from '@langfuse/otel';
-import { BasicTracerProvider } from '@opentelemetry/sdk-trace-base';
-import { HumanMessage } from '@langchain/core/messages';
-import type { Serialized } from '@langchain/core/load/serializable';
-import { createLangfuseHandler } from '@/langfuse';
-
-const mockSpan = {
-  end: jest.fn(),
-  setAttributes: jest.fn(),
-  setStatus: jest.fn(),
-};
-const mockStartSpan = jest.fn(() => mockSpan);
-const mockGetTracer = jest.fn(() => ({
-  startSpan: mockStartSpan,
-}));
+import { CallbackHandler } from '@langfuse/langchain';
+import {
+  createLangfuseHandler,
+  hasLangfuseConfigCredentials,
+  shouldCreateLangfuseHandler,
+} from '@/langfuse';
 
-jest.mock('@langfuse/otel', () => ({
-  LangfuseSpanProcessor: jest.fn().mockImplementation(() => ({})),
-  isDefaultExportSpan: jest.fn(() => false),
+jest.mock('@langfuse/langchain', () => ({
+  CallbackHandler: jest.fn().mockImplementation((params) => ({ params })),
 }));
 
-jest.mock('@opentelemetry/sdk-trace-base', () => ({
-  BasicTracerProvider: jest.fn().mockImplementation(() => ({
-    forceFlush: jest.fn(),
-    getTracer: mockGetTracer,
-    shutdown: jest.fn(),
-  })),
-}));
+const MockedCallbackHandler = CallbackHandler as jest.MockedClass<
+  typeof CallbackHandler
+>;
 
 describe('createLangfuseHandler', () => {
+  const originalEnv = process.env;
+
   beforeEach(() => {
     jest.clearAllMocks();
+    process.env = { ...originalEnv };
+    delete process.env.LANGFUSE_PUBLIC_KEY;
+    delete process.env.LANGFUSE_SECRET_KEY;
+    delete process.env.LANGFUSE_BASE_URL;
+    delete process.env.LANGFUSE_BASEURL;
+  });
+
+  afterEach(() => {
+    process.env = originalEnv;
   });
 
-  it('creates a handler when keys are provided and baseUrl is omitted', () => {
+  it('creates the official Langfuse callback handler when env keys are present', () => {
+    process.env.LANGFUSE_PUBLIC_KEY = 'pk-env';
+    process.env.LANGFUSE_SECRET_KEY = 'sk-env';
+    process.env.LANGFUSE_BASE_URL = 'https://langfuse.env';
+
+    const handler = createLangfuseHandler({
+      userId: 'user-1',
+      sessionId: 'thread-1',
+      traceMetadata: {
+        messageId: 'message-1',
+        agentId: 'agent-1',
+        agentName: 'DWAINE',
+      },
+      tags: ['librechat', 'agent'],
+    });
+
+    expect(handler).toBeDefined();
+    expect(MockedCallbackHandler).toHaveBeenCalledWith({
+      userId: 'user-1',
+      sessionId: 'thread-1',
+      traceMetadata: {
+        messageId: 'message-1',
+        agentId: 'agent-1',
+        agentName: 'DWAINE',
+      },
+      tags: ['librechat', 'agent'],
+    });
+  });
+
+  it('creates a handler for explicit credentials supplied in config', () => {
     const handler = createLangfuseHandler({
       langfuse: {
-        enabled: true,
         publicKey: 'pk-test',
         secretKey: 'sk-test',
       },
     });
 
     expect(handler).toBeDefined();
-    expect(LangfuseSpanProcessor).toHaveBeenCalledWith(
-      expect.objectContaining({
-        publicKey: 'pk-test',
-        secretKey: 'sk-test',
-        exportMode: 'immediate',
-      })
-    );
-    expect(
-      (LangfuseSpanProcessor as jest.Mock).mock.calls[0][0].baseUrl
-    ).toBeUndefined();
-    expect(BasicTracerProvider).toHaveBeenCalledTimes(1);
+    expect(MockedCallbackHandler).toHaveBeenCalledTimes(1);
   });
 
-  it('starts per-agent spans with v5 trace attributes', async () => {
+  it('hydrates redaction-only config from env keys', () => {
+    process.env.LANGFUSE_PUBLIC_KEY = 'pk-env';
+    process.env.LANGFUSE_SECRET_KEY = 'sk-env';
+    process.env.LANGFUSE_BASE_URL = 'https://langfuse.env';
+
     const handler = createLangfuseHandler({
       langfuse: {
-        enabled: true,
+        toolOutputTracing: { enabled: false },
+      },
+    });
+
+    expect(handler).toBeDefined();
+    expect(MockedCallbackHandler).toHaveBeenCalledTimes(1);
+  });
+
+  it('does not create a handler when Langfuse is disabled', () => {
+    const handler = createLangfuseHandler({
+      langfuse: {
+        enabled: false,
         publicKey: 'pk-test',
         secretKey: 'sk-test',
       },
-      userId: 'user-1',
-      sessionId: 'thread-1',
-      traceMetadata: {
-        messageId: 'message-1',
-        agentId: 'agent-1',
-        agentName: 'DWAINE',
-      },
-      tags: ['librechat', 'agent'],
     });
 
-    await handler?.handleChatModelStart(
-      {
-        id: ['langchain', 'chat_models', 'ChatOpenAI'],
-        kwargs: { model: 'gpt-4o' },
-      } as unknown as Serialized,
-      [[new HumanMessage('hello')]],
-      'run-1'
-    );
-
-    expect(mockGetTracer).toHaveBeenCalledWith('langfuse-sdk');
-    expect(mockStartSpan).toHaveBeenCalledWith(
-      'gpt-4o',
-      expect.objectContaining({
-        attributes: expect.objectContaining({
-          'langfuse.trace.name': 'LibreChat Agent: DWAINE',
-          'langfuse.trace.metadata.agentId': 'agent-1',
-          'langfuse.trace.metadata.messageId': 'message-1',
-          'langfuse.observation.model.name': 'gpt-4o',
-          'langfuse.observation.type': 'generation',
-          'user.id': 'user-1',
-          'session.id': 'thread-1',
-          'langfuse.trace.tags': ['librechat', 'agent'],
-        }),
-      })
-    );
+    expect(handler).toBeUndefined();
+    expect(MockedCallbackHandler).not.toHaveBeenCalled();
   });
 
-  it('does not create a handler when a required key is missing', () => {
+  it('does not create a handler when credentials are unavailable', () => {
     const handler = createLangfuseHandler({
       langfuse: {
         enabled: true,
@@ -108,7 +107,44 @@ describe('createLangfuseHandler', () => {
     });
 
     expect(handler).toBeUndefined();
-    expect(LangfuseSpanProcessor).not.toHaveBeenCalled();
-    expect(BasicTracerProvider).not.toHaveBeenCalled();
+    expect(MockedCallbackHandler).not.toHaveBeenCalled();
+  });
+
+  it('detects complete config credentials', () => {
+    expect(
+      hasLangfuseConfigCredentials({
+        publicKey: 'pk-test',
+        secretKey: 'sk-test',
+      })
+    ).toBe(true);
+    expect(
+      hasLangfuseConfigCredentials({
+        publicKey: 'pk-test',
+      })
+    ).toBe(false);
+  });
+
+  it('uses env credentials for redaction-only configs', () => {
+    process.env.LANGFUSE_PUBLIC_KEY = 'pk-env';
+    process.env.LANGFUSE_SECRET_KEY = 'sk-env';
+    process.env.LANGFUSE_BASE_URL = 'https://langfuse.env';
+
+    expect(
+      shouldCreateLangfuseHandler({
+        toolOutputTracing: { enabled: false },
+      })
+    ).toBe(true);
+  });
+
+  it('uses env credentials with a config-provided baseUrl', () => {
+    process.env.LANGFUSE_PUBLIC_KEY = 'pk-env';
+    process.env.LANGFUSE_SECRET_KEY = 'sk-env';
+
+    expect(
+      shouldCreateLangfuseHandler({
+        baseUrl: 'https://langfuse.config',
+        toolOutputTracing: { enabled: false },
+      })
+    ).toBe(true);
   });
 });

package/src/specs/langfuse-instrumentation.test.ts

@@ -0,0 +1,283 @@
+const mockLangfuseSpanProcessorInstance = {};
+const mockLangfuseSpanProcessor = jest.fn(
+  () => mockLangfuseSpanProcessorInstance
+);
+const mockSetLangfuseTracerProvider = jest.fn();
+let mockContextHasActiveValue = false;
+const mockContextKey = Symbol('mock-context-key');
+const mockContextActive = jest.fn(() => ({
+  getValue: jest.fn(() => mockContextHasActiveValue),
+}));
+const mockContextWith = jest.fn(
+  (_contextValue: unknown, callback: () => boolean) => callback()
+);
+const mockSetGlobalContextManager = jest.fn(() => true);
+const mockRootContext = {
+  setValue: jest.fn(() => ({})),
+};
+const mockContextManager = {
+  disable: jest.fn(),
+  enable: jest.fn(),
+};
+const mockAsyncLocalStorageContextManager = jest.fn(() => mockContextManager);
+const mockTracerProvider = {
+  forceFlush: jest.fn(),
+  getTracer: jest.fn(),
+  shutdown: jest.fn(),
+};
+type BasicTracerProviderInput = {
+  spanProcessors: Array<{
+    forceFlush?: unknown;
+    onEnd?: unknown;
+    onStart?: unknown;
+    shutdown?: unknown;
+  }>;
+};
+type RoutingSpanProcessorForTest = BasicTracerProviderInput['spanProcessors'][0] & {
+  processors: Map<
+    string,
+    {
+      fallbackConfig?: {
+        enabled?: boolean;
+      };
+    }
+  >;
+};
+const mockBasicTracerProvider = jest.fn(
+  (_input?: BasicTracerProviderInput) => mockTracerProvider
+);
+
+jest.mock('@langfuse/otel', () => ({
+  LangfuseSpanProcessor: mockLangfuseSpanProcessor,
+  isDefaultExportSpan: jest.fn(() => false),
+}));
+
+jest.mock('@langfuse/tracing', () => ({
+  ...jest.requireActual('@langfuse/tracing'),
+  setLangfuseTracerProvider: mockSetLangfuseTracerProvider,
+}));
+
+jest.mock('@opentelemetry/api', () => ({
+  ...jest.requireActual('@opentelemetry/api'),
+  context: {
+    ...jest.requireActual('@opentelemetry/api').context,
+    active: mockContextActive,
+    setGlobalContextManager: mockSetGlobalContextManager,
+    with: mockContextWith,
+  },
+  createContextKey: jest.fn(() => mockContextKey),
+  ROOT_CONTEXT: mockRootContext,
+}));
+
+jest.mock('@opentelemetry/context-async-hooks', () => ({
+  AsyncLocalStorageContextManager: mockAsyncLocalStorageContextManager,
+}));
+
+jest.mock('@opentelemetry/sdk-trace-base', () => ({
+  BasicTracerProvider: mockBasicTracerProvider,
+  SpanStatusCode: jest.requireActual('@opentelemetry/api').SpanStatusCode,
+}));
+
+describe('Langfuse instrumentation', () => {
+  const originalEnv = process.env;
+
+  beforeEach(() => {
+    jest.resetModules();
+    jest.clearAllMocks();
+    mockContextHasActiveValue = false;
+    mockSetGlobalContextManager.mockReturnValue(true);
+    process.env = { ...originalEnv };
+    delete process.env.LANGFUSE_SECRET_KEY;
+    delete process.env.LANGFUSE_PUBLIC_KEY;
+    delete process.env.LANGFUSE_BASE_URL;
+    delete process.env.LANGFUSE_BASEURL;
+  });
+
+  afterEach(() => {
+    process.env = originalEnv;
+  });
+
+  it('does not initialize tracing when Langfuse env vars are missing', async () => {
+    const { initializeLangfuseTracingFromEnv } = await import(
+      '@/instrumentation'
+    );
+
+    expect(initializeLangfuseTracingFromEnv()).toBeUndefined();
+    expect(mockLangfuseSpanProcessor).not.toHaveBeenCalled();
+    expect(mockBasicTracerProvider).not.toHaveBeenCalled();
+    expect(mockAsyncLocalStorageContextManager).not.toHaveBeenCalled();
+    expect(mockSetLangfuseTracerProvider).not.toHaveBeenCalled();
+  });
+
+  it('registers an isolated Langfuse tracer provider from env config', async () => {
+    process.env.LANGFUSE_SECRET_KEY = 'sk-test';
+    process.env.LANGFUSE_PUBLIC_KEY = 'pk-test';
+    process.env.LANGFUSE_BASE_URL = 'https://langfuse.test';
+
+    const { initializeLangfuseTracingFromEnv } = await import(
+      '@/instrumentation'
+    );
+    const provider = initializeLangfuseTracingFromEnv();
+
+    expect(provider).toBe(mockTracerProvider);
+    expect(mockLangfuseSpanProcessor).toHaveBeenCalledTimes(1);
+    const providerInput = mockBasicTracerProvider.mock
+      .calls[0][0] as BasicTracerProviderInput;
+    expect(providerInput.spanProcessors).toHaveLength(1);
+    expect(providerInput.spanProcessors[0]).not.toBe(
+      mockLangfuseSpanProcessorInstance
+    );
+    expect(providerInput.spanProcessors[0]).toMatchObject({
+      forceFlush: expect.any(Function),
+      onEnd: expect.any(Function),
+      onStart: expect.any(Function),
+      shutdown: expect.any(Function),
+    });
+    expect(mockSetLangfuseTracerProvider).toHaveBeenCalledWith(
+      mockTracerProvider
+    );
+    expect(mockAsyncLocalStorageContextManager).toHaveBeenCalledTimes(1);
+    expect(mockContextManager.enable).toHaveBeenCalledTimes(1);
+    expect(mockSetGlobalContextManager).toHaveBeenCalledWith(
+      mockContextManager
+    );
+  });
+
+  it('registers tracing from explicit Langfuse config credentials', async () => {
+    const { initializeLangfuseTracing } = await import('@/instrumentation');
+    const provider = initializeLangfuseTracing({
+      publicKey: 'pk-config',
+      secretKey: 'sk-config',
+      baseUrl: 'https://langfuse.config',
+    });
+
+    expect(provider).toBe(mockTracerProvider);
+    expect(mockLangfuseSpanProcessor).toHaveBeenCalledWith(
+      expect.objectContaining({
+        publicKey: 'pk-config',
+        secretKey: 'sk-config',
+        baseUrl: 'https://langfuse.config',
+      })
+    );
+    expect(mockBasicTracerProvider).toHaveBeenCalledTimes(1);
+  });
+
+  it('uses env credentials with a config-provided Langfuse baseUrl', async () => {
+    process.env.LANGFUSE_SECRET_KEY = 'sk-env';
+    process.env.LANGFUSE_PUBLIC_KEY = 'pk-env';
+
+    const { initializeLangfuseTracing } = await import('@/instrumentation');
+    const provider = initializeLangfuseTracing({
+      baseUrl: 'https://langfuse.config',
+      toolOutputTracing: { enabled: false },
+    });
+
+    expect(provider).toBe(mockTracerProvider);
+    expect(mockLangfuseSpanProcessor).toHaveBeenCalledWith(
+      expect.objectContaining({
+        publicKey: 'pk-env',
+        secretKey: 'sk-env',
+        baseUrl: 'https://langfuse.config',
+      })
+    );
+    expect(mockBasicTracerProvider).toHaveBeenCalledTimes(1);
+  });
+
+  it('does not replace the global provider when explicit credentials change', async () => {
+    const { initializeLangfuseTracing } = await import('@/instrumentation');
+    initializeLangfuseTracing({
+      publicKey: 'pk-first',
+      secretKey: 'sk-first',
+      baseUrl: 'https://langfuse.first',
+    });
+    initializeLangfuseTracing({
+      publicKey: 'pk-second',
+      secretKey: 'sk-second',
+      baseUrl: 'https://langfuse.second',
+    });
+
+    expect(mockLangfuseSpanProcessor).toHaveBeenCalledTimes(2);
+    expect(mockLangfuseSpanProcessor).toHaveBeenNthCalledWith(
+      1,
+      expect.objectContaining({
+        publicKey: 'pk-first',
+        secretKey: 'sk-first',
+        baseUrl: 'https://langfuse.first',
+      })
+    );
+    expect(mockLangfuseSpanProcessor).toHaveBeenNthCalledWith(
+      2,
+      expect.objectContaining({
+        publicKey: 'pk-second',
+        secretKey: 'sk-second',
+        baseUrl: 'https://langfuse.second',
+      })
+    );
+    expect(mockBasicTracerProvider).toHaveBeenCalledTimes(1);
+    expect(mockSetLangfuseTracerProvider).toHaveBeenCalledTimes(1);
+  });
+
+  it('passes explicit redaction config into the redacting processor fallback', async () => {
+    const { initializeLangfuseTracing } = await import('@/instrumentation');
+    initializeLangfuseTracing({
+      publicKey: 'pk-config',
+      secretKey: 'sk-config',
+      baseUrl: 'https://langfuse.config',
+      toolOutputTracing: { enabled: false },
+    });
+
+    const providerInput = mockBasicTracerProvider.mock
+      .calls[0][0] as BasicTracerProviderInput;
+    const routingProcessor =
+      providerInput.spanProcessors[0] as RoutingSpanProcessorForTest;
+    const childProcessors = Array.from(routingProcessor.processors.values());
+    expect(childProcessors[0]?.fallbackConfig).toMatchObject({
+      enabled: false,
+    });
+  });
+
+  it('reuses the isolated provider after initialization', async () => {
+    process.env.LANGFUSE_SECRET_KEY = 'sk-test';
+    process.env.LANGFUSE_PUBLIC_KEY = 'pk-test';
+    process.env.LANGFUSE_BASE_URL = 'https://langfuse.test';
+
+    const { initializeLangfuseTracingFromEnv } = await import(
+      '@/instrumentation'
+    );
+    const firstProvider = initializeLangfuseTracingFromEnv();
+    const secondProvider = initializeLangfuseTracingFromEnv();
+
+    expect(firstProvider).toBe(mockTracerProvider);
+    expect(secondProvider).toBe(mockTracerProvider);
+    expect(mockLangfuseSpanProcessor).toHaveBeenCalledTimes(1);
+    expect(mockBasicTracerProvider).toHaveBeenCalledTimes(1);
+    expect(mockSetLangfuseTracerProvider).toHaveBeenCalledTimes(1);
+  });
+
+  it('does not replace an existing active context manager', async () => {
+    mockContextHasActiveValue = true;
+    process.env.LANGFUSE_SECRET_KEY = 'sk-test';
+    process.env.LANGFUSE_PUBLIC_KEY = 'pk-test';
+    process.env.LANGFUSE_BASE_URL = 'https://langfuse.test';
+
+    await import('@/instrumentation');
+
+    expect(mockAsyncLocalStorageContextManager).not.toHaveBeenCalled();
+    expect(mockSetGlobalContextManager).not.toHaveBeenCalled();
+  });
+
+  it('disables the local context manager when registration is rejected', async () => {
+    mockSetGlobalContextManager.mockReturnValue(false);
+    process.env.LANGFUSE_SECRET_KEY = 'sk-test';
+    process.env.LANGFUSE_PUBLIC_KEY = 'pk-test';
+    process.env.LANGFUSE_BASE_URL = 'https://langfuse.test';
+
+    await import('@/instrumentation');
+
+    expect(mockContextManager.enable).toHaveBeenCalledTimes(1);
+    expect(mockSetGlobalContextManager).toHaveBeenCalledWith(
+      mockContextManager
+    );
+    expect(mockContextManager.disable).toHaveBeenCalledTimes(1);
+  });
+});

package/src/specs/langfuse-metadata.test.ts

@@ -12,7 +12,8 @@ const MockedCallbackHandler = CallbackHandler as jest.MockedClass<
 
 async function createTestRun(
   agentName?: string,
-  agentOverrides: Record<string, unknown> = {}
+  agentOverrides: Record<string, unknown> = {},
+  runOverrides: Record<string, unknown> = {}
 ): Promise<Run<never>> {
   const run = await Run.create({
     runId: 'test-run-id',
@@ -29,6 +30,7 @@ async function createTestRun(
         },
       ],
     },
+    ...runOverrides,
   });
 
   const emptyStream = (async function* (): AsyncGenerator {
@@ -106,4 +108,55 @@ describe('Langfuse trace metadata includes agentName', () => {
 
     expect(MockedCallbackHandler).not.toHaveBeenCalled();
   });
+
+  it('uses the nested Langfuse CallbackHandler for redaction-only agent config', async () => {
+    const run = await createTestRun('DWAINE', {
+      langfuse: {
+        toolOutputTracing: { enabled: false },
+      },
+    });
+    await run.processStream(
+      { messages: [] },
+      { configurable: { thread_id: 't1', user_id: 'u1' }, version: 'v2' }
+    );
+
+    expect(MockedCallbackHandler).toHaveBeenCalledTimes(1);
+  });
+
+  it('uses the nested Langfuse CallbackHandler for redaction-only run config', async () => {
+    const run = await createTestRun(
+      'DWAINE',
+      {},
+      {
+        langfuse: {
+          toolOutputTracing: { enabled: false },
+        },
+      }
+    );
+    await run.processStream(
+      { messages: [] },
+      { configurable: { thread_id: 't1', user_id: 'u1' }, version: 'v2' }
+    );
+
+    expect(MockedCallbackHandler).toHaveBeenCalledTimes(1);
+  });
+
+  it('preserves run-level Langfuse config after graph cleanup for later turns', async () => {
+    const langfuse = {
+      toolOutputTracing: { enabled: false },
+    };
+    const run = await createTestRun(
+      'DWAINE',
+      {},
+      {
+        langfuse,
+      }
+    );
+    await run.processStream(
+      { messages: [] },
+      { configurable: { thread_id: 't1', user_id: 'u1' }, version: 'v2' }
+    );
+
+    expect(run.Graph?.langfuse).toBe(langfuse);
+  });
 });