@librechat/agents 3.2.58 → 3.2.60

package/dist/esm/tools/ToolNode.mjs

@@ -4,7 +4,7 @@ import "../common/index.mjs";
 import { toLangChainContent } from "../messages/langchain.mjs";
 import { calculateMaxToolResultChars, truncateToolResultContent } from "../utils/truncation.mjs";
 import { safeDispatchCustomEvent } from "../utils/events.mjs";
-import { buildToolExecutionRequestPlan, recordArgsEqual } from "./eagerEventExecution.mjs";
+import { buildToolExecutionRequestPlan, recordArgsEqual, resolveRuntimeSessionHint } from "./eagerEventExecution.mjs";
 import { ToolOutputReferenceRegistry, buildReferenceKey } from "./toolOutputReferences.mjs";
 import { RunnableCallable } from "../utils/run.mjs";
 import "../utils/index.mjs";
@@ -207,6 +207,13 @@ var ToolNode = class extends RunnableCallable {
 	agentLangfuse;
 	toolCallStepIds;
 	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.
+	*/
+	undispatchedToolErrors = /* @__PURE__ */ new Set();
 	toolUsageCount;
 	/** Maps toolCallId → turn captured in runTool, used by handleRunToolCompletions */
 	toolCallTurns = /* @__PURE__ */ new Map();
@@ -249,6 +256,21 @@ var ToolNode = class extends RunnableCallable {
 	/** Tool names that bypass event dispatch and execute directly (e.g., graph-managed handoff tools) */
 	directToolNames;
 	/**
+	* 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}.
+	*/
+	interruptingToolNames;
+	/**
 	* File checkpointer extracted from the local coding tool bundle when
 	* `toolExecution.local.fileCheckpointing === true`. Exposed via
 	* {@link getFileCheckpointer}. Undefined when checkpointing is off
@@ -287,7 +309,7 @@ var ToolNode = class extends RunnableCallable {
 	* other's in-flight state.
 	*/
 	anonBatchCounter = 0;
-	constructor({ tools, toolMap, name, tags, trace, runLangfuse, agentLangfuse, errorHandler, toolCallStepIds, handleToolErrors, loadRuntimeTools, toolRegistry, sessions, eventDrivenMode, eagerEventToolExecution, eagerEventToolExecutions, eagerEventToolUsageCount, agentId, executingAgentId, directToolNames, codeSessionToolNames, maxContextTokens, maxToolResultChars, hookRegistry, humanInTheLoop, toolOutputReferences, toolOutputRegistry, toolExecution, fileCheckpointer }) {
+	constructor({ tools, toolMap, name, tags, trace, runLangfuse, agentLangfuse, errorHandler, toolCallStepIds, handleToolErrors, loadRuntimeTools, toolRegistry, sessions, eventDrivenMode, eagerEventToolExecution, eagerEventToolExecutions, eagerEventToolUsageCount, agentId, executingAgentId, directToolNames, interruptingToolNames, codeSessionToolNames, maxContextTokens, maxToolResultChars, hookRegistry, humanInTheLoop, toolOutputReferences, toolOutputRegistry, toolExecution, fileCheckpointer }) {
 		super({
 			name: name ?? TOOL_NODE_RUN_NAME,
 			tags,
@@ -314,6 +336,7 @@ var ToolNode = class extends RunnableCallable {
 		this.agentId = agentId;
 		this.executingAgentId = executingAgentId ?? agentId;
 		this.directToolNames = directToolNames;
+		this.interruptingToolNames = interruptingToolNames != null && interruptingToolNames.size > 0 ? interruptingToolNames : void 0;
 		this.codeSessionToolNames = codeSessionToolNames != null && codeSessionToolNames.length > 0 ? new Set(codeSessionToolNames) : void 0;
 		this.maxToolResultChars = maxToolResultChars ?? calculateMaxToolResultChars(maxContextTokens);
 		this.hookRegistry = hookRegistry;
@@ -580,6 +603,17 @@ var ToolNode = class extends RunnableCallable {
 					};
 					if (codeSession?.files != null && codeSession.files.length > 0) invokeParams._injected_files = codeSession.files.map((file) => toInjectedFileRef(file, execSessionId));
 				}
+				/**
+				* 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
+				};
 			}
 			/**
 			* Forward the graph state as langgraph 1.4's `runtime.state` so
@@ -659,12 +693,20 @@ var ToolNode = class extends RunnableCallable {
 			if (!this.handleToolErrors) throw e;
 			if (isGraphInterrupt(e)) throw e;
 			if (this.errorHandler) try {
-				await this.errorHandler({
+				if (await this.errorHandler({
 					error: e,
 					id: call.id,
 					name: call.name,
 					input: call.args
-				}, config.metadata);
+				}, config.metadata) === 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) {
 				console.error("Error in errorHandler:", {
 					toolName: call.name,
@@ -1060,6 +1102,11 @@ var ToolNode = class extends RunnableCallable {
 		if (name === "") return false;
 		return CODE_EXECUTION_TOOLS.has(name) || this.codeSessionToolNames?.has(name) === true;
 	}
+	/** Delegates to the shared resolver so the direct and event-driven planning
+	*  paths derive the runtime session hint identically. */
+	resolveRuntimeSessionHint(config) {
+		return resolveRuntimeSessionHint(this.toolExecution, config.configurable?.thread_id);
+	}
 	storeCodeSessionFromResults(results, requestMap) {
 		if (!this.sessions) return;
 		for (let i = 0; i < results.length; i++) {
@@ -1094,7 +1141,8 @@ var ToolNode = class extends RunnableCallable {
 			if (isCommand(output)) continue;
 			const toolMessage = output;
 			const toolCallId = call.id ?? "";
-			if (toolMessage.status === "error" && this.errorHandler != null) continue;
+			if (toolMessage.status === "error" && this.errorHandler != null) if (this.undispatchedToolErrors.has(toolCallId)) this.undispatchedToolErrors.delete(toolCallId);
+			else continue;
 			if (this.sessions && this.participatesInCodeSession(call.name)) {
 				const artifact = toolMessage.artifact;
 				const execSessionId = artifact?.session_id;
@@ -1546,12 +1594,14 @@ var ToolNode = class extends RunnableCallable {
 			const plan = buildToolExecutionRequestPlan({
 				toolCalls: approvedEntries.map((entry) => {
 					const codeSessionContext = this.participatesInCodeSession(entry.call.name) || entry.call.name === "skill" || entry.call.name === "read_file" ? this.getCodeSessionContext() : void 0;
+					const runtimeSessionHint = this.participatesInCodeSession(entry.call.name) ? this.resolveRuntimeSessionHint(config) : void 0;
 					return {
 						id: entry.call.id,
 						name: entry.call.name,
 						args: entry.args,
 						stepId: entry.stepId,
-						codeSessionContext
+						codeSessionContext,
+						runtimeSessionHint
 					};
 				}),
 				usageCount: this.toolUsageCount,
@@ -1921,6 +1971,61 @@ var ToolNode = class extends RunnableCallable {
 		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.
+	*/
+	async runDirectBatchInterruptSafe(directCalls, batchIndices, config, baseContext) {
+		const runOne = (call, position) => this.runDirectToolWithLifecycleHooks(call, config, {
+			...baseContext,
+			batchIndex: batchIndices[position]
+		});
+		const interrupting = this.interruptingToolNames;
+		if (!(interrupting != null && directCalls.some((call) => interrupting.has(call.name)))) return Promise.all(directCalls.map((call, i) => runOne(call, i)));
+		const outputs = new Array(directCalls.length);
+		const interruptingPositions = [];
+		const regularPositions = [];
+		for (let i = 0; i < directCalls.length; i++) if (interrupting.has(directCalls[i].name)) interruptingPositions.push(i);
+		else regularPositions.push(i);
+		const interruptingOutputs = await Promise.all(interruptingPositions.map((i) => runOne(directCalls[i], i)));
+		interruptingPositions.forEach((i, k) => {
+			outputs[i] = interruptingOutputs[k];
+		});
+		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
 	* message ordering (AIMessage tool_calls must be immediately followed
@@ -2057,15 +2162,14 @@ var ToolNode = class extends RunnableCallable {
 					}
 				}
 				const directAdditionalContexts = [];
-				const directOutputs = directCalls.length > 0 ? await Promise.all(directCalls.map((call, i) => this.runDirectToolWithLifecycleHooks(call, config, {
-					batchIndex: directIndices[i],
+				const directOutputs = directCalls.length > 0 ? await this.runDirectBatchInterruptSafe(directCalls, directIndices, config, {
 					turn,
 					batchScopeId,
 					resolvedArgsByCallId,
 					preBatchSnapshot,
 					additionalContextsSink: directAdditionalContexts,
 					runInput: input
-				}))) : [];
+				}) : [];
 				if (directCalls.length > 0 && directOutputs.length > 0) await this.handleRunToolCompletions(directCalls, directOutputs, config, resolvedArgsByCallId);
 				const eventResult = eventCalls.length > 0 ? await this.dispatchToolEvents(eventCalls, config, {
 					batchIndices: eventIndices,
@@ -2093,15 +2197,14 @@ var ToolNode = class extends RunnableCallable {
 			} else {
 				const preBatchSnapshot = this.toolOutputRegistry?.snapshot(batchScopeId);
 				const directAdditionalContexts = [];
-				const toolOutputs = await Promise.all(filteredCalls.map((call, i) => this.runDirectToolWithLifecycleHooks(call, config, {
-					batchIndex: i,
+				const toolOutputs = await this.runDirectBatchInterruptSafe(filteredCalls, filteredCalls.map((_call, i) => i), config, {
 					turn,
 					batchScopeId,
 					resolvedArgsByCallId,
 					preBatchSnapshot,
 					additionalContextsSink: directAdditionalContexts,
 					runInput: input
-				})));
+				});
 				await this.handleRunToolCompletions(filteredCalls, toolOutputs, config, resolvedArgsByCallId);
 				outputs = directAdditionalContexts.length > 0 ? [...toolOutputs, new HumanMessage({
 					content: directAdditionalContexts.join("\n\n"),