ultravisor 1.0.17 → 1.0.18

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "ultravisor",
-    "version": "1.0.17",
+    "version": "1.0.18",
     "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.8",
+        "ultravisor-beacon": "^0.0.9",
         "ws": "^8.20.0"
     },
     "devDependencies": {

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

@@ -231,6 +231,16 @@ class UltravisorBeaconCoordinator extends libPictService
 			{
 				tmpExistingBeacon.BindAddresses = pBeaconInfo.BindAddresses;
 			}
+			// Refresh shared-fs identity on reconnect — host id can change between
+			// container restarts and a reconnecting beacon may have new mounts.
+			if (typeof pBeaconInfo.HostID === 'string' && pBeaconInfo.HostID.length > 0)
+			{
+				tmpExistingBeacon.HostID = pBeaconInfo.HostID;
+			}
+			if (Array.isArray(pBeaconInfo.SharedMounts))
+			{
+				tmpExistingBeacon.SharedMounts = pBeaconInfo.SharedMounts;
+			}
 
 			this.log.info(`BeaconCoordinator: reconnected beacon [${tmpExistingBeacon.BeaconID}] "${tmpName}" with session [${tmpExistingBeacon.SessionID}].`);
 
@@ -272,6 +282,11 @@ class UltravisorBeaconCoordinator extends libPictService
 			Tags: pBeaconInfo.Tags || {},
 			Contexts: pBeaconInfo.Contexts || {},
 			BindAddresses: Array.isArray(pBeaconInfo.BindAddresses) ? pBeaconInfo.BindAddresses : [],
+			// Shared-fs identity. Both fields are optional for backwards compatibility:
+			// older beacons that don't send them just get null/[] and the shared-fs
+			// strategy is silently skipped for them.
+			HostID: (typeof pBeaconInfo.HostID === 'string' && pBeaconInfo.HostID.length > 0) ? pBeaconInfo.HostID : null,
+			SharedMounts: Array.isArray(pBeaconInfo.SharedMounts) ? pBeaconInfo.SharedMounts : [],
 			RegisteredAt: new Date().toISOString()
 		};
 

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

@@ -362,9 +362,17 @@ class UltravisorBeaconReachability extends libPictService
 	 * Determine the transfer strategy between a source beacon (file
 	 * owner) and a requesting beacon (the one that needs the file).
 	 *
+	 * Strategy ordering (most efficient first):
+	 *   local      — same beacon, no transport at all
+	 *   shared-fs  — different beacons but on the same host with overlapping
+	 *                filesystem mounts, so the requesting beacon can read the
+	 *                source's file path directly with no copy
+	 *   direct     — HTTP fetch from the source beacon's bind address
+	 *   proxy      — HTTP fetch via the coordinator
+	 *
 	 * @param {string} pSourceBeaconID - Beacon that owns the resource
 	 * @param {string} pRequestingBeaconID - Beacon that wants the resource
-	 * @returns {object} { Strategy, DirectURL }
+	 * @returns {object} { Strategy, DirectURL, SharedMountRoot? }
 	 */
 	resolveStrategy(pSourceBeaconID, pRequestingBeaconID)
 	{
@@ -386,6 +394,28 @@ class UltravisorBeaconReachability extends libPictService
 			return { Strategy: 'proxy', DirectURL: '' };
 		}
 
+		// Shared-fs detection — check whether both beacons live on the same host
+		// AND advertise at least one shared filesystem mount in common. When they
+		// do, the requesting beacon can read the source file directly from the
+		// shared mount without an HTTP transfer.
+		let tmpRequestingBeacon = tmpCoordinator.getBeacon(pRequestingBeaconID);
+		if (tmpRequestingBeacon
+			&& tmpSourceBeacon.HostID
+			&& tmpRequestingBeacon.HostID
+			&& tmpSourceBeacon.HostID === tmpRequestingBeacon.HostID)
+		{
+			let tmpSharedMount = this._findSharedMount(
+				tmpSourceBeacon.SharedMounts, tmpRequestingBeacon.SharedMounts);
+			if (tmpSharedMount)
+			{
+				return {
+					Strategy: 'shared-fs',
+					DirectURL: '',
+					SharedMountRoot: tmpSharedMount.Root
+				};
+			}
+		}
+
 		// Check matrix
 		let tmpEntry = this.getReachability(pRequestingBeaconID, pSourceBeaconID);
 
@@ -398,6 +428,52 @@ class UltravisorBeaconReachability extends libPictService
 		// unreachable or untested — fall back to proxy
 		return { Strategy: 'proxy', DirectURL: '' };
 	}
+
+	/**
+	 * Find the first MountID that appears in both beacons' SharedMounts arrays.
+	 *
+	 * The MountID is derived from `stat.dev` + the resolved root path on the
+	 * beacon side, so two beacons that bind-mount the same host directory get
+	 * the same ID, while two unrelated /media directories on different machines
+	 * (or in different containers without shared mounts) get different IDs.
+	 *
+	 * @param {Array} pSourceMounts - SharedMounts reported by the source beacon
+	 * @param {Array} pRequestingMounts - SharedMounts reported by the requester
+	 * @returns {object|null} The matching mount entry from the source beacon,
+	 *                        or null if no overlap exists
+	 */
+	_findSharedMount(pSourceMounts, pRequestingMounts)
+	{
+		if (!Array.isArray(pSourceMounts) || pSourceMounts.length === 0)
+		{
+			return null;
+		}
+		if (!Array.isArray(pRequestingMounts) || pRequestingMounts.length === 0)
+		{
+			return null;
+		}
+		for (let i = 0; i < pSourceMounts.length; i++)
+		{
+			let tmpSrc = pSourceMounts[i];
+			if (!tmpSrc || !tmpSrc.MountID)
+			{
+				continue;
+			}
+			for (let j = 0; j < pRequestingMounts.length; j++)
+			{
+				let tmpReq = pRequestingMounts[j];
+				if (!tmpReq || !tmpReq.MountID)
+				{
+					continue;
+				}
+				if (tmpSrc.MountID === tmpReq.MountID)
+				{
+					return tmpSrc;
+				}
+			}
+		}
+		return null;
+	}
 }
 
 module.exports = UltravisorBeaconReachability;

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

@@ -60,7 +60,7 @@ module.exports =
 			{
 				return fCallback(null, {
 					EventToFire: 'Error',
-					Outputs: { URL: '', BeaconID: '', BeaconName: '', Context: '', Path: '', Filename: '' },
+					Outputs: { URL: '', BeaconID: '', BeaconName: '', Context: '', Path: '', Filename: '', LocalPath: '' },
 					Log: [`Resolve Address: could not resolve "${tmpAddress}". Beacon may be offline or context not registered.`]
 				});
 			}
@@ -74,7 +74,8 @@ module.exports =
 				Filename: tmpResolved.Filename,
 				Strategy: 'direct',
 				DirectURL: '',
-				ProxyURL: ''
+				ProxyURL: '',
+				LocalPath: ''
 			};
 
 			// Helper: build a full URL from a beacon's bind address + context path + resource path
@@ -115,7 +116,33 @@ module.exports =
 					let tmpStrategyResult = tmpReachability.resolveStrategy(tmpResolved.BeaconID, tmpRequestingBeaconID);
 					tmpOutputs.Strategy = tmpStrategyResult.Strategy;
 
-					if (tmpStrategyResult.Strategy === 'direct' && tmpStrategyResult.DirectURL)
+					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 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';
+						}
+					}
+					else if (tmpStrategyResult.Strategy === 'direct' && tmpStrategyResult.DirectURL)
 					{
 						tmpOutputs.DirectURL = _buildDirectURL(tmpStrategyResult.DirectURL);
 						tmpOutputs.URL = tmpOutputs.DirectURL;
@@ -158,19 +185,26 @@ module.exports =
 				tmpStateWrites[pResolvedSettings.Destination] = tmpOutputs;
 			}
 
-			pTask.log.info(`Resolve Address: ${tmpAddress} → ${tmpOutputs.URL} [${tmpOutputs.Strategy}] (beacon: ${tmpResolved.BeaconName})`);
+			let tmpResolvedDest = tmpOutputs.LocalPath || tmpOutputs.URL;
+			pTask.log.info(`Resolve Address: ${tmpAddress} → ${tmpResolvedDest} [${tmpOutputs.Strategy}] (beacon: ${tmpResolved.BeaconName})`);
+
+			let tmpLogLines = [
+				`Resolved: ${tmpAddress}`,
+				`URL: ${tmpOutputs.URL}`,
+				`Strategy: ${tmpOutputs.Strategy}`,
+				`Beacon: ${tmpResolved.BeaconName} (${tmpResolved.BeaconID})`,
+				`Context: ${tmpResolved.Context}, Path: ${tmpResolved.Path}`
+			];
+			if (tmpOutputs.LocalPath)
+			{
+				tmpLogLines.push(`LocalPath: ${tmpOutputs.LocalPath} (shared filesystem — no transfer needed)`);
+			}
 
 			return fCallback(null, {
 				EventToFire: 'Complete',
 				Outputs: tmpOutputs,
 				StateWrites: tmpStateWrites,
-				Log: [
-					`Resolved: ${tmpAddress}`,
-					`URL: ${tmpOutputs.URL}`,
-					`Strategy: ${tmpOutputs.Strategy}`,
-					`Beacon: ${tmpResolved.BeaconName} (${tmpResolved.BeaconID})`,
-					`Context: ${tmpResolved.Context}, Path: ${tmpResolved.Path}`
-				]
+				Log: tmpLogLines
 			});
 		}
 	},
@@ -182,13 +216,56 @@ module.exports =
 		Execute: function (pTask, pResolvedSettings, pExecutionContext, fCallback)
 		{
 			let tmpSourceURL = pResolvedSettings.SourceURL;
+			let tmpSourceLocalPath = pResolvedSettings.SourceLocalPath;
 			let tmpFilename = pResolvedSettings.Filename;
 
+			// Shared-filesystem fast path: if the source beacon and the requesting
+			// beacon both report the same MountID, resolve-address will populate
+			// SourceLocalPath with the absolute on-disk path.  Both beacons see the
+			// same file at the same path because they share the mount, so we hand
+			// it back as the LocalPath without copying anything.  This is the
+			// difference between "instant" and "374 MB download to staging" on a
+			// stack-mode deployment where retold-remote and orator-conversion live
+			// in the same container.
+			if (tmpSourceLocalPath)
+			{
+				if (libFS.existsSync(tmpSourceLocalPath))
+				{
+					let tmpStat;
+					try
+					{
+						tmpStat = libFS.statSync(tmpSourceLocalPath);
+					}
+					catch (pStatError)
+					{
+						tmpStat = null;
+					}
+					pTask.log.info(`File Transfer: shared-fs hit, using ${tmpSourceLocalPath} directly (${tmpStat ? tmpStat.size : '?'} bytes, no copy).`);
+					return fCallback(null, {
+						EventToFire: 'Complete',
+						Outputs: {
+							LocalPath: tmpSourceLocalPath,
+							BytesTransferred: 0,
+							DurationMs: 0,
+							Strategy: 'shared-fs'
+						},
+						Log: [
+							`Shared filesystem detected — no transfer needed.`,
+							`Source path: ${tmpSourceLocalPath}`,
+							`Bytes transferred: 0 (zero-copy)`
+						]
+					});
+				}
+				// 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 (!tmpSourceURL)
 			{
 				return fCallback(null, {
 					EventToFire: 'Error',
-					Outputs: { LocalPath: '', BytesTransferred: 0, DurationMs: 0 },
+					Outputs: { LocalPath: '', BytesTransferred: 0, DurationMs: 0, Strategy: '' },
 					Log: ['File Transfer: no SourceURL provided.']
 				});
 			}
@@ -197,7 +274,7 @@ module.exports =
 			{
 				return fCallback(null, {
 					EventToFire: 'Error',
-					Outputs: { LocalPath: '', BytesTransferred: 0, DurationMs: 0 },
+					Outputs: { LocalPath: '', BytesTransferred: 0, DurationMs: 0, Strategy: '' },
 					Log: ['File Transfer: no Filename provided.']
 				});
 			}
@@ -467,7 +544,7 @@ function _pipeToFile(pResponse, pOutputPath, pStartTime, pFilename, pTask, fCall
 
 		return fCallback(null, {
 			EventToFire: 'Complete',
-			Outputs: { LocalPath: pOutputPath, BytesTransferred: tmpBytes, DurationMs: tmpDuration },
+			Outputs: { LocalPath: pOutputPath, BytesTransferred: tmpBytes, DurationMs: tmpDuration, Strategy: 'http' },
 			Log: [
 				`Downloaded: ${pFilename}`,
 				`Size: ${tmpBytes} bytes`,

package/source/services/tasks/platform/definitions/file-transfer.json

@@ -2,7 +2,7 @@
 	"Hash": "file-transfer",
 	"Type": "file-transfer",
 	"Name": "File Transfer",
-	"Description": "Download a file from a URL to the operation's staging directory. Streams the download — no base64 encoding. Logs bytes transferred and duration for visibility in the manifest.",
+	"Description": "Download a file from a URL to the operation's staging directory. Streams the download — no base64 encoding. When SourceLocalPath is provided (set by resolve-address with a shared-fs strategy), the task short-circuits and returns that path directly without copying anything. Logs bytes transferred and duration for visibility in the manifest.",
 	"Category": "platform",
 	"Capability": "Data Transfer",
 	"Action": "Download",
@@ -13,14 +13,17 @@
 		{ "Name": "Error", "IsError": true }
 	],
 	"SettingsInputs": [
-		{ "Name": "SourceURL", "DataType": "String", "Required": true, "Description": "URL to download from" },
-		{ "Name": "Filename", "DataType": "String", "Required": true, "Description": "Filename to save as in the staging directory" },
-		{ "Name": "AffinityKey", "DataType": "String", "Required": false, "Description": "Affinity key for caching (same key skips re-download)" }
+		{ "Name": "SourceURL", "DataType": "String", "Required": false, "Description": "URL to download from. Required unless SourceLocalPath is provided." },
+		{ "Name": "SourceLocalPath", "DataType": "String", "Required": false, "Description": "Absolute filesystem path to read directly. When set and the file exists, the HTTP download is skipped entirely and BytesTransferred reports 0. Used by the shared-fs reachability strategy." },
+		{ "Name": "Filename", "DataType": "String", "Required": false, "Description": "Filename to save as in the staging directory. Required unless SourceLocalPath is provided." },
+		{ "Name": "AffinityKey", "DataType": "String", "Required": false, "Description": "Affinity key for caching (same key skips re-download)" },
+		{ "Name": "TimeoutMs", "DataType": "Number", "Required": false, "Description": "HTTP download timeout in milliseconds (default 300000)" }
 	],
 	"StateOutputs": [
-		{ "Name": "LocalPath", "DataType": "String", "Description": "Absolute path to the downloaded file in staging" },
-		{ "Name": "BytesTransferred", "DataType": "Number", "Description": "Size of the downloaded file in bytes" },
-		{ "Name": "DurationMs", "DataType": "Number", "Description": "Download duration in milliseconds" }
+		{ "Name": "LocalPath", "DataType": "String", "Description": "Absolute path to the file (downloaded to staging, or pointing at the shared-fs source when no copy was needed)" },
+		{ "Name": "BytesTransferred", "DataType": "Number", "Description": "Size of the downloaded file in bytes (0 when shared-fs zero-copy was used)" },
+		{ "Name": "DurationMs", "DataType": "Number", "Description": "Download duration in milliseconds" },
+		{ "Name": "Strategy", "DataType": "String", "Description": "Which path was taken: 'shared-fs' (zero-copy) or 'http' (downloaded)" }
 	],
-	"DefaultSettings": { "SourceURL": "", "Filename": "", "AffinityKey": "" }
+	"DefaultSettings": { "SourceURL": "", "SourceLocalPath": "", "Filename": "", "AffinityKey": "", "TimeoutMs": 300000 }
 }

package/source/services/tasks/platform/definitions/resolve-address.json

@@ -2,7 +2,7 @@
 	"Hash": "resolve-address",
 	"Type": "resolve-address",
 	"Name": "Resolve Address",
-	"Description": "Resolve a universal address (>beacon/context/path) to a concrete URL and metadata, with optional transfer strategy resolution (local/direct/proxy) when a requesting beacon is specified.",
+	"Description": "Resolve a universal address (>beacon/context/path) to a concrete URL and metadata, with optional transfer strategy resolution (local/shared-fs/direct/proxy) when a requesting beacon is specified.",
 	"Category": "platform",
 	"Capability": "Address Resolution",
 	"Action": "Resolve",
@@ -24,9 +24,10 @@
 		{ "Name": "Context", "DataType": "String", "Description": "Context name (e.g. File, Cache)" },
 		{ "Name": "Path", "DataType": "String", "Description": "Path within the context" },
 		{ "Name": "Filename", "DataType": "String", "Description": "Filename portion of the path" },
-		{ "Name": "Strategy", "DataType": "String", "Description": "Transfer strategy: local, direct, or proxy" },
+		{ "Name": "Strategy", "DataType": "String", "Description": "Transfer strategy: local, shared-fs, direct, or proxy" },
 		{ "Name": "DirectURL", "DataType": "String", "Description": "Direct beacon-to-beacon URL (when strategy is direct)" },
-		{ "Name": "ProxyURL", "DataType": "String", "Description": "Proxy URL through Ultravisor (when strategy is proxy)" }
+		{ "Name": "ProxyURL", "DataType": "String", "Description": "Proxy URL through Ultravisor (when strategy is proxy)" },
+		{ "Name": "LocalPath", "DataType": "String", "Description": "Absolute path to the resource on the shared filesystem (when strategy is shared-fs); empty otherwise" }
 	],
 	"DefaultSettings": { "Address": "", "Destination": "", "RequestingBeaconID": "" }
 }