The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.
TypeScript 3d-modelingagent-frameworkagent-harnessai-agentscadclaude-codecodexcoding-agentsdeveloper-toolsesp32game-developmentmcp-servermulti-agentopen-hardwareopencodeopenharnesspcbroboticsterminaltmux
#!/usr/bin/env python3
"""On-demand hardware diagnosis and selected offline Wi-Fi/GPU preparation."""
import argparse
import fcntl
import hashlib
import importlib.util
import json
import os
from pathlib import Path
import re
import shutil
import subprocess
import tempfile
# These older Mac radio families need firmware/driver support beyond the stock
# brcmfmac path. Never treat every Broadcom device as a wl device. In particular,
# BCM43602 (43ba/43bb/43bc) must keep its native driver.
# https://wireless.docs.kernel.org/en/latest/en/users/drivers/b43.html
BROADCOM_IDS = {'14e4:4331': 'BCM4331', '14e4:43a0': 'BCM4360'}
BUNDLE = Path('/usr/share/harness-os/hardware/broadcom')
NVIDIA_BUNDLE = Path('/usr/share/harness-os/hardware/nvidia')
PCI_NAME = re.compile(r'[0-9a-f]{4,8}:[0-9a-f]{2}:[0-9a-f]{2}\.[0-7]')
def read(path):
try:
return path.read_text().strip()
except (OSError, UnicodeError):
return ''
def run(*args, capture=False, timeout=180):
result = subprocess.run(list(map(str, args)), check=True, text=True, timeout=timeout,
stdout=subprocess.PIPE if capture else None)
return result.stdout.strip() if capture else None
def digest(path):
with path.open('rb') as handle:
return hashlib.file_digest(handle, 'sha256').hexdigest()
def pci_devices(sysfs=Path('/sys')):
devices = []
for path in sorted((sysfs / 'bus/pci/devices').glob('*')):
if not PCI_NAME.fullmatch(path.name):
continue
vendor, device, kind = (read(path / name).removeprefix('0x') for name in ['vendor', 'device', 'class'])
if not re.fullmatch(r'[0-9a-f]{4}', vendor) or not re.fullmatch(r'[0-9a-f]{4}', device):
continue
interfaces = []
for interface in (sysfs / 'class/net').glob('*'):
if (interface / 'device').is_symlink() and (interface / 'device').resolve().is_relative_to(path.resolve()):
interfaces.append({'name': interface.name, 'wireless': (interface / 'wireless').is_dir() or (interface / 'phy80211').exists()})
driver = (path / 'driver').resolve().name if (path / 'driver').is_symlink() else None
override = read(path / 'driver_override')
devices.append({'address': path.name, 'id': vendor + ':' + device,
'class': kind, 'driver': driver,
'driver_override': None if override in {'', '(null)'} else override,
'interfaces': interfaces})
return devices
def installation_blocker(sysfs=Path('/sys')):
# The T2 BCE controller identifies this platform independently of DMI names
# and the currently bound driver. The stock image does not ship its stack.
# https://github.com/t2linux/linux-t2-patches/blob/main/1001-Add-t2bce-driver-stack.patch
if any(device['id'] == '106b:1801' for device in pci_devices(sysfs)):
path = Path(__file__).with_name('boot_profile.py')
if path.is_file():
spec = importlib.util.spec_from_file_location('harness_boot_profile', path)
module = importlib.util.module_from_spec(spec)
spec.loader.exec_module(module)
if module.selected()['id'] == 'apple-t2':
pkgbase = Path('/usr/lib/modules') / os.uname().release / 'pkgbase'
if read(pkgbase) == 'linux-t2':
return None
return 'Boot this Mac using the Harness T2 image before installing.'
return 'This Harness image does not support Apple T2 Macs yet.'
return None
def needs_broadcom(device):
if device['id'] not in BROADCOM_IDS or device['class'] != '028000':
return False
# A missing wireless interface does not mean the radio is available: it
# may be assigned to a VM or explicitly disabled with driver_override.
# Apply the same ownership policy to live activation and offline packages.
if device.get('driver_override') not in {None, '', 'wl'}:
return False
if device['driver'] not in {None, 'wl', 'bcma-pci-bridge', 'ssb'}:
return False
return device['driver'] == 'wl' or not any(i['wireless'] for i in device['interfaces'])
def opencode_cpu_supported(proc=Path('/proc')):
"""Return None when the x86 instruction requirement cannot be determined."""
architecture = os.uname().machine
if architecture != 'x86_64' and not re.fullmatch(r'i[3-6]86', architecture):
return None
flags = []
for line in read(proc / 'cpuinfo').splitlines():
key, separator, value = line.partition(':')
if separator and key.strip() == 'flags':
flags.append(value.split())
if not flags or any(not features for features in flags):
return None
return all('sse4_2' in features for features in flags)
def report(sysfs=Path('/sys'), proc=Path('/proc')):
return {'architecture': os.uname().machine, 'kernel': os.uname().release,
'computer': {'vendor': read(sysfs / 'class/dmi/id/sys_vendor') or None,
'model': read(sysfs / 'class/dmi/id/product_name') or None},
'efi_bits': read(sysfs / 'firmware/efi/fw_platform_size') or None,
'opencode_cpu': {'required_x86_feature': 'sse4_2',
'available': opencode_cpu_supported(proc)},
'pci': pci_devices(sysfs),
'installation_blocker': installation_blocker(sysfs),
'backlights': [p.name for p in sorted((sysfs / 'class/backlight').glob('*'))],
'broadcom_bundle_available': (BUNDLE / 'manifest.json').is_file(),
'nvidia_bundle_available': (NVIDIA_BUNDLE / 'manifest.json').is_file(),
'gpu_health': gpu_health().cached_report() if Path(__file__).with_name('gpu_health.py').is_file() else None}
def gpu_health():
spec = importlib.util.spec_from_file_location('harness_gpu_health', Path(__file__).with_name('gpu_health.py'))
module = importlib.util.module_from_spec(spec)
spec.loader.exec_module(module)
return module
def nvidia_bundle_manifest(folder, all_files=False):
manifest = json.loads((folder / 'manifest.json').read_text())
if manifest.get('schema') != 1 or manifest.get('driver') != 'nvidia-open' or manifest.get('architecture') != 'x86_64':
raise ValueError('Unsupported NVIDIA bundle.')
supported = manifest.get('supported_devices', {})
if not supported or any(not re.fullmatch(r'10de:[0-9a-f]{4}', key) or not isinstance(value, list) or
not value or any(not isinstance(name, str) or not name for name in value)
for key, value in supported.items()):
raise ValueError('Invalid NVIDIA support table.')
if not re.fullmatch(r'\d+\.\d+\.\d+', manifest.get('driver_version', '')):
raise ValueError('Invalid NVIDIA driver version.')
if all_files:
for name, expected in manifest.get('files', {}).items():
relative = Path(name)
if relative.is_absolute() or '..' in relative.parts or len(relative.parts) > 2:
raise ValueError('Invalid NVIDIA bundle path.')
path = folder / name
if path.is_symlink() or not path.resolve().is_relative_to(folder.resolve()):
raise ValueError('NVIDIA bundle files must stay inside their directory.')
if not path.is_file() or path.stat().st_size != expected['bytes'] or digest(path) != expected['sha256']:
raise ValueError('NVIDIA bundle checksum mismatch: ' + name)
return manifest
def nvidia_selection(devices, supported):
cards = [d for d in devices if d['id'].startswith('10de:') and d['class'] in {'030000', '030200'}]
if not cards:
return None
# nvidia-utils blacklists nouveau globally. Do not break a second legacy
# NVIDIA display, or take over a GPU explicitly assigned to passthrough.
if any(card['id'] not in supported for card in cards):
return {'status': 'unchanged', 'reason': 'An NVIDIA GPU needs a different driver.'}
# An unbound GPU can still be reserved for passthrough or explicitly kept
# on nouveau. Installing nvidia-utils would blacklist nouveau system-wide.
if any(card['driver'] not in {None, 'nouveau', 'nvidia'} or
card.get('driver_override') not in {None, '', 'nvidia'} for card in cards):
return {'status': 'unchanged', 'reason': 'Keep the existing GPU assignment.'}
return {'status': 'selected', 'devices': [card['id'] for card in cards]}
def configure_nvidia_install(target, devices, bundle=NVIDIA_BUNDLE):
target = target.resolve()
if target == Path('/') or not target.is_mount() or not (target / 'etc/harness-live').is_file():
raise ValueError('GPU preparation requires the mounted installation image.')
if not any(d['id'].startswith('10de:') and d['class'] in {'030000', '030200'} for d in devices):
return None
manifest = nvidia_bundle_manifest(bundle)
selected = nvidia_selection(devices, manifest['supported_devices'])
if selected['status'] != 'selected':
return selected
manifest = nvidia_bundle_manifest(bundle, all_files=True)
lock = json.loads((target / 'usr/share/harness-os/lock.json').read_text())
if manifest['arch_snapshot'] != lock['arch_snapshot']:
raise ValueError('NVIDIA bundle and installed package snapshot differ.')
output = run('arch-chroot', target, 'pacman', '-Q', *manifest['base_packages'], capture=True)
if dict(line.split(' ', 1) for line in output.splitlines()) != manifest['base_packages']:
raise ValueError('NVIDIA dependencies differ from the validated base.')
names = sorted(manifest['packages'])
if not names or any(not re.fullmatch(r'[a-zA-Z0-9_+.:\-]+\.pkg\.tar\.zst', name) for name in names):
raise ValueError('Invalid offline NVIDIA package list.')
for name in names:
if 'packages/' + name not in manifest['files'] or 'packages/' + name + '.sig' not in manifest['files']:
raise ValueError('Offline NVIDIA packages require signatures.')
# Read directly from the live USB. Neither generic nor GPU installations
# copy this large compressed package cache into their permanent filesystem.
with tempfile.TemporaryDirectory(prefix='harness-gpu-', dir=target / 'var/tmp') as temporary:
folder = Path(temporary)
packages = folder / 'packages'
packages.mkdir()
config = folder / 'pacman.conf'
config.write_text('[options]\nArchitecture = auto\nCheckSpace\nSigLevel = Required\nLocalFileSigLevel = Required\n')
config.chmod(0o600)
run('mount', '--bind', bundle / 'packages', packages)
try:
run('mount', '-o', 'remount,bind,ro', packages)
prefix = '/' + str(packages.relative_to(target))
run('arch-chroot', target, 'pacman', '--config', '/' + str(config.relative_to(target)),
'-U', '--needed', '--noconfirm', *[prefix + '/' + name for name in names], timeout=600)
finally:
run('umount', packages)
for module in ['nvidia', 'nvidia_modeset', 'nvidia_uvm', 'nvidia_drm']:
magic = run('arch-chroot', target, 'modinfo', '-k', manifest['kernel'], '-F', 'vermagic', module, capture=True)
version = run('arch-chroot', target, 'modinfo', '-k', manifest['kernel'], '-F', 'version', module, capture=True)
if magic.split()[0] != manifest['kernel'] or version != manifest['driver_version']:
raise ValueError('Installed NVIDIA modules do not match the kernel and userspace.')
config = target / 'etc/mkinitcpio.conf.d/30-harness-nvidia.conf'
config.parent.mkdir(parents=True, exist_ok=True)
config.write_text('# Display driver must be ready for disk unlock and the Harness session.\n'
'MODULES+=(nvidia nvidia_modeset nvidia_drm)\n')
return dict(selected, status='installed', driver='nvidia-open-lts',
kernel=manifest['kernel'], driver_version=manifest['driver_version'], packages=manifest['packages'])
def bundle_manifest(folder, all_files=False):
manifest = json.loads((folder / 'manifest.json').read_text())
if manifest.get('schema') != 1 or manifest.get('driver') != 'broadcom-wl' or manifest.get('architecture') != 'x86_64':
raise ValueError('Unsupported Wi-Fi bundle.')
module = manifest.get('module', '')
if module not in {'wl.ko', 'wl.ko.zst', 'wl.ko.xz'} or module not in manifest.get('files', {}):
raise ValueError('Wi-Fi module is missing from its manifest.')
for name, expected in manifest['files'].items():
relative = Path(name)
if relative.is_absolute() or '..' in relative.parts or len(relative.parts) > 2:
raise ValueError('Invalid Wi-Fi bundle path.')
path = folder / name
if path.is_symlink() or not path.resolve().is_relative_to(folder.resolve()):
raise ValueError('Wi-Fi bundle files must stay inside their directory.')
if all_files or name == module:
if not path.is_file() or path.stat().st_size != expected['bytes'] or digest(path) != expected['sha256']:
raise ValueError('Wi-Fi bundle checksum mismatch: ' + name)
return manifest
def activate(address, sysfs=Path('/sys'), bundle=BUNDLE):
if not PCI_NAME.fullmatch(address):
raise ValueError('Invalid PCI address.')
devices = pci_devices(sysfs)
device = next((d for d in devices if d['address'] == address), None)
if not device or not needs_broadcom(device) or device['driver'] == 'wl':
return {'status': 'unchanged', 'address': address}
# Verify availability before changing a binding. The live image carries only
# a prebuilt module here; installed machines use the ordinary DKMS package.
if (bundle / 'manifest.json').is_file():
manifest = bundle_manifest(bundle)
if manifest['kernel'] != os.uname().release:
raise ValueError('The Wi-Fi bundle is for a different kernel.')
loader = ['insmod', str(bundle / manifest['module'])]
else:
run('modinfo', 'wl', capture=True, timeout=5)
loader = ['modprobe', 'wl']
path = sysfs / 'bus/pci/devices' / address
previous = read(path / 'driver_override')
previous = '' if previous == '(null)' else previous
try:
(path / 'driver_override').write_text('wl\n')
if device['driver']:
(path / 'driver/unbind').write_text(address + '\n')
run('modprobe', 'cfg80211', timeout=8)
if not (sysfs / 'module/wl').is_dir():
run(*loader, timeout=15)
if not (path / 'driver').is_symlink():
(sysfs / 'bus/pci/drivers_probe').write_text(address + '\n')
if not (path / 'driver').is_symlink() or (path / 'driver').resolve().name != 'wl':
raise RuntimeError('Wi-Fi driver did not bind to ' + address)
return {'status': 'activated', 'address': address, 'driver': 'wl'}
except BaseException:
(path / 'driver_override').write_text(previous + '\n')
if not (path / 'driver').is_symlink():
(sysfs / 'bus/pci/drivers_probe').write_text(address + '\n')
raise
def configure_install(target, devices=None, bundle=BUNDLE):
target = target.resolve()
# Only the offline installer's mounted, still-marked image may use this path.
# It must never install a compiler into the running live overlay by mistake.
if target == Path('/') or not target.is_mount() or not (target / 'etc/harness-live').is_file():
raise ValueError('Wi-Fi preparation requires the mounted installation image.')
devices = pci_devices() if devices is None else devices
selected = [d for d in devices if needs_broadcom(d)]
folder = target / BUNDLE.relative_to('/')
result = {'drivers': [], 'devices': [d['id'] for d in selected]}
if selected:
manifest = bundle_manifest(folder)
cache = folder
if not (folder / 'packages').exists():
if bundle_manifest(bundle) != manifest:
raise ValueError('Live Wi-Fi cache and installation image differ.')
cache = bundle
manifest = bundle_manifest(cache, all_files=True)
lock = json.loads((target / 'usr/share/harness-os/lock.json').read_text())
if manifest['arch_snapshot'] != lock['arch_snapshot']:
raise ValueError('Wi-Fi bundle and installed package snapshot differ.')
output = run('arch-chroot', target, 'pacman', '-Q', *manifest['base_packages'], capture=True)
actual = dict(line.split(' ', 1) for line in output.splitlines())
if actual != manifest['base_packages']:
raise ValueError('Wi-Fi dependencies differ from the validated base.')
names = sorted(manifest['packages'])
if not names or any(not re.fullmatch(r'[a-zA-Z0-9_+.:\-]+\.pkg\.tar\.zst', name) for name in names):
raise ValueError('Invalid offline Wi-Fi package list.')
for name in names:
if 'packages/' + name not in manifest['files'] or 'packages/' + name + '.sig' not in manifest['files']:
raise ValueError('Offline Wi-Fi packages require signatures.')
# No repositories: this operation either succeeds from signed local
# packages or fails. It cannot quietly turn into an online installation.
with tempfile.TemporaryDirectory(prefix='harness-driver-', dir=target / 'var/tmp') as temporary:
packages = Path(temporary) / 'packages'
packages.mkdir()
config = Path(temporary) / 'pacman.conf'
config.write_text('[options]\nArchitecture = auto\nCheckSpace\nSigLevel = Required\nLocalFileSigLevel = Required\n')
config.chmod(0o600)
run('mount', '--bind', cache / 'packages', packages)
try:
run('mount', '-o', 'remount,bind,ro', packages)
prefix = '/' + str(packages.relative_to(target))
run('arch-chroot', target, 'pacman', '--config', '/' + str(config.relative_to(target)),
'-U', '--needed', '--noconfirm', *[prefix + '/' + name for name in names], timeout=600)
finally:
run('umount', packages)
run('arch-chroot', target, 'modinfo', '-k', manifest['kernel'], 'wl', capture=True)
result.update(drivers=['broadcom-wl-dkms'], kernel=manifest['kernel'], packages=manifest['packages'])
# The USB keeps the offline cache; the installed computer does not. Unrelated
# machines receive neither wl nor its compiler/kernel-header dependencies.
shutil.rmtree(folder, ignore_errors=False)
nvidia = configure_nvidia_install(target, devices)
if nvidia is not None:
result['nvidia'] = nvidia
if nvidia['status'] == 'installed':
result['drivers'].append(nvidia['driver'])
result['devices'].extend(nvidia['devices'])
state = target / 'var/lib/harness-os/hardware.json'
state.parent.mkdir(parents=True, exist_ok=True)
state.write_text(json.dumps(result, indent=2) + '\n')
return result
def main():
parser = argparse.ArgumentParser(description=__doc__)
sub = parser.add_subparsers(dest='command')
reporting = sub.add_parser('report')
reporting.add_argument('--check-gpu', action='store_true', help='Repeat GPU verification as the current user')
activation = sub.add_parser('activate')
activation.add_argument('address')
installation = sub.add_parser('configure-install')
installation.add_argument('target', type=Path)
args = parser.parse_args()
if args.command in {'activate', 'configure-install'} and os.geteuid() != 0:
parser.error('This operation requires root.')
if args.command == 'activate':
# Multiple matching PCI add events must not race the module load.
descriptor = os.open('/run/lock/harness-broadcom.lock', os.O_CREAT | os.O_RDWR | os.O_NOFOLLOW, 0o600)
with os.fdopen(descriptor, 'r+') as lock:
stat = os.fstat(lock.fileno())
if stat.st_uid != 0 or stat.st_mode & 0o022:
raise ValueError('Wi-Fi activation lock is not root-owned and private.')
fcntl.flock(lock.fileno(), fcntl.LOCK_EX)
result = activate(args.address)
elif args.command == 'configure-install':
result = configure_install(args.target)
else:
if getattr(args, 'check_gpu', False):
if not Path(__file__).with_name('gpu_health.py').is_file():
parser.error('GPU verification is not available in this system profile.')
gpu_health().check(force=True)
result = report()
print(json.dumps(result, indent=2))
if __name__ == '__main__':
main()