ultravisor 1.0.18 → 1.0.20

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "ultravisor",
-    "version": "1.0.18",
+    "version": "1.0.20",
     "description": "Cyclic process execution with ai integration.",
     "main": "source/Ultravisor.cjs",
     "bin": {
@@ -34,7 +34,7 @@
         "pict": "^1.0.361",
         "pict-service-commandlineutility": "^1.0.19",
         "pict-serviceproviderbase": "^1.0.4",
-        "ultravisor-beacon": "^0.0.9",
+        "ultravisor-beacon": "^0.0.10",
         "ws": "^8.20.0"
     },
     "devDependencies": {

package/source/cli/Ultravisor-CLIProgram.cjs

@@ -116,6 +116,34 @@ if (_LogFilePath)
 	console.log(`[Ultravisor] Logging to file: ${_LogFilePath}`);
 }
 
+// Apply LogNoisiness from RETOLD_LOG_NOISINESS env var. Pict-style log
+// noisiness is a 0-5 scale where 0 is silent (production default) and 5 shows
+// everything. Diagnostic log statements throughout Ultravisor (especially the
+// shared-fs reachability auto-detect path and the platform tasks) 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
+//
+// In stack-mode the launcher inherits process.env into the child Ultravisor
+// process automatically, so setting RETOLD_LOG_NOISINESS once on the host
+// (or in the docker-compose `environment:` block) lights up both processes.
+let _LogNoisiness = parseInt(process.env.RETOLD_LOG_NOISINESS, 10);
+if (!isNaN(_LogNoisiness) && _LogNoisiness > 0)
+{
+	_Ultravisor_Pict.LogNoisiness = _LogNoisiness;
+	if (_Ultravisor_Pict.fable && _Ultravisor_Pict.fable !== _Ultravisor_Pict)
+	{
+		_Ultravisor_Pict.fable.LogNoisiness = _LogNoisiness;
+	}
+	console.log(`[Ultravisor] LogNoisiness=${_LogNoisiness} (verbose diagnostics enabled).`);
+}
+
 // If a config file override was passed via --config / -c, apply it on top of the gathered config
 if (_ConfigFileOverride)
 {

package/source/services/Ultravisor-Beacon-Reachability.cjs

@@ -474,6 +474,135 @@ class UltravisorBeaconReachability extends libPictService
 		}
 		return null;
 	}
+
+	/**
+	 * Walk all online beacons looking for one that shares a filesystem with
+	 * the given source beacon. Returns the first peer that:
+	 *   1. is not the source beacon itself
+	 *   2. has the same HostID as the source
+	 *   3. has at least one MountID overlap with the source
+	 *
+	 * This is used by the resolve-address task to auto-detect when a shared-fs
+	 * fast path is available even when the caller did not explicitly identify
+	 * a "requesting beacon". The typical case: retold-remote dispatches a media
+	 * operation, the file lives on retold-remote, and orator-conversion (which
+	 * will eventually consume the file) runs in the same process / on the same
+	 * host with the same content mount. The auto-detection finds orator-conversion
+	 * as a peer of retold-remote and reports the shared-fs strategy so the
+	 * file-transfer task can short-circuit.
+	 *
+	 * Diagnostic logging is gated by Fable.LogNoisiness (set via the
+	 * RETOLD_LOG_NOISINESS env var, 0-5):
+	 *   >= 2: log entry, source beacon summary, final decision
+	 *   >= 3: per-candidate iteration with rejection reasons
+	 *   >= 4: per-mount comparison details
+	 *
+	 * @param {string} pSourceBeaconID
+	 * @returns {object|null} { Peer, Mount } or null if no shared-fs peer exists
+	 */
+	findSharedFsPeer(pSourceBeaconID)
+	{
+		let tmpNoisy = (this.fable && this.fable.LogNoisiness) || 0;
+
+		let tmpCoordinator = this._getService('UltravisorBeaconCoordinator');
+		if (!tmpCoordinator)
+		{
+			if (tmpNoisy >= 2)
+			{
+				this.log.info(`[Reachability] findSharedFsPeer(${pSourceBeaconID}): no UltravisorBeaconCoordinator service registered, returning null.`);
+			}
+			return null;
+		}
+
+		let tmpSource = tmpCoordinator.getBeacon(pSourceBeaconID);
+		if (!tmpSource)
+		{
+			if (tmpNoisy >= 2)
+			{
+				this.log.info(`[Reachability] findSharedFsPeer(${pSourceBeaconID}): source beacon not in coordinator registry, returning null.`);
+			}
+			return null;
+		}
+		if (!tmpSource.HostID)
+		{
+			if (tmpNoisy >= 2)
+			{
+				this.log.info(`[Reachability] findSharedFsPeer(${pSourceBeaconID}): source beacon has no HostID (legacy beacon), returning null.`);
+			}
+			return null;
+		}
+		if (!Array.isArray(tmpSource.SharedMounts) || tmpSource.SharedMounts.length === 0)
+		{
+			if (tmpNoisy >= 2)
+			{
+				this.log.info(`[Reachability] findSharedFsPeer(${pSourceBeaconID}): source beacon advertises no SharedMounts, returning null.`);
+			}
+			return null;
+		}
+
+		if (tmpNoisy >= 2)
+		{
+			this.log.info(`[Reachability] findSharedFsPeer(${pSourceBeaconID}): source HostID=${tmpSource.HostID}, ${tmpSource.SharedMounts.length} mount(s)=${JSON.stringify(tmpSource.SharedMounts.map((m) => m.MountID))}`);
+		}
+
+		let tmpAllBeacons = tmpCoordinator.listBeacons();
+		if (tmpNoisy >= 2)
+		{
+			this.log.info(`[Reachability] findSharedFsPeer(${pSourceBeaconID}): scanning ${tmpAllBeacons.length} registered beacon(s) for shared-fs peers...`);
+		}
+
+		for (let i = 0; i < tmpAllBeacons.length; i++)
+		{
+			let tmpPeer = tmpAllBeacons[i];
+			if (!tmpPeer || tmpPeer.BeaconID === pSourceBeaconID)
+			{
+				if (tmpNoisy >= 3)
+				{
+					this.log.info(`[Reachability]   skip [${tmpPeer ? tmpPeer.BeaconID : '(null)'}]: ${tmpPeer ? 'self' : 'null entry'}`);
+				}
+				continue;
+			}
+			if (tmpPeer.Status && tmpPeer.Status !== 'Online')
+			{
+				if (tmpNoisy >= 3)
+				{
+					this.log.info(`[Reachability]   skip [${tmpPeer.BeaconID}]: status=${tmpPeer.Status} (not Online)`);
+				}
+				continue;
+			}
+			if (!tmpPeer.HostID || tmpPeer.HostID !== tmpSource.HostID)
+			{
+				if (tmpNoisy >= 3)
+				{
+					this.log.info(`[Reachability]   skip [${tmpPeer.BeaconID}]: HostID=${tmpPeer.HostID || '(none)'} != source ${tmpSource.HostID}`);
+				}
+				continue;
+			}
+			if (tmpNoisy >= 4)
+			{
+				this.log.info(`[Reachability]   compare mounts for [${tmpPeer.BeaconID}]: source=${JSON.stringify(tmpSource.SharedMounts.map((m) => m.MountID))} vs peer=${JSON.stringify((tmpPeer.SharedMounts || []).map((m) => m.MountID))}`);
+			}
+			let tmpSharedMount = this._findSharedMount(tmpSource.SharedMounts, tmpPeer.SharedMounts);
+			if (tmpSharedMount)
+			{
+				if (tmpNoisy >= 2)
+				{
+					this.log.info(`[Reachability] findSharedFsPeer(${pSourceBeaconID}): MATCH peer=[${tmpPeer.BeaconID}] mount=[${tmpSharedMount.MountID}] root=${tmpSharedMount.Root}`);
+				}
+				return { Peer: tmpPeer, Mount: tmpSharedMount };
+			}
+			if (tmpNoisy >= 3)
+			{
+				this.log.info(`[Reachability]   skip [${tmpPeer.BeaconID}]: same HostID but no overlapping MountID`);
+			}
+		}
+
+		if (tmpNoisy >= 2)
+		{
+			this.log.info(`[Reachability] findSharedFsPeer(${pSourceBeaconID}): no shared-fs peer found among ${tmpAllBeacons.length} beacon(s).`);
+		}
+		return null;
+	}
 }
 
 module.exports = UltravisorBeaconReachability;

package/source/services/tasks/platform/Ultravisor-TaskConfigs-Platform.cjs

@@ -25,6 +25,18 @@ function _getService(pTask, pTypeName)
 		: null;
 }
 
+/**
+ * Get the LogNoisiness level (0-5) from the Fable instance attached to a task.
+ * Used to gate verbose diagnostic logging in the platform tasks. The user
+ * controls this via the RETOLD_LOG_NOISINESS environment variable, which the
+ * stack launcher applies to both the retold-remote Fable and the Ultravisor
+ * Pict instance at startup.
+ */
+function _getNoisiness(pTask)
+{
+	return (pTask && pTask.fable && pTask.fable.LogNoisiness) || 0;
+}
+
 
 module.exports =
 [
@@ -106,55 +118,115 @@ module.exports =
 				return pDirectBaseURL.replace(/\/$/, '') + tmpContextPath + tmpEncodedPath;
 			};
 
+			// Helper: compute the absolute path on the source beacon's filesystem
+			// for the resolved resource. Returns null if the source beacon does
+			// not have a BasePath registered for this context.
+			let _computeSharedFsLocalPath = function ()
+			{
+				let tmpSourceBeacon = tmpCoordinator.getBeacon(tmpResolved.BeaconID);
+				let tmpCtx = tmpSourceBeacon && tmpSourceBeacon.Contexts
+					? tmpSourceBeacon.Contexts[tmpResolved.Context]
+					: null;
+				if (tmpCtx && tmpCtx.BasePath)
+				{
+					return libPath.join(tmpCtx.BasePath, tmpResolved.Path);
+				}
+				return null;
+			};
+
+			let tmpReachability = _getService(pTask, 'UltravisorBeaconReachability');
+			let tmpNoisy = _getNoisiness(pTask);
+
+			if (tmpNoisy >= 2)
+			{
+				pTask.log.info(`[ResolveAddress] entry: address=${tmpAddress} sourceBeacon=${tmpResolved.BeaconID} requestingBeacon=${pResolvedSettings.RequestingBeaconID || '(none)'} reachability=${tmpReachability ? 'present' : 'missing'}`);
+			}
+
 			// Resolve transfer strategy when a requesting beacon is specified
 			let tmpRequestingBeaconID = pResolvedSettings.RequestingBeaconID;
-			if (tmpRequestingBeaconID)
+			if (tmpRequestingBeaconID && tmpReachability)
 			{
-				let tmpReachability = _getService(pTask, 'UltravisorBeaconReachability');
-				if (tmpReachability)
+				if (tmpNoisy >= 2)
 				{
-					let tmpStrategyResult = tmpReachability.resolveStrategy(tmpResolved.BeaconID, tmpRequestingBeaconID);
-					tmpOutputs.Strategy = tmpStrategyResult.Strategy;
+					pTask.log.info(`[ResolveAddress] explicit RequestingBeaconID=${tmpRequestingBeaconID} provided — calling resolveStrategy directly.`);
+				}
+				let tmpStrategyResult = tmpReachability.resolveStrategy(tmpResolved.BeaconID, tmpRequestingBeaconID);
+				tmpOutputs.Strategy = tmpStrategyResult.Strategy;
 
-					if (tmpStrategyResult.Strategy === 'shared-fs')
+				if (tmpStrategyResult.Strategy === 'shared-fs')
+				{
+					// Both beacons see the same filesystem mount.  Look up the
+					// source beacon's context BasePath and join it with the inner
+					// resource path to get an absolute path that's also valid on
+					// the requesting beacon (because they share the mount).
+					let tmpAbsPath = _computeSharedFsLocalPath();
+					if (tmpAbsPath)
 					{
-						// Both beacons see the same filesystem mount.  Look up the
-						// source beacon's context BasePath and join it with the inner
-						// resource path to get an absolute path that's also valid on
-						// the requesting beacon (because they share the mount).
-						let tmpSourceBeacon = tmpCoordinator.getBeacon(tmpResolved.BeaconID);
-						let tmpCtx = tmpSourceBeacon && tmpSourceBeacon.Contexts
-							? tmpSourceBeacon.Contexts[tmpResolved.Context]
-							: null;
-						if (tmpCtx && tmpCtx.BasePath)
-						{
-							let tmpAbsPath = libPath.join(tmpCtx.BasePath, tmpResolved.Path);
-							tmpOutputs.LocalPath = tmpAbsPath;
-							// URL is intentionally left as the original (relative) URL
-							// — file-transfer will see LocalPath and short-circuit, so
-							// the URL is never actually fetched.
-						}
-						else
-						{
-							// No BasePath available — fall back to direct so the
-							// transfer still works via HTTP.
-							pTask.log.warn(`Resolve Address: shared-fs strategy chosen but no BasePath available for context [${tmpResolved.Context}] on beacon [${tmpResolved.BeaconID}], falling back to direct.`);
-							tmpOutputs.Strategy = 'direct';
-						}
+						tmpOutputs.LocalPath = tmpAbsPath;
+						// URL is intentionally left as the original (relative) URL
+						// — file-transfer will see LocalPath and short-circuit, so
+						// the URL is never actually fetched.
 					}
-					else if (tmpStrategyResult.Strategy === 'direct' && tmpStrategyResult.DirectURL)
+					else
+					{
+						// No BasePath available — fall back to direct so the
+						// transfer still works via HTTP.
+						pTask.log.warn(`Resolve Address: shared-fs strategy chosen but no BasePath available for context [${tmpResolved.Context}] on beacon [${tmpResolved.BeaconID}], falling back to direct.`);
+						tmpOutputs.Strategy = 'direct';
+					}
+				}
+				else if (tmpStrategyResult.Strategy === 'direct' && tmpStrategyResult.DirectURL)
+				{
+					tmpOutputs.DirectURL = _buildDirectURL(tmpStrategyResult.DirectURL);
+					tmpOutputs.URL = tmpOutputs.DirectURL;
+				}
+				else if (tmpStrategyResult.Strategy === 'proxy')
+				{
+					// Proxy URL: Ultravisor's own endpoint serves the file
+					tmpOutputs.ProxyURL = tmpResolved.URL;
+					tmpOutputs.URL = tmpResolved.URL;
+				}
+				// 'local' strategy: URL stays as the context BaseURL (same host)
+			}
+			else if (tmpReachability)
+			{
+				// Auto-detect a shared-fs peer when no RequestingBeaconID was passed.
+				// This is the common case for retold-remote: it dispatches a media
+				// operation, the file lives on the retold-remote beacon, and an
+				// orator-conversion beacon on the same host shares the mount. The
+				// auto-detection finds the orator-conversion peer and lets us
+				// short-circuit the file-transfer entirely.
+				if (tmpNoisy >= 2)
+				{
+					pTask.log.info(`[ResolveAddress] no RequestingBeaconID — entering auto-detect path for source ${tmpResolved.BeaconID}`);
+				}
+				let tmpPeerInfo = tmpReachability.findSharedFsPeer(tmpResolved.BeaconID);
+				if (tmpPeerInfo)
+				{
+					let tmpAbsPath = _computeSharedFsLocalPath();
+					if (tmpAbsPath)
 					{
-						tmpOutputs.DirectURL = _buildDirectURL(tmpStrategyResult.DirectURL);
-						tmpOutputs.URL = tmpOutputs.DirectURL;
+						tmpOutputs.Strategy = 'shared-fs';
+						tmpOutputs.LocalPath = tmpAbsPath;
+						pTask.log.info(`Resolve Address: auto-detected shared-fs peer [${tmpPeerInfo.Peer.BeaconID}] for source [${tmpResolved.BeaconID}] via mount [${tmpPeerInfo.Mount.MountID}].`);
+						if (tmpNoisy >= 2)
+						{
+							pTask.log.info(`[ResolveAddress] auto-detect SUCCESS: LocalPath=${tmpAbsPath} (peer=${tmpPeerInfo.Peer.BeaconID}, mount=${tmpPeerInfo.Mount.MountID})`);
+						}
 					}
-					else if (tmpStrategyResult.Strategy === 'proxy')
+					else if (tmpNoisy >= 2)
 					{
-						// Proxy URL: Ultravisor's own endpoint serves the file
-						tmpOutputs.ProxyURL = tmpResolved.URL;
-						tmpOutputs.URL = tmpResolved.URL;
+						pTask.log.info(`[ResolveAddress] auto-detect found peer [${tmpPeerInfo.Peer.BeaconID}] but source beacon has no BasePath for context [${tmpResolved.Context}] — cannot use shared-fs.`);
 					}
-					// 'local' strategy: URL stays as the context BaseURL (same host)
 				}
+				else if (tmpNoisy >= 2)
+				{
+					pTask.log.info(`[ResolveAddress] auto-detect found NO shared-fs peer for source ${tmpResolved.BeaconID} — falling through to default direct/proxy strategy.`);
+				}
+			}
+			else if (tmpNoisy >= 2)
+			{
+				pTask.log.info(`[ResolveAddress] reachability service not available — skipping auto-detect, default strategy will be used.`);
 			}
 
 			// If the URL is still relative (no protocol), use the beacon's first
@@ -218,6 +290,12 @@ module.exports =
 			let tmpSourceURL = pResolvedSettings.SourceURL;
 			let tmpSourceLocalPath = pResolvedSettings.SourceLocalPath;
 			let tmpFilename = pResolvedSettings.Filename;
+			let tmpNoisy = _getNoisiness(pTask);
+
+			if (tmpNoisy >= 2)
+			{
+				pTask.log.info(`[FileTransfer] entry: SourceURL=${tmpSourceURL ? tmpSourceURL.substring(0, 80) : '(none)'} SourceLocalPath=${tmpSourceLocalPath || '(none)'} Filename=${tmpFilename || '(none)'}`);
+			}
 
 			// Shared-filesystem fast path: if the source beacon and the requesting
 			// beacon both report the same MountID, resolve-address will populate
@@ -259,6 +337,14 @@ module.exports =
 				// Path was provided but doesn't exist on this beacon — log and fall
 				// through to the HTTP path so we still satisfy the request.
 				pTask.log.warn(`File Transfer: SourceLocalPath [${tmpSourceLocalPath}] does not exist on this beacon, falling back to HTTP transfer.`);
+				if (tmpNoisy >= 2)
+				{
+					pTask.log.info(`[FileTransfer] SourceLocalPath was set but file is missing on this beacon — the requesting beacon doesn't actually share this filesystem at the expected path.`);
+				}
+			}
+			else if (tmpNoisy >= 2)
+			{
+				pTask.log.info(`[FileTransfer] no SourceLocalPath in settings — running standard HTTP download path. (Either resolve-address chose 'direct'/'proxy', or the operation graph isn't wiring resolve.LocalPath → transfer.SourceLocalPath.)`);
 			}
 
 			if (!tmpSourceURL)

package/source/web_server/Ultravisor-API-Server.cjs

@@ -2055,6 +2055,11 @@ class UltravisorAPIServer extends libPictService
 			return;
 		}
 
+		// IMPORTANT: this enumeration must include every field the coordinator
+		// cares about, including HostID and SharedMounts (used by the shared-fs
+		// reachability auto-detect). Forgetting to forward a field here means
+		// the WebSocket-registered beacon record will have that field set to
+		// null/empty in the coordinator, even though the client sent the value.
 		let tmpBeacon = tmpCoordinator.registerBeacon({
 			Name: pData.Name,
 			Capabilities: pData.Capabilities,
@@ -2063,7 +2068,9 @@ class UltravisorAPIServer extends libPictService
 			MaxConcurrent: pData.MaxConcurrent,
 			Tags: pData.Tags,
 			Contexts: pData.Contexts,
-			BindAddresses: pData.BindAddresses
+			BindAddresses: pData.BindAddresses,
+			HostID: pData.HostID,
+			SharedMounts: pData.SharedMounts
 		});
 
 		pWebSocket._BeaconID = tmpBeacon.BeaconID;