retold-remote 0.0.23 → 0.0.26

package/source/cli/RetoldRemote-Server-Setup.js

@@ -26,6 +26,8 @@
 
 const libFs = require('fs');
 const libPath = require('path');
+const libOs = require('os');
+const libCrypto = require('crypto');
 const libChildProcess = require('child_process');
 
 const libFable = require('fable');
@@ -48,8 +50,12 @@ const libRetoldRemoteMetadataCache = require('../server/RetoldRemote-MetadataCac
 const libRetoldRemoteFileOperationService = require('../server/RetoldRemote-FileOperationService.js');
 const libRetoldRemoteAISortService = require('../server/RetoldRemote-AISortService.js');
 const libRetoldRemoteImageService = require('../server/RetoldRemote-ImageService.js');
+const libRetoldRemoteSubimageService = require('../server/RetoldRemote-SubimageService.js');
+const libRetoldRemoteCollectionExportService = require('../server/RetoldRemote-CollectionExportService.js');
+const libRetoldRemoteOperationBroadcaster = require('../server/RetoldRemote-OperationBroadcaster.js');
 const libRetoldRemoteUltravisorDispatcher = require('../server/RetoldRemote-UltravisorDispatcher.js');
 const libRetoldRemoteUltravisorBeacon = require('../server/RetoldRemote-UltravisorBeacon.js');
+const libOratorConversion = require('orator-conversion');
 const libUrl = require('url');
 
 function setupRetoldRemoteServer(pOptions, fCallback)
@@ -104,6 +110,28 @@ function setupRetoldRemoteServer(pOptions, fCallback)
 
 	let tmpFable = new libFable(tmpSettings);
 
+	// Apply LogNoisiness from RETOLD_LOG_NOISINESS env var (or pOptions override).
+	// Pict-style log noisiness is a 0-5 scale where 0 is silent (production
+	// default) and 5 shows everything. Diagnostic log statements throughout
+	// retold-remote and Ultravisor are gated with `if (this.fable.LogNoisiness
+	// >= N)` so they're free at level 0 and explosively detailed at level 4-5.
+	// Useful values:
+	//   1 — high-level decisions (auto-detected shared-fs peer X)
+	//   2 — entry points and decisions in shared-fs / dispatch paths
+	//   3 — per-candidate iteration in reachability
+	//   4 — per-mount comparison details
+	//   5 — everything
+	let tmpNoisy = parseInt(pOptions.LogNoisiness, 10);
+	if (isNaN(tmpNoisy))
+	{
+		tmpNoisy = parseInt(process.env.RETOLD_LOG_NOISINESS, 10);
+	}
+	if (!isNaN(tmpNoisy) && tmpNoisy > 0)
+	{
+		tmpFable.LogNoisiness = tmpNoisy;
+		tmpFable.log.info(`Retold-Remote: LogNoisiness=${tmpNoisy} (verbose diagnostics enabled).`);
+	}
+
 	// Ensure the content directory exists
 	if (!libFs.existsSync(tmpContentPath))
 	{
@@ -189,6 +217,12 @@ function setupRetoldRemoteServer(pOptions, fCallback)
 				ContentPath: tmpContentPath
 			});
 
+			// Set up the subimage region service
+			let tmpSubimageService = new libRetoldRemoteSubimageService(tmpFable,
+			{
+				ContentPath: tmpContentPath
+			});
+
 			// Set up the metadata cache service
 			let tmpMetadataCache = new libRetoldRemoteMetadataCache(tmpFable,
 			{
@@ -212,6 +246,12 @@ function setupRetoldRemoteServer(pOptions, fCallback)
 			let tmpCollectionService = new libRetoldRemoteCollectionService(tmpFable, {});
 			tmpCollectionService.setFileOperationService(tmpFileOperationService);
 
+			// Set up the collection export service
+			let tmpCollectionExportService = new libRetoldRemoteCollectionExportService(tmpFable,
+			{
+				ContentPath: tmpContentPath
+			});
+
 			// Set up the media service
 			let tmpMediaService = new libRetoldRemoteMediaService(tmpFable,
 			{
@@ -226,11 +266,38 @@ function setupRetoldRemoteServer(pOptions, fCallback)
 			// Set up the Ultravisor beacon for mesh registration
 			let tmpBeacon = new libRetoldRemoteUltravisorBeacon(tmpFable, {});
 
+			// Set up the Operation Broadcaster — WebSocket pub/sub for
+			// long-running operation progress + cooperative cancellation.
+			// Attached to the HTTP server AFTER startService(), below.
+			let tmpOperationBroadcaster = new libRetoldRemoteOperationBroadcaster(tmpFable, {});
+
+			// Set up orator-conversion for document format conversion
+			tmpFable.serviceManager.addServiceType('OratorFileTranslation', libOratorConversion);
+			let tmpConversionService = tmpFable.serviceManager.instantiateServiceProvider('OratorFileTranslation',
+			{
+				RoutePrefix: '/api/conversion',
+				MaxFileSize: 100 * 1024 * 1024, // 100MB for large documents
+				LogLevel: 1
+			});
+
 			// Wire the dispatcher to services that can offload processing
 			tmpMediaService.setDispatcher(tmpDispatcher);
 			tmpVideoFrameService.setDispatcher(tmpDispatcher);
 			tmpAudioWaveformService.setDispatcher(tmpDispatcher);
 			tmpEbookService.setDispatcher(tmpDispatcher);
+
+			// Wire the operation broadcaster to services that emit progress.
+			// Services must gracefully handle a null broadcaster — this keeps
+			// them runnable outside the stack.
+			tmpMediaService.setBroadcaster(tmpOperationBroadcaster);
+			tmpVideoFrameService.setBroadcaster(tmpOperationBroadcaster);
+			tmpAudioWaveformService.setBroadcaster(tmpOperationBroadcaster);
+			tmpEbookService.setBroadcaster(tmpOperationBroadcaster);
+			tmpImageService.setBroadcaster(tmpOperationBroadcaster);
+			tmpCollectionExportService.setBroadcaster(tmpOperationBroadcaster);
+
+			// Share the orator-conversion service with the ebook service for PDF conversion
+			tmpEbookService.setConversionService(tmpConversionService);
 			tmpImageService.setDispatcher(tmpDispatcher);
 
 			// Share tool capabilities with the image service so it can
@@ -238,10 +305,12 @@ function setupRetoldRemoteServer(pOptions, fCallback)
 			// Also provides the centrally-verified sharp module reference.
 			tmpImageService.setCapabilities(tmpMediaService.capabilities);
 
-			// Share the verified sharp module with the metadata cache
+			// Share the verified sharp module with the metadata cache, subimage, and export services
 			if (tmpMediaService.capabilities.sharpModule)
 			{
 				tmpMetadataCache.setSharpModule(tmpMediaService.capabilities.sharpModule);
+				tmpSubimageService.setSharpModule(tmpMediaService.capabilities.sharpModule);
+				tmpCollectionExportService.setSharpModule(tmpMediaService.capabilities.sharpModule);
 			}
 
 			tmpOrator.initialize(
@@ -252,6 +321,20 @@ function setupRetoldRemoteServer(pOptions, fCallback)
 			// Enable body parsing
 			tmpServiceServer.server.use(tmpServiceServer.bodyParser());
 
+			// X-Op-Id extraction middleware: stash the client-provided
+			// operation id on the request so route handlers can pass it
+			// into services (for progress emission + cancellation).
+			tmpServiceServer.server.use(
+				(pRequest, pResponse, fNext) =>
+				{
+					let tmpOpId = pRequest.headers && pRequest.headers['x-op-id'];
+					if (tmpOpId && typeof tmpOpId === 'string' && tmpOpId.length <= 128)
+					{
+						pRequest.OperationId = tmpOpId;
+					}
+					return fNext();
+				});
+
 			// Hash resolution middleware: if hashed filenames is enabled,
 			// intercept ?path= query params and resolve hashes to paths.
 			// Uses three-tier lookup (memory → Bibliograph → directory walk).
@@ -470,6 +553,74 @@ function setupRetoldRemoteServer(pOptions, fCallback)
 			// Connect collection service API routes
 			tmpCollectionService.connectRoutes(tmpServiceServer);
 
+			// Connect subimage region service API routes
+			tmpSubimageService.connectRoutes(tmpServiceServer);
+
+			// Connect collection export service API routes
+			tmpCollectionExportService.connectRoutes(tmpServiceServer);
+
+			// Connect orator-conversion routes and register custom doc-to-pdf converter
+			if (tmpMediaService.capabilities.libreoffice)
+			{
+				let tmpSofficePath = 'soffice';
+				if (libFs.existsSync('/Applications/LibreOffice.app/Contents/MacOS/soffice'))
+				{
+					tmpSofficePath = '/Applications/LibreOffice.app/Contents/MacOS/soffice';
+				}
+
+				tmpConversionService.addConverter('doc-to-pdf',
+					(pInputBuffer, pRequest, fCallback) =>
+					{
+						// Write input to temp file, convert with LibreOffice, return PDF buffer
+						let tmpTempDir = require('os').tmpdir();
+						let tmpUniqueId = Date.now() + '_' + Math.random().toString(36).slice(2);
+						let tmpInputExt = (pRequest.query && pRequest.query.ext) || 'docx';
+						let tmpInputPath = libPath.join(tmpTempDir, 'retold_doc_' + tmpUniqueId + '.' + tmpInputExt);
+						let tmpOutputDir = libPath.join(tmpTempDir, 'retold_docout_' + tmpUniqueId);
+
+						libFs.mkdirSync(tmpOutputDir, { recursive: true });
+
+						try
+						{
+							libFs.writeFileSync(tmpInputPath, pInputBuffer);
+							libChildProcess.execSync(
+								'"' + tmpSofficePath + '" --headless --convert-to pdf --outdir "' + tmpOutputDir + '" "' + tmpInputPath + '"',
+								{ stdio: 'ignore', timeout: 120000 });
+
+							// Find the output PDF (LibreOffice names it after the input)
+							let tmpBaseName = libPath.basename(tmpInputPath, '.' + tmpInputExt);
+							let tmpOutputPath = libPath.join(tmpOutputDir, tmpBaseName + '.pdf');
+
+							if (!libFs.existsSync(tmpOutputPath))
+							{
+								// Clean up
+								try { libFs.unlinkSync(tmpInputPath); } catch (e) { /* */ }
+								try { libFs.rmSync(tmpOutputDir, { recursive: true }); } catch (e) { /* */ }
+								return fCallback(new Error('LibreOffice conversion produced no output.'));
+							}
+
+							let tmpPdfBuffer = libFs.readFileSync(tmpOutputPath);
+
+							// Clean up temp files
+							try { libFs.unlinkSync(tmpInputPath); } catch (e) { /* */ }
+							try { libFs.rmSync(tmpOutputDir, { recursive: true }); } catch (e) { /* */ }
+
+							return fCallback(null, tmpPdfBuffer, 'application/pdf');
+						}
+						catch (pError)
+						{
+							try { libFs.unlinkSync(tmpInputPath); } catch (e) { /* */ }
+							try { libFs.rmSync(tmpOutputDir, { recursive: true }); } catch (e) { /* */ }
+							return fCallback(new Error('Document conversion failed: ' + pError.message));
+						}
+					});
+
+				tmpFable.log.info('Orator-Conversion: doc-to-pdf converter registered (LibreOffice)');
+			}
+
+			tmpConversionService.connectRoutes();
+			tmpFable.log.info('Orator-Conversion: routes connected at /api/conversion/1.0/');
+
 			// Connect AI sort service API routes
 			tmpAISortService.connectRoutes(tmpServiceServer);
 
@@ -486,6 +637,10 @@ function setupRetoldRemoteServer(pOptions, fCallback)
 			{
 				tmpFable.log.info('Audio explorer state Bibliograph source initialized.');
 			});
+			tmpSubimageService.initializeState(() =>
+			{
+				tmpFable.log.info('Subimage region state Bibliograph source initialized.');
+			});
 			tmpEpubMetadataService.initialize(() =>
 			{
 				tmpFable.log.info('EPUB metadata service initialized.');
@@ -495,6 +650,112 @@ function setupRetoldRemoteServer(pOptions, fCallback)
 				// Non-fatal — if Ultravisor is down, processing stays local
 			});
 
+			// --- GET /api/media/pdf-text ---
+			// Extract text from a specific PDF page (or all pages if no page specified).
+			tmpServiceServer.get('/api/media/pdf-text',
+				(pRequest, pResponse, fNext) =>
+				{
+					try
+					{
+						let tmpParsedUrl = libUrl.parse(pRequest.url, true);
+						let tmpQuery = tmpParsedUrl.query;
+						let tmpRelPath = tmpQuery.path;
+						let tmpPageNum = parseInt(tmpQuery.page, 10) || 0;
+
+						if (!tmpRelPath || typeof (tmpRelPath) !== 'string')
+						{
+							pResponse.send(400, { Success: false, Error: 'Missing path parameter.' });
+							return fNext();
+						}
+
+						tmpRelPath = decodeURIComponent(tmpRelPath).replace(/^\/+/, '');
+						if (tmpRelPath.includes('..') || libPath.isAbsolute(tmpRelPath))
+						{
+							pResponse.send(400, { Success: false, Error: 'Invalid path.' });
+							return fNext();
+						}
+
+						let tmpAbsPath = libPath.join(tmpContentPath, tmpRelPath);
+						if (!libFs.existsSync(tmpAbsPath))
+						{
+							pResponse.send(404, { Success: false, Error: 'File not found.' });
+							return fNext();
+						}
+
+						let tmpExt = tmpRelPath.replace(/^.*\./, '').toLowerCase();
+						if (tmpExt !== 'pdf')
+						{
+							pResponse.send(400, { Success: false, Error: 'Not a PDF file.' });
+							return fNext();
+						}
+
+						// pdf-parse v2.x exports a PDFParse class with async methods.
+						// (v1.x used to export a default async function — that API is gone.)
+						let tmpPdfParseModule = require('pdf-parse');
+						let tmpPDFParseClass = tmpPdfParseModule.PDFParse;
+						if (typeof tmpPDFParseClass !== 'function')
+						{
+							pResponse.send(500, { Success: false, Error: 'pdf-parse module does not export PDFParse class. Update pdf-parse.' });
+							return fNext();
+						}
+
+						let tmpBuffer = libFs.readFileSync(tmpAbsPath);
+						let tmpParser = new tmpPDFParseClass({ data: tmpBuffer });
+
+						let tmpExtractText;
+						if (tmpPageNum > 0)
+						{
+							// Single page text — first/last bound the range
+							tmpExtractText = tmpParser.getText({ first: tmpPageNum, last: tmpPageNum });
+						}
+						else
+						{
+							// All pages
+							tmpExtractText = tmpParser.getText();
+						}
+
+						tmpExtractText
+							.then((pData) =>
+							{
+								// pdf-parse v2 result shape: { text, total, pages: [...] } or similar
+								let tmpText = (pData && typeof pData.text === 'string') ? pData.text : '';
+								let tmpPageCount = (pData && typeof pData.total === 'number') ? pData.total
+									: (pData && Array.isArray(pData.pages)) ? pData.pages.length : 0;
+
+								pResponse.send(
+								{
+									Success: true,
+									Path: tmpRelPath,
+									PageCount: tmpPageCount,
+									Text: tmpText,
+									RequestedPage: tmpPageNum || null
+								});
+
+								// Release native resources
+								if (typeof tmpParser.destroy === 'function')
+								{
+									tmpParser.destroy().catch(() => { /* ignore */ });
+								}
+
+								return fNext();
+							})
+							.catch((pPdfError) =>
+							{
+								if (typeof tmpParser.destroy === 'function')
+								{
+									tmpParser.destroy().catch(() => { /* ignore */ });
+								}
+								pResponse.send(500, { Success: false, Error: 'PDF parse failed: ' + pPdfError.message });
+								return fNext();
+							});
+					}
+					catch (pError)
+					{
+						pResponse.send(500, { Success: false, Error: pError.message });
+						return fNext();
+					}
+				});
+
 			// --- GET /api/media/metadata ---
 			// Get cached metadata (with ID3/format tags) for a single file.
 			tmpServiceServer.get('/api/media/metadata',
@@ -696,7 +957,8 @@ function setupRetoldRemoteServer(pOptions, fCallback)
 							count: tmpQuery.count,
 							width: tmpQuery.width,
 							height: tmpQuery.height,
-							format: tmpQuery.format
+							format: tmpQuery.format,
+							OperationId: pRequest.OperationId || null
 						},
 						(pError, pResult) =>
 						{
@@ -1307,9 +1569,17 @@ function setupRetoldRemoteServer(pOptions, fCallback)
 
 						let tmpStat = libFs.statSync(tmpEbookPath);
 
+						// Determine content type based on file extension
+						let tmpEbookExt = tmpFilename.replace(/^.*\./, '').toLowerCase();
+						let tmpContentType = 'application/epub+zip';
+						if (tmpEbookExt === 'pdf')
+						{
+							tmpContentType = 'application/pdf';
+						}
+
 						pResponse.writeHead(200,
 						{
-							'Content-Type': 'application/epub+zip',
+							'Content-Type': tmpContentType,
 							'Content-Length': tmpStat.size,
 							'Cache-Control': 'public, max-age=86400'
 						});
@@ -1330,6 +1600,57 @@ function setupRetoldRemoteServer(pOptions, fCallback)
 					}
 				});
 
+			// --- GET /api/media/doc-convert ---
+			// Convert a document (DOC, DOCX, RTF, ODT, WPD, etc.) to PDF.
+			tmpServiceServer.get('/api/media/doc-convert',
+				(pRequest, pResponse, fNext) =>
+				{
+					try
+					{
+						let tmpParsedUrl = libUrl.parse(pRequest.url, true);
+						let tmpQuery = tmpParsedUrl.query;
+						let tmpRelPath = tmpQuery.path;
+
+						if (!tmpRelPath || typeof (tmpRelPath) !== 'string')
+						{
+							pResponse.send(400, { Success: false, Error: 'Missing path parameter.' });
+							return fNext();
+						}
+
+						tmpRelPath = decodeURIComponent(tmpRelPath).replace(/^\/+/, '');
+						if (tmpRelPath.includes('..') || libPath.isAbsolute(tmpRelPath))
+						{
+							pResponse.send(400, { Success: false, Error: 'Invalid path.' });
+							return fNext();
+						}
+
+						let tmpAbsPath = libPath.join(tmpContentPath, tmpRelPath);
+						if (!libFs.existsSync(tmpAbsPath))
+						{
+							pResponse.send(404, { Success: false, Error: 'File not found.' });
+							return fNext();
+						}
+
+						tmpEbookService.convertToPdf(tmpAbsPath, tmpRelPath,
+						(pError, pResult) =>
+						{
+							if (pError)
+							{
+								pResponse.send(400, { Success: false, Error: pError.message });
+								return fNext();
+							}
+
+							pResponse.send(pResult);
+							return fNext();
+						});
+					}
+					catch (pError)
+					{
+						pResponse.send(500, { Success: false, Error: pError.message });
+						return fNext();
+					}
+				});
+
 			// --- GET /api/media/ebook-metadata ---
 			// Extract and return cached EPUB metadata (TOC, spine, word counts, etc.)
 			tmpServiceServer.get('/api/media/ebook-metadata',
@@ -1720,6 +2041,7 @@ function setupRetoldRemoteServer(pOptions, fCallback)
 						}
 
 						tmpImageService.generateDziTiles(tmpAbsPath, tmpRelPath,
+							{ OperationId: pRequest.OperationId || null },
 							(pError, pResult) =>
 							{
 								if (pError)
@@ -1775,6 +2097,18 @@ function setupRetoldRemoteServer(pOptions, fCallback)
 
 			// --- GET /api/media/dzi-tile/:cacheKey/:level/:tile ---
 			// Serve an individual DZI tile image.
+			//
+			// OpenSeadragon's DziTileSource.configure() rewrites whatever Url
+			// we hand it and appends a "_files" suffix to the last path segment
+			// (that's how the standard DZI directory layout works — a foo.dzi
+			// descriptor expects the tiles in a sibling foo_files/ directory).
+			// So when we hand OSD `Url: '/api/media/dzi-tile/{cacheKey}/'` it
+			// rewrites the tilesUrl to `/api/media/dzi-tile/{cacheKey}_files/`
+			// and asks for tiles at `/api/media/dzi-tile/{cacheKey}_files/{level}/{x}_{y}.jpg`.
+			//
+			// Strip the trailing "_files" from the cacheKey before resolving so
+			// both the canonical URL (used by anything that bypasses OSD) and
+			// the OSD-generated URL hit the same on-disk cache directory.
 			tmpServiceServer.get('/api/media/dzi-tile/:cacheKey/:level/:tile',
 				(pRequest, pResponse, fNext) =>
 				{
@@ -1783,6 +2117,10 @@ function setupRetoldRemoteServer(pOptions, fCallback)
 						let tmpCacheKey = pRequest.params.cacheKey;
 						let tmpLevel = pRequest.params.level;
 						let tmpTile = pRequest.params.tile;
+						if (typeof tmpCacheKey === 'string' && tmpCacheKey.endsWith('_files'))
+						{
+							tmpCacheKey = tmpCacheKey.slice(0, -6);
+						}
 						let tmpPath = tmpImageService.getDziTilePath(tmpCacheKey, tmpLevel, tmpTile);
 
 						if (!tmpPath)
@@ -2138,6 +2476,29 @@ function setupRetoldRemoteServer(pOptions, fCallback)
 			tmpOrator.startService(
 				function ()
 				{
+					// Attach the operation broadcaster to the underlying Node
+					// http.Server so WebSocket upgrades on /ws/operations reach
+					// our pub/sub hub. The Restify server exposes the raw
+					// http.Server as `.server`.
+					try
+					{
+						let tmpHttpServer = tmpOrator.serviceServer && tmpOrator.serviceServer.server
+							? tmpOrator.serviceServer.server.server
+							: null;
+						if (tmpHttpServer)
+						{
+							tmpOperationBroadcaster.attachTo(tmpHttpServer);
+						}
+						else
+						{
+							tmpFable.log.warn('OperationBroadcaster: could not find underlying http.Server; WebSocket status unavailable');
+						}
+					}
+					catch (pAttachError)
+					{
+						tmpFable.log.warn('OperationBroadcaster attach failed: ' + pAttachError.message);
+					}
+
 					let tmpServerInfo =
 					{
 						Fable: tmpFable,
@@ -2146,6 +2507,10 @@ function setupRetoldRemoteServer(pOptions, fCallback)
 						ArchiveService: tmpArchiveService,
 						VideoFrameService: tmpVideoFrameService,
 						AudioWaveformService: tmpAudioWaveformService,
+						SubimageService: tmpSubimageService,
+						CollectionExportService: tmpCollectionExportService,
+						ConversionService: tmpConversionService,
+						OperationBroadcaster: tmpOperationBroadcaster,
 						PathRegistry: tmpPathRegistry,
 						ParimeCache: tmpParimeCache,
 						MetadataCache: tmpMetadataCache,
@@ -2160,7 +2525,7 @@ function setupRetoldRemoteServer(pOptions, fCallback)
 					{
 						// Discover bind addresses from network interfaces
 						let tmpBindAddresses = [];
-						let tmpNetworkInterfaces = require('os').networkInterfaces();
+						let tmpNetworkInterfaces = libOs.networkInterfaces();
 						for (let tmpIfName of Object.keys(tmpNetworkInterfaces))
 						{
 							for (let tmpIf of tmpNetworkInterfaces[tmpIfName])
@@ -2174,6 +2539,48 @@ function setupRetoldRemoteServer(pOptions, fCallback)
 						// Always include loopback as a fallback
 						tmpBindAddresses.push({ IP: '127.0.0.1', Port: tmpPort, Protocol: 'http' });
 
+						// Shared-fs identity: when retold-remote and the in-process
+						// orator-conversion beacon both live in the same container/host,
+						// they share the same content mount. By computing one HostID and
+						// one MountID here and passing the SAME values to both beacons,
+						// the Ultravisor reachability matrix can detect the overlap and
+						// pick the 'shared-fs' strategy instead of forcing a 374 MB
+						// HTTP file-transfer between two beacons in the same process.
+						//
+						// The RETOLD_SHARED_FS_ENABLED env var provides a test hook to
+						// disable the shared-fs advertisement. When set to 'false' or '0'
+						// both beacons skip SharedMounts, which forces the reachability
+						// matrix to fall through to 'direct' (HTTP file-transfer) or
+						// 'proxy'. This lets the docker smoke test exercise the legacy
+						// path to confirm nothing has regressed there.
+						let tmpHostID = libOs.hostname();
+						let tmpSharedMounts = [];
+						let tmpSharedFsEnvValue = (typeof process.env.RETOLD_SHARED_FS_ENABLED === 'string')
+							? process.env.RETOLD_SHARED_FS_ENABLED.trim().toLowerCase()
+							: '';
+						let tmpSharedFsEnabled = !(tmpSharedFsEnvValue === 'false' || tmpSharedFsEnvValue === '0' || tmpSharedFsEnvValue === 'no' || tmpSharedFsEnvValue === 'off');
+						if (!tmpSharedFsEnabled)
+						{
+							tmpFable.log.warn(`Ultravisor Beacons: RETOLD_SHARED_FS_ENABLED=${process.env.RETOLD_SHARED_FS_ENABLED} -- SharedMounts advertisement DISABLED (forcing direct/proxy transfer strategy).`);
+						}
+						else
+						{
+							try
+							{
+								let tmpMountRoot = libPath.resolve(tmpContentPath);
+								let tmpStat = libFs.statSync(tmpMountRoot);
+								let tmpMountID = libCrypto.createHash('sha256')
+									.update(tmpStat.dev + ':' + tmpMountRoot)
+									.digest('hex').substring(0, 16);
+								tmpSharedMounts.push({ MountID: tmpMountID, Root: tmpMountRoot });
+								tmpFable.log.info(`Ultravisor Beacons: advertising shared mount [${tmpMountID}] = ${tmpMountRoot} (HostID: ${tmpHostID})`);
+							}
+							catch (pMountError)
+							{
+								tmpFable.log.warn(`Ultravisor Beacons: could not stat content path for shared-fs detection: ${pMountError.message}`);
+							}
+						}
+
 						tmpBeacon.connectBeacon(
 							{
 								ServerURL: pOptions.UltravisorURL,
@@ -2182,7 +2589,9 @@ function setupRetoldRemoteServer(pOptions, fCallback)
 								ContentBaseURL: '/content/',
 								CacheRoot: tmpCacheRoot,
 								StagingPath: tmpCacheRoot || process.cwd(),
-								BindAddresses: tmpBindAddresses
+								BindAddresses: tmpBindAddresses,
+								HostID: tmpHostID,
+								SharedMounts: tmpSharedMounts
 							},
 							(pBeaconError) =>
 							{
@@ -2191,8 +2600,52 @@ function setupRetoldRemoteServer(pOptions, fCallback)
 									tmpFable.log.warn(`Ultravisor Beacon: registration failed (server may not be running): ${pBeaconError.message}`);
 									tmpFable.log.warn('Ultravisor Beacon: server is still running. Beacon will not be active.');
 								}
-								// Non-fatal — return server info regardless
-								return fCallback(null, tmpServerInfo);
+
+								// Also register orator-conversion as a separate beacon
+								// so its MediaConversion capability (ImageResize, VideoExtractFrame,
+								// etc.) becomes available as auto-generated task types in the
+								// coordinator's catalog. Without this, operations like
+								// rr-image-thumbnail can't find their `beacon-mediaconversion-imageresize`
+								// process node and silently fall back to local processing.
+								//
+								// We pass the SAME HostID and SharedMounts as the retold-remote
+								// beacon above so the reachability matrix knows these two beacons
+								// can read each other's files directly through the shared mount.
+								try
+								{
+									let tmpConvStagingPath = libPath.join(tmpCacheRoot || process.cwd(), 'orator-conversion-staging');
+									tmpConversionService.connectBeacon(
+										{
+											ServerURL: pOptions.UltravisorURL,
+											Name: 'orator-conversion',
+											MaxConcurrent: 2,
+											StagingPath: tmpConvStagingPath,
+											BindAddresses: tmpBindAddresses,
+											FfmpegPath: 'ffmpeg',
+											FfprobePath: 'ffprobe',
+											HostID: tmpHostID,
+											SharedMounts: tmpSharedMounts
+										},
+										(pConvBeaconError) =>
+										{
+											if (pConvBeaconError)
+											{
+												tmpFable.log.warn('Orator-Conversion beacon registration failed: ' + pConvBeaconError.message);
+												tmpFable.log.warn('Orator-Conversion: media conversion task types will not be available; operations will fall back to local processing.');
+											}
+											else
+											{
+												tmpFable.log.info('Orator-Conversion beacon connected — MediaConversion capability registered with coordinator.');
+											}
+											// Non-fatal — return server info regardless
+											return fCallback(null, tmpServerInfo);
+										});
+								}
+								catch (pConvSetupError)
+								{
+									tmpFable.log.warn('Orator-Conversion beacon setup failed: ' + pConvSetupError.message);
+									return fCallback(null, tmpServerInfo);
+								}
 							});
 					}
 					else