@librechat/agents 3.1.90 → 3.1.91

package/src/run.ts

@@ -1,6 +1,5 @@
 // src/run.ts
 import './instrumentation';
-import { CallbackHandler } from '@langfuse/langchain';
 import { PromptTemplate } from '@langchain/core/prompts';
 import { RunnableLambda } from '@langchain/core/runnables';
 import { AzureChatOpenAI, ChatOpenAI } from '@langchain/openai';
@@ -31,7 +30,14 @@ import { initializeModel } from '@/llm/init';
 import { HandlerRegistry } from '@/events';
 import { executeHooks } from '@/hooks';
 import { isOpenAILike } from '@/utils/llm';
-import { isPresent } from '@/utils/misc';
+import {
+  createLegacyLangfuseHandler,
+  createLangfuseHandler,
+  disposeLangfuseHandler,
+  hasExplicitLangfuseConfig,
+  hasLangfuseEnvConfig,
+  isLangfuseCallbackHandler,
+} from '@/langfuse';
 import type { HookRegistry } from '@/hooks';
 
 export const defaultOmitOptions = new Set([
@@ -607,9 +613,8 @@ export class Run<_T extends t.BaseGraphState> {
       .concat(customHandler);
 
     if (
-      isPresent(process.env.LANGFUSE_SECRET_KEY) &&
-      isPresent(process.env.LANGFUSE_PUBLIC_KEY) &&
-      isPresent(process.env.LANGFUSE_BASE_URL)
+      hasLangfuseEnvConfig() &&
+      !hasExplicitLangfuseConfig(this.Graph.agentContexts.values())
     ) {
       const userId = config.configurable?.user_id;
       const sessionId = config.configurable?.thread_id;
@@ -621,7 +626,7 @@ export class Run<_T extends t.BaseGraphState> {
         parentMessageId: config.configurable?.requestBody?.parentMessageId,
         agentName: primaryContext?.name,
       };
-      const handler = new CallbackHandler({
+      const handler = createLegacyLangfuseHandler({
         userId,
         sessionId,
         traceMetadata,
@@ -1134,12 +1139,8 @@ export class Run<_T extends t.BaseGraphState> {
     titleMethod = TitleMethod.COMPLETION,
     titlePromptTemplate,
   }: t.RunTitleOptions): Promise<{ language?: string; title?: string }> {
-    if (
-      chainOptions != null &&
-      isPresent(process.env.LANGFUSE_SECRET_KEY) &&
-      isPresent(process.env.LANGFUSE_PUBLIC_KEY) &&
-      isPresent(process.env.LANGFUSE_BASE_URL)
-    ) {
+    let titleLangfuseHandler: unknown;
+    if (chainOptions != null) {
       const userId = chainOptions.configurable?.user_id;
       const sessionId = chainOptions.configurable?.thread_id;
       const titleContext = this.Graph?.agentContexts.get(
@@ -1149,14 +1150,31 @@ export class Run<_T extends t.BaseGraphState> {
         messageId: 'title-' + this.id,
         agentName: titleContext?.name,
       };
-      const handler = new CallbackHandler({
-        userId,
-        sessionId,
-        traceMetadata,
-      });
-      chainOptions.callbacks = (
-        (chainOptions.callbacks as t.ProvidedCallbacks) ?? []
-      ).concat([handler]);
+      const hasExplicitLangfuse =
+        this.Graph != null &&
+        hasExplicitLangfuseConfig(this.Graph.agentContexts.values());
+      if (titleContext?.langfuse != null) {
+        titleLangfuseHandler = createLangfuseHandler({
+          langfuse: titleContext.langfuse,
+          userId,
+          sessionId,
+          traceMetadata,
+        });
+      } else if (hasLangfuseEnvConfig() && !hasExplicitLangfuse) {
+        titleLangfuseHandler = createLegacyLangfuseHandler({
+          userId,
+          sessionId,
+          traceMetadata,
+        });
+      }
+
+      if (titleLangfuseHandler != null) {
+        chainOptions.callbacks = (
+          (chainOptions.callbacks as t.ProvidedCallbacks) ?? []
+        ).concat([
+          titleLangfuseHandler as NonNullable<t.ProvidedCallbacks>[number],
+        ]);
+      }
     }
 
     const convoTemplate = PromptTemplate.fromTemplate(
@@ -1221,24 +1239,28 @@ export class Run<_T extends t.BaseGraphState> {
     });
 
     try {
-      return await fullChain.invoke(
-        { input: inputText, output: response },
-        invokeConfig
-      );
-    } catch (_e) {
-      // Fallback: strip callbacks to avoid EventStream tracer errors in certain environments
-      // But preserve langfuse handler if it exists
-      const langfuseHandler = (
-        invokeConfig.callbacks as t.ProvidedCallbacks
-      )?.find((cb) => cb instanceof CallbackHandler);
-      const { callbacks: _cb, ...rest } = invokeConfig;
-      const safeConfig = Object.assign({}, rest, {
-        callbacks: langfuseHandler ? [langfuseHandler] : [],
-      });
-      return await fullChain.invoke(
-        { input: inputText, output: response },
-        safeConfig as Partial<RunnableConfig>
-      );
+      try {
+        return await fullChain.invoke(
+          { input: inputText, output: response },
+          invokeConfig
+        );
+      } catch (_e) {
+        // Fallback: strip callbacks to avoid EventStream tracer errors in certain environments
+        // but preserve Langfuse tracing if it exists.
+        const langfuseHandler = (
+          invokeConfig.callbacks as t.ProvidedCallbacks
+        )?.find(isLangfuseCallbackHandler);
+        const { callbacks: _cb, ...rest } = invokeConfig;
+        const safeConfig = Object.assign({}, rest, {
+          callbacks: langfuseHandler ? [langfuseHandler] : [],
+        });
+        return await fullChain.invoke(
+          { input: inputText, output: response },
+          safeConfig as Partial<RunnableConfig>
+        );
+      }
+    } finally {
+      await disposeLangfuseHandler(titleLangfuseHandler);
     }
   }
 }

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

@@ -0,0 +1,57 @@
+import { LangfuseSpanProcessor } from '@langfuse/otel';
+import { BasicTracerProvider } from '@opentelemetry/sdk-trace-base';
+import { createLangfuseHandler } from '@/langfuse';
+
+jest.mock('@langfuse/otel', () => ({
+  LangfuseSpanProcessor: jest.fn().mockImplementation(() => ({})),
+}));
+
+jest.mock('@opentelemetry/sdk-trace-base', () => ({
+  BasicTracerProvider: jest.fn().mockImplementation(() => ({
+    forceFlush: jest.fn(),
+    getTracer: jest.fn(),
+    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('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) {