@librechat/agents 3.1.89 → 3.1.91

package/dist/types/types/graph.d.ts

@@ -288,6 +288,12 @@ export interface SubagentUpdateEvent {
     /** ISO timestamp for ordering / display. */
     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. */
@@ -301,6 +307,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/dist/types/types/tools.d.ts

@@ -284,9 +284,8 @@ export type FileRef = {
      * `true` when the codeapi sandbox echoed this entry as an unchanged
      * passthrough of an input the caller already owns (skill files,
      * downloaded inputs whose hash matched the baseline, inherited
-     * `.dirkeep` markers). The tool-result formatter renders these as
-     * "Available files" rather than "Generated files" so the LLM doesn't
-     * conflate infrastructure inputs with newly-produced outputs.
+     * `.dirkeep` markers). The host can use this flag to skip
+     * post-processing work for files the caller already owns.
      */
     inherited?: true;
 };
@@ -468,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 {
     /**
@@ -587,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 = {
     /**
@@ -741,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@librechat/agents",
-  "version": "3.1.89",
+  "version": "3.1.91",
   "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": "^4.6.1",
+    "@langfuse/otel": "^4.6.1",
+    "@langfuse/tracing": "^4.6.1",
     "@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

@@ -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) {
@@ -1562,6 +1599,13 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
           maxDepth: effectiveSubagentDepth,
           createChildGraph: (input): StandardGraph => {
             const childGraph = new StandardGraph(input);
+            childGraph.hookRegistry = this.hookRegistry;
+            /**
+             * Do not propagate `humanInTheLoop` into the child graph yet:
+             * nested subagent interrupts need a stable child checkpoint and
+             * resume bridge. Child hooks still fire; `ask` decisions fail
+             * closed inside the subagent until that flow is implemented.
+             */
             childGraph.toolOutputReferences = this.toolOutputReferences;
             childGraph.eagerEventToolExecution = this.eagerEventToolExecution;
             childGraph.toolExecution = this.toolExecution;

package/src/hooks/__tests__/executeHooks.test.ts

@@ -109,6 +109,44 @@ describe('executeHooks', () => {
     consoleWarnSpy.mockRestore();
   });
 
+  describe('abort listener management', () => {
+    it('uses one abort listener for many hooks on one matcher', async () => {
+      const registry = new HookRegistry();
+      const listenerCounts = new Map<AbortSignal, number>();
+      let maxAbortListeners = 0;
+      const addEventListenerSpy = jest
+        .spyOn(AbortSignal.prototype, 'addEventListener')
+        .mockImplementation(function (
+          this: AbortSignal,
+          type: string,
+          _listener: EventListenerOrEventListenerObject | null
+        ): void {
+          if (type !== 'abort') {
+            return;
+          }
+          const count = (listenerCounts.get(this) ?? 0) + 1;
+          listenerCounts.set(this, count);
+          maxAbortListeners = Math.max(maxAbortListeners, count);
+        });
+      const hooks = Array.from({ length: 12 }, () =>
+        runStartHook(async (): Promise<RunStartHookOutput> => ({}))
+      );
+
+      try {
+        registry.register('RunStart', { hooks });
+
+        await executeHooks({
+          registry,
+          input: runStartInput(),
+          timeoutMs: 1000,
+        });
+        expect(maxAbortListeners).toBe(1);
+      } finally {
+        addEventListenerSpy.mockRestore();
+      }
+    });
+  });
+
   describe('empty matcher set', () => {
     it('returns an empty aggregated result when no matchers are registered', async () => {
       const registry = new HookRegistry();

package/src/hooks/executeHooks.ts

@@ -46,6 +46,11 @@ interface HookOutcome {
   timedOut: boolean;
 }
 
+interface AbortRace {
+  promise: Promise<never>;
+  cleanup: () => void;
+}
+
 function freshResult(): AggregatedHookResult {
   return {
     additionalContexts: [],
@@ -110,10 +115,10 @@ async function runHook(
   hook: WideCallback,
   input: HookInput,
   signal: AbortSignal,
+  abortPromise: Promise<never>,
   matcher: WideMatcher
 ): Promise<HookOutcome> {
   const hookPromise = Promise.resolve().then(() => hook(input, signal));
-  const { promise: abortPromise, cleanup } = makeAbortPromise(signal);
   try {
     const output = await Promise.race([hookPromise, abortPromise]);
     return { matcher, output, error: null, timedOut: false };
@@ -124,8 +129,22 @@ async function runHook(
       error: describeError(err),
       timedOut: isTimeout(err),
     };
+  }
+}
+
+async function runMatcherHooks(
+  matcher: WideMatcher,
+  input: HookInput,
+  signal: AbortSignal
+): Promise<HookOutcome[]> {
+  const abortRace: AbortRace = makeAbortPromise(signal);
+  const tasks = matcher.hooks.map((hook) =>
+    runHook(hook, input, signal, abortRace.promise, matcher)
+  );
+  try {
+    return await Promise.all(tasks);
   } finally {
-    cleanup();
+    abortRace.cleanup();
   }
 }
 
@@ -373,7 +392,7 @@ export async function executeHooks(
   }
 
   // --- SYNC CRITICAL SECTION: once-matcher removal must complete before any await ---
-  const tasks: Promise<HookOutcome>[] = [];
+  const tasks: Promise<HookOutcome[]>[] = [];
   for (const matcher of matchers) {
     if (!matchesQuery(matcher.pattern, matchQuery)) {
       continue;
@@ -381,18 +400,19 @@ export async function executeHooks(
     if (matcher.once === true) {
       registry.removeMatcher(event, matcher, sessionId);
     }
+    if (matcher.hooks.length === 0) {
+      continue;
+    }
     const perHookTimeout = matcher.timeout ?? timeoutMs;
     const matcherSignal = combineSignals(signal, perHookTimeout);
-    for (const hook of matcher.hooks) {
-      tasks.push(runHook(hook, input, matcherSignal, matcher));
-    }
+    tasks.push(runMatcherHooks(matcher, input, matcherSignal));
   }
   // --- END SYNC CRITICAL SECTION ---
   if (tasks.length === 0) {
     return freshResult();
   }
 
-  const outcomes = await Promise.all(tasks);
+  const outcomes = (await Promise.all(tasks)).flat();
   reportErrors(outcomes, event, logger);
   const aggregated = fold(outcomes);
   /**

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. */