@librechat/agents 3.4.0 → 3.4.1

package/dist/esm/tools/subagent/SubagentExecutor.mjs

@@ -1,11 +1,15 @@
+import { SUBAGENT_PARENT_BATCH_CONFIG_KEY, SUBAGENT_RESUME_ATTEMPT_CONFIG_KEY, SUBAGENT_RESUME_MANIFEST_CONFIG_KEY, attachSubagentResumeManifest, getSubagentResumeManifest } from "./SubagentReplay.mjs";
 import "../../common/enum.mjs";
 import "../../common/index.mjs";
 import { StreamLimitExceededError } from "../../llm/streamLimits.mjs";
 import { executeHooks } from "../../hooks/executeHooks.mjs";
+import { TOOL_APPROVAL_EXECUTION_SCOPE_CONFIG_KEY } from "../../hooks/types.mjs";
 import "../../hooks/index.mjs";
 import { nanoid } from "nanoid";
 import { BaseCallbackHandler } from "@langchain/core/callbacks/base";
-import { HumanMessage } from "@langchain/core/messages";
+import { AIMessage, BaseMessage, HumanMessage, ToolMessage } from "@langchain/core/messages";
+import { Command, END, GraphInterrupt, INTERRUPT, MessagesAnnotation, START, StateGraph, copyCheckpoint, isGraphInterrupt, isInterrupted } from "@langchain/langgraph";
+import { AsyncLocalStorageProviderSingleton } from "@langchain/core/singletons";
 //#region src/tools/subagent/SubagentExecutor.ts
 const DEFAULT_MAX_TURNS = 25;
 const RECURSION_MULTIPLIER = 3;
@@ -18,11 +22,185 @@ const HOOK_FALLBACK = Object.freeze({
 	errors: []
 });
 const LANGGRAPH_RUNTIME_CONFIG_PREFIX = "__pregel_";
+const LANGGRAPH_RESUME_MAP_CONFIG_KEY = "__pregel_resume_map";
 const LANGGRAPH_CHECKPOINT_CONFIG_KEYS = new Set([
 	"checkpoint_id",
 	"checkpoint_map",
 	"checkpoint_ns"
 ]);
+const SUBAGENT_CHECKPOINT_MARKER_KEY = "__librechat_subagent_checkpoint";
+const SUBAGENT_HOOK_SESSION_KEY = "__librechat_subagent_hook_session";
+const SUBAGENT_RUN_ID_KEY = "__librechat_subagent_run_id";
+const SUBAGENT_REPLAY_NODE = "subagent-replay";
+function isCheckpointSaver(value) {
+	if (value == null || typeof value !== "object") return false;
+	const candidate = value;
+	return typeof candidate.getTuple === "function" && typeof candidate.list === "function" && typeof candidate.put === "function" && typeof candidate.putWrites === "function" && typeof candidate.deleteThread === "function";
+}
+function isSubagentCheckpointMarker(value) {
+	if (value == null || typeof value !== "object") return false;
+	const marker = value;
+	return marker.version === 1 && marker.lifecycleComplete === true && typeof marker.parentToolCallId === "string" && (marker.hookSessionId == null || typeof marker.hookSessionId === "string") && (marker.childRunId == null || typeof marker.childRunId === "string") && (marker.settledOutput == null || isPersistedToolOutput(marker.settledOutput));
+}
+function isPersistedToolOutput(value) {
+	if (value == null || typeof value !== "object") return false;
+	const output = value;
+	const contentIsValid = typeof output.content === "string" || Array.isArray(output.content);
+	const statusIsValid = output.status == null || output.status === "success" || output.status === "error";
+	const contextsAreValid = Array.isArray(output.additionalContexts) && output.additionalContexts.every((context) => typeof context === "string");
+	const resolvedArgsAreValid = output.resolvedArgs == null || typeof output.resolvedArgs === "object" && !Array.isArray(output.resolvedArgs);
+	return contentIsValid && typeof output.toolCallId === "string" && output.additionalKwargs != null && typeof output.additionalKwargs === "object" && output.responseMetadata != null && typeof output.responseMetadata === "object" && statusIsValid && contextsAreValid && resolvedArgsAreValid && (output.referenceContent == null || typeof output.referenceContent === "string");
+}
+function getSubagentCheckpointMarker(messages, parentToolCallId) {
+	for (let i = messages.length - 1; i >= 0; i--) {
+		const marker = messages[i].additional_kwargs[SUBAGENT_CHECKPOINT_MARKER_KEY];
+		if (isSubagentCheckpointMarker(marker) && marker.parentToolCallId === parentToolCallId) return marker;
+	}
+}
+function getSubagentHookSessionId(messages) {
+	for (let i = messages.length - 1; i >= 0; i--) {
+		const sessionId = messages[i].additional_kwargs[SUBAGENT_HOOK_SESSION_KEY];
+		if (typeof sessionId === "string" && sessionId.length > 0) return sessionId;
+	}
+}
+function getSubagentRunId(messages) {
+	for (let i = messages.length - 1; i >= 0; i--) {
+		const runId = messages[i].additional_kwargs[SUBAGENT_RUN_ID_KEY];
+		if (typeof runId === "string" && runId.length > 0) return runId;
+		const marker = messages[i].additional_kwargs[SUBAGENT_CHECKPOINT_MARKER_KEY];
+		if (isSubagentCheckpointMarker(marker) && marker.childRunId != null && marker.childRunId.length > 0) return marker.childRunId;
+	}
+}
+function isSubagentCheckpointMarkerMessage(message) {
+	return isSubagentCheckpointMarker(message.additional_kwargs[SUBAGENT_CHECKPOINT_MARKER_KEY]);
+}
+function createSubagentCheckpointMarkerMessage(marker) {
+	return new AIMessage({
+		content: "",
+		additional_kwargs: { [SUBAGENT_CHECKPOINT_MARKER_KEY]: marker }
+	});
+}
+function getCheckpointMessages(value) {
+	return Array.isArray(value) ? value.filter(BaseMessage.isInstance) : [];
+}
+function getConfigurableString(config, key) {
+	const value = config?.configurable?.[key];
+	return typeof value === "string" && value.length > 0 ? value : void 0;
+}
+function getTupleMessages(tuple) {
+	return getCheckpointMessages(tuple?.checkpoint.channel_values.messages);
+}
+function getCheckpointReference(tuple) {
+	const configurable = tuple?.config.configurable;
+	const threadId = configurable?.thread_id;
+	const checkpointId = configurable?.checkpoint_id;
+	const checkpointNs = configurable?.checkpoint_ns ?? "";
+	if (typeof threadId !== "string" || threadId.length === 0 || typeof checkpointId !== "string" || checkpointId.length === 0 || typeof checkpointNs !== "string") return;
+	return {
+		threadId,
+		checkpointId,
+		checkpointNs
+	};
+}
+function serializeToolOutput(settled) {
+	const { output } = settled;
+	return {
+		content: output.content,
+		toolCallId: output.tool_call_id,
+		...output.id == null ? {} : { id: output.id },
+		...output.name == null ? {} : { name: output.name },
+		...output.status == null ? {} : { status: output.status },
+		additionalKwargs: output.additional_kwargs,
+		responseMetadata: output.response_metadata,
+		...output.metadata == null ? {} : { metadata: output.metadata },
+		additionalContexts: settled.additionalContexts,
+		...settled.resolvedArgs == null ? {} : { resolvedArgs: settled.resolvedArgs },
+		...settled.referenceContent == null ? {} : { referenceContent: settled.referenceContent }
+	};
+}
+function deserializeToolOutput(output) {
+	return {
+		output: new ToolMessage({
+			content: output.content,
+			tool_call_id: output.toolCallId,
+			...output.id == null ? {} : { id: output.id },
+			...output.name == null ? {} : { name: output.name },
+			...output.status == null ? {} : { status: output.status },
+			additional_kwargs: output.additionalKwargs,
+			response_metadata: output.responseMetadata,
+			...output.metadata == null ? {} : { metadata: output.metadata }
+		}),
+		additionalContexts: output.additionalContexts,
+		...output.resolvedArgs == null ? {} : { resolvedArgs: output.resolvedArgs },
+		...output.referenceContent == null ? {} : { referenceContent: output.referenceContent }
+	};
+}
+function getParentCheckpointFork(configurable) {
+	const checkpointId = configurable?.checkpoint_id;
+	return typeof checkpointId === "string" && checkpointId.length > 0 ? checkpointId : "root";
+}
+function getResumeAttemptId(configurable, fallback) {
+	const attemptId = configurable?.[SUBAGENT_RESUME_ATTEMPT_CONFIG_KEY];
+	return typeof attemptId === "string" && attemptId.length > 0 ? attemptId : fallback;
+}
+function getApprovalExecutionScope(childRunId, resumeAttemptId) {
+	return `subagent-approval:${Buffer.from(JSON.stringify([childRunId, resumeAttemptId])).toString("base64url")}`;
+}
+function getChildThreadId(args) {
+	const durableParentId = args.threadId ?? args.parentRunId;
+	const parentFork = getParentCheckpointFork(args.parentConfigurable);
+	const parentBatch = args.parentConfigurable?.[SUBAGENT_PARENT_BATCH_CONFIG_KEY];
+	const identity = [
+		durableParentId,
+		parentFork,
+		args.parentAgentId ?? "agent",
+		args.parentToolCallId,
+		typeof parentBatch === "string" && parentBatch.length > 0 ? parentBatch : "batch"
+	];
+	if (args.branchId != null) identity.push(args.branchId);
+	return `subagent:${Buffer.from(JSON.stringify(identity)).toString("base64url")}`;
+}
+function isToolApprovalPayload(value) {
+	return value != null && typeof value === "object" && value.type === "tool_approval";
+}
+function addSubagentScope(interrupts, scope, resumeManifest) {
+	return interrupts.map((childInterrupt) => {
+		const payload = isToolApprovalPayload(childInterrupt.value) ? {
+			...childInterrupt.value,
+			subagent: childInterrupt.value.subagent ?? scope
+		} : childInterrupt.value;
+		return {
+			...childInterrupt,
+			value: resumeManifest == null ? payload : attachSubagentResumeManifest(payload, resumeManifest)
+		};
+	});
+}
+function getChildResumeMap(pendingInterrupts, parentConfigurable) {
+	const resumeMap = parentConfigurable?.[LANGGRAPH_RESUME_MAP_CONFIG_KEY];
+	if (resumeMap == null || typeof resumeMap !== "object") return;
+	const parentResumeMap = resumeMap;
+	const childResumeMap = {};
+	for (const childInterrupt of pendingInterrupts) {
+		const interruptId = childInterrupt.id;
+		if (typeof interruptId === "string" && Object.prototype.hasOwnProperty.call(parentResumeMap, interruptId)) childResumeMap[interruptId] = parentResumeMap[interruptId];
+	}
+	return Object.keys(childResumeMap).length > 0 ? childResumeMap : void 0;
+}
+function getPersistedInterrupts(snapshot) {
+	const interrupts = [];
+	for (const task of snapshot.tasks) for (const pendingInterrupt of task.interrupts) interrupts.push(pendingInterrupt);
+	return interrupts;
+}
+function getPersistedMessages(snapshot) {
+	if (snapshot.values == null || typeof snapshot.values !== "object") return;
+	const values = snapshot.values;
+	if (!Array.isArray(values.messages) || values.messages.length === 0) return;
+	const messages = values.messages.filter((message) => !isSubagentCheckpointMarkerMessage(message));
+	return messages.length > 0 ? messages : void 0;
+}
+function createReplayCheckpointWorkflow(checkpointer) {
+	return new StateGraph(MessagesAnnotation).addNode(SUBAGENT_REPLAY_NODE, (state) => state).addEdge(START, SUBAGENT_REPLAY_NODE).addEdge(SUBAGENT_REPLAY_NODE, END).compile({ checkpointer });
+}
 var SubagentExecutor = class {
 	configs;
 	parentSignal;
@@ -40,9 +218,18 @@ var SubagentExecutor = class {
 	langfuse;
 	tokenCounter;
 	streamLimits;
+	humanInTheLoop;
+	checkpointer;
 	maxDepth;
 	createChildGraph;
 	usageSink;
+	checkpointThreadIds = /* @__PURE__ */ new Set();
+	startedChildRuns = /* @__PURE__ */ new Set();
+	completedChildRuns = /* @__PURE__ */ new Set();
+	completedChildResults = /* @__PURE__ */ new Map();
+	childExecutionIdentities = /* @__PURE__ */ new Map();
+	activeChildRuns = /* @__PURE__ */ new Map();
+	replayCheckpointWorkflow;
 	resolveParentHandlerRegistry;
 	constructor(options) {
 		this.configs = options.configs;
@@ -54,6 +241,8 @@ var SubagentExecutor = class {
 		this.langfuse = options.langfuse;
 		this.tokenCounter = options.tokenCounter;
 		this.streamLimits = options.streamLimits;
+		this.humanInTheLoop = options.humanInTheLoop;
+		this.checkpointer = isCheckpointSaver(options.checkpointer) ? options.checkpointer : void 0;
 		this.maxDepth = options.maxDepth ?? 1;
 		this.createChildGraph = options.createChildGraph;
 		this.usageSink = options.usageSink;
@@ -78,6 +267,274 @@ var SubagentExecutor = class {
 	getParentHandlerRegistry() {
 		return this.resolveParentHandlerRegistry?.();
 	}
+	/**
+	* Keeps the original child thread as an immutable resume source once a
+	* different parent Run reconstructs it. Each rebuilt parent gets a private
+	* checkpoint fork, while the persisted child run ID remains stable for
+	* activity and usage correlation across the interrupt boundary.
+	*/
+	async resolveChildExecutionIdentity(params) {
+		const currentChildRunId = `${this.parentRunId}_sub_${params.parentToolCallId}`;
+		const resumeAttemptId = getResumeAttemptId(params.parentConfigurable, this.parentRunId);
+		const baseChildThreadId = getChildThreadId({
+			parentRunId: this.parentRunId,
+			parentAgentId: this.parentAgentId,
+			threadId: params.threadId,
+			parentToolCallId: params.parentToolCallId,
+			parentConfigurable: params.parentConfigurable
+		});
+		if (this.humanInTheLoop?.enabled !== true || this.checkpointer == null) return {
+			childRunId: currentChildRunId,
+			childThreadId: baseChildThreadId,
+			approvalExecutionScope: currentChildRunId
+		};
+		const resumeExecution = getSubagentResumeManifest(params.parentConfigurable)?.executions.find((execution) => execution.parentToolCallId === params.parentToolCallId);
+		const branchChildThreadId = getChildThreadId({
+			parentRunId: this.parentRunId,
+			parentAgentId: this.parentAgentId,
+			threadId: params.threadId,
+			parentToolCallId: params.parentToolCallId,
+			parentConfigurable: params.parentConfigurable,
+			branchId: resumeAttemptId
+		});
+		if (resumeExecution != null) {
+			const approvalExecutionScope = getApprovalExecutionScope(resumeExecution.childRunId, resumeAttemptId);
+			await this.forkCheckpointSnapshot(resumeExecution.checkpoints, branchChildThreadId);
+			this.hookRegistry?.restorePendingToolApprovals(approvalExecutionScope, approvalExecutionScope, resumeExecution.approvalReplays);
+			this.checkpointThreadIds.add(branchChildThreadId);
+			return {
+				childRunId: resumeExecution.childRunId,
+				childThreadId: branchChildThreadId,
+				approvalExecutionScope,
+				resumeExecution
+			};
+		}
+		const branchTuple = await this.checkpointer.getTuple({ configurable: { thread_id: branchChildThreadId } });
+		if (branchTuple != null) {
+			const childRunId = getSubagentRunId(getTupleMessages(branchTuple)) ?? currentChildRunId;
+			this.checkpointThreadIds.add(branchChildThreadId);
+			return {
+				childRunId,
+				childThreadId: branchChildThreadId,
+				approvalExecutionScope: getApprovalExecutionScope(childRunId, resumeAttemptId)
+			};
+		}
+		const baseTuple = await this.checkpointer.getTuple({ configurable: { thread_id: baseChildThreadId } });
+		const persistedChildRunId = getSubagentRunId(getTupleMessages(baseTuple));
+		if (baseTuple == null || persistedChildRunId == null || persistedChildRunId === currentChildRunId) {
+			this.checkpointThreadIds.add(baseChildThreadId);
+			return {
+				childRunId: persistedChildRunId ?? currentChildRunId,
+				childThreadId: baseChildThreadId,
+				approvalExecutionScope: getApprovalExecutionScope(persistedChildRunId ?? currentChildRunId, resumeAttemptId)
+			};
+		}
+		const sourceCheckpoints = await this.getLatestCheckpointSnapshot(baseChildThreadId);
+		if (sourceCheckpoints.length === 0) throw new Error(`Cannot fork subagent checkpoint thread "${baseChildThreadId}" without a checkpoint ID.`);
+		await this.forkCheckpointSnapshot(sourceCheckpoints, branchChildThreadId);
+		this.checkpointThreadIds.add(branchChildThreadId);
+		return {
+			childRunId: persistedChildRunId,
+			childThreadId: branchChildThreadId,
+			approvalExecutionScope: getApprovalExecutionScope(persistedChildRunId, resumeAttemptId)
+		};
+	}
+	/** Captures one exact checkpoint head per namespace for a child thread. */
+	async getLatestCheckpointSnapshot(threadId) {
+		if (this.checkpointer == null) return [];
+		const checkpointsByNamespace = /* @__PURE__ */ new Map();
+		for await (const tuple of this.checkpointer.list({ configurable: { thread_id: threadId } })) {
+			const checkpoint = getCheckpointReference(tuple);
+			const current = checkpoint == null ? void 0 : checkpointsByNamespace.get(checkpoint.checkpointNs);
+			if (checkpoint != null && (current == null || checkpoint.checkpointId.localeCompare(current.checkpointId) > 0)) checkpointsByNamespace.set(checkpoint.checkpointNs, checkpoint);
+		}
+		return [...checkpointsByNamespace.values()].sort((left, right) => left.checkpointNs.localeCompare(right.checkpointNs));
+	}
+	/** Copies exact checkpoint lineages, including pending task writes. */
+	async forkCheckpointSnapshot(sources, targetThreadId) {
+		if (this.checkpointer == null || sources.length === 0 || sources.every((source) => source.threadId === targetThreadId)) return;
+		for (const source of sources) {
+			const tuples = [];
+			const visited = /* @__PURE__ */ new Set();
+			let tuple = await this.checkpointer.getTuple({ configurable: {
+				thread_id: source.threadId,
+				checkpoint_ns: source.checkpointNs,
+				checkpoint_id: source.checkpointId
+			} });
+			if (tuple == null) throw new Error(`Subagent checkpoint "${source.checkpointId}" is unavailable.`);
+			for (;;) {
+				const reference = getCheckpointReference(tuple);
+				if (reference == null) throw new Error("Subagent checkpoint lineage contains an invalid tuple.");
+				if (reference.threadId !== source.threadId || reference.checkpointNs !== source.checkpointNs) throw new Error("Subagent checkpoint lineage escapes its source namespace.");
+				const lineageKey = JSON.stringify([
+					reference.threadId,
+					reference.checkpointNs,
+					reference.checkpointId
+				]);
+				if (visited.has(lineageKey)) throw new Error("Subagent checkpoint lineage contains a cycle.");
+				visited.add(lineageKey);
+				tuples.push(tuple);
+				if (tuple.parentConfig == null) break;
+				tuple = await this.checkpointer.getTuple(tuple.parentConfig);
+				if (tuple == null) throw new Error("Subagent checkpoint lineage is incomplete.");
+			}
+			tuples.reverse();
+			for (const lineageTuple of tuples) {
+				const checkpointNs = getConfigurableString(lineageTuple.config, "checkpoint_ns") ?? "";
+				const parentCheckpointId = getConfigurableString(lineageTuple.parentConfig, "checkpoint_id");
+				const storedConfig = await this.checkpointer.put({ configurable: {
+					thread_id: targetThreadId,
+					checkpoint_ns: checkpointNs,
+					...parentCheckpointId == null ? {} : { checkpoint_id: parentCheckpointId }
+				} }, copyCheckpoint(lineageTuple.checkpoint), lineageTuple.metadata ?? {
+					source: "fork",
+					step: -1,
+					parents: {}
+				}, lineageTuple.checkpoint.channel_versions);
+				const writesByTask = /* @__PURE__ */ new Map();
+				for (const [taskId, channel, value] of lineageTuple.pendingWrites ?? []) {
+					let writes = writesByTask.get(taskId);
+					if (writes == null) {
+						writes = [];
+						writesByTask.set(taskId, writes);
+					}
+					writes.push([channel, value]);
+				}
+				for (const [taskId, writes] of writesByTask) await this.checkpointer.putWrites(storedConfig, writes, taskId);
+			}
+		}
+	}
+	async createResumeManifest(parentToolCallIds) {
+		if (this.checkpointer == null) return;
+		const executions = [];
+		for (const [parentToolCallId, identity] of this.childExecutionIdentities) {
+			if (parentToolCallIds != null && !parentToolCallIds.has(parentToolCallId)) continue;
+			const checkpoints = await this.getLatestCheckpointSnapshot(identity.childThreadId);
+			if (checkpoints.length === 0) continue;
+			const activeChildRun = this.activeChildRuns.get(identity.childThreadId);
+			const configuredHookSessionId = activeChildRun?.invokeConfig?.configurable?.run_id;
+			const hookSessionId = typeof configuredHookSessionId === "string" && configuredHookSessionId.length > 0 ? configuredHookSessionId : this.parentRunId;
+			const approvalReplays = this.hookRegistry?.snapshotPendingToolApprovals(identity.approvalExecutionScope, identity.approvalExecutionScope) ?? [];
+			const descendant = activeChildRun?.pendingInterrupts.map((pendingInterrupt) => getSubagentResumeManifest(pendingInterrupt.value)).find((manifest) => manifest != null);
+			const graphState = activeChildRun?.graph.createSubagentResumeState(hookSessionId) ?? {
+				toolCallSteps: [],
+				toolSessions: [],
+				toolNodes: [],
+				eagerToolUsage: [],
+				eagerToolSuppressions: []
+			};
+			executions.push({
+				parentToolCallId,
+				childRunId: identity.childRunId,
+				approvalExecutionScope: identity.approvalExecutionScope,
+				checkpoints,
+				graphState,
+				approvalReplays,
+				...descendant == null ? {} : { descendant }
+			});
+		}
+		if (executions.length === 0) return;
+		return {
+			version: 1,
+			executions
+		};
+	}
+	getResumeManifest(parentToolCallIds) {
+		return this.createResumeManifest(parentToolCallIds);
+	}
+	getChildCheckpointThreadIds() {
+		const threadIds = new Set(this.checkpointThreadIds);
+		for (const activeChildRun of this.activeChildRuns.values()) for (const threadId of this.getGraphChildCheckpointThreadIds(activeChildRun.graph)) threadIds.add(threadId);
+		return [...threadIds];
+	}
+	resetCheckpointThreadIds() {
+		this.checkpointThreadIds.clear();
+	}
+	getGraphChildCheckpointThreadIds(graph) {
+		return graph.getChildCheckpointThreadIds?.() ?? [];
+	}
+	clearChildGraph(graph) {
+		for (const threadId of this.getGraphChildCheckpointThreadIds(graph)) this.checkpointThreadIds.add(threadId);
+		graph.clearHeavyState();
+	}
+	clearHeavyState() {
+		for (const activeChildRun of this.activeChildRuns.values()) this.clearChildGraph(activeChildRun.graph);
+		this.activeChildRuns.clear();
+		this.completedChildResults.clear();
+		for (const identity of this.childExecutionIdentities.values()) this.hookRegistry?.clearSession(identity.approvalExecutionScope);
+		this.childExecutionIdentities.clear();
+		this.startedChildRuns.clear();
+		this.completedChildRuns.clear();
+		this.replayCheckpointWorkflow = void 0;
+	}
+	async getSettledToolOutput(call, config) {
+		const parentToolCallId = call.id;
+		if (this.humanInTheLoop?.enabled !== true || this.checkpointer == null || parentToolCallId == null || parentToolCallId === "") return;
+		const parentConfigurable = config.configurable;
+		const threadId = parentConfigurable?.thread_id;
+		const { childRunId, childThreadId, approvalExecutionScope } = await this.resolveChildExecutionIdentity({
+			threadId: typeof threadId === "string" ? threadId : void 0,
+			parentToolCallId,
+			parentConfigurable
+		});
+		this.childExecutionIdentities.set(parentToolCallId, {
+			childRunId,
+			childThreadId,
+			approvalExecutionScope
+		});
+		this.checkpointThreadIds.add(childThreadId);
+		const messages = getCheckpointMessages((await this.checkpointer.getTuple({ configurable: { thread_id: childThreadId } }))?.checkpoint.channel_values.messages);
+		const marker = getSubagentCheckpointMarker(messages, parentToolCallId);
+		const persistedHookSessionId = marker?.hookSessionId ?? getSubagentHookSessionId(messages);
+		const currentHookSessionId = parentConfigurable?.run_id;
+		if (persistedHookSessionId != null && typeof currentHookSessionId === "string" && currentHookSessionId.length > 0) this.hookRegistry?.copySession(persistedHookSessionId, currentHookSessionId);
+		return marker?.settledOutput == null ? void 0 : deserializeToolOutput(marker.settledOutput);
+	}
+	async persistSettledToolOutput(call, config, settled) {
+		const parentToolCallId = call.id;
+		if (this.humanInTheLoop?.enabled !== true || this.checkpointer == null || parentToolCallId == null || parentToolCallId === "") return;
+		const parentConfigurable = config.configurable;
+		const threadId = parentConfigurable?.thread_id;
+		const { childRunId, childThreadId, approvalExecutionScope } = await this.resolveChildExecutionIdentity({
+			threadId: typeof threadId === "string" ? threadId : void 0,
+			parentToolCallId,
+			parentConfigurable
+		});
+		this.childExecutionIdentities.set(parentToolCallId, {
+			childRunId,
+			childThreadId,
+			approvalExecutionScope
+		});
+		this.checkpointThreadIds.add(childThreadId);
+		const activeChildRun = this.activeChildRuns.get(childThreadId);
+		const persistedOutput = serializeToolOutput(settled);
+		if (activeChildRun != null) {
+			await this.persistChildCheckpointMarker(activeChildRun, parentToolCallId, persistedOutput);
+			this.clearChildGraph(activeChildRun.graph);
+			this.activeChildRuns.delete(childThreadId);
+			return;
+		}
+		this.replayCheckpointWorkflow ??= createReplayCheckpointWorkflow(this.checkpointer);
+		await this.replayCheckpointWorkflow.updateState({ configurable: { thread_id: childThreadId } }, { messages: [createSubagentCheckpointMarkerMessage({
+			version: 1,
+			parentToolCallId,
+			lifecycleComplete: true,
+			hookSessionId: typeof parentConfigurable?.run_id === "string" ? parentConfigurable.run_id : this.parentRunId,
+			childRunId,
+			settledOutput: persistedOutput
+		})] }, SUBAGENT_REPLAY_NODE);
+	}
+	async persistChildCheckpointMarker(activeChildRun, parentToolCallId, settledOutput) {
+		if (this.humanInTheLoop?.enabled !== true || activeChildRun.workflow.updateState == null || activeChildRun.invokeConfig == null) return;
+		await activeChildRun.workflow.updateState(activeChildRun.invokeConfig, { messages: [createSubagentCheckpointMarkerMessage({
+			version: 1,
+			parentToolCallId,
+			lifecycleComplete: true,
+			hookSessionId: typeof activeChildRun.invokeConfig.configurable?.run_id === "string" ? activeChildRun.invokeConfig.configurable.run_id : this.parentRunId,
+			childRunId: activeChildRun.childRunId,
+			...settledOutput == null ? {} : { settledOutput }
+		})] }, activeChildRun.childAgentId);
+	}
 	async execute(params) {
 		const { description, subagentType, threadId, parentToolCallId } = params;
 		/** Captured ONCE per execution, preferring the controller the parent
@@ -98,32 +555,25 @@ var SubagentExecutor = class {
 			content: "Error: Maximum subagent nesting depth exceeded.",
 			messages: []
 		};
-		const childAgentId = config.agentInputs.agentId || `${this.parentAgentId ?? "agent"}_sub_${nanoid(8)}`;
-		if (this.hookRegistry?.hasHookFor("SubagentStart", this.parentRunId) === true) {
-			const hookResult = await executeHooks({
-				registry: this.hookRegistry,
-				input: {
-					hook_event_name: "SubagentStart",
-					runId: this.parentRunId,
-					threadId,
-					parentAgentId: this.parentAgentId,
-					agentId: childAgentId,
-					agentType: subagentType,
-					inputs: [new HumanMessage(description)]
-				},
-				sessionId: this.parentRunId,
-				matchQuery: subagentType
-			}).catch(() => HOOK_FALLBACK);
-			/**
-			* `ask` is treated identically to `deny` in the subagent context:
-			* subagents are non-interactive, so there is no prompt path for `ask`.
-			* Both decisions block execution and return a "Blocked" tool result.
-			*/
-			if (hookResult.decision === "deny" || hookResult.decision === "ask") return {
-				content: `Blocked: ${hookResult.reason ?? "Blocked by hook"}`,
-				messages: []
-			};
-		}
+		if (this.humanInTheLoop?.enabled === true && (parentToolCallId == null || parentToolCallId === "")) return {
+			content: "Error: Resumable subagent execution requires a parent tool call ID.",
+			messages: []
+		};
+		const executionSuffix = parentToolCallId ?? nanoid(8);
+		const { childRunId, childThreadId, approvalExecutionScope, resumeExecution } = await this.resolveChildExecutionIdentity({
+			threadId,
+			parentToolCallId: executionSuffix,
+			parentConfigurable: params.parentConfigurable
+		});
+		this.childExecutionIdentities.set(executionSuffix, {
+			childRunId,
+			childThreadId,
+			approvalExecutionScope
+		});
+		const childExecutionKey = childThreadId;
+		const childAgentId = config.agentInputs.agentId || `${this.parentAgentId ?? "agent"}_sub_${executionSuffix}`;
+		const completedChildResult = this.completedChildResults.get(childExecutionKey);
+		if (completedChildResult != null) return completedChildResult;
 		const parentRegistry = this.getParentHandlerRegistry();
 		const forwardingEnabled = parentRegistry != null;
 		/**
@@ -137,10 +587,10 @@ var SubagentExecutor = class {
 		*/
 		const hasToolExecuteHandler = parentRegistry?.getHandler("on_tool_execute") != null;
 		const childInputs = buildChildInputs(config, childAgentId, this.maxDepth, hasToolExecuteHandler);
-		const childRunId = `${this.parentRunId}_sub_${nanoid(8)}`;
 		const maxTurns = config.maxTurns ?? DEFAULT_MAX_TURNS;
 		const hostUsageSink = this.usageSink;
-		const childGraph = this.createChildGraph({
+		const cachedChildRun = this.activeChildRuns.get(childExecutionKey);
+		const childGraph = cachedChildRun?.graph ?? this.createChildGraph({
 			runId: childRunId,
 			signal: childSignal,
 			agents: [childInputs],
@@ -177,17 +627,21 @@ var SubagentExecutor = class {
 			parentToolCallId
 		});
 		const forwarder = forwarding?.handler;
-		if (forwarder) await this.emitSubagentUpdate(parentRegistry, {
-			childRunId,
-			subagentType,
-			subagentAgentId: childAgentId,
-			parentToolCallId,
-			phase: "start",
-			label: `Subagent "${subagentType}" started`
-		});
+		let childAlreadyStarted = this.startedChildRuns.has(childExecutionKey);
+		let childAlreadyCompleted = this.completedChildRuns.has(childExecutionKey);
 		let result;
+		let recoveredComplete = false;
+		let recoveredInProgress = false;
 		try {
-			const workflow = childGraph.createWorkflow();
+			const workflow = cachedChildRun?.workflow ?? childGraph.createWorkflow();
+			const activeChildRun = cachedChildRun ?? {
+				graph: childGraph,
+				workflow,
+				pendingInterrupts: [],
+				childAgentId,
+				childRunId
+			};
+			if (cachedChildRun == null) this.activeChildRuns.set(childExecutionKey, activeChildRun);
 			/**
 			* When `parentHandlerRegistry` is provided (forwarding mode), attach a
 			* lightweight callback that intercepts the child's `on_custom_event`
@@ -225,46 +679,136 @@ var SubagentExecutor = class {
 			}));
 			const callbacks = callbackHandlers;
 			/**
-			* Inherit the parent's host `configurable` — host-set fields
-			* (`requestBody`, `user`, `userMCPAuthMap`, etc.) AND the run-
-			* identity fields (`run_id`, `parent_run_id`, `thread_id`) all
-			* propagate. LangGraph's own runtime keys are excluded because the
-			* child graph creates its own scratchpad/checkpoint/abort plumbing.
+			* Inherit the parent's host `configurable` while binding LangGraph's
+			* checkpoint identity to a stable child id derived from the durable
+			* parent thread and checkpoint fork. The parent thread id cannot be
+			* reused here: parent and child share one checkpointer when nested HITL
+			* is enabled, and root checkpoint namespaces are normalized by
+			* LangGraph, so a shared `thread_id` would collide with the parent.
 			*
-			* Run-identity propagation is intentional and matches the
-			* convention this executor itself already uses for `SubagentStart`
-			* / `SubagentStop` hooks (`sessionId: this.parentRunId`): the
-			* subagent runs under the parent's session scope, not its own.
-			* Forwarding `run_id` / `parent_run_id` / `thread_id` makes
-			* `ToolNode`'s hook lookups (`hasHookFor(eventName, runId)`),
-			* `ToolOutputReferenceRegistry` keying, and trace lineage all
-			* resolve to the parent's session for tools dispatched from the
-			* subagent — so `PreToolUse` / `PostToolUse` hooks the host
-			* registered against the parent's run fire for subagent tool
-			* calls too. "Same run" matches the user-perceptual mental model.
-			*
-			* `thread_id` falls back to `childRunId` only when the parent
-			* didn't supply one (legacy behavior preserved for hosts that
-			* never set thread_id).
-			*
-			* NOTE: a future revision will likely make this configurable per
-			* spawn type — e.g. a background / async subagent that runs after
-			* the parent's run completes wants isolation, not inheritance.
-			* For now the inheritance path matches LibreChat's primary use
-			* case (synchronous subagents within a single user turn).
+			* `run_id` still propagates as the parent run id, which is the key used
+			* for session-scoped hook lookup. Child hook inputs therefore retain
+			* the parent policy scope while their `threadId` truthfully identifies
+			* the independently checkpointed child execution.
 			*/
 			const inheritedConfigurable = sanitizeChildConfigurable(params.parentConfigurable);
-			result = await workflow.invoke({ messages: [new HumanMessage(description)] }, {
+			const resumeAttemptId = getResumeAttemptId(params.parentConfigurable, this.parentRunId);
+			const currentHookSessionId = typeof inheritedConfigurable.run_id === "string" && inheritedConfigurable.run_id.length > 0 ? inheritedConfigurable.run_id : this.parentRunId;
+			if (cachedChildRun == null && resumeExecution != null) childGraph.restoreSubagentResumeState(resumeExecution.graphState, currentHookSessionId);
+			const childInvokeConfig = {
 				recursionLimit: maxTurns * RECURSION_MULTIPLIER,
 				signal: childSignal,
 				callbacks,
 				runName: `subagent:${subagentType}`,
 				configurable: {
-					thread_id: childRunId,
-					...inheritedConfigurable
+					...inheritedConfigurable,
+					...this.humanInTheLoop?.enabled === true ? { [TOOL_APPROVAL_EXECUTION_SCOPE_CONFIG_KEY]: approvalExecutionScope } : {},
+					...resumeExecution?.descendant == null ? {} : {
+						[SUBAGENT_RESUME_MANIFEST_CONFIG_KEY]: resumeExecution.descendant,
+						[SUBAGENT_RESUME_ATTEMPT_CONFIG_KEY]: resumeAttemptId
+					},
+					thread_id: this.humanInTheLoop?.enabled === true ? childThreadId : inheritedConfigurable.thread_id ?? childRunId
 				}
-			});
+			};
+			activeChildRun.invokeConfig = childInvokeConfig;
+			if (cachedChildRun == null && this.humanInTheLoop?.enabled === true) {
+				/** Rehydrate child-owned interrupt state when a host rebuilds Run
+				* around the same durable checkpointer after a process boundary. */
+				const persistedState = await workflow.getState(childInvokeConfig);
+				const checkpointMessages = getCheckpointMessages(persistedState.values?.messages);
+				const persistedHookSessionId = getSubagentHookSessionId(checkpointMessages);
+				if (persistedHookSessionId != null) this.hookRegistry?.copySession(persistedHookSessionId, currentHookSessionId);
+				const persistedInterrupts = getPersistedInterrupts(persistedState);
+				if (persistedInterrupts.length > 0) {
+					activeChildRun.pendingInterrupts = persistedInterrupts;
+					this.startedChildRuns.add(childExecutionKey);
+					childAlreadyStarted = true;
+				} else if (persistedState.next.length > 0) {
+					recoveredInProgress = true;
+					childAlreadyStarted = true;
+					this.startedChildRuns.add(childExecutionKey);
+				} else if (persistedState.next.length === 0) {
+					const persistedMessages = getPersistedMessages(persistedState);
+					if (persistedMessages != null) {
+						const marker = getSubagentCheckpointMarker(checkpointMessages, executionSuffix);
+						result = { messages: persistedMessages };
+						recoveredComplete = true;
+						childAlreadyStarted = true;
+						childAlreadyCompleted = marker?.lifecycleComplete === true;
+						this.startedChildRuns.add(childExecutionKey);
+					}
+				}
+			}
+			if (!recoveredComplete) {
+				const childResumeMap = getChildResumeMap(activeChildRun.pendingInterrupts, params.parentConfigurable);
+				if (activeChildRun.pendingInterrupts.length > 0 && childResumeMap == null) throw new GraphInterrupt(activeChildRun.pendingInterrupts);
+				let childInput;
+				if (childResumeMap != null) childInput = new Command({ resume: childResumeMap });
+				else if (recoveredInProgress) childInput = null;
+				else childInput = { messages: [new HumanMessage({
+					content: description,
+					additional_kwargs: {
+						[SUBAGENT_HOOK_SESSION_KEY]: currentHookSessionId,
+						[SUBAGENT_RUN_ID_KEY]: childRunId
+					}
+				})] };
+				if (!childAlreadyStarted && this.hookRegistry?.hasHookFor("SubagentStart", this.parentRunId) === true) {
+					const hookResult = await executeHooks({
+						registry: this.hookRegistry,
+						input: {
+							hook_event_name: "SubagentStart",
+							runId: this.parentRunId,
+							threadId,
+							parentAgentId: this.parentAgentId,
+							agentId: childAgentId,
+							agentType: subagentType,
+							inputs: [new HumanMessage(description)]
+						},
+						sessionId: this.parentRunId,
+						matchQuery: subagentType
+					}).catch(() => HOOK_FALLBACK);
+					if (hookResult.decision === "deny" || hookResult.decision === "ask") {
+						this.clearChildGraph(childGraph);
+						this.activeChildRuns.delete(childExecutionKey);
+						return {
+							content: `Blocked: ${hookResult.reason ?? "Blocked by hook"}`,
+							messages: []
+						};
+					}
+				}
+				this.startedChildRuns.add(childExecutionKey);
+				if (forwarder && !childAlreadyStarted) await this.emitSubagentUpdate(parentRegistry, {
+					childRunId,
+					subagentType,
+					subagentAgentId: childAgentId,
+					parentToolCallId,
+					phase: "start",
+					label: `Subagent "${subagentType}" started`
+				});
+				let childResult;
+				if (this.humanInTheLoop?.enabled === true)
+ /** Execute as an independently checkpointed root instead of inheriting
+				* the parent's Pregel namespace. Parent decisions are routed explicitly
+				* by interrupt id, so concurrent children keep isolated resume state. */
+				childResult = await AsyncLocalStorageProviderSingleton.runWithConfig(childInvokeConfig, () => workflow.invoke(childInput, childInvokeConfig));
+				else childResult = await workflow.invoke(childInput, childInvokeConfig);
+				const childInterrupts = isInterrupted(childResult) ? childResult[INTERRUPT] : void 0;
+				if (childInterrupts != null && childInterrupts.length > 0) throw new GraphInterrupt(childInterrupts);
+				result = { messages: childResult.messages };
+			}
 		} catch (error) {
+			if (isGraphInterrupt(error)) {
+				const activeChildRun = this.activeChildRuns.get(childExecutionKey);
+				if (activeChildRun != null) activeChildRun.pendingInterrupts = error.interrupts;
+				const resumeManifest = activeChildRun == null || parentToolCallId == null ? void 0 : await this.createResumeManifest();
+				await forwarding?.drain();
+				throw new GraphInterrupt(addSubagentScope(error.interrupts, {
+					run_id: childRunId,
+					agent_id: childAgentId,
+					subagent_type: subagentType,
+					parent_tool_call_id: parentToolCallId
+				}, resumeManifest));
+			}
 			/** Aborted before any observational work below: parallel siblings — in
 			* this executor and, via the graph-scoped breaker, under other
 			* parallel agent nodes — stream on the composed child signal, and
@@ -286,7 +830,8 @@ var SubagentExecutor = class {
 					data: { message: errorMessage }
 				});
 			}
-			childGraph.clearHeavyState();
+			this.clearChildGraph(childGraph);
+			this.activeChildRuns.delete(childExecutionKey);
 			/**
 			* A tripped stream circuit breaker is a safety abort, not a recoverable
 			* subagent failure: converting it into a tool result would let the
@@ -300,8 +845,9 @@ var SubagentExecutor = class {
 				messages: []
 			};
 		}
+		if (result == null) throw new Error("Subagent completed without producing graph state.");
 		const filteredContent = filterSubagentResult(result.messages);
-		if (this.hookRegistry?.hasHookFor("SubagentStop", this.parentRunId) === true)
+		if (!childAlreadyCompleted && this.hookRegistry?.hasHookFor("SubagentStop", this.parentRunId) === true)
  /**
 		* Awaited (not fire-and-forget) for deterministic test synchronization
 		* and consistency with PostCompact. The parent is already waiting on the
@@ -321,7 +867,7 @@ var SubagentExecutor = class {
 			sessionId: this.parentRunId,
 			matchQuery: subagentType
 		}).catch(() => {});
-		if (forwarding) {
+		if (forwarding && !childAlreadyCompleted) {
 			await forwarding.drain();
 			await this.emitSubagentUpdate(parentRegistry, {
 				childRunId,
@@ -332,11 +878,18 @@ var SubagentExecutor = class {
 				label: `Subagent "${subagentType}" finished`
 			});
 		}
-		childGraph.clearHeavyState();
-		return {
+		if (!childAlreadyCompleted) {
+			const activeChildRun = this.activeChildRuns.get(childExecutionKey);
+			if (activeChildRun != null && parentToolCallId != null) await this.persistChildCheckpointMarker(activeChildRun, parentToolCallId);
+		}
+		this.completedChildRuns.add(childExecutionKey);
+		this.clearChildGraph(childGraph);
+		const completedResult = {
 			content: filteredContent,
 			messages: result.messages
 		};
+		this.completedChildResults.set(childExecutionKey, completedResult);
+		return completedResult;
 	}
 	/**
 	* Emits a single {@link GraphEvents.ON_SUBAGENT_UPDATE} envelope through the
@@ -583,7 +1136,7 @@ function sanitizeChildConfigurable(parentConfigurable) {
 	return Object.fromEntries(Object.entries(parentConfigurable).filter(([key]) => !isLangGraphRuntimeConfigKey(key)));
 }
 function isLangGraphRuntimeConfigKey(key) {
-	return key.startsWith(LANGGRAPH_RUNTIME_CONFIG_PREFIX) || LANGGRAPH_CHECKPOINT_CONFIG_KEYS.has(key) || key === "lc_run_breaker_scope";
+	return key.startsWith(LANGGRAPH_RUNTIME_CONFIG_PREFIX) || LANGGRAPH_CHECKPOINT_CONFIG_KEYS.has(key) || key === "__librechat_subagent_resume_attempt" || key === "__librechat_subagent_resume_manifest" || key === "__librechat_subagent_parent_batch" || key === "lc_run_breaker_scope";
 }
 function sanitizeForwardedSubagentUpdateData(eventName, data) {
 	if (eventName === "on_tool_execute") return sanitizeToolExecuteUpdateData(data);
@@ -880,11 +1433,10 @@ function buildChildInputs(config, childAgentId, parentMaxDepth, keepToolDefiniti
 		* Host-supplied direct tools are scrubbed from INHERITED configs only.
 		* A self-spawn config's `agentInputs` is a shallow spread of the parent's
 		* `_sourceInputs`, so without this a parent-scoped graph tool (e.g. an
-		* interrupt-raising ask_user_question, which needs the parent's
-		* checkpointer — child graphs compile without one) would silently leak
-		* into the child and deterministically throw `No checkpointer set`. An
-		* EXPLICIT child config that lists its own `graphTools` is a deliberate
-		* host choice and keeps them (Codex #289 P2).
+		* interrupt-raising ask_user_question) would silently become available to
+		* the child. An EXPLICIT child config that lists its own `graphTools` is a
+		* deliberate host choice and keeps them (Codex #289 P2); with HITL enabled,
+		* those tools use the shared checkpointer and can pause and resume safely.
 		*/
 		graphTools: config.self === true ? void 0 : agentInputs.graphTools
 	};