@librechat/agents 3.2.44 → 3.2.45

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

@@ -1,50 +1,109 @@
 import { HumanMessage } from '@langchain/core/messages';
 import { CallbackManager } from '@langchain/core/callbacks/manager';
+import { context as otelContext, trace as otelTrace } from '@opentelemetry/api';
 import type * as t from '@/types';
+import { traceIdFromSeed } from '@/langfuseRuntimeContext';
 import { Providers } from '@/common';
 import { Run } from '@/run';
 
-const mockSpan = {
-  end: jest.fn(),
-  spanContext: jest.fn(() => ({
-    traceId: 'trace-id',
-    spanId: 'span-id',
-    traceFlags: 1,
-  })),
-  setAttributes: jest.fn(),
-  setStatus: jest.fn(),
+const mockProcessorStarts: Array<{
+  params: unknown;
+  traceId: string;
+}> = [];
+const mockSpanAttributeSets: Array<Record<string, unknown>> = [];
+let mockProviderInput:
+  | {
+      spanProcessors?: Array<{
+        onStart?: (span: unknown, parentContext: unknown) => void;
+        onEnd?: (span: unknown) => void;
+      }>;
+      idGenerator?: {
+        generateTraceId: () => string;
+        generateSpanId: () => string;
+      };
+    }
+  | undefined;
+
+const createMockSpan = (traceIdOverride?: string) => {
+  const traceId =
+    traceIdOverride ??
+    mockProviderInput?.idGenerator?.generateTraceId() ??
+    'trace-id';
+  const spanId = mockProviderInput?.idGenerator?.generateSpanId() ?? 'span-id';
+  const span = {
+    end: jest.fn(() => {
+      for (const processor of mockProviderInput?.spanProcessors ?? []) {
+        processor.onEnd?.(span);
+      }
+    }),
+    spanContext: jest.fn(() => ({
+      traceId,
+      spanId,
+      traceFlags: 1,
+    })),
+    setAttributes: jest.fn((attributes: Record<string, unknown>) => {
+      mockSpanAttributeSets.push(attributes);
+    }),
+    setStatus: jest.fn(),
+    attributes: {},
+  };
+  for (const processor of mockProviderInput?.spanProcessors ?? []) {
+    processor.onStart?.(span, otelContext.active());
+  }
+  return span;
 };
-const mockStartSpan = jest.fn(() => mockSpan);
+
+const mockStartSpan = jest.fn(() => createMockSpan());
 const mockStartActiveSpan = jest.fn(
   (
     _name: string,
     _options: unknown,
-    _context: unknown,
-    callback: (span: typeof mockSpan) => unknown
-  ) => callback(mockSpan)
+    activeContext: Parameters<typeof otelTrace.getSpanContext>[0],
+    callback: (span: ReturnType<typeof createMockSpan>) => unknown
+  ) =>
+    callback(createMockSpan(otelTrace.getSpanContext(activeContext)?.traceId))
 );
 const mockForceFlush = jest.fn();
 const mockShutdown = jest.fn();
 
 jest.mock('@langfuse/otel', () => ({
-  LangfuseSpanProcessor: jest.fn().mockImplementation(() => ({})),
+  LangfuseSpanProcessor: jest.fn().mockImplementation((params) => ({
+    forceFlush: jest.fn(),
+    onEnd: jest.fn(),
+    onStart: jest.fn((span) => {
+      mockProcessorStarts.push({
+        params,
+        traceId: span.spanContext().traceId,
+      });
+    }),
+    shutdown: jest.fn(),
+  })),
   isDefaultExportSpan: jest.fn(() => false),
 }));
 
 jest.mock('@opentelemetry/sdk-trace-base', () => ({
-  BasicTracerProvider: jest.fn().mockImplementation(() => ({
-    forceFlush: mockForceFlush,
-    getTracer: jest.fn(() => ({
-      startActiveSpan: mockStartActiveSpan,
-      startSpan: mockStartSpan,
-    })),
-    shutdown: mockShutdown,
-  })),
+  BasicTracerProvider: jest.fn().mockImplementation((input) => {
+    mockProviderInput = input;
+    return {
+      forceFlush: mockForceFlush,
+      getTracer: jest.fn(() => ({
+        startActiveSpan: mockStartActiveSpan,
+        startSpan: mockStartSpan,
+      })),
+      shutdown: mockShutdown,
+    };
+  }),
 }));
 
 describe('Langfuse callback composition', () => {
   beforeEach(() => {
     jest.clearAllMocks();
+    mockProcessorStarts.length = 0;
+    mockSpanAttributeSets.length = 0;
+    delete process.env.LANGFUSE_PUBLIC_KEY;
+    delete process.env.LANGFUSE_SECRET_KEY;
+    delete process.env.LANGFUSE_BASE_URL;
+    delete process.env.LANGFUSE_BASEURL;
     delete process.env.LANGFUSE_FORCE_FLUSH_ON_DISPOSE;
   });
 
@@ -183,6 +242,203 @@ describe('Langfuse callback composition', () => {
     );
   });
 
+  it('binds handler callback spans to their own Langfuse config and trace seed', async () => {
+    const { createLangfuseHandler } = await import('@/langfuse');
+    const { initializeLangfuseTracing } = await import('@/instrumentation');
+    const tenantA = {
+      publicKey: 'pk-tenant-a',
+      secretKey: 'sk-tenant-a',
+      baseUrl: 'https://langfuse.proxy',
+      deterministicTraceId: true,
+    };
+    const tenantB = {
+      publicKey: 'pk-tenant-b',
+      secretKey: 'sk-tenant-b',
+      baseUrl: 'https://langfuse.proxy',
+      deterministicTraceId: true,
+    };
+    initializeLangfuseTracing(tenantA);
+    initializeLangfuseTracing(tenantB);
+
+    const handlerA = createLangfuseHandler({
+      langfuse: tenantA,
+      traceIdSeed: 'run-tenant-a',
+    });
+    const handlerB = createLangfuseHandler({
+      langfuse: tenantB,
+      traceIdSeed: 'run-tenant-b',
+    });
+
+    await Promise.all([
+      handlerA?.handleChainStart(
+        { lc: 1, type: 'not_implemented', id: ['TenantAChain'] },
+        { input: 'tenant a' },
+        'lc-run-a'
+      ),
+      handlerB?.handleChainStart(
+        { lc: 1, type: 'not_implemented', id: ['TenantBChain'] },
+        { input: 'tenant b' },
+        'lc-run-b'
+      ),
+    ]);
+
+    expect(mockProcessorStarts).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          params: expect.objectContaining({
+            publicKey: 'pk-tenant-a',
+            secretKey: 'sk-tenant-a',
+            baseUrl: 'https://langfuse.proxy',
+          }),
+          traceId: traceIdFromSeed('run-tenant-a'),
+        }),
+        expect.objectContaining({
+          params: expect.objectContaining({
+            publicKey: 'pk-tenant-b',
+            secretKey: 'sk-tenant-b',
+            baseUrl: 'https://langfuse.proxy',
+          }),
+          traceId: traceIdFromSeed('run-tenant-b'),
+        }),
+      ])
+    );
+  });
+
+  it('preserves an active agent Langfuse runtime scope for callback-created spans', async () => {
+    const { createLangfuseHandler } = await import('@/langfuse');
+    const { initializeLangfuseTracing } = await import('@/instrumentation');
+    const { withLangfuseRuntimeScope } = await import('@/langfuseRuntimeScope');
+    const runLangfuse = {
+      publicKey: 'pk-run',
+      secretKey: 'sk-run',
+      baseUrl: 'https://langfuse.run',
+      deterministicTraceId: true,
+    };
+    const agentLangfuse = {
+      publicKey: 'pk-agent',
+      secretKey: 'sk-agent',
+      baseUrl: 'https://langfuse.agent',
+      deterministicTraceId: true,
+    };
+    initializeLangfuseTracing(runLangfuse);
+    initializeLangfuseTracing(agentLangfuse);
+    const streamHandler = createLangfuseHandler({
+      langfuse: runLangfuse,
+      traceIdSeed: 'run-seed',
+    });
+
+    await withLangfuseRuntimeScope(
+      { langfuse: agentLangfuse, traceIdSeed: 'agent-seed' },
+      () =>
+        streamHandler?.handleChainStart(
+          { lc: 1, type: 'not_implemented', id: ['AgentScopedChain'] },
+          { input: 'agent scoped' },
+          'lc-agent-run'
+        )
+    );
+
+    expect(mockProcessorStarts).toContainEqual(
+      expect.objectContaining({
+        params: expect.objectContaining({
+          publicKey: 'pk-agent',
+          secretKey: 'sk-agent',
+          baseUrl: 'https://langfuse.agent',
+        }),
+        traceId: traceIdFromSeed('agent-seed'),
+      })
+    );
+    expect(mockProcessorStarts).not.toContainEqual(
+      expect.objectContaining({
+        params: expect.objectContaining({
+          publicKey: 'pk-run',
+          secretKey: 'sk-run',
+          baseUrl: 'https://langfuse.run',
+        }),
+        traceId: traceIdFromSeed('run-seed'),
+      })
+    );
+  });
+
+  it('attaches configured trace attributes to Langfuse callback spans', async () => {
+    const { createLangfuseHandler } = await import('@/langfuse');
+    const { initializeLangfuseTracing } = await import('@/instrumentation');
+    const langfuse = {
+      publicKey: 'pk-tenant-a',
+      secretKey: 'sk-tenant-a',
+      baseUrl: 'https://langfuse.proxy',
+      librechatTraceAttributes: {
+        'librechat.langfuse.tenant_export.enabled': 'true',
+        'librechat.langfuse.destination': 'eu',
+        ignored: '',
+      },
+    };
+    initializeLangfuseTracing(langfuse);
+    const handler = createLangfuseHandler({ langfuse });
+
+    await handler?.handleChainStart(
+      { lc: 1, type: 'not_implemented', id: ['TenantAChain'] },
+      { input: 'tenant a' },
+      'lc-run-a'
+    );
+
+    expect(mockSpanAttributeSets).toContainEqual({
+      'librechat.langfuse.tenant_export.enabled': 'true',
+      'librechat.langfuse.destination': 'eu',
+    });
+  });
+
+  it('uses deterministic trace ids when tracing is configured from env only', async () => {
+    process.env.LANGFUSE_PUBLIC_KEY = 'pk-env';
+    process.env.LANGFUSE_SECRET_KEY = 'sk-env';
+    process.env.LANGFUSE_BASE_URL = 'https://langfuse.env';
+
+    const runId = 'test-langfuse-env-deterministic-run';
+    const run = await Run.create<t.IState>({
+      runId,
+      graphConfig: {
+        type: 'standard',
+        agents: [
+          {
+            agentId: 'agent_abc123',
+            name: 'DWAINE',
+            provider: Providers.OPENAI,
+            clientOptions: { model: 'gpt-4' },
+            tools: [],
+          },
+        ],
+      },
+      langfuse: {
+        deterministicTraceId: true,
+        metadata: { 'librechat.tenant.id': 'tenant-env' },
+        tags: ['tenant:tenant-env'],
+      },
+      skipCleanup: true,
+    });
+
+    run.Graph?.overrideTestModel(['hello']);
+
+    await run.processStream(
+      { messages: [new HumanMessage('hello')] },
+      {
+        configurable: { thread_id: 'thread-1', user_id: 'user-1' },
+        version: 'v2' as const,
+      }
+    );
+
+    expect(mockProcessorStarts).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          params: expect.objectContaining({
+            publicKey: 'pk-env',
+            secretKey: 'sk-env',
+            baseUrl: 'https://langfuse.env',
+          }),
+          traceId: traceIdFromSeed(runId),
+        }),
+      ])
+    );
+  });
+
   it('adds current agent metadata when a stream Langfuse callback already exists', async () => {
     const metadataSpy = jest.fn();
     const { createLangfuseHandler } = await import('@/langfuse');

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

@@ -9,9 +9,16 @@ import {
 
 const mockForceFlush = jest.fn();
 
-jest.mock('@langfuse/langchain', () => ({
-  CallbackHandler: jest.fn().mockImplementation((params) => ({ params })),
-}));
+jest.mock('@langfuse/langchain', () => {
+  const CallbackHandler = jest.fn(function (
+    this: { params?: unknown; name?: string },
+    params: unknown
+  ) {
+    this.params = params;
+    this.name = 'LangfuseCallbackHandler';
+  });
+  return { CallbackHandler };
+});
 
 jest.mock('@langfuse/tracing', () => ({
   getLangfuseTracerProvider: jest.fn(() => ({

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

@@ -33,16 +33,17 @@ type BasicTracerProviderInput = {
     shutdown?: unknown;
   }>;
 };
-type RoutingSpanProcessorForTest = BasicTracerProviderInput['spanProcessors'][0] & {
-  processors: Map<
-    string,
-    {
-      fallbackConfig?: {
-        enabled?: boolean;
-      };
-    }
-  >;
-};
+type RoutingSpanProcessorForTest =
+  BasicTracerProviderInput['spanProcessors'][0] & {
+    processors: Map<
+      string,
+      {
+        fallbackConfig?: {
+          enabled?: boolean;
+        };
+      }
+    >;
+  };
 const mockBasicTracerProvider = jest.fn(
   (_input?: BasicTracerProviderInput) => mockTracerProvider
 );
@@ -217,6 +218,25 @@ describe('Langfuse instrumentation', () => {
     expect(mockSetLangfuseTracerProvider).toHaveBeenCalledTimes(1);
   });
 
+  it('does not store raw secret keys in processor cache keys', async () => {
+    const { initializeLangfuseTracing } = await import('@/instrumentation');
+    initializeLangfuseTracing({
+      publicKey: 'pk-cache',
+      secretKey: 'sk-cache-secret',
+      baseUrl: 'https://langfuse.cache',
+    });
+
+    const providerInput = mockBasicTracerProvider.mock
+      .calls[0][0] as BasicTracerProviderInput;
+    const routingProcessor = providerInput
+      .spanProcessors[0] as RoutingSpanProcessorForTest;
+    const processorKeys = Array.from(routingProcessor.processors.keys());
+
+    expect(processorKeys).toHaveLength(1);
+    expect(processorKeys[0]).toContain('secretKeyHash');
+    expect(processorKeys[0]).not.toContain('sk-cache-secret');
+  });
+
   it('passes explicit redaction config into the redacting processor fallback', async () => {
     const { initializeLangfuseTracing } = await import('@/instrumentation');
     initializeLangfuseTracing({
@@ -228,8 +248,8 @@ describe('Langfuse instrumentation', () => {
 
     const providerInput = mockBasicTracerProvider.mock
       .calls[0][0] as BasicTracerProviderInput;
-    const routingProcessor =
-      providerInput.spanProcessors[0] as RoutingSpanProcessorForTest;
+    const routingProcessor = providerInput
+      .spanProcessors[0] as RoutingSpanProcessorForTest;
     const childProcessors = Array.from(routingProcessor.processors.values());
     expect(childProcessors[0]?.fallbackConfig).toMatchObject({
       enabled: false,