@librechat/agents 3.4.0 → 3.4.2

package/dist/cjs/graphs/Graph.cjs

@@ -1,3 +1,4 @@
+const require_SubagentReplay = require("../tools/subagent/SubagentReplay.cjs");
 const require_misc = require("../utils/misc.cjs");
 const require_langfuseConfig = require("../langfuseConfig.cjs");
 const require_langfuseRuntimeScope = require("../langfuseRuntimeScope.cjs");
@@ -7,6 +8,7 @@ const require_enum = require("../common/enum.cjs");
 require("../common/index.cjs");
 const require_langfuseToolOutputTracing = require("../langfuseToolOutputTracing.cjs");
 const require_callbacks = require("../utils/callbacks.cjs");
+const require_applyGraphRuntimeConfig = require("./applyGraphRuntimeConfig.cjs");
 const require_truncation = require("../utils/truncation.cjs");
 const require_toolContent = require("../utils/toolContent.cjs");
 const require_tokens = require("../utils/tokens.cjs");
@@ -27,30 +29,31 @@ const require_handoffCue = require("../messages/handoffCue.cjs");
 const require_reducer = require("../messages/reducer.cjs");
 const require_recency = require("../messages/recency.cjs");
 require("../messages/index.cjs");
+const require_graph = require("../utils/graph.cjs");
+const require_llm = require("../utils/llm.cjs");
 const require_handlers = require("../tools/handlers.cjs");
 const require_streamLimits = require("../llm/streamLimits.cjs");
 const require_toolOutputReferences = require("../tools/toolOutputReferences.cjs");
-const require_llm = require("../utils/llm.cjs");
-const require_toolCache = require("../llm/bedrock/toolCache.cjs");
-const require_preempt = require("../llm/preempt.cjs");
-const require_graph = require("../utils/graph.cjs");
 const require_events$1 = require("../events.cjs");
 const require_run = require("../utils/run.cjs");
 require("../utils/index.cjs");
+const require_toolCache = require("../llm/bedrock/toolCache.cjs");
+const require_preempt = require("../llm/preempt.cjs");
 const require_init = require("../llm/init.cjs");
 const require_invoke = require("../llm/invoke.cjs");
-const require_contextOverflowRecovery = require("../llm/contextOverflowRecovery.cjs");
-const require_toolCache$1 = require("../llm/openrouter/toolCache.cjs");
 const require_executeHooks = require("../hooks/executeHooks.cjs");
 require("../hooks/index.cjs");
+const require_childGraphConfig = require("../tools/subagent/childGraphConfig.cjs");
+const require_SubagentExecutor = require("../tools/subagent/SubagentExecutor.cjs");
+require("../tools/subagent/index.cjs");
+const require_contextOverflowRecovery = require("../llm/contextOverflowRecovery.cjs");
+const require_toolCache$1 = require("../llm/openrouter/toolCache.cjs");
 const require_LocalCodingTools = require("../tools/local/LocalCodingTools.cjs");
 const require_CloudflareSandboxTools = require("../tools/cloudflare/CloudflareSandboxTools.cjs");
 require("../tools/cloudflare/index.cjs");
 const require_resolveLocalExecutionTools = require("../tools/local/resolveLocalExecutionTools.cjs");
 require("../tools/local/index.cjs");
 const require_ToolNode = require("../tools/ToolNode.cjs");
-const require_SubagentExecutor = require("../tools/subagent/SubagentExecutor.cjs");
-require("../tools/subagent/index.cjs");
 const require_SubagentTool = require("../tools/SubagentTool.cjs");
 const require_index$7 = require("../summarization/index.cjs");
 const require_request = require("../llm/request.cjs");
@@ -72,11 +75,13 @@ const EMPTY_PREEMPT_BOUNDARY = {
 };
 /** Minimum relative variance before calibrated toolSchemaTokens overrides current value. */
 const CALIBRATION_VARIANCE_THRESHOLD = .15;
-function createToolHandlerRegistry(source) {
+function createChildHandlerRegistry(source) {
 	const toolHandler = source?.getHandler("on_tool_execute");
-	if (toolHandler == null) return;
+	const updateHandler = source?.getHandler("on_subagent_update");
+	if (toolHandler == null && updateHandler == null) return;
 	const registry = new require_events$1.HandlerRegistry();
-	registry.register("on_tool_execute", toolHandler);
+	if (toolHandler != null) registry.register("on_tool_execute", toolHandler);
+	if (updateHandler != null) registry.register("on_subagent_update", updateHandler);
 	return registry;
 }
 function getHandlerDispatchedEventKey(eventName, stepId) {
@@ -262,6 +267,7 @@ function getDispatchableFinalReasoningContent({ agentContext, responseReasoningC
 	return responseReasoningContent;
 }
 var Graph = class {
+	restoreCheckpointMessages(_messages, _pendingMessages) {}
 	/** Returns a snapshot of deferred tools discovered by this graph. */
 	getDiscoveredTools(_agentId) {
 		return [];
@@ -419,7 +425,7 @@ var Graph = class {
 		this._toolOutputRegistry?.clear();
 		this._toolOutputRegistry = void 0;
 		for (const node of this._compiledToolNodes) node.clearDirectPathTurns();
-		this._compiledToolNodes.clear();
+		for (const executor of this._subagentExecutors) executor.clearHeavyState();
 		this.sessions.clear();
 	}
 	getEagerEventToolUsageCount(agentId) {
@@ -460,6 +466,73 @@ var Graph = class {
 	registerCompiledToolNode(node) {
 		this._compiledToolNodes.add(node);
 	}
+	registerSubagentExecutor(executor) {
+		this._subagentExecutors.add(executor);
+	}
+	resetSubagentCheckpointThreadIds() {
+		for (const executor of this._subagentExecutors) executor.resetCheckpointThreadIds();
+	}
+	getChildCheckpointThreadIds() {
+		const threadIds = /* @__PURE__ */ new Set();
+		for (const executor of this._subagentExecutors) for (const threadId of executor.getChildCheckpointThreadIds()) threadIds.add(threadId);
+		return [...threadIds];
+	}
+	createSubagentResumeState(runId) {
+		return {
+			toolCallSteps: [...this.toolCallStepIds].map(([toolCallId, stepId]) => ({
+				toolCallId,
+				stepId
+			})),
+			toolSessions: [...this.sessions].map(([toolName, context]) => ({
+				toolName,
+				context: {
+					...context,
+					...context.files == null ? {} : { files: context.files.map((file) => ({ ...file })) }
+				}
+			})),
+			toolNodes: [...this._compiledToolNodes].map((node) => node.createSubagentResumeState()),
+			eagerToolUsage: [{
+				agentId: "",
+				toolUsageCounts: [...this.eagerEventToolUsageCount].map(([toolName, count]) => ({
+					toolName,
+					count
+				}))
+			}, ...[...this.eagerEventToolUsageCountsByAgentId].map(([agentId, usageCounts]) => ({
+				agentId,
+				toolUsageCounts: [...usageCounts].map(([toolName, count]) => ({
+					toolName,
+					count
+				}))
+			}))],
+			eagerToolSuppressions: [...this.eagerEventToolSuppressions],
+			...this._toolOutputRegistry == null ? {} : { toolOutputReferences: this._toolOutputRegistry.snapshotState(runId) }
+		};
+	}
+	restoreSubagentResumeState(state, runId) {
+		const toolNodesByKey = new Map([...this._compiledToolNodes].map((node) => {
+			return [node.createSubagentResumeState().stateKey, node];
+		}));
+		if (toolNodesByKey.size !== state.toolNodes.length) throw new Error("Cannot restore changed subagent tool topology.");
+		for (const nodeState of state.toolNodes) if (!toolNodesByKey.has(nodeState.stateKey)) throw new Error(`Cannot restore subagent tool state for "${nodeState.stateKey}".`);
+		const registry = state.toolOutputReferences == null ? void 0 : this.getOrCreateToolOutputRegistry();
+		if (state.toolOutputReferences != null && registry == null) throw new Error("Cannot restore disabled tool output references.");
+		this.toolCallStepIds.clear();
+		for (const { toolCallId, stepId } of state.toolCallSteps) this.toolCallStepIds.set(toolCallId, stepId);
+		this.sessions.clear();
+		for (const { toolName, context } of state.toolSessions) this.sessions.set(toolName, {
+			...context,
+			...context.files == null ? {} : { files: context.files.map((file) => ({ ...file })) }
+		});
+		for (const nodeState of state.toolNodes) toolNodesByKey.get(nodeState.stateKey).restoreSubagentResumeState(nodeState);
+		this.clearEagerEventToolUsageCounts();
+		for (const usageState of state.eagerToolUsage) {
+			const usageCounts = this.getEagerEventToolUsageCount(usageState.agentId);
+			for (const { toolName, count } of usageState.toolUsageCounts) usageCounts.set(toolName, count);
+		}
+		this.eagerEventToolSuppressions.clear();
+		for (const toolName of state.eagerToolSuppressions) this.eagerEventToolSuppressions.add(toolName);
+		if (state.toolOutputReferences != null && registry != null) registry.restoreState(runId, state.toolOutputReferences);
+	}
 	/**
 	* Returns the shared `ToolOutputReferenceRegistry` for this run,
 	* constructing it on first access. Returns `undefined` when the
@@ -501,6 +574,7 @@ var Graph = class {
 	* across Runs if a provider reuses call ids (Codex P2 #33).
 	*/
 	_compiledToolNodes = /* @__PURE__ */ new Set();
+	_subagentExecutors = /* @__PURE__ */ new Set();
 	getOrCreateFileCheckpointer() {
 		if (this._fileCheckpointer != null) return this._fileCheckpointer;
 		if (this.toolExecution?.engine === "local" && this.toolExecution.local?.fileCheckpointing === true) {
@@ -518,11 +592,15 @@ var Graph = class {
 var StandardGraph = class StandardGraph extends Graph {
 	overrideModel;
 	subagentModelOverride;
+	graphFactory;
+	supportsMultiAgentChildren;
 	/** Optional compile options passed into workflow.compile() */
 	compileOptions;
 	/** Whether the workflow was actually compiled with a checkpointer. */
 	hasCompiledCheckpointer = false;
 	messages = [];
+	/** Whether a rebuilt resume seeded the message baseline from its checkpoint. */
+	hasRestoredCheckpointMessages = false;
 	/** Cached run messages preserved before clearHeavyState() so getRunMessages() works after cleanup. */
 	cachedRunMessages;
 	/** Per-agent discovery snapshots preserved before contexts are reset on cleanup. */
@@ -564,6 +642,8 @@ var StandardGraph = class StandardGraph extends Graph {
 	subagentUsageSink;
 	/** See {@link t.StandardGraphInput.subagentScope}. */
 	subagentScope;
+	/** See {@link t.StandardGraphInput.subagentExecutionContext}. */
+	subagentExecutionContext;
 	/** See {@link t.StandardGraphInput.preemption}. */
 	preemption;
 	/**
@@ -667,14 +747,20 @@ var StandardGraph = class StandardGraph extends Graph {
 	* another's turn.
 	*/
 	pendingPreemptReturn = /* @__PURE__ */ new Set();
-	constructor({ runId, signal, agents, langfuse, tokenCounter, indexTokenCountMap, calibrationRatio, subagentUsageSink, subagentScope, preemption, streamLimits }) {
+	constructor({ runId, signal, agents, langfuse, tokenCounter, indexTokenCountMap, calibrationRatio, subagentUsageSink, subagentScope, subagentExecutionContext, preemption, streamLimits }, dependencies) {
 		super();
+		this.supportsMultiAgentChildren = dependencies != null;
+		this.graphFactory = dependencies?.graphFactory ?? ((request) => {
+			if (request.kind !== "standard") throw new Error("A polymorphic graph factory is required for multi-agent graph construction.");
+			return new StandardGraph(request.input);
+		});
 		this.runId = runId;
 		this.langfuseScopeRunId = `${runId ?? "graph"}:${(0, nanoid.nanoid)()}`;
 		this.signal = signal;
 		this.langfuse = langfuse;
 		this.subagentUsageSink = subagentUsageSink;
 		this.subagentScope = subagentScope === true;
+		this.subagentExecutionContext = subagentExecutionContext;
 		this.preemption = preemption;
 		this.streamLimits = require_streamLimits.resolveStreamLimits(streamLimits);
 		if (agents.length === 0) throw new Error("At least one agent configuration is required");
@@ -686,7 +772,9 @@ var StandardGraph = class StandardGraph extends Graph {
 		this.defaultAgentId = agents[0].agentId;
 	}
 	resetValues(keepContent, checkpointScope) {
+		this.resetSubagentCheckpointThreadIds();
 		this.messages = [];
+		this.hasRestoredCheckpointMessages = false;
 		this.cachedRunMessages = void 0;
 		this.cachedDiscoveredTools = void 0;
 		this.config = require_graph.resetIfNotEmpty(this.config, void 0);
@@ -744,6 +832,14 @@ var StandardGraph = class StandardGraph extends Graph {
 		for (const context of this.agentContexts.values()) context.reset({ preserveOriginalToolContent });
 		this.originalToolContentCheckpointScope = hasScopedCheckpoint ? checkpointScope : void 0;
 	}
+	/** Seeds the sidecar message view that checkpoint restoration bypasses. */
+	restoreCheckpointMessages(messages, pendingMessages) {
+		if (this.messages.length > 0) return;
+		this.messages = pendingMessages == null ? [...messages] : require_reducer.messagesStateReducer(messages, pendingMessages);
+		this.startIndex = this.messages.length;
+		this.hasRestoredCheckpointMessages = true;
+		this.cachedRunMessages = void 0;
+	}
 	clearHeavyState() {
 		this.cachedRunMessages = this.messages.slice(this.startIndex);
 		this.cachedDiscoveredTools = new Map(Array.from(this.agentContexts, ([agentId, context]) => [agentId, context.getDiscoveredTools()]));
@@ -1031,6 +1127,9 @@ var StandardGraph = class StandardGraph extends Graph {
 			runLangfuse: this.langfuse,
 			agentLangfuse: agentContext?.langfuse
 		});
+		const interruptingToolNames = new Set(this.interruptingToolNames ?? []);
+		if (this.humanInTheLoop?.enabled === true && (agentContext?.subagentConfigs?.length ?? 0) > 0) interruptingToolNames.add("subagent");
+		const effectiveInterruptingToolNames = interruptingToolNames.size > 0 ? interruptingToolNames : void 0;
 		if (eventDrivenMode) {
 			const schemaTools = require_schema.createSchemaOnlyTools(toolDefinitions);
 			const toolDefMap = new Map(toolDefinitions.map((def) => [def.name, def]));
@@ -1067,7 +1166,7 @@ var StandardGraph = class StandardGraph extends Graph {
 				eagerEventToolSuppressions: this.eagerEventToolSuppressions,
 				toolExecution: this.toolExecution,
 				directToolNames: directToolNames.size > 0 ? directToolNames : void 0,
-				interruptingToolNames: this.interruptingToolNames != null && this.interruptingToolNames.length > 0 ? new Set(this.interruptingToolNames) : void 0,
+				interruptingToolNames: effectiveInterruptingToolNames,
 				maxContextTokens: agentContext?.maxContextTokens,
 				maxToolResultChars: agentContext?.maxToolResultChars,
 				toolOutputRegistry: this.getOrCreateToolOutputRegistry(),
@@ -1095,7 +1194,7 @@ var StandardGraph = class StandardGraph extends Graph {
 			sessions: this.sessions,
 			toolExecution: this.toolExecution,
 			codeSessionToolNames: this.codeSessionToolNames,
-			interruptingToolNames: this.interruptingToolNames != null && this.interruptingToolNames.length > 0 ? new Set(this.interruptingToolNames) : void 0,
+			interruptingToolNames: effectiveInterruptingToolNames,
 			hookRegistry: this.hookRegistry,
 			humanInTheLoop: this.humanInTheLoop,
 			maxContextTokens: agentContext?.maxContextTokens,
@@ -2323,11 +2422,33 @@ var StandardGraph = class StandardGraph extends Graph {
 		*/
 		const effectiveSubagentDepth = agentContext.maxSubagentDepth ?? 1;
 		if (agentContext.subagentConfigs != null && agentContext.subagentConfigs.length > 0 && effectiveSubagentDepth > 0) {
-			const resolvedConfigs = require_SubagentExecutor.resolveSubagentConfigs(agentContext.subagentConfigs, agentContext);
-			if (resolvedConfigs.length > 0) {
+			const executableConfigs = require_childGraphConfig.normalizeSubagentConfigEntries(agentContext.subagentConfigs, agentContext);
+			if (executableConfigs.length > 0) {
+				if (!this.supportsMultiAgentChildren && executableConfigs.some(require_childGraphConfig.isGraphSubagentConfig)) throw new Error("Graph subagents require constructing the parent with createGraph() or an injected GraphFactory dependency.");
 				const getParentHandlerRegistry = () => this.handlerRegistry ?? this.parentToolHandlerRegistry;
+				const createConfiguredChildGraph = (request) => {
+					const childGraph = this.graphFactory(request);
+					if (this.subagentModelOverride != null) {
+						childGraph.overrideModel = this.subagentModelOverride;
+						childGraph.setSubagentModelOverride(this.subagentModelOverride);
+					}
+					const childHandlerRegistry = createChildHandlerRegistry(getParentHandlerRegistry());
+					require_applyGraphRuntimeConfig.applyGraphRuntimeConfig(childGraph, {
+						hookRegistry: this.hookRegistry,
+						humanInTheLoop: this.humanInTheLoop,
+						toolOutputReferences: this.toolOutputReferences,
+						eagerEventToolExecution: this.eagerEventToolExecution,
+						codeSessionToolNames: this.codeSessionToolNames,
+						interruptingToolNames: this.interruptingToolNames,
+						toolExecution: this.toolExecution
+					});
+					if (this.humanInTheLoop?.enabled === true) childGraph.compileOptions = { checkpointer: this.compileOptions?.checkpointer };
+					childGraph.parentToolHandlerRegistry = childHandlerRegistry;
+					childGraph.eventToolExecutionAvailable = childHandlerRegistry?.getHandler("on_tool_execute") != null;
+					return childGraph;
+				};
 				const executor = new require_SubagentExecutor.SubagentExecutor({
-					configs: new Map(resolvedConfigs.map((c) => [c.type, c])),
+					configs: new Map(executableConfigs.map((config) => [config.type, config])),
 					parentSignal: this.signal,
 					breakerScope: { controller: () => this.breakerAbort },
 					hookRegistry: this.hookRegistry,
@@ -2337,53 +2458,33 @@ var StandardGraph = class StandardGraph extends Graph {
 					parentHandlerRegistry: getParentHandlerRegistry,
 					parentRunId: this.runId ?? "",
 					parentAgentId: agentContext.agentId,
+					executionContext: this.subagentExecutionContext,
 					langfuse: this.langfuse,
 					tokenCounter: agentContext.tokenCounter,
 					usageSink: this.subagentUsageSink,
 					streamLimits: this.streamLimits,
+					humanInTheLoop: this.humanInTheLoop,
+					checkpointer: this.compileOptions?.checkpointer,
 					maxDepth: effectiveSubagentDepth,
-					createChildGraph: (input) => {
-						const childGraph = new StandardGraph(input);
-						if (this.subagentModelOverride != null) {
-							childGraph.overrideModel = this.subagentModelOverride;
-							childGraph.setSubagentModelOverride(this.subagentModelOverride);
-						}
-						const toolHandlerRegistry = createToolHandlerRegistry(getParentHandlerRegistry());
-						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.codeSessionToolNames = this.codeSessionToolNames;
-						childGraph.interruptingToolNames = this.interruptingToolNames;
-						childGraph.toolExecution = this.toolExecution;
-						childGraph.parentToolHandlerRegistry = toolHandlerRegistry;
-						childGraph.eventToolExecutionAvailable = toolHandlerRegistry != null;
-						return childGraph;
-					}
+					createChildGraph: (input) => createConfiguredChildGraph({
+						kind: "standard",
+						input
+					}),
+					createChildGraphByKind: createConfiguredChildGraph
 				});
+				this.registerSubagentExecutor(executor);
 				const subagentTool = (0, _langchain_core_tools.tool)(async (rawInput, config) => {
 					const input = rawInput;
-					const description = typeof input.description === "string" && input.description.trim().length > 0 ? input.description : "No task description provided";
+					const description = typeof input.description === "string" && input.description.trim().length > 0 ? input.description : require_SubagentExecutor.DEFAULT_SUBAGENT_DESCRIPTION;
 					const subagentType = typeof input.subagent_type === "string" ? input.subagent_type : "";
 					const threadId = config.configurable?.thread_id;
-					/**
-					* When the tool is dispatched from an LLM's `tool_call`, LangChain
-					* threads the originating `ToolCall` onto the RunnableConfig as
-					* `config.toolCall` (see `ToolRunnableConfig` in
-					* `@langchain/core/tools` — internal but stable since ≥0.3.x).
-					* Surfacing its id lets hosts correlate `SubagentUpdateEvent`s
-					* back to the parent's `tool_call_id` deterministically — no
-					* temporal heuristics needed. If a future LangChain version
-					* changes the threading, the type-guarded read falls back to
-					* `undefined` and the correlation degrades gracefully.
-					*/
-					const toolCall = config.toolCall;
-					const parentToolCallId = typeof toolCall?.id === "string" ? toolCall.id : void 0;
+					/** Surface the parent call id so child checkpoints, interrupts, and
+					* update events remain correlated across replay and resume. */
+					const toolRuntime = config;
+					const toolCall = toolRuntime.toolCall;
+					let parentToolCallId;
+					if (typeof toolRuntime.toolCallId === "string" && toolRuntime.toolCallId !== "") parentToolCallId = toolRuntime.toolCallId;
+					else if (typeof toolCall?.id === "string" && toolCall.id !== "") parentToolCallId = toolCall.id;
 					/** The parent tool batch's entry-captured scope (stamped by
 					* ToolNode before PreToolUse hooks) — binds this child to the
 					* run that dispatched it, not to whatever controller a reset
@@ -2393,6 +2494,7 @@ var StandardGraph = class StandardGraph extends Graph {
 						description,
 						subagentType,
 						threadId,
+						signal: config.signal,
 						parentToolCallId,
 						breaker: batchScope?.controller,
 						/**
@@ -2403,7 +2505,13 @@ var StandardGraph = class StandardGraph extends Graph {
 						*/
 						parentConfigurable: config.configurable
 					})).content;
-				}, require_SubagentTool.buildSubagentToolParams(resolvedConfigs));
+				}, require_SubagentTool.buildSubagentToolParams(executableConfigs));
+				const replayableSubagentTool = subagentTool;
+				replayableSubagentTool[require_SubagentReplay.SUBAGENT_REPLAY_CONTROLLER] = {
+					getResumeManifest: (parentToolCallIds, config) => executor.getResumeManifest(parentToolCallIds, config),
+					getSettledOutput: (call, config) => executor.getSettledToolOutput(call, config),
+					persistSettledOutput: (call, config, output) => executor.persistSettledToolOutput(call, config, output)
+				};
 				if (!agentContext.graphTools) agentContext.graphTools = [];
 				agentContext.graphTools.push(subagentTool);
 				/**
@@ -2556,7 +2664,7 @@ var StandardGraph = class StandardGraph extends Graph {
 		const agentNode = this.createAgentNode(this.defaultAgentId);
 		return new _langchain_langgraph.StateGraph(_langchain_langgraph.Annotation.Root({ messages: (0, _langchain_langgraph.Annotation)({
 			reducer: (a, b) => {
-				if (!this.messages.length) this.startIndex = a.length + b.length;
+				if (!this.messages.length && !this.hasRestoredCheckpointMessages) this.startIndex = a.length + b.length;
 				const result = require_reducer.messagesStateReducer(a, b);
 				this.messages = result;
 				return result;