@librechat/agents 3.1.90 → 3.1.91

package/src/__tests__/stream.eagerEventExecution.test.ts

@@ -2847,6 +2847,72 @@ describe('ChatModelStreamHandler eager event tool execution', () => {
     expect(graph.eagerEventToolCallChunks.size).toBe(0);
   });
 
+  it('does not prestart streamed Cloudflare sandbox direct coding tools', async () => {
+    const graph = createGraph({
+      toolExecution: {
+        engine: 'cloudflare-sandbox',
+        cloudflare: { sandbox: {} },
+      } as StandardGraph['toolExecution'],
+      getAgentContext: jest.fn(
+        (): Partial<AgentContext> => ({
+          provider: Providers.OPENAI,
+          reasoningKey: 'reasoning_content',
+          toolDefinitions: [{ name: Constants.BASH_TOOL }, { name: 'weather' }],
+          graphTools: [],
+          agentId: 'agent_1',
+        })
+      ) as unknown as StandardGraph['getAgentContext'],
+    });
+    const dispatchSpy = jest.spyOn(events, 'safeDispatchCustomEvent');
+    const handler = new ChatModelStreamHandler();
+    const metadata = { langgraph_node: 'agent' };
+
+    await handler.handle(
+      GraphEvents.CHAT_MODEL_STREAM,
+      {
+        chunk: {
+          content: '',
+          tool_call_chunks: [
+            {
+              id: 'call_weather',
+              name: 'weather',
+              args: '{"city":"NYC"}',
+              index: 0,
+            },
+          ],
+        } as unknown as t.StreamChunk,
+      },
+      metadata,
+      graph
+    );
+    await handler.handle(
+      GraphEvents.CHAT_MODEL_STREAM,
+      {
+        chunk: {
+          content: '',
+          tool_call_chunks: [
+            {
+              id: 'call_bash',
+              name: Constants.BASH_TOOL,
+              args: '{"command":"echo ok"}',
+              index: 1,
+            },
+          ],
+        } as unknown as t.StreamChunk,
+      },
+      metadata,
+      graph
+    );
+
+    expect(dispatchSpy).not.toHaveBeenCalledWith(
+      GraphEvents.ON_TOOL_EXECUTE,
+      expect.anything(),
+      expect.anything()
+    );
+    expect(graph.eagerEventToolExecutions.size).toBe(0);
+    expect(graph.eagerEventToolCallChunks.size).toBe(0);
+  });
+
   it('prestarts streamed remote bash tools when the next Anthropic tool call begins', async () => {
     const graph = createGraph({
       getAgentContext: jest.fn(

package/src/agents/AgentContext.ts

@@ -53,6 +53,7 @@ export class AgentContext {
       name,
       provider,
       clientOptions,
+      langfuse,
       tools,
       toolMap,
       toolEnd,
@@ -80,6 +81,7 @@ export class AgentContext {
       name: name ?? agentId,
       provider,
       clientOptions,
+      langfuse,
       maxContextTokens,
       streamBuffer,
       tools,
@@ -149,6 +151,8 @@ export class AgentContext {
   provider: Providers;
   /** Client options for this agent */
   clientOptions?: t.ClientOptions;
+  /** Per-agent Langfuse tracing configuration. */
+  langfuse?: t.LangfuseConfig;
   /** Token count map indexed by message position */
   indexTokenCountMap: Record<string, number | undefined> = {};
   /** Canonical pre-run token map used to restore token accounting on reset */
@@ -309,6 +313,7 @@ export class AgentContext {
     name,
     provider,
     clientOptions,
+    langfuse,
     maxContextTokens,
     streamBuffer,
     tokenCounter,
@@ -332,6 +337,7 @@ export class AgentContext {
     name?: string;
     provider: Providers;
     clientOptions?: t.ClientOptions;
+    langfuse?: t.LangfuseConfig;
     maxContextTokens?: number;
     streamBuffer?: number;
     tokenCounter?: t.TokenCounter;
@@ -355,6 +361,7 @@ export class AgentContext {
     this.name = name;
     this.provider = provider;
     this.clientOptions = clientOptions;
+    this.langfuse = langfuse;
     this.maxContextTokens = maxContextTokens;
     this.streamBuffer = streamBuffer;
     this.tokenCounter = tokenCounter;
@@ -458,11 +465,14 @@ export class AgentContext {
   }
 
   private hasAvailableTool(name: string): boolean {
-    if (this.toolDefinitions?.some((tool) => tool.name === name)) return true;
-    if (this.tools?.some((tool) => 'name' in tool && tool.name === name)) {
+    if (this.toolDefinitions?.some((tool) => tool.name === name) === true)
+      return true;
+    if (
+      this.tools?.some((tool) => 'name' in tool && tool.name === name) === true
+    ) {
       return true;
     }
-    if (this.toolMap?.has(name)) return true;
+    if (this.toolMap?.has(name) === true) return true;
     return this.toolRegistry?.has(name) === true;
   }
 

package/src/graphs/Graph.ts

@@ -58,8 +58,10 @@ import { createFakeStreamingLLM } from '@/llm/fake';
 import { handleToolCalls } from '@/tools/handlers';
 import { resolveLocalToolsForBinding } from '@/tools/local';
 import { createLocalCodingToolBundle } from '@/tools/local/LocalCodingTools';
+import { createCloudflareCodingToolBundle } from '@/tools/cloudflare';
 import { isThinkingEnabled } from '@/llm/request';
 import { initializeModel } from '@/llm/init';
+import { createLangfuseHandler, disposeLangfuseHandler } from '@/langfuse';
 import { HandlerRegistry } from '@/events';
 import { ChatOpenAI } from '@/llm/openai';
 import { partitionAndMarkOpenRouterToolCache } from '@/llm/openrouter/toolCache';
@@ -337,11 +339,12 @@ export abstract class Graph<
   /**
    * Single per-Run file checkpointer shared across every ToolNode the
    * graph compiles. Lazily constructed when
-   * `toolExecution.local.fileCheckpointing === true` so multi-agent
-   * graphs see ONE snapshot store, not one-per-agent. Returns
-   * undefined when checkpointing is disabled or the local engine
-   * isn't selected. Exposed via `Run.getFileCheckpointer()` /
-   * `Run.rewindFiles()`.
+   * `toolExecution.local.fileCheckpointing === true` or
+   * `toolExecution.cloudflare.fileCheckpointing === true` so
+   * multi-agent graphs see ONE snapshot store, not one-per-agent.
+   * Returns undefined when checkpointing is disabled or a supported
+   * coding-tool engine isn't selected. Exposed via
+   * `Run.getFileCheckpointer()` / `Run.rewindFiles()`.
    */
   private _fileCheckpointer?: t.LocalFileCheckpointer;
   /**
@@ -364,20 +367,32 @@ export abstract class Graph<
     if (this._fileCheckpointer != null) {
       return this._fileCheckpointer;
     }
-    if (
-      this.toolExecution?.engine !== 'local' ||
-      this.toolExecution.local?.fileCheckpointing !== true
-    ) {
-      return undefined;
-    }
     // Eagerly create via the bundle factory so the construction path
     // matches the bundle-only callers (and future bundle-internal
     // cleanup hooks fire). The bundle factory itself accepts a pre-
     // supplied checkpointer when present, so re-injecting this one
     // into every ToolNode is idempotent.
-    const bundle = createLocalCodingToolBundle(this.toolExecution.local ?? {});
-    this._fileCheckpointer = bundle.checkpointer;
-    return this._fileCheckpointer;
+    if (
+      this.toolExecution?.engine === 'local' &&
+      this.toolExecution.local?.fileCheckpointing === true
+    ) {
+      const bundle = createLocalCodingToolBundle(
+        this.toolExecution.local ?? {}
+      );
+      this._fileCheckpointer = bundle.checkpointer;
+      return this._fileCheckpointer;
+    }
+    if (
+      this.toolExecution?.engine === 'cloudflare-sandbox' &&
+      this.toolExecution.cloudflare?.fileCheckpointing === true
+    ) {
+      const bundle = createCloudflareCodingToolBundle(
+        this.toolExecution.cloudflare
+      );
+      this._fileCheckpointer = bundle.checkpointer;
+      return this._fileCheckpointer;
+    }
+    return undefined;
   }
 }
 
@@ -1318,6 +1333,26 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
         { force: true }
       );
 
+      const langfuseHandler = createLangfuseHandler({
+        langfuse: agentContext.langfuse,
+        userId: config.configurable?.user_id as string | undefined,
+        sessionId: config.configurable?.thread_id as string | undefined,
+        traceMetadata: {
+          messageId: this.runId,
+          parentMessageId: config.configurable?.requestBody?.parentMessageId,
+          agentId,
+          agentName: agentContext.name,
+        },
+      });
+      const invokeConfig = langfuseHandler
+        ? {
+          ...config,
+          callbacks: ((config.callbacks as t.ProvidedCallbacks) ?? []).concat(
+            [langfuseHandler]
+          ),
+        }
+        : config;
+
       try {
         result = await attemptInvoke(
           {
@@ -1326,17 +1361,19 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
             provider: agentContext.provider,
             context: this,
           },
-          config
+          invokeConfig
         );
       } catch (primaryError) {
         result = await tryFallbackProviders({
           fallbacks,
           tools: agentContext.tools,
           messages: finalMessages,
-          config,
+          config: invokeConfig,
           primaryError,
           context: this,
         });
+      } finally {
+        await disposeLangfuseHandler(langfuseHandler);
       }
 
       if (!result) {

package/src/index.ts

@@ -27,6 +27,7 @@ export * from './tools/ToolNode';
 export * from './tools/schema';
 export * from './tools/handlers';
 export * from './tools/local';
+export * from './tools/cloudflare';
 export * from './tools/search';
 
 /* Misc. */

package/src/langfuse.ts

@@ -0,0 +1,358 @@
+import { CallbackHandler } from '@langfuse/langchain';
+import { LangfuseSpanProcessor } from '@langfuse/otel';
+import {
+  createObservationAttributes,
+  createTraceAttributes,
+} from '@langfuse/tracing';
+import { BaseCallbackHandler } from '@langchain/core/callbacks/base';
+import { BasicTracerProvider } from '@opentelemetry/sdk-trace-base';
+import { SpanStatusCode } from '@opentelemetry/api';
+import type { Serialized } from '@langchain/core/load/serializable';
+import type { BaseMessage } from '@langchain/core/messages';
+import type { LLMResult } from '@langchain/core/outputs';
+import type { Span } from '@opentelemetry/api';
+import type * as t from '@/types';
+import { isPresent } from '@/utils/misc';
+
+type TraceMetadata = Record<string, unknown>;
+
+type LangfuseHandlerParams = {
+  userId?: string;
+  sessionId?: string;
+  traceMetadata?: TraceMetadata;
+};
+
+type AgentLangfuseHandlerParams = LangfuseHandlerParams & {
+  langfuse?: t.LangfuseConfig;
+};
+
+type ResolvedLangfuseConfig = t.LangfuseConfig & {
+  enabled: true;
+  publicKey: string;
+  secretKey: string;
+};
+
+function getModelName(serialized: Serialized): string {
+  const serializedRecord = serialized as unknown as Record<string, unknown>;
+  const kwargs = serializedRecord.kwargs as Record<string, unknown> | undefined;
+  const modelName =
+    kwargs?.model ??
+    kwargs?.model_name ??
+    kwargs?.modelName ??
+    kwargs?.model_id ??
+    kwargs?.modelId ??
+    serializedRecord.name;
+
+  if (typeof modelName === 'string' && modelName.trim() !== '') {
+    return modelName;
+  }
+
+  if (Array.isArray(serializedRecord.id) && serializedRecord.id.length > 0) {
+    return String(serializedRecord.id[serializedRecord.id.length - 1]);
+  }
+
+  return 'ChatModel';
+}
+
+function getModelParameters(
+  extraParams?: Record<string, unknown>
+): Record<string, string | number> {
+  const invocationParams = extraParams?.invocation_params;
+  const params =
+    invocationParams != null && typeof invocationParams === 'object'
+      ? (invocationParams as Record<string, unknown>)
+      : (extraParams ?? {});
+
+  return Object.fromEntries(
+    Object.entries(params).filter(([, value]) => {
+      return typeof value === 'string' || typeof value === 'number';
+    })
+  ) as Record<string, string | number>;
+}
+
+function getOutput(output: LLMResult): unknown {
+  return output.generations.map((generation) =>
+    generation.map((item) => {
+      if ('message' in item && item.message != null) {
+        return (item.message as { content?: unknown }).content;
+      }
+      return item.text;
+    })
+  );
+}
+
+function getUsageDetails(
+  output: LLMResult
+): Record<string, number> | undefined {
+  const llmOutput = output.llmOutput as Record<string, unknown> | undefined;
+  const usage = llmOutput?.tokenUsage ?? llmOutput?.usage;
+  if (usage == null || typeof usage !== 'object') {
+    return undefined;
+  }
+
+  const usageEntries = Object.entries(usage as Record<string, unknown>).filter(
+    ([, value]) => typeof value === 'number'
+  );
+
+  return usageEntries.length > 0
+    ? (Object.fromEntries(usageEntries) as Record<string, number>)
+    : undefined;
+}
+
+function getTraceName(traceMetadata?: TraceMetadata): string {
+  const agentName = traceMetadata?.agentName;
+  return typeof agentName === 'string' && agentName.trim() !== ''
+    ? `LibreChat Agent: ${agentName}`
+    : 'LibreChat Agent';
+}
+
+export class LangfuseAgentCallbackHandler extends BaseCallbackHandler {
+  name = 'librechat_langfuse_agent_handler';
+
+  private readonly provider: BasicTracerProvider;
+  private readonly processor: LangfuseSpanProcessor;
+  private readonly userId?: string;
+  private readonly sessionId?: string;
+  private readonly traceMetadata?: TraceMetadata;
+  private readonly spans = new Map<string, Span>();
+
+  constructor({
+    langfuse,
+    userId,
+    sessionId,
+    traceMetadata,
+  }: LangfuseHandlerParams & { langfuse: ResolvedLangfuseConfig }) {
+    super();
+    this.userId = userId;
+    this.sessionId = sessionId;
+    this.traceMetadata = traceMetadata;
+    this.processor = new LangfuseSpanProcessor({
+      publicKey: langfuse.publicKey,
+      secretKey: langfuse.secretKey,
+      ...(isPresent(langfuse.baseUrl) ? { baseUrl: langfuse.baseUrl } : {}),
+      environment:
+        process.env.LANGFUSE_TRACING_ENVIRONMENT ??
+        process.env.NODE_ENV ??
+        'development',
+      exportMode: 'immediate',
+    });
+    this.provider = new BasicTracerProvider({
+      spanProcessors: [this.processor],
+    });
+  }
+
+  private startGenerationSpan({
+    llm,
+    input,
+    runId,
+    extraParams,
+    metadata,
+    name,
+  }: {
+    llm: Serialized;
+    input: unknown;
+    runId: string;
+    extraParams?: Record<string, unknown>;
+    metadata?: Record<string, unknown>;
+    name?: string;
+  }): void {
+    if (this.spans.has(runId)) {
+      return;
+    }
+
+    const tracer = this.provider.getTracer('librechat-agents-langfuse');
+    const spanName =
+      typeof name === 'string' && name.trim() !== '' ? name : getModelName(llm);
+    const span = tracer.startSpan(spanName, {
+      attributes: {
+        ...createTraceAttributes({
+          name: getTraceName(this.traceMetadata),
+          userId: this.userId,
+          sessionId: this.sessionId,
+          metadata: this.traceMetadata,
+        }),
+        ...createObservationAttributes('generation', {
+          input,
+          model: getModelName(llm),
+          modelParameters: getModelParameters(extraParams),
+          metadata: {
+            ...metadata,
+            ...this.traceMetadata,
+          },
+        }),
+      },
+    });
+    this.spans.set(runId, span);
+  }
+
+  async handleChatModelStart(
+    llm: Serialized,
+    messages: BaseMessage[][],
+    runId: string,
+    _parentRunId?: string,
+    extraParams?: Record<string, unknown>,
+    _tags?: string[],
+    metadata?: Record<string, unknown>,
+    name?: string
+  ): Promise<void> {
+    this.startGenerationSpan({
+      llm,
+      input: messages,
+      runId,
+      extraParams,
+      metadata,
+      name,
+    });
+  }
+
+  async handleLLMStart(
+    llm: Serialized,
+    prompts: string[],
+    runId: string,
+    _parentRunId?: string,
+    extraParams?: Record<string, unknown>,
+    _tags?: string[],
+    metadata?: Record<string, unknown>,
+    name?: string
+  ): Promise<void> {
+    this.startGenerationSpan({
+      llm,
+      input: prompts,
+      runId,
+      extraParams,
+      metadata,
+      name,
+    });
+  }
+
+  async handleLLMEnd(output: LLMResult, runId: string): Promise<void> {
+    const span = this.spans.get(runId);
+    if (!span) {
+      return;
+    }
+
+    span.setAttributes(
+      createObservationAttributes('generation', {
+        output: getOutput(output),
+        usageDetails: getUsageDetails(output),
+      })
+    );
+    span.end();
+    this.spans.delete(runId);
+    await this.flush();
+  }
+
+  async handleLLMError(err: unknown, runId: string): Promise<void> {
+    const span = this.spans.get(runId);
+    if (!span) {
+      return;
+    }
+
+    const message = err instanceof Error ? err.message : String(err);
+    span.setStatus({ code: SpanStatusCode.ERROR, message });
+    span.setAttributes(
+      createObservationAttributes('generation', {
+        level: 'ERROR',
+        statusMessage: message,
+      })
+    );
+    span.end();
+    this.spans.delete(runId);
+    await this.flush();
+  }
+
+  private async flush(): Promise<void> {
+    try {
+      await this.provider.forceFlush();
+    } catch (error) {
+      process.emitWarning(
+        `[LangfuseAgentCallbackHandler] Failed to flush Langfuse spans: ${
+          error instanceof Error ? error.message : String(error)
+        }`
+      );
+    }
+  }
+
+  async dispose(): Promise<void> {
+    for (const span of this.spans.values()) {
+      span.end();
+    }
+    this.spans.clear();
+    await this.flush();
+    try {
+      await this.provider.shutdown();
+    } catch (error) {
+      process.emitWarning(
+        `[LangfuseAgentCallbackHandler] Failed to shut down Langfuse provider: ${
+          error instanceof Error ? error.message : String(error)
+        }`
+      );
+    }
+  }
+}
+
+function hasRequiredLangfuseConfig(
+  langfuse?: t.LangfuseConfig
+): langfuse is ResolvedLangfuseConfig {
+  return (
+    langfuse?.enabled === true &&
+    isPresent(langfuse.publicKey) &&
+    isPresent(langfuse.secretKey)
+  );
+}
+
+export function createLegacyLangfuseHandler(
+  params: LangfuseHandlerParams
+): CallbackHandler {
+  return new CallbackHandler(params);
+}
+
+export function createLangfuseHandler({
+  langfuse,
+  userId,
+  sessionId,
+  traceMetadata,
+}: AgentLangfuseHandlerParams): LangfuseAgentCallbackHandler | undefined {
+  if (!hasRequiredLangfuseConfig(langfuse)) {
+    return undefined;
+  }
+
+  return new LangfuseAgentCallbackHandler({
+    langfuse,
+    userId,
+    sessionId,
+    traceMetadata,
+  });
+}
+
+export function hasExplicitLangfuseConfig(
+  contexts: Iterable<{ langfuse?: t.LangfuseConfig }>
+): boolean {
+  for (const context of contexts) {
+    if (context.langfuse != null) {
+      return true;
+    }
+  }
+  return false;
+}
+
+export function hasLangfuseEnvConfig(): boolean {
+  return (
+    isPresent(process.env.LANGFUSE_SECRET_KEY) &&
+    isPresent(process.env.LANGFUSE_PUBLIC_KEY) &&
+    isPresent(process.env.LANGFUSE_BASE_URL)
+  );
+}
+
+export function isLangfuseCallbackHandler(value: unknown): boolean {
+  return (
+    value instanceof CallbackHandler ||
+    value instanceof LangfuseAgentCallbackHandler
+  );
+}
+
+export async function disposeLangfuseHandler(value: unknown): Promise<void> {
+  if (value instanceof LangfuseAgentCallbackHandler) {
+    await value.dispose();
+  }
+}