@librechat/agents 3.1.90 → 3.1.92

package/dist/types/types/tools.d.ts

@@ -467,10 +467,11 @@ export type ToolOutputReferencesConfig = {
      */
     maxTotalSize?: number;
 };
-export type ToolExecutionEngine = 'sandbox' | 'local';
+export type ToolExecutionEngine = 'sandbox' | 'local' | 'cloudflare-sandbox';
 /**
  * Records pre-write file contents so callers can rewind edits/writes
- * made by the local engine. Implementations live in `src/tools/local`.
+ * made by local-compatible coding-tool engines. Implementations live
+ * in `src/tools/local`.
  */
 export interface LocalFileCheckpointer {
     /**
@@ -586,6 +587,12 @@ export type LocalExecConfig = {
      * overridden together for non-host engines.
      */
     fs?: import('@/tools/local/workspaceFS').WorkspaceFS;
+    /**
+     * Set by custom execution backends that already provide their own
+     * sandbox boundary. Suppresses the local host-sandbox warning while
+     * preserving the warning for plain host `child_process` execution.
+     */
+    sandboxed?: boolean;
 };
 export type LocalExecutionConfig = {
     /**
@@ -740,11 +747,120 @@ export type LocalExecutionConfig = {
         timeoutMs?: number;
     };
 };
+export type CloudflareSandboxExecOptions = {
+    cwd?: string;
+    env?: Record<string, string | undefined>;
+    timeout?: number;
+    stream?: boolean;
+    onOutput?: (stream: 'stdout' | 'stderr', data: string) => void;
+    signal?: AbortSignal;
+};
+export type CloudflareSandboxExecResult = {
+    success?: boolean;
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+    command?: string;
+    duration?: number;
+    timestamp?: string;
+};
+export type CloudflareSandboxReadFileResult = string | Buffer | Uint8Array | {
+    content: string | Buffer | Uint8Array | ReadableStream<Uint8Array>;
+    size?: number;
+    mimeType?: string;
+    encoding?: 'utf-8' | 'utf8' | 'base64';
+    isBinary?: boolean;
+};
+export type CloudflareSandboxListFilesOptions = {
+    recursive?: boolean;
+    includeHidden?: boolean;
+};
+export type CloudflareSandboxFileInfo = {
+    name: string;
+    absolutePath?: string;
+    relativePath?: string;
+    type?: 'file' | 'directory' | 'symlink' | 'other';
+    size?: number;
+    modifiedAt?: string;
+    mode?: string;
+};
+export type CloudflareSandboxListFilesResult = CloudflareSandboxFileInfo[] | {
+    files: CloudflareSandboxFileInfo[];
+    count?: number;
+    path?: string;
+    success?: boolean;
+};
+export interface CloudflareSandboxRuntime {
+    exec(command: string, options?: CloudflareSandboxExecOptions): Promise<CloudflareSandboxExecResult>;
+    readFile(path: string, options?: {
+        encoding?: string;
+    }): Promise<CloudflareSandboxReadFileResult>;
+    writeFile(path: string, content: string | ReadableStream<Uint8Array>, options?: {
+        encoding?: string;
+    }): Promise<unknown>;
+    mkdir(path: string, options?: {
+        recursive?: boolean;
+    }): Promise<unknown>;
+    listFiles(path: string, options?: CloudflareSandboxListFilesOptions): Promise<CloudflareSandboxListFilesResult>;
+    deleteFile(path: string): Promise<unknown>;
+}
+export type CloudflareSandboxExecutionConfig = {
+    sandbox: CloudflareSandboxRuntime | (() => CloudflareSandboxRuntime | Promise<CloudflareSandboxRuntime>);
+    /** Working directory inside the sandbox. Defaults to `/workspace`. */
+    workspaceRoot?: string;
+    /** Extra environment variables merged into sandbox command executions. */
+    env?: Record<string, string | undefined>;
+    /** Default timeout for sandbox commands, in milliseconds. */
+    timeoutMs?: number;
+    /** Maximum stdout/stderr characters surfaced to the model. */
+    maxOutputChars?: number;
+    /**
+     * Add the built-in coding suite when `engine` is `cloudflare-sandbox`.
+     * Defaults to true, matching the local execution backend.
+     */
+    includeCodingTools?: boolean;
+    /**
+     * Optional exact coding-tool names to expose when `includeCodingTools`
+     * is on. Defaults to the full local-parity Cloudflare bundle. Use this
+     * to publish a bash-only sandbox surface, for example file/search tools
+     * plus `bash_tool` and `run_tools_with_bash`, without exposing
+     * `execute_code`.
+     */
+    codingToolNames?: readonly string[];
+    /** Optional shell executable for bash-style tools. Defaults to `bash`. */
+    shell?: string;
+    /**
+     * Optional project-level compile check configuration. Mirrors the local
+     * execution backend.
+     */
+    compileCheck?: LocalExecutionConfig['compileCheck'];
+    /** Optional read-only guard for mutating coding tools. */
+    readOnly?: boolean;
+    /** Permit dangerous commands that the validator otherwise blocks. */
+    allowDangerousCommands?: LocalExecutionConfig['allowDangerousCommands'];
+    /** Tree-sitter-bash AST validation pass for bash commands. */
+    bashAst?: LocalExecutionConfig['bashAst'];
+    /**
+     * Enable per-Run file checkpointing for `edit_file` / `write_file`
+     * against the Cloudflare Sandbox workspace.
+     */
+    fileCheckpointing?: LocalExecutionConfig['fileCheckpointing'];
+    /** Maximum bytes to read in `read_file` before returning a stub. */
+    maxReadBytes?: LocalExecutionConfig['maxReadBytes'];
+    /** Controls whether `read_file` returns binary files as attachments. */
+    attachReadAttachments?: LocalExecutionConfig['attachReadAttachments'];
+    /** Maximum pre-encoding byte size to embed inline. */
+    maxAttachmentBytes?: LocalExecutionConfig['maxAttachmentBytes'];
+    /** Run a fast per-file syntax check after successful edits/writes. */
+    postEditSyntaxCheck?: LocalExecutionConfig['postEditSyntaxCheck'];
+};
 export type ToolExecutionConfig = {
     /** `sandbox` preserves the remote Code API behavior and is the default. */
     engine?: ToolExecutionEngine;
     /** Local process execution settings used when `engine` is `local`. */
     local?: LocalExecutionConfig;
+    /** Cloudflare Sandbox execution settings used when `engine` is `cloudflare-sandbox`. */
+    cloudflare?: CloudflareSandboxExecutionConfig;
 };
 export type ProgrammaticCache = {
     toolMap: ToolMap;

package/dist/types/utils/callbacks.d.ts

@@ -0,0 +1,5 @@
+import type { BaseCallbackHandler, CallbackHandlerMethods } from '@langchain/core/callbacks/base';
+import type { Callbacks } from '@langchain/core/callbacks/manager';
+export type CallbackEntry = BaseCallbackHandler | CallbackHandlerMethods;
+export declare function appendCallbacks(callbacks: Callbacks | undefined, additions: readonly CallbackEntry[]): Callbacks;
+export declare function findCallback(callbacks: Callbacks | undefined, predicate: (callback: CallbackEntry) => boolean): CallbackEntry | undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@librechat/agents",
-  "version": "3.1.90",
+  "version": "3.1.92",
   "main": "./dist/cjs/main.cjs",
   "module": "./dist/esm/main.mjs",
   "types": "./dist/types/index.d.ts",
@@ -227,9 +227,9 @@
     "@langchain/openai": "1.4.5",
     "@langchain/textsplitters": "^1.0.1",
     "@langchain/xai": "^1.3.17",
-    "@langfuse/langchain": "^4.3.0",
-    "@langfuse/otel": "^4.3.0",
-    "@langfuse/tracing": "^4.3.0",
+    "@langfuse/langchain": "^5.3.0",
+    "@langfuse/otel": "^5.3.0",
+    "@langfuse/tracing": "^5.3.0",
     "@opentelemetry/sdk-node": "^0.218.0",
     "@scarf/scarf": "^1.4.0",
     "@types/diff": "^7.0.2",

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

@@ -52,14 +52,21 @@ import { attemptInvoke, tryFallbackProviders } from '@/llm/invoke';
 import { shouldTriggerSummarization } from '@/summarization';
 import { createSummarizeNode } from '@/summarization/node';
 import { messagesStateReducer } from '@/messages/reducer';
+import { appendCallbacks } from '@/utils/callbacks';
 import { createSchemaOnlyTools } from '@/tools/schema';
 import { AgentContext } from '@/agents/AgentContext';
 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,
+  createLangfuseTraceMetadata,
+} from '@/langfuse';
 import { HandlerRegistry } from '@/events';
 import { ChatOpenAI } from '@/llm/openai';
 import { partitionAndMarkOpenRouterToolCache } from '@/llm/openrouter/toolCache';
@@ -337,11 +344,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 +372,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 +1338,25 @@ 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: createLangfuseTraceMetadata({
+          messageId: this.runId,
+          parentMessageId: config.configurable?.requestBody?.parentMessageId,
+          agentId,
+          agentName: agentContext.name,
+        }),
+        tags: ['librechat', 'agent'],
+      });
+      const invokeConfig = langfuseHandler
+        ? {
+          ...config,
+          callbacks: appendCallbacks(config.callbacks, [langfuseHandler]),
+        }
+        : config;
+
       try {
         result = await attemptInvoke(
           {
@@ -1326,17 +1365,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/instrumentation.ts

@@ -5,14 +5,9 @@ import { isPresent } from '@/utils/misc';
 if (
   isPresent(process.env.LANGFUSE_SECRET_KEY) &&
   isPresent(process.env.LANGFUSE_PUBLIC_KEY) &&
-  isPresent(process.env.LANGFUSE_BASE_URL)
+  isPresent(process.env.LANGFUSE_BASE_URL ?? process.env.LANGFUSE_BASEURL)
 ) {
-  const langfuseSpanProcessor = new LangfuseSpanProcessor({
-    publicKey: process.env.LANGFUSE_PUBLIC_KEY,
-    secretKey: process.env.LANGFUSE_SECRET_KEY,
-    baseUrl: process.env.LANGFUSE_BASE_URL,
-    environment: process.env.LANGFUSE_TRACING_ENVIRONMENT ?? process.env.NODE_ENV ?? 'development',
-  });
+  const langfuseSpanProcessor = new LangfuseSpanProcessor();
 
   const sdk = new NodeSDK({
     spanProcessors: [langfuseSpanProcessor],