feat(ios): add MOBILECLI_IOS_AGENT_URL to use an already running agent, including over the Wi-Fi CoreDevice tunnel

README.md

@@ -513,6 +513,23 @@ The CLI and daemon talk JSON-RPC over a unix domain socket in `~/.mobilecli/` (o
 
 On Android, the daemon keeps a small server running on the device (`com.mobilenext.mobilecli.DeviceServer`) that holds the device's only UiAutomation connection, so other UiAutomator clients such as `uiautomator dump` or Appium cannot run alongside it. The daemon stops that server when it exits, so `mobilecli daemon stop` hands the device back to other tools; the server also exits by itself after 30 minutes without requests (`MOBILECLI_DEVICE_SERVER_IDLE_TIMEOUT=5m` shortens that).
 
+On a real iOS device, the daemon launches the on-device agent itself and reaches it through a tunnel (iOS 17+) and a port forward. If the agent is already running and reachable another way, set `MOBILECLI_IOS_AGENT_URL` to its URL and the daemon uses that agent as is, without launching it or starting a tunnel or forward for it. Commands that do not go through the agent (apps, logs, crashes, AVC streaming) are unchanged.
+
+The variable takes either a bare URL, which mobilecli accepts only while exactly one real iOS device is connected, or a comma-separated list of `<udid>=<url>` pairs such as `00008101-00161CEC3CDB001E=http://[fd34:13d9:5468::1]:12004,00008110-001A2B3C4D5E001E=http://localhost:8100`. With a list, each device uses only its own entry and a device without one is reached the usual way. The agent cannot report which device it runs on, so the mapping is what binds a device to its agent. The URL cannot have a query, a fragment, or a user name and password. The agent serves plain HTTP with no authentication, so point the variable at loopback (a USB forward) or at the CoreDevice tunnel address below, not at the device's local network address. The daemon reads the variable when it starts, so run `mobilecli daemon stop` after changing it.
+
+For a device paired over Wi-Fi, the agent can listen on the Xcode CoreDevice tunnel address (devicekit-ios `DEVICEKIT_LISTEN_HOST`), which only the paired Mac can reach:
+
+```bash
+UDID=<udid>
+TUNNEL=$(xcrun devicectl device info details --device $UDID --json-output - | jq -r '.result.connectionProperties.tunnelIPAddress')
+# in the devicekit-ios checkout, after building the runner for the device once
+TEST_RUNNER_DEVICEKIT_LISTEN_HOST="127.0.0.1,$TUNNEL" xcodebuild test-without-building \
+  -project devicekit-ios.xcodeproj -scheme devicekit-ios -destination "id=$UDID" -collect-test-diagnostics never &
+MOBILECLI_IOS_AGENT_URL="$UDID=http://[$TUNNEL]:12004" mobilecli --device $UDID device info
+```
+
+The tunnel address can change when the tunnel reconnects, so read it right before launching the runner. With USB, the same variable works with a forward instead, for example `iproxy 8100 12004` and `MOBILECLI_IOS_AGENT_URL=http://localhost:8100`.
+
 ## HTTP API 🔌
 
 ***mobilecli*** provides an http interface for all the functionality that is available through command line. The server is a thin front for the daemon above, so HTTP clients and the CLI share one set of devices and tunnels.

devices/common.go

@@ -82,7 +82,12 @@ const (
 )
 
 func buildMjpegURL(port, fps int, scale float64) string {
-	url := fmt.Sprintf("http://localhost:%d/mjpeg", port)
+	return buildMjpegURLForAgent(fmt.Sprintf("http://localhost:%d", port), fps, scale)
+}
+
+// buildMjpegURLForAgent builds the mjpeg URL served by the agent at baseURL.
+func buildMjpegURLForAgent(baseURL string, fps int, scale float64) string {
+	url := baseURL + "/mjpeg"
 	sep := "?"
 	if fps > 0 {
 		url += fmt.Sprintf("%sfps=%d", sep, fps)

devices/devicekit/types.go

@@ -31,6 +31,11 @@ func NewDeviceKitClient(hostPort string) *DeviceKitClient {
 	}
 }
 
+// BaseURL returns the agent URL this client talks to, without a trailing slash.
+func (c *DeviceKitClient) BaseURL() string {
+	return c.baseURL
+}
+
 // Port returns the port this client talks to, parsed from its base URL.
 func (c *DeviceKitClient) Port() int {
 	parsed, err := url.Parse(c.baseURL)

devices/ios.go

@@ -500,6 +500,14 @@ func (d *IOSDevice) StartAgent(config StartAgentConfig) error {
 	// 6. we need to wait for the agent to be ready ✅
 	// 7. just in case, click HOME button ✅
 
+	agentURL, err := iosAgentURLOverride(d.Udid)
+	if err != nil {
+		return err
+	}
+	if agentURL != "" {
+		return d.useExternalAgent(agentURL)
+	}
+
 	if _, err := d.deviceKitClient.GetStatus(); err == nil {
 		return nil
 	}
@@ -1149,8 +1157,7 @@ func (d *IOSDevice) StartScreenCapture(config ScreenCaptureConfig) error {
 
 	// mjpeg is served on the same port as the agent HTTP server at /mjpeg
 	d.mu.Lock()
-	wdaPort := d.deviceKitClient.Port()
-	mjpegURL := buildMjpegURL(wdaPort, config.FPS, config.Scale)
+	mjpegURL := buildMjpegURLForAgent(d.deviceKitClient.BaseURL(), config.FPS, config.Scale)
 	d.mjpegClient = mjpeg.NewDeviceKitMjpegClient(mjpegURL)
 	d.mu.Unlock()
 

devices/ios_agent_url.go

@@ -0,0 +1,149 @@
+package devices
+
+import (
+	"fmt"
+	"net/url"
+	"os"
+	"strings"
+
+	goios "github.com/danielpaulus/go-ios/ios"
+	"github.com/mobile-next/mobilecli/devices/devicekit"
+)
+
+// iosAgentURLEnv points real iOS devices at a DeviceKit agent that is already
+// running and reachable at that URL (e.g. "http://localhost:8100", or the Xcode
+// CoreDevice tunnel address of a Wi-Fi paired device such as
+// "http://[fd34:13d9:5468::1]:12004"). When set, mobilecli neither launches the
+// agent nor starts a tunnel or port forward to reach it. Calls that do not go
+// through the agent (apps, logs, crashes) are unchanged.
+//
+// The value is either a comma-separated list of <udid>=<url> pairs, where each
+// device uses only its own entry and a device without one takes the normal
+// tunnel path, or a bare URL, which is accepted only while exactly one real iOS
+// device is connected. The agent cannot confirm which device it runs on
+// (device.info returns only the screen size and scale), so the device is bound
+// to the agent by this mapping alone.
+const iosAgentURLEnv = "MOBILECLI_IOS_AGENT_URL"
+
+// countConnectedIOSDevices returns how many distinct real iOS devices usbmuxd
+// reports. It only asks usbmuxd for its list, without opening a lockdown
+// session per device as ListIOSDevices does. Tests replace it.
+var countConnectedIOSDevices = func() (int, error) {
+	deviceList, err := goios.ListDevices()
+	if err != nil {
+		return 0, fmt.Errorf("failed getting device list: %w", err)
+	}
+
+	// go-ios returns one entry per connection (usb, network), count by udid
+	seen := make(map[string]bool)
+	for _, deviceEntry := range deviceList.DeviceList {
+		seen[deviceEntry.Properties.SerialNumber] = true
+	}
+	return len(seen), nil
+}
+
+// iosAgentURLOverride returns the agent URL that iosAgentURLEnv sets for the
+// device with this udid, or "" when the device should take the normal path.
+func iosAgentURLOverride(udid string) (string, error) {
+	value := strings.TrimSpace(os.Getenv(iosAgentURLEnv))
+	if value == "" {
+		return "", nil
+	}
+
+	// a bare URL may have '=' or ',' in its path, so classify it before
+	// treating those characters as mapping separators
+	if isBareAgentURL(value) || !strings.ContainsAny(value, "=,") {
+		return bareAgentURL(value)
+	}
+
+	agentURLs, err := parseAgentURLMapping(value)
+	if err != nil {
+		return "", err
+	}
+	return agentURLs[strings.ToUpper(udid)], nil
+}
+
+// isBareAgentURL reports whether value parses as a single http(s) URL with a
+// host. A <udid>=<url> mapping never does: '=' cannot appear in a URL scheme.
+func isBareAgentURL(value string) bool {
+	parsed, err := url.Parse(value)
+	return err == nil && (parsed.Scheme == "http" || parsed.Scheme == "https") && parsed.Host != ""
+}
+
+// bareAgentURL accepts a URL without a udid only when it cannot reach the
+// wrong device, that is with a single real iOS device connected.
+func bareAgentURL(value string) (string, error) {
+	agentURL, err := parseAgentURL(value)
+	if err != nil {
+		return "", err
+	}
+
+	count, err := countConnectedIOSDevices()
+	if err != nil {
+		return "", err
+	}
+	if count != 1 {
+		return "", fmt.Errorf("%s holds a single URL, which needs exactly one connected iOS device but found %d, use <udid>=<url> to say which device runs the agent", iosAgentURLEnv, count)
+	}
+
+	return agentURL, nil
+}
+
+// parseAgentURLMapping parses "<udid>=<url>,<udid>=<url>" into URLs keyed by
+// upper-case udid.
+func parseAgentURLMapping(value string) (map[string]string, error) {
+	agentURLs := make(map[string]string)
+	for _, entry := range strings.Split(value, ",") {
+		udid, rawURL, found := strings.Cut(strings.TrimSpace(entry), "=")
+		udid = strings.TrimSpace(udid)
+		rawURL = strings.TrimSpace(rawURL)
+		if !found || udid == "" || rawURL == "" || strings.ContainsAny(udid, ":/") {
+			return nil, fmt.Errorf("%s has a malformed entry %q, expected <udid>=<url> such as 00008101-00161CEC3CDB001E=http://localhost:8100 (agent URLs cannot have a query)", iosAgentURLEnv, entry)
+		}
+
+		key := strings.ToUpper(udid)
+		if _, duplicate := agentURLs[key]; duplicate {
+			return nil, fmt.Errorf("%s lists device %s more than once", iosAgentURLEnv, udid)
+		}
+
+		agentURL, err := parseAgentURL(rawURL)
+		if err != nil {
+			return nil, err
+		}
+		agentURLs[key] = agentURL
+	}
+	return agentURLs, nil
+}
+
+// parseAgentURL checks that value can serve as the base of agent requests,
+// which append /health, /rpc and /mjpeg to it.
+func parseAgentURL(value string) (string, error) {
+	parsed, err := url.Parse(value)
+	if err != nil || (parsed.Scheme != "http" && parsed.Scheme != "https") || parsed.Host == "" {
+		return "", fmt.Errorf("%s=%q is not a valid agent URL, expected something like http://localhost:8100", iosAgentURLEnv, value)
+	}
+	if parsed.RawQuery != "" || parsed.ForceQuery || parsed.Fragment != "" || strings.Contains(value, "#") {
+		return "", fmt.Errorf("%s=%q is not a valid agent URL, it cannot have a query or fragment", iosAgentURLEnv, value)
+	}
+	// the agent has no authentication, so credentials would only travel in the clear
+	if parsed.User != nil {
+		return "", fmt.Errorf("%s=%q is not a valid agent URL, it cannot carry a user name or password", iosAgentURLEnv, value)
+	}
+
+	return strings.TrimSuffix(value, "/"), nil
+}
+
+// useExternalAgent switches the device to the agent at agentURL and checks that
+// it answers. It never launches the agent or sets up a tunnel or forward.
+func (d *IOSDevice) useExternalAgent(agentURL string) error {
+	client := devicekit.NewDeviceKitClient(agentURL)
+	if _, err := client.GetStatus(); err != nil {
+		return fmt.Errorf("no agent answering at %s (from %s): %w", agentURL, iosAgentURLEnv, err)
+	}
+
+	d.mu.Lock()
+	d.deviceKitClient = client
+	d.mu.Unlock()
+
+	return nil
+}