@librechat/agents 3.1.91 → 3.1.93

package/src/run.ts

@@ -30,10 +30,17 @@ import { initializeModel } from '@/llm/init';
 import { HandlerRegistry } from '@/events';
 import { executeHooks } from '@/hooks';
 import { isOpenAILike } from '@/utils/llm';
+import {
+  appendCallbacks,
+  findCallback,
+  type CallbackEntry,
+} from '@/utils/callbacks';
 import {
   createLegacyLangfuseHandler,
+  createLangfuseTraceMetadata,
   createLangfuseHandler,
   disposeLangfuseHandler,
+  getLangfuseTraceName,
   hasExplicitLangfuseConfig,
   hasLangfuseEnvConfig,
   isLangfuseCallbackHandler,
@@ -598,42 +605,48 @@ export class Run<_T extends t.BaseGraphState> {
     /** Custom event callback to intercept and handle custom events */
     const customEventCallback = this.createCustomEventCallback();
 
-    const baseCallbacks = (config.callbacks as t.ProvidedCallbacks) ?? [];
     const streamCallbacks = streamOptions?.callbacks
       ? this.getCallbacks(streamOptions.callbacks)
-      : [];
+      : undefined;
 
     const customHandler = BaseCallbackHandler.fromMethods({
       [Callback.CUSTOM_EVENT]: customEventCallback,
     });
     customHandler.awaitHandlers = true;
 
-    config.callbacks = baseCallbacks
-      .concat(streamCallbacks)
-      .concat(customHandler);
+    config.callbacks = appendCallbacks(
+      config.callbacks,
+      streamCallbacks ? [streamCallbacks, customHandler] : [customHandler]
+    );
 
     if (
       hasLangfuseEnvConfig() &&
       !hasExplicitLangfuseConfig(this.Graph.agentContexts.values())
     ) {
-      const userId = config.configurable?.user_id;
-      const sessionId = config.configurable?.thread_id;
+      const userId =
+        typeof config.configurable?.user_id === 'string'
+          ? config.configurable.user_id
+          : undefined;
+      const sessionId =
+        typeof config.configurable?.thread_id === 'string'
+          ? config.configurable.thread_id
+          : undefined;
       const primaryContext = this.Graph.agentContexts.get(
         this.Graph.defaultAgentId
       );
-      const traceMetadata = {
+      const traceMetadata = createLangfuseTraceMetadata({
         messageId: this.id,
         parentMessageId: config.configurable?.requestBody?.parentMessageId,
         agentName: primaryContext?.name,
-      };
+      });
       const handler = createLegacyLangfuseHandler({
         userId,
         sessionId,
         traceMetadata,
+        tags: ['librechat', 'agent'],
       });
-      config.callbacks = (
-        (config.callbacks as t.ProvidedCallbacks) ?? []
-      ).concat([handler]);
+      config.runName = config.runName ?? getLangfuseTraceName(traceMetadata);
+      config.callbacks = appendCallbacks(config.callbacks, [handler]);
     }
 
     if (!this.id) {
@@ -1139,17 +1152,26 @@ export class Run<_T extends t.BaseGraphState> {
     titleMethod = TitleMethod.COMPLETION,
     titlePromptTemplate,
   }: t.RunTitleOptions): Promise<{ language?: string; title?: string }> {
-    let titleLangfuseHandler: unknown;
+    let titleLangfuseHandler: CallbackEntry | undefined;
+    const titleContext =
+      this.Graph == null
+        ? undefined
+        : this.Graph.agentContexts.get(this.Graph.defaultAgentId);
+    const traceMetadata = createLangfuseTraceMetadata({
+      messageId: 'title-' + this.id,
+      agentName: titleContext?.name,
+    });
+    const titleRunName = getLangfuseTraceName(traceMetadata, 'LibreChat Title');
+
     if (chainOptions != null) {
-      const userId = chainOptions.configurable?.user_id;
-      const sessionId = chainOptions.configurable?.thread_id;
-      const titleContext = this.Graph?.agentContexts.get(
-        this.Graph.defaultAgentId
-      );
-      const traceMetadata = {
-        messageId: 'title-' + this.id,
-        agentName: titleContext?.name,
-      };
+      const userId =
+        typeof chainOptions.configurable?.user_id === 'string'
+          ? chainOptions.configurable.user_id
+          : undefined;
+      const sessionId =
+        typeof chainOptions.configurable?.thread_id === 'string'
+          ? chainOptions.configurable.thread_id
+          : undefined;
       const hasExplicitLangfuse =
         this.Graph != null &&
         hasExplicitLangfuseConfig(this.Graph.agentContexts.values());
@@ -1159,20 +1181,20 @@ export class Run<_T extends t.BaseGraphState> {
           userId,
           sessionId,
           traceMetadata,
+          tags: ['librechat', 'title'],
         });
       } else if (hasLangfuseEnvConfig() && !hasExplicitLangfuse) {
         titleLangfuseHandler = createLegacyLangfuseHandler({
           userId,
           sessionId,
           traceMetadata,
+          tags: ['librechat', 'title'],
         });
       }
 
       if (titleLangfuseHandler != null) {
-        chainOptions.callbacks = (
-          (chainOptions.callbacks as t.ProvidedCallbacks) ?? []
-        ).concat([
-          titleLangfuseHandler as NonNullable<t.ProvidedCallbacks>[number],
+        chainOptions.callbacks = appendCallbacks(chainOptions.callbacks, [
+          titleLangfuseHandler,
         ]);
       }
     }
@@ -1236,6 +1258,7 @@ export class Run<_T extends t.BaseGraphState> {
     const invokeConfig = Object.assign({}, chainOptions, {
       run_id: this.id,
       runId: this.id,
+      runName: chainOptions?.runName ?? titleRunName,
     });
 
     try {
@@ -1247,9 +1270,10 @@ export class Run<_T extends t.BaseGraphState> {
       } 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 langfuseHandler = findCallback(
+          invokeConfig.callbacks,
+          isLangfuseCallbackHandler
+        );
         const { callbacks: _cb, ...rest } = invokeConfig;
         const safeConfig = Object.assign({}, rest, {
           callbacks: langfuseHandler ? [langfuseHandler] : [],

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

@@ -1,15 +1,28 @@
 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: jest.fn(),
+    getTracer: mockGetTracer,
     shutdown: jest.fn(),
   })),
 }));
@@ -42,6 +55,50 @@ describe('createLangfuseHandler', () => {
     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: {

package/src/tools/__tests__/CloudflareSandboxExecution.test.ts

@@ -107,26 +107,105 @@ describe('Cloudflare sandbox execution backend', () => {
     expect(listPaths).toEqual(['/workspace']);
   });
 
-  it('aborts remote exec when the local timeout kills the spawn wrapper', async () => {
-    let signal: AbortSignal | undefined;
+  it('does not pass AbortSignal to Cloudflare spawn exec options', async () => {
+    let resolveExecCalled!: () => void;
+    const execCalled = new Promise<void>((resolve) => {
+      resolveExecCalled = resolve;
+    });
+    let receivedOptions: t.CloudflareSandboxExecOptions | undefined;
+    const sandbox = createRuntime({
+      exec: (_command, options) => {
+        receivedOptions = options;
+        resolveExecCalled();
+        return new Promise<t.CloudflareSandboxExecResult>(() => undefined);
+      },
+    });
+    const config = createCloudflareLocalExecutionConfig({
+      sandbox,
+      timeoutMs: 50,
+      workspaceRoot: '/workspace',
+    });
+
+    const resultPromise = spawnLocalProcess(
+      'bash',
+      ['-lc', 'sleep 10'],
+      config
+    );
+    await execCalled;
+    const result = await resultPromise;
+
+    expect(receivedOptions).not.toHaveProperty('signal');
+    expect(result.timedOut).toBe(true);
+    expect(result.exitCode).toBe(143);
+  });
+
+  it('passes AbortSignal to signal-aware runtimes and aborts it on kill', async () => {
+    let resolveExecCalled!: () => void;
+    const execCalled = new Promise<void>((resolve) => {
+      resolveExecCalled = resolve;
+    });
+    let receivedSignal: AbortSignal | undefined;
+    let abortEvents = 0;
     const sandbox = createRuntime({
-      exec: (_command, options) =>
-        new Promise<t.CloudflareSandboxExecResult>((_resolve, reject) => {
-          signal = options?.signal;
-          signal?.addEventListener('abort', () => reject(new Error('aborted')));
-        }),
+      supportsExecSignal: true,
+      exec: (_command, options) => {
+        receivedSignal = options?.signal;
+        receivedSignal?.addEventListener('abort', () => {
+          abortEvents += 1;
+        });
+        resolveExecCalled();
+        return new Promise<t.CloudflareSandboxExecResult>(() => undefined);
+      },
     });
     const config = createCloudflareLocalExecutionConfig({
       sandbox,
+      timeoutMs: 50,
+      workspaceRoot: '/workspace',
+    });
+
+    const resultPromise = spawnLocalProcess(
+      'bash',
+      ['-lc', 'sleep 10'],
+      config
+    );
+    await execCalled;
+    const result = await resultPromise;
+
+    expect(receivedSignal).toBeDefined();
+    expect(receivedSignal?.aborted).toBe(true);
+    expect(abortEvents).toBe(1);
+    expect(result.timedOut).toBe(true);
+    expect(result.exitCode).toBe(143);
+  });
+
+  it('does not start remote exec when killed before async sandbox resolution finishes', async () => {
+    let execCalls = 0;
+    let resolveSandbox!: (runtime: t.CloudflareSandboxRuntime) => void;
+    const sandboxPromise = new Promise<t.CloudflareSandboxRuntime>(
+      (resolve) => {
+        resolveSandbox = resolve;
+      }
+    );
+    const config = createCloudflareLocalExecutionConfig({
+      sandbox: () => sandboxPromise,
       timeoutMs: 10,
       workspaceRoot: '/workspace',
     });
 
     const result = await spawnLocalProcess('bash', ['-lc', 'sleep 10'], config);
+    resolveSandbox(
+      createRuntime({
+        exec: async () => {
+          execCalls += 1;
+          return { exitCode: 0, stdout: '', stderr: '' };
+        },
+      })
+    );
+    await new Promise((resolve) => setTimeout(resolve, 0));
 
-    expect(signal?.aborted).toBe(true);
     expect(result.timedOut).toBe(true);
     expect(result.exitCode).toBe(143);
+    expect(execCalls).toBe(0);
   });
 
   it('memoizes sandbox factory results per config object', async () => {

package/src/tools/cloudflare/CloudflareBridgeRuntime.ts

@@ -469,6 +469,7 @@ export function createCloudflareBridgeRuntime(
   }
 
   return {
+    supportsExecSignal: true,
     getSandboxId,
     exec,
     readFile,

package/src/tools/cloudflare/CloudflareSandboxExecutionEngine.ts

@@ -400,8 +400,8 @@ function createCloudflareSpawn(
   return (command, args, options) => {
     const stdout = new PassThrough();
     const stderr = new PassThrough();
-    const abortController = new AbortController();
     const child = new EventEmitter() as ChildProcessWithoutNullStreams;
+    const abortController = new AbortController();
     const state = { closed: false };
     const closeOnce = (
       exitCode: number | null,
@@ -451,13 +451,19 @@ function createCloudflareSpawn(
       const timedCommand = withInSandboxTimeout(rendered, timeoutMs);
       const cwd =
         options.cwd == null ? ctx.workspaceRoot : options.cwd.toString();
+      if (state.closed) {
+        return;
+      }
+      const execOptions: t.CloudflareSandboxExecOptions = {
+        cwd,
+        env: ctx.env,
+        timeout: outerTimeoutMs(timeoutMs),
+      };
+      if (ctx.sandbox.supportsExecSignal === true) {
+        execOptions.signal = abortController.signal;
+      }
       try {
-        const result = await ctx.sandbox.exec(timedCommand, {
-          cwd,
-          env: ctx.env,
-          timeout: outerTimeoutMs(timeoutMs),
-          signal: abortController.signal,
-        });
+        const result = await ctx.sandbox.exec(timedCommand, execOptions);
         if (state.closed) {
           return;
         }

package/src/types/run.ts

@@ -3,10 +3,7 @@ import type * as z from 'zod';
 import type { BaseMessage } from '@langchain/core/messages';
 import type { StructuredTool } from '@langchain/core/tools';
 import type { RunnableConfig } from '@langchain/core/runnables';
-import type {
-  BaseCallbackHandler,
-  CallbackHandlerMethods,
-} from '@langchain/core/callbacks/base';
+import type { Callbacks } from '@langchain/core/callbacks/manager';
 import type * as s from '@/types/stream';
 import type * as e from '@/common/enum';
 import type * as g from '@/types/graph';
@@ -213,9 +210,7 @@ export type RunConfig = {
   humanInTheLoop?: HumanInTheLoopConfig;
 };
 
-export type ProvidedCallbacks =
-  | (BaseCallbackHandler | CallbackHandlerMethods)[]
-  | undefined;
+export type ProvidedCallbacks = Callbacks | undefined;
 
 export type TokenCounter = (message: BaseMessage) => number;
 

package/src/types/tools.ts

@@ -853,6 +853,12 @@ export type CloudflareSandboxListFilesResult =
     };
 
 export interface CloudflareSandboxRuntime {
+  /**
+   * True when this runtime can consume AbortSignal values in exec options.
+   * Native Cloudflare Sandbox Durable Object RPC cannot clone AbortSignal,
+   * but HTTP bridge runtimes can use it to abort the underlying fetch.
+   */
+  supportsExecSignal?: boolean;
   exec(
     command: string,
     options?: CloudflareSandboxExecOptions

package/src/utils/callbacks.ts

@@ -0,0 +1,39 @@
+import { ensureHandler } from '@langchain/core/callbacks/manager';
+import type {
+  BaseCallbackHandler,
+  CallbackHandlerMethods,
+} from '@langchain/core/callbacks/base';
+import type { Callbacks } from '@langchain/core/callbacks/manager';
+
+export type CallbackEntry = BaseCallbackHandler | CallbackHandlerMethods;
+
+export function appendCallbacks(
+  callbacks: Callbacks | undefined,
+  additions: readonly CallbackEntry[]
+): Callbacks {
+  if (additions.length === 0) {
+    return callbacks ?? [];
+  }
+
+  if (callbacks == null) {
+    return [...additions];
+  }
+
+  if (Array.isArray(callbacks)) {
+    return callbacks.concat(additions);
+  }
+
+  return callbacks.copy(additions.map(ensureHandler));
+}
+
+export function findCallback(
+  callbacks: Callbacks | undefined,
+  predicate: (callback: CallbackEntry) => boolean
+): CallbackEntry | undefined {
+  if (callbacks == null) {
+    return undefined;
+  }
+
+  const handlers = Array.isArray(callbacks) ? callbacks : callbacks.handlers;
+  return handlers.find(predicate);
+}