@librechat/agents 3.2.58 → 3.2.60

package/src/tools/ToolNode.ts

@@ -37,6 +37,11 @@ import type {
   PostToolBatchEntry,
 } from '@/hooks';
 import type * as t from '@/types';
+import {
+  buildToolExecutionRequestPlan,
+  resolveRuntimeSessionHint,
+  recordArgsEqual,
+} from '@/tools/eagerEventExecution';
 import {
   resolveLangfuseRuntimeScope,
   withLangfuseRuntimeScope,
@@ -45,10 +50,6 @@ import {
   buildReferenceKey,
   ToolOutputReferenceRegistry,
 } from '@/tools/toolOutputReferences';
-import {
-  buildToolExecutionRequestPlan,
-  recordArgsEqual,
-} from '@/tools/eagerEventExecution';
 import {
   calculateMaxToolResultChars,
   truncateToolResultContent,
@@ -415,6 +416,13 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
   private agentLangfuse?: t.LangfuseConfig;
   toolCallStepIds?: Map<string, string>;
   errorHandler?: t.ToolNodeConstructorParams['errorHandler'];
+  /**
+   * Tool call ids whose `errorHandler` did NOT dispatch the error completion
+   * event (it returned `false` or threw). The output loop must dispatch the
+   * completion for these itself — skipping them there would strand the
+   * client's tool-call part without a terminal event.
+   */
+  private undispatchedToolErrors: Set<string> = new Set();
   private toolUsageCount: Map<string, number>;
   /** Maps toolCallId → turn captured in runTool, used by handleRunToolCompletions */
   private toolCallTurns: Map<string, number> = new Map();
@@ -456,6 +464,21 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
   private executingAgentId?: string;
   /** Tool names that bypass event dispatch and execute directly (e.g., graph-managed handoff tools) */
   private directToolNames?: Set<string>;
+  /**
+   * Tool names whose in-process body may raise a LangGraph `interrupt()`
+   * mid-execution (e.g. `ask_user_question`). Used only to REORDER within
+   * the direct group: a tool named here that is *already* direct (a real
+   * in-process graphTool — the only kind whose body can reach
+   * `interrupt()`) is scheduled ahead of its non-interrupting direct
+   * siblings, so a mid-body interrupt unwinds the ToolNode before a
+   * non-idempotent sibling executes and LangGraph's resume-time batch
+   * re-execution can't double it. This set is deliberately NOT folded
+   * into direct classification: a name that resolves to a schema-only
+   * event stub (an inherited `toolDefinition` with no executable
+   * instance) stays event-dispatched — forcing it direct would invoke
+   * the stub, which throws. See {@link t.ToolNodeOptions.interruptingToolNames}.
+   */
+  private interruptingToolNames?: Set<string>;
   /**
    * File checkpointer extracted from the local coding tool bundle when
    * `toolExecution.local.fileCheckpointing === true`. Exposed via
@@ -517,6 +540,7 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
     agentId,
     executingAgentId,
     directToolNames,
+    interruptingToolNames,
     codeSessionToolNames,
     maxContextTokens,
     maxToolResultChars,
@@ -555,6 +579,10 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
     // existing agentId option) still get attribution without knowing the new option.
     this.executingAgentId = executingAgentId ?? agentId;
     this.directToolNames = directToolNames;
+    this.interruptingToolNames =
+      interruptingToolNames != null && interruptingToolNames.size > 0
+        ? interruptingToolNames
+        : undefined;
     this.codeSessionToolNames =
       codeSessionToolNames != null && codeSessionToolNames.length > 0
         ? new Set(codeSessionToolNames)
@@ -997,6 +1025,20 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
             );
           }
         }
+
+        /**
+         * Stateful runtime session hint — orthogonal to the transient
+         * exec-session above, and injected independently (a first call has a
+         * hint but no exec session yet). Explicit host hint wins; otherwise
+         * fall back to the conversation's thread_id.
+         */
+        const runtimeSessionHint = this.resolveRuntimeSessionHint(config);
+        if (runtimeSessionHint != null) {
+          invokeParams = {
+            ...invokeParams,
+            _runtime_session_hint: runtimeSessionHint,
+          };
+        }
       }
 
       /**
@@ -1125,7 +1167,7 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
       }
       if (this.errorHandler) {
         try {
-          await this.errorHandler(
+          const dispatched = await this.errorHandler(
             {
               error: e,
               id: call.id!,
@@ -1134,7 +1176,24 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
             },
             config.metadata
           );
+          if (dispatched === false && call.id != null && call.id !== '') {
+            /**
+             * The handler could not dispatch the error completion (typically
+             * a resume pass, where a fast-failing tool errors before the
+             * step replay registers its run step). Remember the call so the
+             * output loop dispatches the completion itself instead of
+             * assuming the handler covered it.
+             */
+            this.undispatchedToolErrors.add(call.id);
+          }
         } catch (handlerError) {
+          // A THROWN handler is not proof the completion wasn't dispatched: the
+          // built-in session handler emits `tool.completed` BEFORE invoking a
+          // user ON_RUN_STEP_COMPLETED callback, so a throw from that callback
+          // has already dispatched. Marking it undispatched would make the
+          // fallback loop re-emit a duplicate completion — only an explicit
+          // `false` return (handled above) means "nothing dispatched"; a throw
+          // is just logged.
           // eslint-disable-next-line no-console
           console.error('Error in errorHandler:', {
             toolName: call.name,
@@ -1783,6 +1842,17 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
     );
   }
 
+  /** Delegates to the shared resolver so the direct and event-driven planning
+   *  paths derive the runtime session hint identically. */
+  private resolveRuntimeSessionHint(
+    config: RunnableConfig
+  ): string | undefined {
+    return resolveRuntimeSessionHint(
+      this.toolExecution,
+      config.configurable?.thread_id as string | undefined
+    );
+  }
+
   private storeCodeSessionFromResults(
     results: t.ToolExecuteResult[],
     requestMap: Map<string, t.ToolCallRequest>
@@ -1849,9 +1919,22 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
       const toolCallId = call.id ?? '';
 
       // Skip error ToolMessages when errorHandler already dispatched ON_RUN_STEP_COMPLETED
-      // via handleToolCallErrorStatic. Without this check, errors would be double-dispatched.
+      // via handleToolCallErrorStatic — dispatching again here would double-dispatch.
+      // When the handler reported it could NOT dispatch (no run step registered yet at
+      // error time, e.g. a fast-failing tool on a resume pass), fall through: by now the
+      // step replay has usually registered the id, so this loop's dispatch is the only
+      // terminal event the client's tool-call part will ever get.
       if (toolMessage.status === 'error' && this.errorHandler != null) {
-        continue;
+        if (this.undispatchedToolErrors.has(toolCallId)) {
+          // CONSUME the marker: this loop now owns the dispatch for this id.
+          // Leaving it set would let a later re-entry (same ToolNode instance
+          // re-executing the batch, where the handler CAN dispatch) fall
+          // through here too and double-dispatch — and the set would grow
+          // unbounded across a long-lived graph's fast-failing calls.
+          this.undispatchedToolErrors.delete(toolCallId);
+        } else {
+          continue;
+        }
       }
 
       if (this.sessions && this.participatesInCodeSession(call.name)) {
@@ -2492,12 +2575,18 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
             entry.call.name === Constants.READ_FILE
               ? this.getCodeSessionContext()
               : undefined;
+          const runtimeSessionHint = this.participatesInCodeSession(
+            entry.call.name
+          )
+            ? this.resolveRuntimeSessionHint(config)
+            : undefined;
           return {
             id: entry.call.id,
             name: entry.call.name,
             args: entry.args,
             stepId: entry.stepId,
             codeSessionContext,
+            runtimeSessionHint,
           };
         }),
         usageCount: this.toolUsageCount,
@@ -3148,6 +3237,94 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
     return converted;
   }
 
+  /**
+   * Execute a group of direct (in-process) tool calls with interrupt-safe
+   * ordering, returning outputs aligned 1:1 with `directCalls`.
+   *
+   * Fast path (the common case): when no call in the group is in
+   * `interruptingToolNames`, this is a single `Promise.all` — byte-for-byte
+   * the prior behavior, so ordinary batches are unaffected.
+   *
+   * Interrupt-safe path: when the group contains an interrupting tool (e.g.
+   * `ask_user_question`, whose body raises a LangGraph `interrupt()` to
+   * collect a human answer), the interrupting calls run as their own awaited
+   * group **first**; only after they all settle without interrupting do the
+   * remaining (potentially non-idempotent) siblings run. If an interrupting
+   * call throws a `GraphInterrupt`, the `await` below rejects and unwinds the
+   * whole ToolNode *before* any non-interrupting sibling has started — so a
+   * sibling with real side effects (send_email, billing) never executes on
+   * the first pass. On the resume pass LangGraph re-runs the batch from the
+   * top; the interrupting tool resolves with the host's answer instead of
+   * throwing, and the siblings execute for the FIRST time, exactly once.
+   *
+   * Without this ordering, a flat `Promise.all` starts every sibling
+   * concurrently, so a non-idempotent sibling can complete its side effect
+   * before the interrupt unwinds and then run a SECOND time on resume — the
+   * duplicate side effect this method exists to prevent. Interrupting tools
+   * are expected to be side-effect-free (they only suspend), so running them
+   * as a group and re-running them on resume is harmless.
+   *
+   * `batchIndices[i]` is `directCalls[i]`'s position within the parent
+   * ToolNode batch (used for `{{tool<i>turn<n>}}` registration); it is
+   * preserved regardless of execution order. `baseContext` carries the
+   * batch-scoped fields every call shares; `batchIndex` is filled in
+   * per-call here.
+   */
+  private async runDirectBatchInterruptSafe(
+    directCalls: ToolCall[],
+    batchIndices: number[],
+    config: RunnableConfig,
+    baseContext: Omit<RunToolBatchContext<T>, 'batchIndex'>
+  ): Promise<(BaseMessage | Command)[]> {
+    const runOne = (
+      call: ToolCall,
+      position: number
+    ): Promise<BaseMessage | Command> =>
+      this.runDirectToolWithLifecycleHooks(call, config, {
+        ...baseContext,
+        batchIndex: batchIndices[position],
+      });
+
+    const interrupting = this.interruptingToolNames;
+    const hasInterrupting =
+      interrupting != null &&
+      directCalls.some((call) => interrupting.has(call.name));
+
+    if (!hasInterrupting) {
+      return Promise.all(directCalls.map((call, i) => runOne(call, i)));
+    }
+
+    const outputs: (BaseMessage | Command)[] = new Array(directCalls.length);
+    const interruptingPositions: number[] = [];
+    const regularPositions: number[] = [];
+    for (let i = 0; i < directCalls.length; i++) {
+      if (interrupting.has(directCalls[i].name)) {
+        interruptingPositions.push(i);
+      } else {
+        regularPositions.push(i);
+      }
+    }
+
+    // Interrupting group first. A GraphInterrupt here propagates out of the
+    // `await` before any regular sibling is dispatched below.
+    const interruptingOutputs = await Promise.all(
+      interruptingPositions.map((i) => runOne(directCalls[i], i))
+    );
+    interruptingPositions.forEach((i, k) => {
+      outputs[i] = interruptingOutputs[k];
+    });
+
+    // No interrupting call suspended — safe to run the remaining siblings.
+    const regularOutputs = await Promise.all(
+      regularPositions.map((i) => runOne(directCalls[i], i))
+    );
+    regularPositions.forEach((i, k) => {
+      outputs[i] = regularOutputs[k];
+    });
+
+    return outputs;
+  }
+
   /**
    * Execute all tool calls via ON_TOOL_EXECUTE event dispatch.
    * Injected messages are placed AFTER ToolMessages to respect provider
@@ -3394,18 +3571,18 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
         const directAdditionalContexts: string[] = [];
         const directOutputs: (BaseMessage | Command)[] =
           directCalls.length > 0
-            ? await Promise.all(
-              directCalls.map((call, i) =>
-                this.runDirectToolWithLifecycleHooks(call, config, {
-                  batchIndex: directIndices[i],
-                  turn,
-                  batchScopeId,
-                  resolvedArgsByCallId,
-                  preBatchSnapshot,
-                  additionalContextsSink: directAdditionalContexts,
-                  runInput: input as T,
-                })
-              )
+            ? await this.runDirectBatchInterruptSafe(
+              directCalls,
+              directIndices,
+              config,
+              {
+                turn,
+                batchScopeId,
+                resolvedArgsByCallId,
+                preBatchSnapshot,
+                additionalContextsSink: directAdditionalContexts,
+                runInput: input as T,
+              }
             )
             : [];
 
@@ -3459,18 +3636,18 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
         const preBatchSnapshot =
           this.toolOutputRegistry?.snapshot(batchScopeId);
         const directAdditionalContexts: string[] = [];
-        const toolOutputs = await Promise.all(
-          filteredCalls.map((call, i) =>
-            this.runDirectToolWithLifecycleHooks(call, config, {
-              batchIndex: i,
-              turn,
-              batchScopeId,
-              resolvedArgsByCallId,
-              preBatchSnapshot,
-              additionalContextsSink: directAdditionalContexts,
-              runInput: input as T,
-            })
-          )
+        const toolOutputs = await this.runDirectBatchInterruptSafe(
+          filteredCalls,
+          filteredCalls.map((_call, i) => i),
+          config,
+          {
+            turn,
+            batchScopeId,
+            resolvedArgsByCallId,
+            preBatchSnapshot,
+            additionalContextsSink: directAdditionalContexts,
+            runInput: input as T,
+          }
         );
         await this.handleRunToolCompletions(
           filteredCalls,

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

@@ -2,8 +2,10 @@ import { describe, it, expect } from '@jest/globals';
 import {
   BashExecutionToolDescription,
   BashToolOutputReferencesGuide,
+  StatefulBashExecutionToolDescription,
   buildBashExecutionToolDescription,
 } from '../BashExecutor';
+import { CODE_ARTIFACT_PATH_GUIDANCE } from '../CodeExecutor';
 
 describe('buildBashExecutionToolDescription', () => {
   it('returns the base description by default', () => {
@@ -55,4 +57,41 @@ describe('buildBashExecutionToolDescription', () => {
     });
     expect(composed.includes(`${BashExecutionToolDescription}\n\n`)).toBe(true);
   });
+
+  describe('stateful variant', () => {
+    it('selects the stateful description when statefulSessions is on', () => {
+      expect(
+        buildBashExecutionToolDescription({ statefulSessions: true })
+      ).toBe(StatefulBashExecutionToolDescription);
+    });
+
+    it('hedges: usually-persists but may-reset, and only /mnt/data is durable', () => {
+      const d = StatefulBashExecutionToolDescription;
+      expect(d).toContain('usually');
+      expect(d).toContain('may be reset');
+      expect(d).toContain('Only /mnt/data is durable');
+      /* filesystem-tier, not shell-variable-tier */
+      expect(d).toContain('do not rely on shell variables');
+    });
+
+    it('keeps the artifact-path guidance in both variants', () => {
+      expect(BashExecutionToolDescription).toContain(
+        CODE_ARTIFACT_PATH_GUIDANCE
+      );
+      expect(StatefulBashExecutionToolDescription).toContain(
+        CODE_ARTIFACT_PATH_GUIDANCE
+      );
+    });
+
+    it('still composes with the output-references guide', () => {
+      const composed = buildBashExecutionToolDescription({
+        statefulSessions: true,
+        enableToolOutputReferences: true,
+      });
+      expect(composed.startsWith(StatefulBashExecutionToolDescription)).toBe(
+        true
+      );
+      expect(composed).toContain(BashToolOutputReferencesGuide);
+    });
+  });
 });

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

@@ -0,0 +1,113 @@
+import { describe, it, expect, jest, afterEach } from '@jest/globals';
+import type { RunnableConfig } from '@langchain/core/runnables';
+
+/* CodeExecutor imports the default export of node-fetch; capture POST bodies. */
+const fetchCalls: Array<Record<string, unknown>> = [];
+jest.mock('node-fetch', () => ({
+  __esModule: true,
+  default: async (_url: string, init?: { body?: string }) => {
+    fetchCalls.push(JSON.parse(init?.body ?? '{}'));
+    return {
+      ok: true,
+      json: async () => ({
+        session_id: 's1',
+        stdout: 'ok',
+        stderr: '',
+        files: [],
+      }),
+    };
+  },
+}));
+
+import {
+  CODE_ARTIFACT_PATH_GUIDANCE,
+  CodeExecutionToolDescription,
+  StatefulCodeExecutionToolDescription,
+  buildCodeExecutionToolDescription,
+  buildCodeExecutionToolSchema,
+  createCodeExecutionTool,
+} from '../CodeExecutor';
+
+describe('CodeExecutor stateful description', () => {
+  it('selects the stateful description only when statefulSessions is on', () => {
+    expect(buildCodeExecutionToolDescription()).toBe(
+      CodeExecutionToolDescription
+    );
+    expect(buildCodeExecutionToolDescription({ statefulSessions: false })).toBe(
+      CodeExecutionToolDescription
+    );
+    expect(buildCodeExecutionToolDescription({ statefulSessions: true })).toBe(
+      StatefulCodeExecutionToolDescription
+    );
+  });
+
+  it('hedges the stateful wording and keeps /mnt/data as the durable store', () => {
+    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(CODE_ARTIFACT_PATH_GUIDANCE);
+  });
+
+  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');
+  });
+});
+
+describe('CodeExecutor runtime_session_hint wire field', () => {
+  afterEach(() => {
+    fetchCalls.length = 0;
+  });
+
+  async function run(
+    toolCall: Record<string, unknown>,
+    params: Record<string, unknown> = {}
+  ): Promise<Record<string, unknown>[]> {
+    const codeTool = createCodeExecutionTool(params);
+    await codeTool.invoke({ lang: 'py', code: 'print(1)' }, {
+      toolCall,
+    } as unknown as RunnableConfig);
+    return fetchCalls;
+  }
+
+  it('sends runtime_session_hint when ToolNode injected it', async () => {
+    const calls = await run({ _runtime_session_hint: 'conv-42' });
+    expect(calls[0].runtime_session_hint).toBe('conv-42');
+  });
+
+  it('omits runtime_session_hint when not injected', async () => {
+    const calls = await run({});
+    expect('runtime_session_hint' in calls[0]).toBe(false);
+  });
+
+  it('does not leak the statefulSessions factory flag onto the wire', async () => {
+    const calls = await run({}, { statefulSessions: true });
+    expect('statefulSessions' in calls[0]).toBe(false);
+  });
+
+  it('strips a model-supplied runtime_session_hint from the raw args', async () => {
+    const codeTool = createCodeExecutionTool({});
+    await codeTool.invoke(
+      { lang: 'py', code: 'print(1)', runtime_session_hint: 'model-picked' },
+      { toolCall: {} } as unknown as RunnableConfig
+    );
+    expect('runtime_session_hint' in fetchCalls[0]).toBe(false);
+  });
+
+  it('lets only the ToolNode-injected hint reach the wire, ignoring model args', async () => {
+    const codeTool = createCodeExecutionTool({});
+    await codeTool.invoke(
+      { lang: 'py', code: 'print(1)', runtime_session_hint: 'model-picked' },
+      {
+        toolCall: { _runtime_session_hint: 'host-conv' },
+      } as unknown as RunnableConfig
+    );
+    expect(fetchCalls[0].runtime_session_hint).toBe('host-conv');
+  });
+});

package/src/tools/__tests__/ToolNode.session.test.ts

@@ -1263,4 +1263,90 @@ describe('ToolNode code execution session management', () => {
       );
     });
   });
+
+  describe('stateful runtime session hint injection', () => {
+    it('injects the explicit runtimeSessionHint when statefulSessions is on', async () => {
+      const capturedConfigs: Record<string, unknown>[] = [];
+      const mockTool = createMockCodeTool({ capturedConfigs });
+      const toolNode = new ToolNode({
+        tools: [mockTool],
+        sessions: new Map(),
+        toolExecution: {
+          engine: 'sandbox',
+          sandbox: {
+            statefulSessions: true,
+            runtimeSessionHint: 'conv-explicit',
+          },
+        },
+      });
+
+      await toolNode.invoke({ messages: [createAIMessageWithCodeCall('c1')] });
+
+      expect(capturedConfigs[0]._runtime_session_hint).toBe('conv-explicit');
+    });
+
+    it('falls back to configurable.thread_id when no explicit hint is given', async () => {
+      const capturedConfigs: Record<string, unknown>[] = [];
+      const mockTool = createMockCodeTool({ capturedConfigs });
+      const toolNode = new ToolNode({
+        tools: [mockTool],
+        sessions: new Map(),
+        toolExecution: {
+          engine: 'sandbox',
+          sandbox: { statefulSessions: true },
+        },
+      });
+
+      await toolNode.invoke(
+        { messages: [createAIMessageWithCodeCall('c1')] },
+        { configurable: { thread_id: 'thread-abc' } }
+      );
+
+      expect(capturedConfigs[0]._runtime_session_hint).toBe('thread-abc');
+    });
+
+    it('does not inject a hint when statefulSessions is off', async () => {
+      const capturedConfigs: Record<string, unknown>[] = [];
+      const mockTool = createMockCodeTool({ capturedConfigs });
+      const toolNode = new ToolNode({
+        tools: [mockTool],
+        sessions: new Map(),
+        toolExecution: {
+          engine: 'sandbox',
+          sandbox: { statefulSessions: false },
+        },
+      });
+
+      await toolNode.invoke(
+        { messages: [createAIMessageWithCodeCall('c1')] },
+        { configurable: { thread_id: 'thread-abc' } }
+      );
+
+      expect(capturedConfigs[0]._runtime_session_hint).toBeUndefined();
+    });
+
+    it('injects the hint independently of an existing exec session', async () => {
+      const capturedConfigs: Record<string, unknown>[] = [];
+      const sessions: t.ToolSessionMap = new Map();
+      sessions.set(Constants.EXECUTE_CODE, {
+        session_id: 'exec-1',
+        files: [],
+        lastUpdated: 0,
+      });
+      const mockTool = createMockCodeTool({ capturedConfigs });
+      const toolNode = new ToolNode({
+        tools: [mockTool],
+        sessions,
+        toolExecution: {
+          engine: 'sandbox',
+          sandbox: { statefulSessions: true, runtimeSessionHint: 'conv-1' },
+        },
+      });
+
+      await toolNode.invoke({ messages: [createAIMessageWithCodeCall('c1')] });
+
+      expect(capturedConfigs[0].session_id).toBe('exec-1');
+      expect(capturedConfigs[0]._runtime_session_hint).toBe('conv-1');
+    });
+  });
 });