@librechat/agents 3.1.90 → 3.1.92

package/src/tools/cloudflare/CloudflareSandboxTools.ts

@@ -0,0 +1,225 @@
+import { tool } from '@langchain/core/tools';
+import type { DynamicStructuredTool } from '@langchain/core/tools';
+import type * as t from '@/types';
+import {
+  CodeExecutionToolName,
+  CodeExecutionToolSchema,
+} from '@/tools/CodeExecutor';
+import {
+  BashExecutionToolName,
+  BashExecutionToolSchema,
+  BashToolOutputReferencesGuide,
+} from '@/tools/BashExecutor';
+import {
+  createLocalReadFileTool,
+  createLocalWriteFileTool,
+  createLocalEditFileTool,
+  createLocalGrepSearchTool,
+  createLocalGlobSearchTool,
+  createLocalListDirectoryTool,
+} from '@/tools/local/LocalCodingTools';
+import { createLocalFileCheckpointer } from '@/tools/local/FileCheckpointer';
+import { createCompileCheckTool } from '@/tools/local/CompileCheckTool';
+import { Constants } from '@/common';
+import {
+  createCloudflareLocalExecutionConfig,
+  createCloudflareWorkspaceFS,
+  executeCloudflareBash,
+  executeCloudflareCode,
+  formatCloudflareOutput,
+  getCloudflareWorkspaceRoot,
+} from './CloudflareSandboxExecutionEngine';
+import {
+  createCloudflareBashProgrammaticToolCallingTool,
+  createCloudflareProgrammaticToolCallingTool,
+} from './CloudflareProgrammaticToolCalling';
+
+export const CLOUDFLARE_CODING_TOOL_NAMES: readonly string[] = [
+  Constants.READ_FILE,
+  Constants.WRITE_FILE,
+  Constants.EDIT_FILE,
+  Constants.GREP_SEARCH,
+  Constants.GLOB_SEARCH,
+  Constants.LIST_DIRECTORY,
+  Constants.COMPILE_CHECK,
+  Constants.BASH_TOOL,
+  Constants.EXECUTE_CODE,
+  Constants.PROGRAMMATIC_TOOL_CALLING,
+  Constants.BASH_PROGRAMMATIC_TOOL_CALLING,
+];
+
+export const CLOUDFLARE_BASH_CODING_TOOL_NAMES: readonly string[] = [
+  Constants.READ_FILE,
+  Constants.WRITE_FILE,
+  Constants.EDIT_FILE,
+  Constants.GREP_SEARCH,
+  Constants.GLOB_SEARCH,
+  Constants.LIST_DIRECTORY,
+  Constants.COMPILE_CHECK,
+  Constants.BASH_TOOL,
+  Constants.BASH_PROGRAMMATIC_TOOL_CALLING,
+];
+
+export const CloudflareCodeExecutionToolDescription = `
+Runs code inside the configured Cloudflare Sandbox workspace. The sandbox can see files and installed runtimes available inside the Cloudflare Sandbox container.
+
+Usage:
+- Commands execute in the Cloudflare Sandbox workspace and may modify sandbox files.
+- Input code is already displayed to the user, so do not repeat it unless asked.
+- Output is not displayed unless you print it explicitly.
+`.trim();
+
+export const CloudflareBashExecutionToolDescription = `
+Runs bash commands inside the configured Cloudflare Sandbox workspace.
+
+Usage:
+- Commands execute in the Cloudflare Sandbox workspace and may modify sandbox files.
+- Output is not displayed unless you print it explicitly.
+- Prefer project-native commands and inspect files before changing them.
+`.trim();
+
+export function createCloudflareCodeExecutionTool(
+  config: t.CloudflareSandboxExecutionConfig
+): DynamicStructuredTool {
+  return tool(
+    async (rawInput) => {
+      const input = rawInput as {
+        lang: string;
+        code: string;
+        args?: string[];
+      };
+      const cwd = getCloudflareWorkspaceRoot(config);
+      const result = await executeCloudflareCode(input, config);
+      return [
+        formatCloudflareOutput(result, cwd),
+        {
+          session_id: 'cloudflare-sandbox',
+          files: [],
+        } satisfies t.CodeExecutionArtifact,
+      ];
+    },
+    {
+      name: CodeExecutionToolName,
+      description: CloudflareCodeExecutionToolDescription,
+      schema: CodeExecutionToolSchema,
+      responseFormat: Constants.CONTENT_AND_ARTIFACT,
+    }
+  );
+}
+
+export function createCloudflareBashExecutionTool(options: {
+  config: t.CloudflareSandboxExecutionConfig;
+  enableToolOutputReferences?: boolean;
+}): DynamicStructuredTool {
+  const { config } = options;
+  return tool(
+    async (rawInput) => {
+      const input = rawInput as { command: string; args?: string[] };
+      const cwd = getCloudflareWorkspaceRoot(config);
+      const result = await executeCloudflareBash(
+        input.command,
+        config,
+        input.args ?? []
+      );
+      return [
+        formatCloudflareOutput(result, cwd),
+        {
+          session_id: 'cloudflare-sandbox',
+          files: [],
+        } satisfies t.CodeExecutionArtifact,
+      ];
+    },
+    {
+      name: BashExecutionToolName,
+      description:
+        options.enableToolOutputReferences === true
+          ? `${CloudflareBashExecutionToolDescription}\n\n${BashToolOutputReferencesGuide}`
+          : CloudflareBashExecutionToolDescription,
+      schema: BashExecutionToolSchema,
+      responseFormat: Constants.CONTENT_AND_ARTIFACT,
+    }
+  );
+}
+
+export type CloudflareCodingToolBundle = {
+  tools: DynamicStructuredTool[];
+  checkpointer?: t.LocalFileCheckpointer;
+};
+
+function getSelectedCodingToolNames(
+  config: t.CloudflareSandboxExecutionConfig
+): Set<string> {
+  return new Set(config.codingToolNames ?? CLOUDFLARE_CODING_TOOL_NAMES);
+}
+
+export function createCloudflareCodingTools(
+  config: t.CloudflareSandboxExecutionConfig,
+  options: { checkpointer?: t.LocalFileCheckpointer } = {}
+): DynamicStructuredTool[] {
+  const localConfig = createCloudflareLocalExecutionConfig(config);
+  const checkpointer =
+    options.checkpointer ??
+    (config.fileCheckpointing === true
+      ? createLocalFileCheckpointer({
+        fs: createCloudflareWorkspaceFS(config),
+      })
+      : undefined);
+  const tools = [
+    [Constants.READ_FILE, createLocalReadFileTool(localConfig)],
+    [Constants.WRITE_FILE, createLocalWriteFileTool(localConfig, checkpointer)],
+    [Constants.EDIT_FILE, createLocalEditFileTool(localConfig, checkpointer)],
+    [Constants.GREP_SEARCH, createLocalGrepSearchTool(localConfig)],
+    [Constants.GLOB_SEARCH, createLocalGlobSearchTool(localConfig)],
+    [Constants.LIST_DIRECTORY, createLocalListDirectoryTool(localConfig)],
+    [Constants.COMPILE_CHECK, createCompileCheckTool(localConfig)],
+    [Constants.BASH_TOOL, createCloudflareBashExecutionTool({ config })],
+    [Constants.EXECUTE_CODE, createCloudflareCodeExecutionTool(config)],
+    [
+      Constants.PROGRAMMATIC_TOOL_CALLING,
+      createCloudflareProgrammaticToolCallingTool(config),
+    ],
+    [
+      Constants.BASH_PROGRAMMATIC_TOOL_CALLING,
+      createCloudflareBashProgrammaticToolCallingTool(config),
+    ],
+  ] satisfies Array<[string, DynamicStructuredTool]>;
+  const selectedNames = getSelectedCodingToolNames(config);
+  return tools
+    .filter(([name]) => selectedNames.has(name))
+    .map(([, selectedTool]) => selectedTool);
+}
+
+export function createCloudflareCodingToolBundle(
+  config: t.CloudflareSandboxExecutionConfig,
+  options: { checkpointer?: t.LocalFileCheckpointer } = {}
+): CloudflareCodingToolBundle {
+  const checkpointer =
+    options.checkpointer ??
+    (config.fileCheckpointing === true
+      ? createLocalFileCheckpointer({
+        fs: createCloudflareWorkspaceFS(config),
+      })
+      : undefined);
+  return {
+    tools: createCloudflareCodingTools(config, { checkpointer }),
+    checkpointer,
+  };
+}
+
+export function createCloudflareExecutionTool(
+  name: string,
+  config: t.CloudflareSandboxExecutionConfig
+): t.GenericTool | undefined {
+  switch (name) {
+  case Constants.EXECUTE_CODE:
+    return createCloudflareCodeExecutionTool(config);
+  case Constants.BASH_TOOL:
+    return createCloudflareBashExecutionTool({ config });
+  case Constants.PROGRAMMATIC_TOOL_CALLING:
+    return createCloudflareProgrammaticToolCallingTool(config);
+  case Constants.BASH_PROGRAMMATIC_TOOL_CALLING:
+    return createCloudflareBashProgrammaticToolCallingTool(config);
+  default:
+    return undefined;
+  }
+}

package/src/tools/cloudflare/index.ts

@@ -0,0 +1,4 @@
+export * from './CloudflareBridgeRuntime';
+export * from './CloudflareProgrammaticToolCalling';
+export * from './CloudflareSandboxExecutionEngine';
+export * from './CloudflareSandboxTools';

package/src/tools/local/LocalExecutionEngine.ts

@@ -342,7 +342,11 @@ function shouldUseLocalSandbox(config: t.LocalExecutionConfig): boolean {
 let sandboxOffWarned = false;
 
 function maybeWarnSandboxOff(config: t.LocalExecutionConfig): void {
-  if (sandboxOffWarned || shouldUseLocalSandbox(config)) {
+  if (
+    sandboxOffWarned ||
+    shouldUseLocalSandbox(config) ||
+    config.exec?.sandboxed === true
+  ) {
     return;
   }
   sandboxOffWarned = true;
@@ -700,6 +704,8 @@ export interface SpawnLocalProcessOptions {
   internal?: boolean;
 }
 
+export const LOCAL_SPAWN_TIMEOUT_MS = Symbol('librechat.localSpawn.timeoutMs');
+
 export async function spawnLocalProcess(
   command: string,
   args: string[],
@@ -742,12 +748,16 @@ export async function spawnLocalProcess(
 
   const launcher = getSpawn(config);
   return new Promise<SpawnResult>((resolveResult, reject) => {
-    const child = launcher(spawnCommand, spawnArgs, {
+    const spawnOptions: import('child_process').SpawnOptions = {
       cwd,
       detached: process.platform !== 'win32',
       env: { ...process.env, ...(config.env ?? {}) },
       stdio: ['ignore', 'pipe', 'pipe'],
+    };
+    Object.defineProperty(spawnOptions, LOCAL_SPAWN_TIMEOUT_MS, {
+      value: timeoutMs,
     });
+    const child = launcher(spawnCommand, spawnArgs, spawnOptions);
 
     let stdout = '';
     let stderr = '';
@@ -1166,7 +1176,10 @@ function configShell(): string {
 const SIGKILL_ESCALATION_MS = 2000;
 
 function sigterm(child: ChildProcess): void {
-  if (child.pid == null) return;
+  if (child.pid == null) {
+    child.kill('SIGTERM');
+    return;
+  }
   try {
     if (process.platform === 'win32') {
       child.kill('SIGTERM');
@@ -1179,8 +1192,11 @@ function sigterm(child: ChildProcess): void {
 }
 
 function sigkill(child: ChildProcess): void {
-  if (child.pid == null) return;
   if (child.exitCode != null || child.signalCode != null) return;
+  if (child.pid == null) {
+    child.kill('SIGKILL');
+    return;
+  }
   try {
     if (process.platform === 'win32') {
       child.kill('SIGKILL');

package/src/tools/local/resolveLocalExecutionTools.ts

@@ -1,4 +1,8 @@
-import { Constants, CODE_EXECUTION_TOOLS } from '@/common';
+import {
+  Constants,
+  CODE_EXECUTION_TOOLS,
+  LOCAL_CODING_BUNDLE_NAMES,
+} from '@/common';
 import {
   createLocalBashExecutionTool,
   createLocalCodeExecutionTool,
@@ -12,6 +16,11 @@ import {
   createLocalBashProgrammaticToolCallingTool,
   createLocalProgrammaticToolCallingTool,
 } from './LocalProgrammaticToolCalling';
+import {
+  createCloudflareCodingToolBundle,
+  createCloudflareCodingTools,
+  createCloudflareExecutionTool,
+} from '@/tools/cloudflare';
 import type * as t from '@/types';
 
 type ResolveLocalToolsResult = {
@@ -34,13 +43,68 @@ function shouldUseLocalExecution(config?: t.ToolExecutionConfig): boolean {
   return config?.engine === 'local';
 }
 
+function shouldUseCloudflareSandboxExecution(
+  config?: t.ToolExecutionConfig
+): boolean {
+  return config?.engine === 'cloudflare-sandbox';
+}
+
 function shouldIncludeCodingTools(config?: t.ToolExecutionConfig): boolean {
   return (
-    shouldUseLocalExecution(config) &&
-    config?.local?.includeCodingTools !== false
+    (shouldUseLocalExecution(config) &&
+      config?.local?.includeCodingTools !== false) ||
+    (shouldUseCloudflareSandboxExecution(config) &&
+      config?.cloudflare?.includeCodingTools !== false)
   );
 }
 
+function getCloudflareConfig(
+  config?: t.ToolExecutionConfig
+): t.CloudflareSandboxExecutionConfig {
+  if (config?.cloudflare == null) {
+    throw new Error(
+      'toolExecution.cloudflare is required when engine is "cloudflare-sandbox".'
+    );
+  }
+  return config.cloudflare;
+}
+
+function getSelectedCloudflareCodingToolNames(
+  config: t.CloudflareSandboxExecutionConfig
+): Set<string> {
+  return new Set(config.codingToolNames ?? LOCAL_CODING_BUNDLE_NAMES);
+}
+
+function filterCloudflareCodingToolAllowlist(
+  tools: t.GraphTools | undefined,
+  selectedNames: Set<string>
+): t.GraphTools | undefined {
+  const existingTools = (tools as t.GenericTool[] | undefined) ?? [];
+  if (existingTools.length === 0) {
+    return tools;
+  }
+  return existingTools.filter((existingTool) => {
+    if (!('name' in existingTool) || typeof existingTool.name !== 'string') {
+      return true;
+    }
+    return (
+      !LOCAL_CODING_BUNDLE_NAMES.includes(existingTool.name) ||
+      selectedNames.has(existingTool.name)
+    );
+  });
+}
+
+function pruneCloudflareCodingToolAllowlist(
+  toolMap: t.ToolMap,
+  selectedNames: Set<string>
+): void {
+  for (const name of LOCAL_CODING_BUNDLE_NAMES) {
+    if (!selectedNames.has(name)) {
+      toolMap.delete(name);
+    }
+  }
+}
+
 function createLocalExecutionTool(
   name: string,
   config: t.LocalExecutionConfig
@@ -90,10 +154,44 @@ export function resolveLocalToolsForBinding(args: {
   tools?: t.GraphTools;
   toolExecution?: t.ToolExecutionConfig;
 }): t.GraphTools | undefined {
-  if (!shouldUseLocalExecution(args.toolExecution)) {
+  if (
+    !shouldUseLocalExecution(args.toolExecution) &&
+    !shouldUseCloudflareSandboxExecution(args.toolExecution)
+  ) {
     return args.tools;
   }
 
+  if (shouldUseCloudflareSandboxExecution(args.toolExecution)) {
+    const cloudflareConfig = getCloudflareConfig(args.toolExecution);
+    if (shouldIncludeCodingTools(args.toolExecution)) {
+      const selectedNames =
+        getSelectedCloudflareCodingToolNames(cloudflareConfig);
+      return mergeToolsByName(
+        filterCloudflareCodingToolAllowlist(args.tools, selectedNames),
+        createCloudflareCodingTools(cloudflareConfig)
+      );
+    }
+
+    const replacements = ((args.tools as t.GenericTool[] | undefined) ?? [])
+      .filter(
+        (existingTool): existingTool is t.GenericTool & { name: string } =>
+          'name' in existingTool &&
+          typeof existingTool.name === 'string' &&
+          CODE_EXECUTION_TOOLS.has(existingTool.name)
+      )
+      .map((existingTool) =>
+        createCloudflareExecutionTool(existingTool.name, cloudflareConfig)
+      )
+      .filter(
+        (cloudflareTool): cloudflareTool is t.GenericTool =>
+          cloudflareTool != null
+      );
+
+    return replacements.length === 0
+      ? args.tools
+      : mergeToolsByName(args.tools, replacements);
+  }
+
   const localConfig = args.toolExecution?.local ?? {};
   if (shouldIncludeCodingTools(args.toolExecution)) {
     return mergeToolsByName(args.tools, createLocalCodingTools(localConfig));
@@ -125,7 +223,16 @@ export function resolveLocalToolRegistry(args: {
   }
 
   const registry = new Map(args.toolRegistry ?? []);
+  const selectedNames = shouldUseCloudflareSandboxExecution(args.toolExecution)
+    ? getSelectedCloudflareCodingToolNames(
+      getCloudflareConfig(args.toolExecution)
+    )
+    : undefined;
   for (const definition of createLocalCodingToolDefinitions()) {
+    if (selectedNames != null && !selectedNames.has(definition.name)) {
+      registry.delete(definition.name);
+      continue;
+    }
     registry.set(definition.name, definition);
   }
   return registry;
@@ -145,17 +252,69 @@ export function resolveLocalExecutionTools(args: {
   fileCheckpointer?: t.LocalFileCheckpointer;
 }): ResolveLocalToolsResult {
   const directToolNames = new Set<string>();
-  if (!shouldUseLocalExecution(args.toolExecution)) {
+  if (
+    !shouldUseLocalExecution(args.toolExecution) &&
+    !shouldUseCloudflareSandboxExecution(args.toolExecution)
+  ) {
     return {
       toolMap: args.toolMap,
       directToolNames,
     };
   }
 
-  const localConfig = args.toolExecution?.local ?? {};
   const toolMap = new Map(args.toolMap);
   let fileCheckpointer: t.LocalFileCheckpointer | undefined;
 
+  if (shouldUseCloudflareSandboxExecution(args.toolExecution)) {
+    const cloudflareConfig = getCloudflareConfig(args.toolExecution);
+    if (shouldIncludeCodingTools(args.toolExecution)) {
+      const selectedNames =
+        getSelectedCloudflareCodingToolNames(cloudflareConfig);
+      pruneCloudflareCodingToolAllowlist(toolMap, selectedNames);
+      if (
+        cloudflareConfig.fileCheckpointing === true ||
+        args.fileCheckpointer != null
+      ) {
+        const bundle = createCloudflareCodingToolBundle(cloudflareConfig, {
+          checkpointer: args.fileCheckpointer,
+        });
+        fileCheckpointer = bundle.checkpointer;
+        for (const cloudflareTool of bundle.tools) {
+          toolMap.set(cloudflareTool.name, cloudflareTool);
+          directToolNames.add(cloudflareTool.name);
+        }
+      } else {
+        for (const cloudflareTool of createCloudflareCodingTools(
+          cloudflareConfig
+        )) {
+          toolMap.set(cloudflareTool.name, cloudflareTool);
+          directToolNames.add(cloudflareTool.name);
+        }
+      }
+    }
+
+    const includeCodingTools = shouldIncludeCodingTools(args.toolExecution);
+    for (const name of CODE_EXECUTION_TOOLS) {
+      if (includeCodingTools) continue;
+      if (!toolMap.has(name)) continue;
+
+      const cloudflareTool = createCloudflareExecutionTool(
+        name,
+        cloudflareConfig
+      );
+      if (cloudflareTool == null) {
+        continue;
+      }
+
+      toolMap.set(name, cloudflareTool);
+      directToolNames.add(name);
+    }
+
+    return { toolMap, directToolNames, fileCheckpointer };
+  }
+
+  const localConfig = args.toolExecution?.local ?? {};
+
   if (shouldIncludeCodingTools(args.toolExecution)) {
     // Use the bundle factory when fileCheckpointing is on so we can
     // surface the checkpointer back to the caller — without this, the
@@ -163,7 +322,10 @@ export function resolveLocalExecutionTools(args: {
     // immediately discarded, making the public `fileCheckpointing`
     // config flag a silent no-op outside of direct
     // `createLocalCodingToolBundle()` use.
-    if (localConfig.fileCheckpointing === true || args.fileCheckpointer != null) {
+    if (
+      localConfig.fileCheckpointing === true ||
+      args.fileCheckpointer != null
+    ) {
       const bundle = createLocalCodingToolBundle(localConfig, {
         checkpointer: args.fileCheckpointer,
       });

package/src/types/graph.ts

@@ -408,6 +408,13 @@ export interface SubagentUpdateEvent {
   timestamp: string;
 }
 
+export interface LangfuseConfig {
+  enabled?: boolean;
+  publicKey?: string;
+  secretKey?: string;
+  baseUrl?: string;
+}
+
 export interface AgentInputs {
   agentId: string;
   /** Human-readable name for the agent (used in handoff context). Defaults to agentId if not provided. */
@@ -421,6 +428,8 @@ export interface AgentInputs {
   streamBuffer?: number;
   maxContextTokens?: number;
   clientOptions?: ClientOptions;
+  /** Per-agent Langfuse tracing configuration. */
+  langfuse?: LangfuseConfig;
   /** Dynamic system tail appended after stable instructions without provider cache markers. */
   additional_instructions?: string;
   reasoningKey?: 'reasoning_content' | 'reasoning';

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;