Skip to content

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.

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.ts
new file mode 100644
index 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.ts
index 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.host
if (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.ts
index 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.ts
index 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.dart
index 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);
@override
diff --git a/desktop/lib/settings/sections/devices_section.dart b/desktop/lib/settings/sections/devices_section.dart
index 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.plist
index 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.dart
index 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 {
@override
Future<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};
+ }
+
@override
Future<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.md
index 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 |