@librechat/agents 3.1.90 → 3.1.92

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

@@ -0,0 +1,75 @@
+import { CallbackManager } from '@langchain/core/callbacks/manager';
+import { HumanMessage } from '@langchain/core/messages';
+import { Providers } from '@/common';
+import { Run } from '@/run';
+import type * as t from '@/types';
+
+const mockSpan = {
+  end: jest.fn(),
+  setAttributes: jest.fn(),
+  setStatus: jest.fn(),
+};
+const mockStartSpan = jest.fn(() => mockSpan);
+const mockForceFlush = jest.fn();
+const mockShutdown = jest.fn();
+
+jest.mock('@langfuse/otel', () => ({
+  LangfuseSpanProcessor: jest.fn().mockImplementation(() => ({})),
+  isDefaultExportSpan: jest.fn(() => false),
+}));
+
+jest.mock('@opentelemetry/sdk-trace-base', () => ({
+  BasicTracerProvider: jest.fn().mockImplementation(() => ({
+    forceFlush: mockForceFlush,
+    getTracer: jest.fn(() => ({
+      startSpan: mockStartSpan,
+    })),
+    shutdown: mockShutdown,
+  })),
+}));
+
+describe('Langfuse callback composition', () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+  });
+
+  it('runs explicit per-agent tracing when callbacks is a CallbackManager', async () => {
+    const manager = CallbackManager.fromHandlers({
+      handleCustomEvent: async (): Promise<void> => undefined,
+    });
+    const run = await Run.create<t.IState>({
+      runId: 'test-langfuse-callback-manager',
+      graphConfig: {
+        type: 'standard',
+        agents: [
+          {
+            agentId: 'agent_abc123',
+            name: 'DWAINE',
+            provider: Providers.OPENAI,
+            clientOptions: { model: 'gpt-4' },
+            tools: [],
+            langfuse: {
+              enabled: true,
+              publicKey: 'pk-test',
+              secretKey: 'sk-test',
+            },
+          },
+        ],
+      },
+      skipCleanup: true,
+    });
+
+    run.Graph?.overrideTestModel(['hello']);
+
+    const config = {
+      callbacks: manager,
+      configurable: { thread_id: 'thread-1', user_id: 'user-1' },
+      streamMode: 'values' as const,
+      version: 'v2' as const,
+    };
+
+    await run.processStream({ messages: [new HumanMessage('hello')] }, config);
+
+    expect(mockStartSpan).toHaveBeenCalled();
+  });
+});

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

@@ -0,0 +1,114 @@
+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,
+}));
+
+jest.mock('@langfuse/otel', () => ({
+  LangfuseSpanProcessor: jest.fn().mockImplementation(() => ({})),
+  isDefaultExportSpan: jest.fn(() => false),
+}));
+
+jest.mock('@opentelemetry/sdk-trace-base', () => ({
+  BasicTracerProvider: jest.fn().mockImplementation(() => ({
+    forceFlush: jest.fn(),
+    getTracer: mockGetTracer,
+    shutdown: jest.fn(),
+  })),
+}));
+
+describe('createLangfuseHandler', () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+  });
+
+  it('creates a handler when keys are provided and baseUrl is omitted', () => {
+    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);
+  });
+
+  it('starts per-agent spans with v5 trace attributes', async () => {
+    const handler = createLangfuseHandler({
+      langfuse: {
+        enabled: true,
+        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'],
+        }),
+      })
+    );
+  });
+
+  it('does not create a handler when a required key is missing', () => {
+    const handler = createLangfuseHandler({
+      langfuse: {
+        enabled: true,
+        publicKey: 'pk-test',
+      },
+    });
+
+    expect(handler).toBeUndefined();
+    expect(LangfuseSpanProcessor).not.toHaveBeenCalled();
+    expect(BasicTracerProvider).not.toHaveBeenCalled();
+  });
+});

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

@@ -10,7 +10,10 @@ const MockedCallbackHandler = CallbackHandler as jest.MockedClass<
   typeof CallbackHandler
 >;
 
-async function createTestRun(agentName?: string): Promise<Run<never>> {
+async function createTestRun(
+  agentName?: string,
+  agentOverrides: Record<string, unknown> = {}
+): Promise<Run<never>> {
   const run = await Run.create({
     runId: 'test-run-id',
     graphConfig: {
@@ -22,6 +25,7 @@ async function createTestRun(agentName?: string): Promise<Run<never>> {
           provider: Providers.OPENAI,
           clientOptions: { model: 'gpt-4' },
           tools: [],
+          ...agentOverrides,
         },
       ],
     },
@@ -88,4 +92,18 @@ describe('Langfuse trace metadata includes agentName', () => {
 
     expect(MockedCallbackHandler).not.toHaveBeenCalled();
   });
+
+  it('does not create the legacy CallbackHandler when explicit agent config is supplied', async () => {
+    const run = await createTestRun('DWAINE', {
+      langfuse: {
+        enabled: false,
+      },
+    });
+    await run.processStream(
+      { messages: [] },
+      { configurable: { thread_id: 't1', user_id: 'u1' }, version: 'v2' }
+    );
+
+    expect(MockedCallbackHandler).not.toHaveBeenCalled();
+  });
 });

package/src/stream.ts

@@ -136,10 +136,19 @@ function isDirectGraphTool(
 }
 
 function isDirectLocalTool(name: string, graph: StandardGraph): boolean {
-  if (graph.toolExecution?.engine !== 'local') {
+  const toolExecution = graph.toolExecution;
+  const engine = toolExecution?.engine;
+  if (
+    toolExecution == null ||
+    (engine !== 'local' && engine !== 'cloudflare-sandbox')
+  ) {
     return false;
   }
-  if (graph.toolExecution.local?.includeCodingTools === false) {
+  const includeCodingTools =
+    engine === 'cloudflare-sandbox'
+      ? toolExecution.cloudflare?.includeCodingTools
+      : toolExecution.local?.includeCodingTools;
+  if (includeCodingTools === false) {
     return CODE_EXECUTION_TOOLS.has(name);
   }
   return LOCAL_CODING_BUNDLE_NAME_SET.has(name);
@@ -270,7 +279,8 @@ function hasPotentialDirectToolInStreamContext(args: {
   agentContext?: AgentContext;
 }): boolean {
   const { graph, agentContext } = args;
-  if (graph.toolExecution?.engine === 'local') {
+  const engine = graph.toolExecution?.engine;
+  if (engine === 'local' || engine === 'cloudflare-sandbox') {
     return true;
   }
   if ((agentContext?.graphTools?.length ?? 0) > 0) {