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
feat(device-discovery): implement local network discovery and handling for blocked networks
45175a7e9c188e8b7c48fc3335c1
diff --git a/cli/src/lib/autonomous-device/discovery.spec.ts b/cli/src/lib/autonomous-device/discovery.spec.tsnew file mode 100644index 000000000..48e4e8f2a--- /dev/null+++ b/cli/src/lib/autonomous-device/discovery.spec.ts@@ -0,0 +1,50 @@+import { EventEmitter } from 'node:events'+import { describe, expect, it } from 'vitest'+import { discoverDevices, type DiscoveryTransport } from './discovery.js'++const lamp = { fqdn: 'lamp-ee17._autonomous._tcp.local', name: 'lamp-ee17', host: 'lamp-ee17.local', port: 80, addresses: ['172.168.20.174'] }+/** A fake multicast socket: `sendError` is what macOS returns for the probe query. */+function transport(options: { services?: typeof lamp[]; sendError?: string; bindError?: string } = {}) {+ const mdns = Object.assign(new EventEmitter(), {+ query: (_query: unknown, callback: (error?: NodeJS.ErrnoException | null) => void) =>+ queueMicrotask(() => callback(options.sendError ? Object.assign(new Error(`send ${options.sendError} 224.0.0.251:5353`), { code: options.sendError }) : null)),+ })+ let destroyed = false+ const create = (): DiscoveryTransport => ({+ find: onService => {+ for (const service of options.services ?? []) queueMicrotask(() => onService(service))+ if (options.bindError) queueMicrotask(() => mdns.emit('error', Object.assign(new Error(`bind ${options.bindError}`), { code: options.bindError })))+ },+ mdns,+ destroy: () => { destroyed = true },+ })+ return { create, destroyed: () => destroyed }+}++describe('autonomous device discovery', () => {+ it('lists advertised devices by their IPv4 address', async () => {+ const t = transport({ services: [lamp] })+ expect(await discoverDevices(20, t.create)).toEqual([{ id: lamp.fqdn, name: 'lamp-ee17', host: '172.168.20.174', port: 80 }])+ expect(t.destroyed()).toBe(true)+ })++ it('reports an empty network as empty, not as blocked', async () => {+ expect(await discoverDevices(20, transport().create)).toEqual([])+ })++ it.each(['EHOSTUNREACH', 'ENETUNREACH', 'EPERM'])('names a refused multicast send (%s) as a blocked local network', async code => {+ await expect(discoverDevices(20, transport({ sendError: code }).create)).rejects.toMatchObject({ code: 'LOCAL_NETWORK_BLOCKED' })+ })++ it('names a refused socket bind as a blocked local network instead of crashing on the error event', async () => {+ await expect(discoverDevices(1000, transport({ bindError: 'EACCES' }).create)).rejects.toMatchObject({ code: 'LOCAL_NETWORK_BLOCKED' })+ })++ it('trusts devices that answered over a failed probe', async () => {+ expect(await discoverDevices(20, transport({ services: [lamp], sendError: 'EHOSTUNREACH' }).create)).toHaveLength(1)+ })++ it('keeps other send failures out of the blocked diagnosis', async () => {+ expect(await discoverDevices(20, transport({ sendError: 'EMSGSIZE' }).create)).toEqual([])+ })+})diff --git a/cli/src/lib/autonomous-device/discovery.ts b/cli/src/lib/autonomous-device/discovery.tsindex abc8eb2e3..12674a503 100644--- a/cli/src/lib/autonomous-device/discovery.ts+++ b/cli/src/lib/autonomous-device/discovery.ts@@ -1,20 +1,55 @@import Bonjour from 'bonjour-service'import { isIP } from 'node:net'export interface DiscoveredDevice { id: string; name: string; host: string; port: number }+interface Mdns {+ query(query: unknown, callback: (error?: NodeJS.ErrnoException | null) => void): void+ on(event: 'error' | 'warning', listener: (error: NodeJS.ErrnoException) => void): void+}+/** The seam tests replace: a browser plus the multicast socket underneath it. */+export interface DiscoveryTransport {+ find(onService: (service: { fqdn?: string; name: string; host?: string; port: number; addresses?: string[] }) => void): void+ mdns: Mdns | null+ destroy(): void+}+/** macOS answers a multicast send with these when Local Network access is denied to the app that+ * launched the daemon. The browser's own queries drop send errors, so without a probe of our own+ * a refused network is indistinguishable from an empty one. */+const BLOCKED = new Set(['EHOSTUNREACH', 'ENETUNREACH', 'EPERM', 'EACCES'])+function bonjourTransport(onError: (error: Error) => void): DiscoveryTransport {+ const bonjour = new Bonjour({}, onError)+ let browser: { stop(): void } | undefined+ // `server.mdns` is private in the typings; a future version without it just loses the probe.+ const mdns = (bonjour as unknown as { server?: { mdns?: Mdns } }).server?.mdns ?? null+ return {+ find: onService => { browser = bonjour.find({ type: 'autonomous', protocol: 'tcp' }, onService) },+ mdns,+ destroy: () => { browser?.stop(); bonjour.destroy() },+ }+}/** Reuse the OS's existing Avahi _autonomous._tcp advertisement. Discovery grants no trust. */-export function discoverDevices(durationMs = 3000): Promise<DiscoveredDevice[]> {+export function discoverDevices(durationMs = 3000, transport = bonjourTransport): Promise<DiscoveredDevice[]> {return new Promise((resolve, reject) => {const found = new Map<string, DiscoveredDevice>()- let done = false- const bonjour = new Bonjour({}, (error: Error) => finish(error))- const browser = bonjour.find({ type: 'autonomous', protocol: 'tcp' }, service => {+ let done = false, blocked: string | undefined+ const noteBlocked = (error?: NodeJS.ErrnoException | null) => { if (error?.code && BLOCKED.has(error.code)) blocked ??= error.code }+ const t = transport(finish)+ // An unhandled 'error' on the socket (bind refused) would otherwise throw inside the daemon.+ t.mdns?.on('error', finish)+ t.mdns?.on('warning', noteBlocked)+ t.find(service => {const host = service.addresses?.find(a => isIP(a) === 4) ?? service.hostif (service.fqdn && host && service.port > 0 && service.port <= 65535) found.set(service.fqdn, { id: service.fqdn, name: service.name, host, port: service.port })})+ t.mdns?.query({ questions: [{ name: '_autonomous._tcp.local', type: 'PTR' }] }, noteBlocked)const timer = setTimeout(() => finish(), durationMs)- function finish(error?: Error) {- if (done) return; done = true; clearTimeout(timer); browser.stop(); bonjour.destroy()- if (error) reject(error); else resolve([...found.values()].sort((a, b) => a.name.localeCompare(b.name)))+ function finish(error?: NodeJS.ErrnoException) {+ if (done) return; done = true; clearTimeout(timer); t.destroy()+ noteBlocked(error)+ // Devices that answered prove the network works, whatever the probe said.+ if (found.size) resolve([...found.values()].sort((a, b) => a.name.localeCompare(b.name)))+ else if (blocked) reject(Object.assign(new Error('Harness is not allowed to use the local network. Allow it in System Settings › Privacy & Security › Local Network.'), { code: 'LOCAL_NETWORK_BLOCKED' }))+ else if (error) reject(error)+ else resolve([])}})}diff --git a/cli/src/lib/autonomous-device/localApi.spec.ts b/cli/src/lib/autonomous-device/localApi.spec.tsindex eea4f6927..5adad0b31 100644--- a/cli/src/lib/autonomous-device/localApi.spec.ts+++ b/cli/src/lib/autonomous-device/localApi.spec.ts@@ -88,6 +88,13 @@ describe('device local management validation', () => {.toEqual({ status: 500, body: { error: { code: 'INTERNAL_ERROR', message: 'Autonomous device management request failed' } } })})+ it('names a blocked local network so the app can say where to allow it', async () => {+ const service = fixture()+ service.discover.mockRejectedValue(Object.assign(new Error('Harness is not allowed to use the local network.'), { code: 'LOCAL_NETWORK_BLOCKED' }))+ expect(await autonomousDeviceLocalRequest(service, 'GET', '/api/autonomous-device/discover'))+ .toEqual({ status: 503, body: { error: { code: 'LOCAL_NETWORK_BLOCKED', message: 'Harness is not allowed to use the local network.' } } })+ })+it('routes all read-only and cancel operations', async () => {const service = fixture()for (const [method, path, name] of [diff --git a/cli/src/lib/autonomous-device/localApi.ts b/cli/src/lib/autonomous-device/localApi.tsindex 6a70e2703..69456e629 100644--- a/cli/src/lib/autonomous-device/localApi.ts+++ b/cli/src/lib/autonomous-device/localApi.ts@@ -24,6 +24,7 @@ const routes: Record<string, string> = {const errorStatus: Record<string, number> = {BAD_REQUEST: 400, UNKNOWN_DEVICE: 404, ALREADY_PAIRED: 409, BUSY: 409,DEVICE_NOT_FOUND: 404, BAD_CODE: 400, NO_INTENT: 409, STALE_PAIR: 409, CODE_MISMATCH: 403, BACKEND_DOWN: 503, TIMEOUT: 504, RATE_LIMITED: 429, EXPIRED: 410, CANCELLED: 409,+ LOCAL_NETWORK_BLOCKED: 503,}function failure(status: number, code: string, message: string): AutonomousDeviceLocalResponse {diff --git a/desktop/lib/autonomous_device/autonomous_device_cli.dart b/desktop/lib/autonomous_device/autonomous_device_cli.dartindex ea4c059f5..eb7831fc4 100644--- a/desktop/lib/autonomous_device/autonomous_device_cli.dart+++ b/desktop/lib/autonomous_device/autonomous_device_cli.dart@@ -21,8 +21,12 @@ class AutonomousDeviceCliException implements Exception {'CODE_MISMATCH' => 'That code did not match. Generate a new code on your Autonomous robot, then try again.','RATE_LIMITED' => 'Too many pairing attempts. Wait five minutes, then generate a new code on your Autonomous robot and try again.','EXPIRED' => 'The pairing code expired. Generate a new code on your Autonomous robot, then try again.',+ 'LOCAL_NETWORK_BLOCKED' => 'Harness can’t see your local network, so it can’t find Autonomous robots. Allow Harness in System Settings › Privacy & Security › Local Network, then refresh.',_ => message,};++ /// macOS refused the daemon's multicast: no robot can be found until the user allows it.+ bool get localNetworkBlocked => code == 'LOCAL_NETWORK_BLOCKED';bool get unsupported =>const {'NOT_FOUND', 'UNSUPPORTED', 'UNKNOWN_COMMAND'}.contains(code);@overridediff --git a/desktop/lib/settings/sections/devices_section.dart b/desktop/lib/settings/sections/devices_section.dartindex 0dea38dcb..c06e9cb0a 100644--- a/desktop/lib/settings/sections/devices_section.dart+++ b/desktop/lib/settings/sections/devices_section.dart@@ -1,7 +1,9 @@import 'dart:async';import 'dart:convert';+import 'dart:io';import 'package:flutter/material.dart';+import 'package:url_launcher/url_launcher.dart';import '../../autonomous_device/autonomous_device_cli.dart';import '../../core/test_run.dart';@@ -30,6 +32,7 @@ class _DevicesSectionState extends State<DevicesSection> {bool _refreshing = false;int _generation = 0;bool _unsupported = false;+ bool _networkBlocked = false;String? _error;String? _actionError;String? _selectedDevice;@@ -74,13 +77,32 @@ class _DevicesSectionState extends State<DevicesSection> {}}+ /// A refused local network loses discovery only: paired robots still list, and the+ /// notice says where to allow it instead of "no robots found".+ Future<Map<String, dynamic>> _discoverOrBlocked() async {+ try {+ return await _cli.discover();+ } on AutonomousDeviceCliException catch (error) {+ if (!error.localNetworkBlocked) rethrow;+ return {'devices': const [], 'localNetworkBlocked': true};+ }+ }++ void _openLocalNetworkSettings() => unawaited(+ launchUrl(+ Uri.parse(+ 'x-apple.systempreferences:com.apple.preference.security?Privacy_LocalNetwork',+ ),+ ),+ );+Future<void> _refresh() async {if (_refreshing || (kUnderTest && widget.cli == null)) return;_refreshing = true;final generation = _generation;try {final status = await _cli.status();- final results = await Future.wait([_cli.list(), _cli.discover()]);+ final results = await Future.wait([_cli.list(), _discoverOrBlocked()]);if (!mounted || generation != _generation) return;final devices = <Map<String, dynamic>>[for (final row in results[0]['devices'] as List? ?? [])@@ -93,6 +115,7 @@ class _DevicesSectionState extends State<DevicesSection> {(row['id'] as String).isNotEmpty)row,];+ final networkBlocked = results[1]['localNetworkBlocked'] == true;if (_selectedDevice != null &&!discovered.any((device) => device['id'] == _selectedDevice)) {_selectedDevice = null;@@ -101,12 +124,14 @@ class _DevicesSectionState extends State<DevicesSection> {if (_loading ||_unsupported ||_error != null ||+ networkBlocked != _networkBlocked ||jsonEncode([status, devices, discovered]) !=jsonEncode([_status, _devices, _discovered])) {setState(() {_status = status;_devices = devices;_discovered = discovered;+ _networkBlocked = networkBlocked;_loading = false;_unsupported = false;_error = null;@@ -300,6 +325,23 @@ class _DevicesSectionState extends State<DevicesSection> {),),if (!_unsupported && !_loading) ...[+ if (_networkBlocked) ...[+ SettingRow(+ key: const Key('autonomous-device-network-blocked'),+ title: 'Allow Harness on your local network',+ alignTop: true,+ detail:+ 'macOS is blocking Harness from your local network, so it can’t find Autonomous robots. '+ 'Turn on Harness in Privacy & Security › Local Network, then refresh.',+ control: Platform.isMacOS+ ? action(+ 'Open Settings',+ disabled ? null : _openLocalNetworkSettings,+ )+ : const SizedBox.shrink(),+ ),+ const SizedBox(height: 10),+ ],for (final device in _devices) ...[SettingRow(title: device['label']?.toString() ?? 'Autonomous robot',@@ -329,7 +371,9 @@ class _DevicesSectionState extends State<DevicesSection> {? 'Pair a device': 'Pair another device',alignTop: true,- detail: _discovered.isEmpty+ detail: _networkBlocked+ ? 'Allow local network access above to find your robot.'+ : _discovered.isEmpty? 'No Autonomous robots found. Keep your device on the same network, then refresh.': 'Select your device and enter its six-character code. Separators are allowed, for example ABC-123.',control: SizedBox(diff --git a/desktop/macos/Runner/Info.plist b/desktop/macos/Runner/Info.plistindex 93e78c367..cb2fe6268 100644--- a/desktop/macos/Runner/Info.plist+++ b/desktop/macos/Runner/Info.plist@@ -65,5 +65,11 @@</dict></dict></dict>+ <key>NSLocalNetworkUsageDescription</key>+ <string>Harness finds and connects to Autonomous robots on your local network.</string>+ <key>NSBonjourServices</key>+ <array>+ <string>_autonomous._tcp</string>+ </array></dict></plist>diff --git a/desktop/test/autonomous_device_pairing_test.dart b/desktop/test/autonomous_device_pairing_test.dartindex 0731d2c13..f3fe61a96 100644--- a/desktop/test/autonomous_device_pairing_test.dart+++ b/desktop/test/autonomous_device_pairing_test.dart@@ -14,6 +14,7 @@ class FakeAutonomousDeviceCli extends AutonomousDeviceCli {int statusCalls = 0;Completer<void>? statusWait;String? pairFailure;+ bool networkBlocked = false;List<Map<String, dynamic>> discovered = [{'id': 'device-1', 'name': 'Kitchen', 'host': '192.168.1.2', 'port': 5000},];@@ -33,7 +34,16 @@ class FakeAutonomousDeviceCli extends AutonomousDeviceCli {@overrideFuture<Map<String, dynamic>> list() async => {'devices': devices};@override- Future<Map<String, dynamic>> discover() async => {'devices': discovered};+ Future<Map<String, dynamic>> discover() async {+ if (networkBlocked) {+ throw const AutonomousDeviceCliException(+ 'LOCAL_NETWORK_BLOCKED',+ 'Harness is not allowed to use the local network.',+ );+ }+ return {'devices': discovered};+ }+@overrideFuture<Map<String, dynamic>> pair({required String code,@@ -118,6 +128,32 @@ void main() {expect(find.text('Cancel pairing'), findsNothing);},);+ testWidgets(+ 'a blocked local network says where to allow it and keeps paired robots listed',+ (tester) async {+ final cli = FakeAutonomousDeviceCli()+ ..networkBlocked = true+ ..devices = [+ {+ 'id': 'fingerprint-1',+ 'fingerprint': 'fingerprint-1',+ 'label': 'Desk lamp',+ 'online': false,+ },+ ];+ await open(tester, cli);+ final notice = find.byKey(const Key('autonomous-device-network-blocked'));+ expect(notice, findsOneWidget);+ expect(find.text('Allow Harness on your local network'), findsOneWidget);+ expect(find.text('Desk lamp'), findsOneWidget);+ expect(find.textContaining('No Autonomous robots found'), findsNothing);++ cli.networkBlocked = false;+ await refresh(tester);+ expect(notice, findsNothing);+ expect(find.text('Desk lamp'), findsOneWidget);+ },+ );testWidgets('pairing controls align with the title and explain persistence', (tester,) async {diff --git a/docs/autonomous-device-integration.md b/docs/autonomous-device-integration.mdindex 673388a24..cc38fda46 100644--- a/docs/autonomous-device-integration.md+++ b/docs/autonomous-device-integration.md@@ -65,7 +65,7 @@ All routes remain on the credential-checked loopback hook server. There is no ne| Route | Input/result ||---|---|-| GET `/api/autonomous-device/discover` | `{devices:[{id,name,host,port}]}` discovered candidates |+| GET `/api/autonomous-device/discover` | `{devices:[{id,name,host,port}]}` discovered candidates; 503 `LOCAL_NETWORK_BLOCKED` when the OS refused the multicast query and nothing answered (macOS Local Network privacy) || POST `/api/autonomous-device/pair/start` | `{code,device:<discovery-id>}` → `{state:"paired",label,fingerprint}` || GET `/api/autonomous-device/pair/status` | existing pending device status idle/waiting/running || GET `/api/autonomous-device/status` | `{transport:"direct",connected,paired,sessions,proto:1}`; connected/sessions count authenticated application-ready direct sessions only |