feat(filesystem): implement filesystem tree watch functionality using chokidar for real-time updates on local folder changes

surfsense_web/components/assistant-ui/markdown-text.tsx

@@ -229,6 +229,44 @@ function extractDomain(url: string): string {
 // Canonical local-file virtual paths are mount-prefixed: /<mount>/<relative/path>
 const LOCAL_FILE_PATH_REGEX = /^\/[a-z0-9_-]+\/[^\s`]+(?:\/[^\s`]+)*$/;
 
+type AgentFilesystemMount = {
+	mount: string;
+	rootPath: string;
+};
+
+function normalizeLocalVirtualPathForEditor(
+	candidatePath: string,
+	mounts: AgentFilesystemMount[]
+): string {
+	const normalizedCandidate = candidatePath.trim().replace(/\\/g, "/").replace(/\/+/g, "/");
+	if (!normalizedCandidate) {
+		return candidatePath;
+	}
+	const defaultMount = mounts[0]?.mount;
+	if (!defaultMount) {
+		return normalizedCandidate.startsWith("/")
+			? normalizedCandidate
+			: `/${normalizedCandidate.replace(/^\/+/, "")}`;
+	}
+
+	const mountNames = new Set(mounts.map((entry) => entry.mount));
+	if (normalizedCandidate.startsWith("/")) {
+		const relative = normalizedCandidate.replace(/^\/+/, "");
+		const [firstSegment] = relative.split("/", 1);
+		if (mountNames.has(firstSegment)) {
+			return `/${relative}`;
+		}
+		return `/${defaultMount}/${relative}`;
+	}
+
+	const relative = normalizedCandidate.replace(/^\/+/, "");
+	const [firstSegment] = relative.split("/", 1);
+	if (mountNames.has(firstSegment)) {
+		return `/${relative}`;
+	}
+	return `/${defaultMount}/${relative}`;
+}
+
 function isVirtualFilePathToken(value: string): boolean {
 	if (!LOCAL_FILE_PATH_REGEX.test(value) || value.startsWith("//")) {
 		return false;
@@ -421,8 +459,15 @@ const defaultComponents = memoizeMarkdownComponents({
 			!codeString.includes("\n");
 		if (!isCodeBlock) {
 			const inlineValue = String(children ?? "").trim();
+			const normalizedInlinePath = inlineValue.replace(/\/+$/, "");
+			const leafSegment = normalizedInlinePath.split("/").filter(Boolean).at(-1) ?? "";
+			const isLikelyFolder =
+				inlineValue.endsWith("/") || !leafSegment || !leafSegment.includes(".");
 			const isLocalPath =
-				!!electronAPI && isVirtualFilePathToken(inlineValue) && !inlineValue.startsWith("//");
+				!!electronAPI &&
+				isVirtualFilePathToken(inlineValue) &&
+				!inlineValue.startsWith("//") &&
+				!isLikelyFolder;
 			const displayLocalPath = inlineValue.replace(/^\/+/, "");
 			const searchSpaceIdParam = params?.search_space_id;
 			const parsedSearchSpaceId = Array.isArray(searchSpaceIdParam)
@@ -438,14 +483,31 @@ const defaultComponents = memoizeMarkdownComponents({
 						onClick={(event) => {
 							event.preventDefault();
 							event.stopPropagation();
-							openEditorPanel({
-								kind: "local_file",
-								localFilePath: inlineValue,
-								title: inlineValue.split("/").pop() || inlineValue,
-								searchSpaceId: Number.isFinite(parsedSearchSpaceId)
+							void (async () => {
+								let resolvedLocalPath = inlineValue;
+								const resolvedSearchSpaceId = Number.isFinite(parsedSearchSpaceId)
 									? parsedSearchSpaceId
-									: undefined,
-							});
+									: undefined;
+								if (electronAPI?.getAgentFilesystemMounts) {
+									try {
+										const mounts = (await electronAPI.getAgentFilesystemMounts(
+											resolvedSearchSpaceId
+										)) as AgentFilesystemMount[];
+										resolvedLocalPath = normalizeLocalVirtualPathForEditor(
+											inlineValue,
+											mounts
+										);
+									} catch {
+										// Fall back to the raw inline path if mount lookup fails.
+									}
+								}
+								openEditorPanel({
+									kind: "local_file",
+									localFilePath: resolvedLocalPath,
+									title: resolvedLocalPath.split("/").pop() || resolvedLocalPath,
+									searchSpaceId: resolvedSearchSpaceId,
+								});
+							})();
 						}}
 						title="Open in editor panel"
 					>

surfsense_web/components/editor-panel/editor-panel.tsx

@@ -47,6 +47,42 @@ interface EditorContent {
 const EDITABLE_DOCUMENT_TYPES = new Set(["FILE", "NOTE"]);
 type EditorRenderMode = "rich_markdown" | "source_code";
 
+type AgentFilesystemMount = {
+	mount: string;
+	rootPath: string;
+};
+
+function normalizeLocalVirtualPathForEditor(
+	candidatePath: string,
+	mounts: AgentFilesystemMount[]
+): string {
+	const normalizedCandidate = candidatePath.trim().replace(/\\/g, "/").replace(/\/+/g, "/");
+	if (!normalizedCandidate) return candidatePath;
+	const defaultMount = mounts[0]?.mount;
+	if (!defaultMount) {
+		return normalizedCandidate.startsWith("/")
+			? normalizedCandidate
+			: `/${normalizedCandidate.replace(/^\/+/, "")}`;
+	}
+
+	const mountNames = new Set(mounts.map((entry) => entry.mount));
+	if (normalizedCandidate.startsWith("/")) {
+		const relative = normalizedCandidate.replace(/^\/+/, "");
+		const [firstSegment] = relative.split("/", 1);
+		if (mountNames.has(firstSegment)) {
+			return `/${relative}`;
+		}
+		return `/${defaultMount}/${relative}`;
+	}
+
+	const relative = normalizedCandidate.replace(/^\/+/, "");
+	const [firstSegment] = relative.split("/", 1);
+	if (mountNames.has(firstSegment)) {
+		return `/${relative}`;
+	}
+	return `/${defaultMount}/${relative}`;
+}
+
 function EditorPanelSkeleton() {
 	return (
 		<div className="space-y-6 p-6">
@@ -100,6 +136,22 @@ export function EditorPanelContent({
 	const [displayTitle, setDisplayTitle] = useState(title || "Untitled");
 	const isLocalFileMode = kind === "local_file";
 	const editorRenderMode: EditorRenderMode = isLocalFileMode ? "source_code" : "rich_markdown";
+	const resolveLocalVirtualPath = useCallback(
+		async (candidatePath: string): Promise<string> => {
+			if (!electronAPI?.getAgentFilesystemMounts) {
+				return candidatePath;
+			}
+			try {
+				const mounts = (await electronAPI.getAgentFilesystemMounts(
+					searchSpaceId
+				)) as AgentFilesystemMount[];
+				return normalizeLocalVirtualPathForEditor(candidatePath, mounts);
+			} catch {
+				return candidatePath;
+			}
+		},
+		[electronAPI, searchSpaceId]
+	);
 
 	const isLargeDocument = (editorDoc?.content_size_bytes ?? 0) > LARGE_DOCUMENT_THRESHOLD;
 
@@ -124,14 +176,15 @@ export function EditorPanelContent({
 					if (!electronAPI?.readAgentLocalFileText) {
 						throw new Error("Local file editor is available only in desktop mode.");
 					}
+					const resolvedLocalPath = await resolveLocalVirtualPath(localFilePath);
 					const readResult = await electronAPI.readAgentLocalFileText(
-						localFilePath,
+						resolvedLocalPath,
 						searchSpaceId
 					);
 					if (!readResult.ok) {
 						throw new Error(readResult.error || "Failed to read local file");
 					}
-					const inferredTitle = localFilePath.split("/").pop() || localFilePath;
+					const inferredTitle = resolvedLocalPath.split("/").pop() || resolvedLocalPath;
 					const content: EditorContent = {
 						document_id: -1,
 						title: inferredTitle,
@@ -195,7 +248,7 @@ export function EditorPanelContent({
 
 		doFetch().catch(() => {});
 		return () => controller.abort();
-	}, [documentId, electronAPI, isLocalFileMode, localFilePath, searchSpaceId, title]);
+	}, [documentId, electronAPI, isLocalFileMode, localFilePath, resolveLocalVirtualPath, searchSpaceId, title]);
 
 	useEffect(() => {
 		return () => {
@@ -239,9 +292,10 @@ export function EditorPanelContent({
 				if (!electronAPI?.writeAgentLocalFileText) {
 					throw new Error("Local file editor is available only in desktop mode.");
 				}
+				const resolvedLocalPath = await resolveLocalVirtualPath(localFilePath);
 				const contentToSave = markdownRef.current;
 				const writeResult = await electronAPI.writeAgentLocalFileText(
-					localFilePath,
+					resolvedLocalPath,
 					contentToSave,
 					searchSpaceId
 				);
@@ -290,7 +344,7 @@ export function EditorPanelContent({
 		} finally {
 			setSaving(false);
 		}
-	}, [documentId, electronAPI, isLocalFileMode, localFilePath, searchSpaceId]);
+	}, [documentId, electronAPI, isLocalFileMode, localFilePath, resolveLocalVirtualPath, searchSpaceId]);
 
 	const isEditableType = editorDoc
 		? (editorRenderMode === "source_code" ||

surfsense_web/components/layout/ui/sidebar/LocalFilesystemBrowser.tsx

@@ -86,7 +86,8 @@ export function LocalFilesystemBrowser({
 	const [mountByRootKey, setMountByRootKey] = useState<Map<string, string>>(new Map());
 	const [mountStatus, setMountStatus] = useState<MountLoadStatus>("idle");
 	const [mountRefreshInFlight, setMountRefreshInFlight] = useState(false);
-	const lastLoadedRootsSignatureRef = useRef<string>("");
+	const [reloadNonceByRoot, setReloadNonceByRoot] = useState<Record<string, number>>({});
+	const lastLoadedSignatureByRootRef = useRef<Map<string, string>>(new Map());
 	const hasLoadedMountsOnceRef = useRef(false);
 	const hasResolvedAtLeastOneRootRef = useRef(false);
 	const supportedExtensions = useMemo(() => Array.from(getSupportedExtensionsSet()), []);
@@ -107,18 +108,34 @@ export function LocalFilesystemBrowser({
 			}
 			return;
 		}
-		const rootsSignature = rootPaths
-			.map((rootPath) => normalizeRootPathForLookup(rootPath, isWindowsPlatform))
-			.sort()
-			.join("|");
-		const settingsSignature = `${searchSpaceId}:${rootsSignature}`;
-		if (settingsSignature === lastLoadedRootsSignatureRef.current) {
+		const rootEntries = rootPaths.map((rootPath) => ({
+			rootPath,
+			rootKey: normalizeRootPathForLookup(rootPath, isWindowsPlatform),
+		}));
+		const activeRootKeys = new Set(rootEntries.map((entry) => entry.rootKey));
+		for (const key of Array.from(lastLoadedSignatureByRootRef.current.keys())) {
+			if (!activeRootKeys.has(key)) {
+				lastLoadedSignatureByRootRef.current.delete(key);
+			}
+		}
+		const rootsToReload = rootEntries.filter(({ rootKey }) => {
+			const nonce = reloadNonceByRoot[rootKey] ?? 0;
+			const signature = `${searchSpaceId}:${rootKey}:${nonce}`;
+			return lastLoadedSignatureByRootRef.current.get(rootKey) !== signature;
+		});
+		if (rootsToReload.length === 0) {
 			return;
 		}
-		lastLoadedRootsSignatureRef.current = settingsSignature;
+		for (const { rootKey } of rootsToReload) {
+			const nonce = reloadNonceByRoot[rootKey] ?? 0;
+			lastLoadedSignatureByRootRef.current.set(
+				rootKey,
+				`${searchSpaceId}:${rootKey}:${nonce}`
+			);
+		}
 		let cancelled = false;
 
-		for (const rootPath of rootPaths) {
+		for (const { rootPath } of rootsToReload) {
 			setRootStateMap((prev) => ({
 				...prev,
 				[rootPath]: {
@@ -130,7 +147,7 @@ export function LocalFilesystemBrowser({
 		}
 
 		void Promise.all(
-			rootPaths.map(async (rootPath) => {
+			rootsToReload.map(async ({ rootPath }) => {
 				try {
 					const files = (await electronAPI.listAgentFilesystemFiles({
 						rootPath,
@@ -164,6 +181,57 @@ export function LocalFilesystemBrowser({
 		return () => {
 			cancelled = true;
 		};
+	}, [active, electronAPI, isWindowsPlatform, reloadNonceByRoot, rootPaths, searchSpaceId, supportedExtensions]);
+
+	useEffect(() => {
+		if (active) return;
+		lastLoadedSignatureByRootRef.current.clear();
+	}, [active]);
+
+	useEffect(() => {
+		if (!electronAPI?.startAgentFilesystemTreeWatch) return;
+		if (!electronAPI?.stopAgentFilesystemTreeWatch) return;
+		if (!electronAPI?.onAgentFilesystemTreeDirty) return;
+		if (!active) return;
+		if (rootPaths.length === 0) {
+			void electronAPI.stopAgentFilesystemTreeWatch(searchSpaceId);
+			return;
+		}
+
+		const unsubscribe = electronAPI.onAgentFilesystemTreeDirty((event) => {
+			if ((event.searchSpaceId ?? null) !== (searchSpaceId ?? null)) {
+				return;
+			}
+			const eventRootKey = normalizeRootPathForLookup(event.rootPath, isWindowsPlatform);
+			const knownRootKeys = new Set(
+				rootPaths.map((rootPath) => normalizeRootPathForLookup(rootPath, isWindowsPlatform))
+			);
+			if (!knownRootKeys.has(eventRootKey)) {
+				setReloadNonceByRoot((prev) => {
+					const next = { ...prev };
+					for (const rootKey of knownRootKeys) {
+						next[rootKey] = (prev[rootKey] ?? 0) + 1;
+					}
+					return next;
+				});
+				return;
+			}
+			setReloadNonceByRoot((prev) => ({
+				...prev,
+				[eventRootKey]: (prev[eventRootKey] ?? 0) + 1,
+			}));
+		});
+		void electronAPI.startAgentFilesystemTreeWatch({
+			searchSpaceId,
+			rootPaths,
+			excludePatterns: DEFAULT_EXCLUDE_PATTERNS,
+			fileExtensions: supportedExtensions,
+		});
+
+		return () => {
+			unsubscribe();
+			void electronAPI.stopAgentFilesystemTreeWatch(searchSpaceId);
+		};
 	}, [active, electronAPI, isWindowsPlatform, rootPaths, searchSpaceId, supportedExtensions]);
 
 	useEffect(() => {