@librechat/agents 3.2.65 → 3.2.66

package/src/specs/subagent.test.ts

@@ -312,6 +312,186 @@ describe('Subagent Integration', () => {
     createWorkflowSpy.mockRestore();
   });
 
+  it('forwards event-driven tools through nested child graphs', async () => {
+    const originalCreateWorkflow = StandardGraph.prototype.createWorkflow;
+    const parentToolHandler = jest.fn(
+      (_event: string, rawData: unknown): void => {
+        const request = rawData as t.ToolExecuteBatchRequest;
+        request.resolve(
+          request.toolCalls.map((call) => ({
+            toolCallId: call.id,
+            status: 'success' as const,
+            content: `ran ${call.name}`,
+          }))
+        );
+      }
+    );
+    const parentUpdateHandler = jest.fn();
+    let specialistToolDefinitions: t.LCTool[] | undefined;
+    let forwardedToolResults: t.ToolExecuteResult[] | undefined;
+
+    const createWorkflowSpy = jest
+      .spyOn(StandardGraph.prototype, 'createWorkflow')
+      .mockImplementation(function (this: StandardGraph) {
+        const workflow = originalCreateWorkflow.call(this);
+        if (this.defaultAgentId === 'router') {
+          return {
+            invoke: jest.fn(async () => {
+              const routerContext = this.agentContexts.get('router');
+              const nestedTool = (
+                routerContext?.graphTools as t.GenericTool[] | undefined
+              )?.find(
+                (tool) => 'name' in tool && tool.name === Constants.SUBAGENT
+              );
+              if (nestedTool == null) {
+                throw new Error('Nested subagent tool was not created');
+              }
+              await nestedTool.invoke(
+                {
+                  description: 'Use the event-driven lookup tool.',
+                  subagent_type: 'specialist',
+                },
+                callerConfig
+              );
+              return { messages: [new AIMessage('router done')] };
+            }),
+          } as unknown as ReturnType<StandardGraph['createWorkflow']>;
+        }
+        if (this.defaultAgentId === 'specialist') {
+          specialistToolDefinitions =
+            this.agentContexts.get('specialist')?.toolDefinitions;
+          return {
+            invoke: jest.fn(async (_state, options) => {
+              const invokeOptions = options as
+                | { callbacks?: unknown[] }
+                | undefined;
+              const forwarder = (invokeOptions?.callbacks ?? [])[0] as
+                | {
+                    handleCustomEvent?: (
+                      eventName: string,
+                      data: unknown,
+                      runId: string
+                    ) => Promise<void> | void;
+                  }
+                | undefined;
+              if (forwarder?.handleCustomEvent != null) {
+                forwardedToolResults = await new Promise<t.ToolExecuteResult[]>(
+                  (resolve, reject) => {
+                    const request: t.ToolExecuteBatchRequest = {
+                      toolCalls: [
+                        { id: 'nested-call', name: 'mcp_lookup', args: {} },
+                      ],
+                      agentId: 'specialist',
+                      resolve,
+                      reject,
+                    };
+                    void forwarder.handleCustomEvent?.(
+                      GraphEvents.ON_TOOL_EXECUTE,
+                      request,
+                      'specialist-run'
+                    );
+                  }
+                );
+                await forwarder.handleCustomEvent(
+                  GraphEvents.ON_RUN_STEP,
+                  { id: 'specialist-step', type: 'tool_calls' },
+                  'specialist-run'
+                );
+              }
+              return { messages: [new AIMessage('specialist done')] };
+            }),
+          } as unknown as ReturnType<StandardGraph['createWorkflow']>;
+        }
+        return workflow;
+      });
+
+    const rootAgent: t.AgentInputs = {
+      agentId: 'root',
+      provider: Providers.OPENAI,
+      clientOptions: { modelName: 'gpt-4o-mini', apiKey: 'test-key' },
+      instructions: 'Delegate through the router.',
+      maxContextTokens: 8000,
+      maxSubagentDepth: 2,
+      subagentConfigs: [
+        {
+          type: 'router',
+          name: 'Router',
+          description: 'Routes work to specialists.',
+          allowNested: true,
+          agentInputs: {
+            agentId: 'router',
+            provider: Providers.OPENAI,
+            clientOptions: { modelName: 'gpt-4o-mini', apiKey: 'test-key' },
+            instructions: 'Delegate to the specialist.',
+            maxContextTokens: 8000,
+            subagentConfigs: [
+              {
+                type: 'specialist',
+                name: 'Specialist',
+                description: 'Uses an event-driven tool.',
+                agentInputs: {
+                  agentId: 'specialist',
+                  provider: Providers.OPENAI,
+                  clientOptions: {
+                    modelName: 'gpt-4o-mini',
+                    apiKey: 'test-key',
+                  },
+                  instructions: 'Use the lookup tool.',
+                  maxContextTokens: 8000,
+                  toolDefinitions: [{ name: 'mcp_lookup' }],
+                },
+              },
+            ],
+          },
+        },
+      ],
+    };
+
+    try {
+      const run = await Run.create<t.IState>({
+        runId: `nested-event-tools-${Date.now()}`,
+        graphConfig: { type: 'standard', agents: [rootAgent] },
+        customHandlers: {
+          [GraphEvents.ON_TOOL_EXECUTE]: { handle: parentToolHandler },
+          [GraphEvents.ON_SUBAGENT_UPDATE]: {
+            handle: parentUpdateHandler,
+          },
+        },
+        returnContent: true,
+        skipCleanup: true,
+      });
+      const rootContext = (run.Graph as StandardGraph).agentContexts.get(
+        'root'
+      );
+      const rootSubagentTool = (
+        rootContext?.graphTools as t.GenericTool[] | undefined
+      )?.find((tool) => 'name' in tool && tool.name === Constants.SUBAGENT);
+      expect(rootSubagentTool).toBeDefined();
+
+      await rootSubagentTool!.invoke(
+        { description: 'Route this task.', subagent_type: 'router' },
+        callerConfig
+      );
+
+      expect(specialistToolDefinitions).toEqual([{ name: 'mcp_lookup' }]);
+      expect(parentToolHandler).toHaveBeenCalledTimes(1);
+      expect(forwardedToolResults).toEqual([
+        {
+          toolCallId: 'nested-call',
+          status: 'success',
+          content: 'ran mcp_lookup',
+        },
+      ]);
+      const forwardedSubagentTypes = parentUpdateHandler.mock.calls.map(
+        ([, data]) => (data as t.SubagentUpdateEvent).subagentType
+      );
+      expect(forwardedSubagentTypes).toContain('router');
+      expect(forwardedSubagentTypes).not.toContain('specialist');
+    } finally {
+      createWorkflowSpy.mockRestore();
+    }
+  });
+
   it('should not create subagent tool when maxSubagentDepth is 0', async () => {
     const agentWithZeroDepth: t.AgentInputs = {
       ...createParentAgent(),

package/src/tools/BashExecutor.ts

@@ -58,17 +58,18 @@ Usage:
 `.trim();
 
 /**
- * Bash statefulness is filesystem-tier: on a warm session the machine (files
- * including /tmp, installed packages, background processes) persists between
- * calls, but each call may start a fresh shell — so shell variables and cwd
- * are NOT reliable, and the machine can be reset at any time. Only /mnt/data
- * is durable.
+ * Bash statefulness is filesystem-tier and scoped to `/mnt/data`. The machine
+ * is warm across calls, but each call runs in a fresh sandbox (new process
+ * tree + private /tmp), so background processes are reaped when the call ends
+ * and anything written outside /mnt/data is discarded. The note must not
+ * promise otherwise: a model told background processes survive will start a
+ * server in one call and assume it is listening in the next.
  */
 export const STATEFUL_BASH_NOTE =
-  'Session state (best-effort): commands in this conversation usually run on the same machine, so files (including /tmp), installed packages, and running background processes from earlier calls typically persist. Each call may still start a fresh shell — do not rely on shell variables or the working directory carrying over — and the machine may be reset at any time. Only /mnt/data is durable.';
+  'Session state: commands in this conversation run on the same warm machine, so files written to /mnt/data persist between calls. Each call runs in a fresh, isolated sandbox: shell variables, the working directory, /tmp, and background processes do NOT survive after the call returns — a process started in one call is terminated when that call ends. Only /mnt/data is durable (the machine itself may also be reset at any time).';
 
 export const StatefulBashExecutionToolDescription = `
-Runs bash commands and returns stdout/stderr output from a session-based execution environment, similar to a long-running machine.
+Runs bash commands and returns stdout/stderr output. Commands in this conversation share one warm machine with a persistent /mnt/data, but each command runs in its own isolated sandbox (not a persistent shell session).
 
 ${STATEFUL_BASH_NOTE}
 
@@ -125,7 +126,7 @@ export function buildBashExecutionToolDescription(options?: {
 const STATELESS_BASH_PARAM_NOTE =
   'The environment is stateless; variables and state don\'t persist between executions.';
 const STATEFUL_BASH_PARAM_NOTE =
-  'Files, installed packages, and background processes usually persist between calls, but each call may start a fresh shell (do not rely on shell variables or cwd) and the machine may reset. Only /mnt/data is durable.';
+  'Files written to /mnt/data persist between calls on the same warm machine. Each call runs in a fresh sandbox: shell variables, cwd, /tmp, and background processes do NOT survive the call. Only /mnt/data is durable.';
 
 export function buildBashExecutionToolSchema(opts?: {
   statefulSessions?: boolean;

package/src/tools/CodeExecutor.ts

@@ -150,16 +150,18 @@ Usage:
 `.trim();
 
 /**
- * Best-effort statefulness note. Deliberately hedged: warm reuse is an
- * optimization, not a guarantee (the runtime may be reset on idle timeout,
- * eviction, or the 8h VM lifetime), so the model must never depend on carried
- * state for correctness and must persist anything durable to /mnt/data.
+ * Statefulness here is FILESYSTEM-tier, not runtime-tier. Executions in a
+ * session reuse one warm machine, so `/mnt/data` carries across calls — but
+ * every execution is a brand-new interpreter process in a fresh sandbox, so
+ * variables and imports never survive. The note must not imply otherwise: a
+ * model told its in-memory state persists writes `df = ...` in one call and
+ * `df.head()` in the next, then hits a NameError it was told to treat as rare.
  */
 export const STATEFUL_ENV_NOTE =
-  'Session state (best-effort): consecutive executions in this conversation usually share one runtime, so variables, imports, and in-memory data from earlier successful calls are typically still available. The runtime may be reset at any time, so treat carried-over state as an optimization, never a guarantee. Anything that must survive MUST be written to /mnt/data. If a NameError/ImportError signals lost state, re-run the needed setup and continue.';
+  'Session state: executions in this conversation run on the same warm machine, so files persist between calls — but each execution is a NEW process. Variables, imports, and in-memory data NEVER carry over: every call must re-import and rebuild the state it needs. Only /mnt/data is durable (the machine itself may also be reset at any time), so write anything that must survive there and read it back next call.';
 
 export const StatefulCodeExecutionToolDescription = `
-Runs code and returns stdout/stderr output from a session-based execution environment, similar to a long-running command-line session.
+Runs code and returns stdout/stderr output. Executions in this conversation share one warm machine with a persistent /mnt/data, but each execution runs as a separate process (not a notebook-style kernel).
 
 ${STATEFUL_ENV_NOTE}
 
@@ -181,7 +183,7 @@ export function buildCodeExecutionToolDescription(opts?: {
 const STATELESS_CODE_PARAM_NOTE =
   'The environment is stateless; variables and imports don\'t persist between executions.';
 const STATEFUL_CODE_PARAM_NOTE =
-  'Executions in this conversation usually share one runtime: variables and imports from prior successful calls are typically still defined, but the runtime may reset between calls. Rebuild state on NameError/ImportError; persist anything important to /mnt/data.';
+  'Executions in this conversation share one warm machine, so files written to /mnt/data persist between calls. Each execution is a new process: variables and imports do NOT carry over — re-import and reload from /mnt/data every call.';
 
 export function buildCodeExecutionToolSchema(opts?: {
   statefulSessions?: boolean;

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

@@ -65,13 +65,24 @@ describe('buildBashExecutionToolDescription', () => {
       ).toBe(StatefulBashExecutionToolDescription);
     });
 
-    it('hedges: usually-persists but may-reset, and only /mnt/data is durable', () => {
+    /* Filesystem-tier only: each call runs in a fresh sandbox (new process
+     * tree + private /tmp), so background processes are reaped and non-
+     * /mnt/data writes are discarded. The description must not promise
+     * otherwise. */
+    it('promises /mnt/data persistence WITHOUT promising surviving processes or /tmp', () => {
       const d = StatefulBashExecutionToolDescription;
-      expect(d).toContain('usually');
-      expect(d).toContain('may be reset');
+      expect(d).toContain('same warm machine');
       expect(d).toContain('Only /mnt/data is durable');
-      /* filesystem-tier, not shell-variable-tier */
-      expect(d).toContain('do not rely on shell variables');
+      expect(d).toContain('background processes do NOT survive');
+      expect(d).toContain('/tmp');
+    });
+
+    it('never claims /tmp or background processes persist between calls', () => {
+      const d = StatefulBashExecutionToolDescription;
+      expect(d).not.toContain('files (including /tmp)');
+      expect(d).not.toContain(
+        'background processes from earlier calls typically persist'
+      );
     });
 
     it('keeps the artifact-path guidance in both variants', () => {

package/src/tools/__tests__/CodeExecutor.stateful.test.ts

@@ -41,22 +41,33 @@ describe('CodeExecutor stateful description', () => {
     );
   });
 
-  it('hedges the stateful wording and keeps /mnt/data as the durable store', () => {
+  /* Statefulness is filesystem-tier only: the machine is warm across calls,
+   * but every execution is a new interpreter process, so in-memory state never
+   * carries over. The description must not imply a notebook-style kernel. */
+  it('promises filesystem persistence WITHOUT promising a shared runtime', () => {
     const d = StatefulCodeExecutionToolDescription;
-    expect(d).toContain('usually share one runtime');
-    expect(d).toContain('may be reset at any time');
-    expect(d).toContain('MUST be written to /mnt/data');
+    expect(d).toContain('same warm machine');
+    expect(d).toContain('/mnt/data');
+    expect(d).toContain('NEW process');
+    expect(d).toContain('NEVER carry over');
     expect(d).toContain(CODE_ARTIFACT_PATH_GUIDANCE);
   });
 
+  it('never claims variables/imports survive between executions', () => {
+    const d = StatefulCodeExecutionToolDescription;
+    expect(d).not.toContain('share one runtime');
+    expect(d).not.toContain('typically still available');
+  });
+
   it('adjusts the code-param note per mode', () => {
     const stateless =
       buildCodeExecutionToolSchema().properties.code.description;
     const stateful = buildCodeExecutionToolSchema({ statefulSessions: true })
       .properties.code.description;
     expect(stateless).toContain('variables and imports don\'t persist');
-    expect(stateful).toContain('typically still defined');
-    expect(stateful).toContain('may reset between calls');
+    expect(stateful).toContain('do NOT carry over');
+    expect(stateful).toContain('/mnt/data');
+    expect(stateful).not.toContain('typically still defined');
   });
 });
 

package/src/types/graph.ts

@@ -534,9 +534,9 @@ export type LangfuseToolOutputTracingConfig = {
 
 export type LangfuseToolNodeTracingConfig = {
   /**
-   * Overrides ToolNode callback tracing. ToolNode spans are exported by the
-   * env-backed Langfuse callback, so this only enables tracing when that
-   * callback is configured.
+   * Opts into the internal ToolNode batch observation. Graph tool-dispatch
+   * and individual tool observations are exported without this wrapper, so
+   * the default is false to avoid a redundant hierarchy level.
    */
   enabled?: boolean;
 };
@@ -546,6 +546,13 @@ export interface LangfuseConfig {
   publicKey?: string;
   secretKey?: string;
   baseUrl?: string;
+  /**
+   * Environment identifier attached to exported traces (Langfuse
+   * `environment`). When unset, falls back to `LANGFUSE_TRACING_ENVIRONMENT`
+   * then `NODE_ENV`, so production traces are not collapsed under the
+   * `default` environment.
+   */
+  environment?: string;
   metadata?: Record<string, string | number | boolean | null | undefined>;
   /**
    * Internal OTLP span attributes to attach to Langfuse observations before