Extend wave-agent with host-mode for Local Agent layer (Protocol Plane)

[yakimoto]

Proposal: extend wave-agent for the Local Agent layer (workstation mode)

The newly-shipped Protocol Plane framework (wave-foundation PR #144) describes a 4-layer architecture where one of the layers is a Local Agent daemon on customer workstations that bridges LAN-local mDNS-discovered NDI/Dante sources to the WAVE cloud.

This repo (wave-agent) is the natural home for that capability, in addition to its current scope (embedded device firmware on WAVE-Certified hardware).

Two operational modes (proposal)

Mode	Runs on	Purpose	Trigger
device-mode (today)	WAVE-Certified hardware boxes (encoders, decoders, OB-van rack stacks)	Identity, lifecycle, OTA, telemetry	embedded build, runs as PID-1 or systemd-required service
host-mode (proposed new)	macOS / Windows / Linux workstations in studio LANs	LAN-local mDNS NDI/Dante discovery, registration with gateway, bidirectional bridging	brew/MSI/deb install, runs as LaunchAgent / Windows Service / systemd user unit

Same Go binary, different config — selected via --mode device or --mode host.

Host-mode features (new code)

1. mDNS discovery — continuously listens for _ndi._tcp and _netaudio._udp service advertisements on the local LAN
2. Source registration — POST discovered sources to gateway with stable URIs (ndi://<customer>.wave.online/<source-id>); refresh every 30s
3. Bridging —
   • Outbound: when gateway routes a request for one of our registered sources, agent forwards the L2/UDP traffic via an encrypted tunnel
   • Inbound: when a cloud-side wave-bridge-edge container needs to emit a stream as a local NDI/Dante source, agent re-emits it on the LAN
4. Auth — device-binding token, 24h rotating, stored in keychain (macOS) / credstore (Windows) / libsecret (Linux)
5. UI — system tray app showing current bridged sources + connection status; reuse the existing embedded web UI for the dashboard

Why both modes in one binary

• Same identity model, same OTA flow (host-mode auto-update like a normal app), same cloud connector
• Code sharing: device-mode and host-mode both have to authenticate to the gateway, both report telemetry, both need to be reachable for remote control
• One thing for partners + customers to install regardless of context

Linked

• Protocol Plane framework: wave-foundation/frameworks/protocol-plane/README.md (PR #144)
• wave-bridge-edge: https://github.com/wave-av/wave-bridge-edge — the cloud-side counterpart that talks to the Local Agent
• Strategic roadmap update: wave-foundation #95 (2026-05-30 comment)

Filing this so the design choice is captured before the host-mode work starts. Either: (a) extend this repo with a cmd/host/ entry point + shared internal packages; (b) split into wave-agent-device + wave-agent-host if the surfaces drift too far. (a) is preferred per single-binary-install argument.