@librechat/agents 3.2.59 → 3.2.60

package/src/tools/ToolNode.ts

@@ -416,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();
@@ -457,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
@@ -518,6 +540,7 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
     agentId,
     executingAgentId,
     directToolNames,
+    interruptingToolNames,
     codeSessionToolNames,
     maxContextTokens,
     maxToolResultChars,
@@ -556,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)
@@ -1140,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!,
@@ -1149,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,
@@ -1875,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)) {
@@ -3180,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
@@ -3426,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,
+              }
             )
             : [];
 
@@ -3491,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__/hitl.test.ts

@@ -3996,6 +3996,54 @@ describe('AskUserQuestion — interrupt + resume', () => {
     expect(resumedAnswer).toBe('production');
   });
 
+  it('carries multiSelect through the interrupt payload and resumes with the joined option values', async () => {
+    const { askUserQuestion } = await import('@/hitl');
+
+    let resumedAnswer: string | undefined;
+
+    const builder = new StateGraph(MessagesAnnotation)
+      .addNode('clarifier', () => {
+        const resolution = askUserQuestion({
+          question: 'Which environments?',
+          options: [
+            { label: 'Staging', value: 'staging' },
+            { label: 'Production', value: 'production' },
+          ],
+          multiSelect: true,
+        });
+        resumedAnswer = resolution.answer;
+        return { messages: [] };
+      })
+      .addEdge(START, 'clarifier')
+      .addEdge('clarifier', END);
+    const graph = builder.compile({ checkpointer: new MemorySaver() });
+
+    const config = { configurable: { thread_id: 'ask-q-multi-thread' } };
+
+    const interrupted = (await graph.invoke({ messages: [] }, config)) as {
+      __interrupt__?: Array<{ id?: string; value?: t.HumanInterruptPayload }>;
+    };
+    const payload = interrupted.__interrupt__![0].value!;
+    if (payload.type !== 'ask_user_question') {
+      throw new Error('expected ask_user_question');
+    }
+    expect(payload.question.multiSelect).toBe(true);
+    expect(payload.question.options).toHaveLength(2);
+
+    // Host joins the selected option values with ", ".
+    const resolution: t.AskUserQuestionResolution = {
+      answer: 'staging, production',
+    };
+    await resumeGraph(
+      graph as unknown as CompiledMessagesGraph,
+      interrupted,
+      resolution,
+      config
+    );
+
+    expect(resumedAnswer).toBe('staging, production');
+  });
+
   it('a DIRECT tool in event-driven mode can raise ask_user_question from its body and resume with the answer as its ToolMessage', async () => {
     /**
      * The production host shape (e.g. LibreChat's `AgentInputs.graphTools`

package/src/types/hitl.ts

@@ -140,6 +140,13 @@ export interface AskUserQuestionRequest {
    * UI allows it. Omit to require a free-form answer.
    */
   options?: AskUserQuestionOption[];
+  /**
+   * When `true`, the host UI may let the user pick several options; the
+   * resulting `AskUserQuestionResolution.answer` is the selected option
+   * values joined by `", "`. When omitted or `false`, hosts render a
+   * single-select picker. Only meaningful alongside `options`.
+   */
+  multiSelect?: boolean;
 }
 
 /**
@@ -168,9 +175,10 @@ export type HumanInterruptPayload =
 export interface AskUserQuestionResolution {
   /**
    * The human's answer. Free-form text, or — when `options` were
-   * provided — one of the option `value`s. Hosts may also send any
-   * structured object their custom UI defines; see the host docs for
-   * what your downstream consumer expects.
+   * provided — one of the option `value`s (or, when the request set
+   * `multiSelect`, several option `value`s joined by `", "`). Hosts may
+   * also send any structured object their custom UI defines; see the
+   * host docs for what your downstream consumer expects.
    */
   answer: string;
 }
@@ -287,6 +295,44 @@ export function isAskUserQuestionInterrupt(
  * an interrupt. This applies equally to direct tools (handoffs,
  * subagents) and to event tools.
  *
+ * ### Guarding non-idempotent siblings via `interruptingToolNames`
+ *
+ * The "must be idempotent" rule above is unavoidable in the general
+ * case, but the SDK can protect siblings against the one interrupt
+ * shape it can predict: a tool whose *body* raises `interrupt()`
+ * mid-execution — the `ask_user_question` shape, where the tool
+ * suspends the run to collect a human answer. Declare such tools in
+ * `RunConfig.interruptingToolNames`
+ * ({@link ToolNodeOptions.interruptingToolNames}) and the ToolNode
+ * schedules them, within each batch, **ahead of** their
+ * non-interrupting direct siblings. When one interrupts, the batch
+ * unwinds before any declared-safe sibling has run, so the sibling
+ * executes exactly once (on resume) instead of twice. Empirically:
+ *
+ *   - A **direct** sibling sharing the interrupter's in-process
+ *     `Promise.all` is the only shape that double-executes; declaring
+ *     the interrupter closes it.
+ *   - An **event-dispatched** sibling is already safe without any
+ *     config: the ToolNode awaits the whole direct group (where the
+ *     body interrupt unwinds) before it dispatches event tools, so a
+ *     dispatched sibling never runs on the first pass.
+ *
+ * This is a *scheduling* guard, not full resume idempotency: it only
+ * covers tools that interrupt from their own body and only protects
+ * siblings scheduled after them. It does not retroactively make a
+ * `PreToolUse` `'ask'` gate on tool B stop tool A (already executed)
+ * from re-running — unless B is itself declared interrupting, so it
+ * runs first. Tools with side effects should still be written
+ * idempotent as defense in depth.
+ *
+ * The guard only REORDERS the direct group — declaring a name does not
+ * force it onto the direct path. The interrupting tool must already be a
+ * real in-process graphTool (the only kind whose body can reach
+ * `interrupt()`). A name that resolves to a schema-only event stub (an
+ * inherited `toolDefinition` with no executable instance, e.g. in a
+ * self-spawned child that scrubs `graphTools`) stays event-dispatched
+ * and the ordering is a no-op for it.
+ *
  * ## Note on idempotency
  *
  * Same root cause as the resume re-execution above: LangGraph

package/src/types/run.ts

@@ -193,6 +193,27 @@ export type RunConfig = {
    * the SDK stays name-agnostic.
    */
   codeSessionToolNames?: string[];
+  /**
+   * Names of host tools whose in-process body may raise a LangGraph
+   * `interrupt()` mid-execution — the canonical example is an
+   * `ask_user_question` tool that suspends the run to collect a human
+   * answer. Within a single tool-call batch, a named tool that is a real
+   * in-process graphTool (the only kind whose body can reach `interrupt()`;
+   * graphTools are auto-marked direct) is scheduled **ahead of** its
+   * non-interrupting direct siblings. That ordering guarantees a mid-body
+   * interrupt unwinds the tool batch before a non-idempotent sibling
+   * (send_email, billing) executes, so the sibling cannot run once on the
+   * first pass and AGAIN when LangGraph re-runs the interrupted batch on
+   * resume.
+   *
+   * This only reorders the direct group — it does NOT force a name onto
+   * the direct path. A name that is only an inherited event `toolDefinition`
+   * (schema-only stub, e.g. in a self-spawned child) stays event-dispatched;
+   * the guard applies only to tools that are independently direct.
+   * Host-declared so the SDK stays name-agnostic; omit to keep the prior
+   * (unguarded) behavior.
+   */
+  interruptingToolNames?: string[];
   /**
    * Selects the execution backend for built-in code tools. Omit this to keep
    * the remote LibreChat Code API sandbox. Set `{ engine: 'local' }` to run

package/src/types/tools.ts

@@ -89,10 +89,18 @@ export type ToolNodeOptions = {
   handleToolErrors?: boolean;
   loadRuntimeTools?: ToolRefGenerator;
   toolCallStepIds?: Map<string, string>;
+  /**
+   * Dispatches the error completion event for a failed tool call. Returns
+   * whether the event was actually dispatched — `false` (e.g. no run step is
+   * registered for the call yet, which happens when a tool fails fast on a
+   * resume pass) tells the ToolNode to fall back to its own completion
+   * dispatch for the error ToolMessage. A `void` resolution is treated as
+   * dispatched for backward compatibility.
+   */
   errorHandler?: (
     data: ToolErrorData,
     metadata?: Record<string, unknown>
-  ) => Promise<void>;
+  ) => Promise<boolean | void>;
   /** Tool registry for lazy computation of programmatic tools and tool search */
   toolRegistry?: LCToolRegistry;
   /** Reference to Graph's sessions map for automatic session injection */
@@ -108,6 +116,34 @@ export type ToolNodeOptions = {
   executingAgentId?: string;
   /** Tool names that must be executed directly (via runTool) even in event-driven mode (e.g., graph-managed handoff tools) */
   directToolNames?: Set<string>;
+  /**
+   * Tool names whose in-process body may raise a LangGraph `interrupt()`
+   * mid-execution — e.g. an `ask_user_question` tool that suspends the
+   * run to collect a human answer.
+   *
+   * Within a single tool-call batch, a named tool that is *already*
+   * direct (a real in-process graphTool — the only kind whose body can
+   * reach `interrupt()`; graphTools are auto-marked direct by the graph)
+   * is executed as its own awaited group **before** its non-interrupting
+   * direct siblings. If it interrupts, the ToolNode unwinds before any
+   * sibling runs, so a non-idempotent sibling (send_email, billing)
+   * cannot execute once on the first pass and AGAIN when LangGraph re-runs
+   * the interrupted batch on resume.
+   *
+   * This set only REORDERS the direct group; it does NOT promote a name
+   * into it. A name that resolves to a schema-only event stub (an
+   * inherited `toolDefinition` with no executable instance — e.g. in a
+   * self-spawned child that scrubs `graphTools`) stays event-dispatched.
+   * Forcing such a name direct would invoke the stub, which throws
+   * "should not be invoked directly in event-driven mode". For the guard
+   * to apply, the interrupting tool must independently be direct.
+   *
+   * Opt-in and empty by default: when unset (or when no direct batch call
+   * matches), direct-batch execution is byte-for-byte unchanged. See the
+   * "Resume re-execution" section of {@link HumanInTheLoopConfig} for the
+   * batch re-execution contract this guards against.
+   */
+  interruptingToolNames?: Set<string>;
   /** Opt-in eager execution for event-driven tool calls. */
   eagerEventToolExecution?: EagerEventToolExecutionConfig;
   /**