Add iOS device runner support and document platform matrix

Author: thymikee

README.md

@@ -13,7 +13,7 @@ CLI to control iOS and Android devices for AI agents influenced by Vercel’s [a
 The project is in early development and considered experimental. Pull requests are welcome!
 
 ## Features
-- Platforms: iOS (simulator + limited device support) and Android (emulator + device).
+- Platforms: iOS (simulator + physical device core automation) and Android (emulator + device).
 - Core commands: `open`, `back`, `home`, `app-switcher`, `press`, `long-press`, `focus`, `type`, `fill`, `scroll`, `scrollintoview`, `wait`, `alert`, `screenshot`, `close`, `reinstall`.
 - Inspection commands: `snapshot` (accessibility tree).
 - Device tooling: `adb` (Android), `simctl`/`devicectl` (iOS via Xcode).
@@ -91,9 +91,10 @@ Coordinates:
 | `ax` | Fast | Medium | Accessibility permission for the terminal app, not recommended |
 
 Notes:
-- Default backend is `xctest` on iOS.
+- Default backend is `xctest` on iOS simulators and iOS devices.
 - Scope snapshots with `-s "<label>"` or `-s @ref`.
-- If XCTest returns 0 nodes (e.g., foreground app changed), agent-device falls back to AX when available.
+- If XCTest returns 0 nodes (e.g., foreground app changed), agent-device falls back to AX on simulators when available.
+- `ax` backend is simulator-only.
 
 Flags:
 - `--version, -V` print version and exit
@@ -184,14 +185,14 @@ Android fill reliability:
 - If value does not match, agent-device clears the field and retries once with slower typing.
 - This reduces IME-related character swaps on long strings (e.g. emails and IDs).
 
-Settings helpers (simulators):
+Settings helpers:
 - `settings wifi on|off`
 - `settings airplane on|off`
 - `settings location on|off` (iOS uses per-app permission for the current session app)
-Note: iOS wifi/airplane toggles status bar indicators, not actual network state. Airplane off clears status bar overrides.
+Note: iOS supports these only on simulators in v1. iOS wifi/airplane toggles status bar indicators, not actual network state. Airplane off clears status bar overrides.
 
 App state:
-- `appstate` shows the foreground app/activity (Android). On iOS it uses the current session app when available, otherwise it falls back to a snapshot-based guess (AX first, XCTest if AX can’t identify).
+- `appstate` shows the foreground app/activity (Android). On iOS it uses the current session app when available, otherwise it falls back to a snapshot-based guess (`xctest` on devices; AX-first on simulators with XCTest fallback).
 - `apps --metadata` returns app list with minimal metadata.
 
 ## Debug
@@ -215,9 +216,10 @@ Boot diagnostics:
 - Built-in aliases include `Settings` for both platforms.
 
 ## iOS notes
-- Input commands (`press`, `type`, `scroll`, etc.) are supported only on simulators in v1 and use the XCTest runner.
-- `alert` and `scrollintoview` use the XCTest runner and are simulator-only in v1.
-- Real device support (including snapshots) is on the roadmap for iOS.
+- Core runner commands (`snapshot`, `wait`, `click`, `fill`, `get`, `is`, `find`, `press`, `long-press`, `focus`, `type`, `scroll`, `scrollintoview`, `back`, `home`, `app-switcher`) support iOS simulators and iOS devices.
+- Simulator-only commands in v1: `alert`, `pinch`, `record`, `reinstall`, `apps`, `settings`.
+- iOS deep link open (`open <url>`) is simulator-only in v1.
+- iOS device runs require valid signing/provisioning (Automatic Signing recommended). Optional overrides: `AGENT_DEVICE_IOS_TEAM_ID`, `AGENT_DEVICE_IOS_SIGNING_IDENTITY`, `AGENT_DEVICE_IOS_PROVISIONING_PROFILE`.
 
 ## Testing
 
@@ -243,6 +245,10 @@ Environment selectors:
 - `ANDROID_DEVICE=Pixel_9_Pro_XL` or `ANDROID_SERIAL=emulator-5554`
 - `IOS_DEVICE="iPhone 17 Pro"` or `IOS_UDID=<udid>`
 - `AGENT_DEVICE_IOS_BOOT_TIMEOUT_MS=<ms>` to adjust iOS simulator boot timeout (default: `120000`, minimum: `5000`).
+- `AGENT_DEVICE_DAEMON_TIMEOUT_MS=<ms>` to increase daemon request timeout for slow first-run iOS device setup (for example `180000`).
+- `AGENT_DEVICE_IOS_TEAM_ID=<team-id>` optional Team ID override for iOS device runner signing.
+- `AGENT_DEVICE_IOS_SIGNING_IDENTITY=<identity>` optional signing identity override (defaults to `Apple Development` when signing overrides are used).
+- `AGENT_DEVICE_IOS_PROVISIONING_PROFILE=<profile>` optional provisioning profile specifier for iOS device runner signing.
 
 Test screenshots are written to:
 - `test/screenshots/android-settings.png`

skills/agent-device/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: agent-device
-description: Automates mobile and simulator interactions for iOS and Android devices. Use when navigating apps, taking snapshots/screenshots, tapping, typing, scrolling, pinching, or extracting UI info on mobile devices or simulators.
+description: Automates interactions for iOS simulators/devices and Android emulators/devices. Use when navigating apps, taking snapshots/screenshots, tapping, typing, scrolling, or extracting UI info on mobile targets.
 ---
 
 # Mobile Automation with agent-device
@@ -39,13 +39,13 @@ npx -y agent-device
 
 ```bash
 agent-device boot                 # Ensure target is booted/ready without opening app
-agent-device boot --platform ios  # Boot iOS simulator
+agent-device boot --platform ios  # Boot iOS simulator/device target
 agent-device boot --platform android # Boot Android emulator/device target
 agent-device open [app|url]       # Boot device/simulator; optionally launch app or deep link URL
 agent-device open [app] --relaunch # Terminate app process first, then launch (fresh runtime)
 agent-device open [app] --activity com.example/.MainActivity # Android: open specific activity (app targets only)
 agent-device open "myapp://home" --platform android          # Android deep link
-agent-device open "https://example.com" --platform ios       # iOS simulator deep link
+agent-device open "https://example.com" --platform ios       # iOS simulator deep link (device unsupported in v1)
 agent-device close [app]          # Close app or just end session
 agent-device reinstall <app> <path> # Uninstall + install app in one command
 agent-device session list         # List active sessions
@@ -82,7 +82,7 @@ agent-device find "Settings" wait 10000
 agent-device find "Settings" exists
 ```
 
-### Settings helpers (simulators)
+### Settings helpers
 
 ```bash
 agent-device settings wifi on
@@ -95,6 +95,7 @@ agent-device settings location off
 
 Note: iOS wifi/airplane toggles status bar indicators, not actual network state.
 Airplane off clears status bar overrides.
+iOS settings helpers are simulator-only in v1.
 
 ### App state
 
@@ -114,7 +115,7 @@ agent-device type "text"               # Type into focused field without clearin
 agent-device press 300 500             # Tap by coordinates
 agent-device long-press 300 500 800    # Long press (where supported)
 agent-device scroll down 0.5
-agent-device pinch 2.0              # Zoom in 2x (iOS simulator + Android)
+agent-device pinch 2.0              # Zoom in 2x (iOS simulator only)
 agent-device pinch 0.5 200 400     # Zoom out at coordinates
 agent-device back
 agent-device home
@@ -167,19 +168,21 @@ agent-device apps --platform android --user-installed
 
 ## Best practices
 
-- Pinch (`pinch <scale> [x y]`) is supported on iOS simulators and Android; scale > 1 zooms in, < 1 zooms out. On Android, pinch uses multi-touch `sendevent` injection.
+- Pinch (`pinch <scale> [x y]`) is iOS simulator-only in v1; scale > 1 zooms in, < 1 zooms out.
 - Snapshot refs are the core mechanism for interactive agent flows.
 - Use selectors for deterministic replay artifacts and assertions (e.g. in e2e test workflows).
 - Prefer `snapshot -i` to reduce output size.
 - On iOS, `xctest` is the default and does not require Accessibility permission.
-- If XCTest returns 0 nodes (foreground app changed), agent-device falls back to AX when available.
+- If XCTest returns 0 nodes (foreground app changed), agent-device falls back to AX on simulators when available.
 - `open <app|url>` can be used within an existing session to switch apps or open deep links.
 - `open <app>` updates session app bundle context; URL opens do not set an app bundle id.
 - Use `open <app> --relaunch` during React Native/Fast Refresh debugging when you need a fresh app process without ending the session.
 - If AX returns the Simulator window or empty tree, restart Simulator or use `--backend xctest`.
 - Use `--session <name>` for parallel sessions; avoid device contention.
 - Use `--activity <component>` on Android to launch a specific activity (e.g. TV apps with LEANBACK); do not combine with URL opens.
 - iOS deep-link opens are simulator-only in v1.
+- iOS physical-device runner requires Xcode signing/provisioning; optional overrides: `AGENT_DEVICE_IOS_TEAM_ID`, `AGENT_DEVICE_IOS_SIGNING_IDENTITY`, `AGENT_DEVICE_IOS_PROVISIONING_PROFILE`.
+- For long first-run physical-device setup/build, increase daemon timeout: `AGENT_DEVICE_DAEMON_TIMEOUT_MS=180000` (or higher).
 - Use `fill` when you want clear-then-type semantics.
 - Use `type` when you want to append/enter text without clearing.
 - On Android, prefer `fill` for important fields; it verifies entered text and retries once when IME reorders characters.

skills/agent-device/references/permissions.md

@@ -13,6 +13,20 @@ agent-device snapshot --backend xctest --platform ios
 ```
 
 Hybrid/AX is fast; XCTest is equally fast but does not require permissions.
+AX backend is simulator-only in v1.
+
+## iOS physical device runner
+
+For iOS physical devices, XCTest runner setup requires valid signing/provisioning.
+Use Automatic Signing in Xcode, or provide optional overrides:
+
+- `AGENT_DEVICE_IOS_TEAM_ID`
+- `AGENT_DEVICE_IOS_SIGNING_IDENTITY`
+- `AGENT_DEVICE_IOS_PROVISIONING_PROFILE`
+
+If first-run setup/build takes long, increase:
+
+- `AGENT_DEVICE_DAEMON_TIMEOUT_MS` (for example `180000`)
 
 ## Simulator troubleshooting
 

skills/agent-device/references/session-management.md

@@ -14,6 +14,7 @@ Sessions isolate device context. A device can only be held by one session at a t
 - Name sessions semantically.
 - Close sessions when done.
 - Use separate sessions for parallel work.
+- In iOS sessions, use `open <app>` for simulator/device. `open <url>` is simulator-only in v1.
 - For dev loops where runtime state can persist (for example React Native Fast Refresh), use `open <app> --relaunch` to restart the app process in the same session.
 - For deterministic replay scripts, prefer selector-based actions and assertions.
 - Use `replay -u` to update selector drift during maintenance.

skills/agent-device/references/snapshot-refs.md

@@ -55,6 +55,7 @@ agent-device snapshot -i -s @e3
 - Ref not found: re-snapshot.
 - AX returns Simulator window: restart Simulator and re-run.
 - AX empty: verify Accessibility permission or use `--backend xctest` (XCTest is more complete).
+- AX backend is simulator-only in v1; use `--backend xctest` on iOS devices.
 
 ## Replay note
 

skills/agent-device/references/video-recording.md

@@ -20,6 +20,8 @@ agent-device close
 agent-device record stop
 ```
 
+`record` is iOS simulator-only in v1.
+
 ## Android Emulator/Device
 
 Use `agent-device record` commands (wrapper around adb):

src/core/__tests__/capabilities.test.ts

@@ -32,10 +32,17 @@ test('iOS simulator-only commands reject iOS devices and Android', () => {
   }
 });
 
-test('iOS simulator + Android commands reject iOS devices', () => {
+test('simulator-only iOS commands with Android support reject iOS devices', () => {
+  for (const cmd of ['apps', 'reinstall', 'record', 'settings']) {
+    assert.equal(isCommandSupportedOnDevice(cmd, iosSimulator), true, `${cmd} on iOS sim`);
+    assert.equal(isCommandSupportedOnDevice(cmd, iosDevice), false, `${cmd} on iOS device`);
+    assert.equal(isCommandSupportedOnDevice(cmd, androidDevice), true, `${cmd} on Android`);
+  }
+});
+
+test('core commands support iOS simulator, iOS device, and Android', () => {
   for (const cmd of [
     'app-switcher',
-    'apps',
     'back',
     'boot',
     'click',
@@ -47,18 +54,16 @@ test('iOS simulator + Android commands reject iOS devices', () => {
     'home',
     'long-press',
     'open',
-    'reinstall',
     'press',
-    'record',
     'screenshot',
     'scroll',
-    'settings',
+    'scrollintoview',
     'snapshot',
     'type',
     'wait',
   ]) {
     assert.equal(isCommandSupportedOnDevice(cmd, iosSimulator), true, `${cmd} on iOS sim`);
-    assert.equal(isCommandSupportedOnDevice(cmd, iosDevice), false, `${cmd} on iOS device`);
+    assert.equal(isCommandSupportedOnDevice(cmd, iosDevice), true, `${cmd} on iOS device`);
     assert.equal(isCommandSupportedOnDevice(cmd, androidDevice), true, `${cmd} on Android`);
   }
 });

src/core/capabilities.ts

@@ -16,29 +16,30 @@ const COMMAND_CAPABILITY_MATRIX: Record<string, CommandCapability> = {
   // iOS simulator-only in v1.
   alert: { ios: { simulator: true }, android: {} },
   pinch: { ios: { simulator: true }, android: {} },
-  'app-switcher': { ios: { simulator: true }, android: { emulator: true, device: true, unknown: true } },
+  'app-switcher': { ios: { simulator: true, device: true }, android: { emulator: true, device: true, unknown: true } },
   apps: { ios: { simulator: true }, android: { emulator: true, device: true, unknown: true } },
-  back: { ios: { simulator: true }, android: { emulator: true, device: true, unknown: true } },
-  boot: { ios: { simulator: true }, android: { emulator: true, device: true, unknown: true } },
-  click: { ios: { simulator: true }, android: { emulator: true, device: true, unknown: true } },
-  close: { ios: { simulator: true }, android: { emulator: true, device: true, unknown: true } },
-  fill: { ios: { simulator: true }, android: { emulator: true, device: true, unknown: true } },
-  find: { ios: { simulator: true }, android: { emulator: true, device: true, unknown: true } },
-  focus: { ios: { simulator: true }, android: { emulator: true, device: true, unknown: true } },
-  get: { ios: { simulator: true }, android: { emulator: true, device: true, unknown: true } },
-  is: { ios: { simulator: true }, android: { emulator: true, device: true, unknown: true } },
-  home: { ios: { simulator: true }, android: { emulator: true, device: true, unknown: true } },
-  'long-press': { ios: { simulator: true }, android: { emulator: true, device: true, unknown: true } },
-  open: { ios: { simulator: true }, android: { emulator: true, device: true, unknown: true } },
+  back: { ios: { simulator: true, device: true }, android: { emulator: true, device: true, unknown: true } },
+  boot: { ios: { simulator: true, device: true }, android: { emulator: true, device: true, unknown: true } },
+  click: { ios: { simulator: true, device: true }, android: { emulator: true, device: true, unknown: true } },
+  close: { ios: { simulator: true, device: true }, android: { emulator: true, device: true, unknown: true } },
+  fill: { ios: { simulator: true, device: true }, android: { emulator: true, device: true, unknown: true } },
+  find: { ios: { simulator: true, device: true }, android: { emulator: true, device: true, unknown: true } },
+  focus: { ios: { simulator: true, device: true }, android: { emulator: true, device: true, unknown: true } },
+  get: { ios: { simulator: true, device: true }, android: { emulator: true, device: true, unknown: true } },
+  is: { ios: { simulator: true, device: true }, android: { emulator: true, device: true, unknown: true } },
+  home: { ios: { simulator: true, device: true }, android: { emulator: true, device: true, unknown: true } },
+  'long-press': { ios: { simulator: true, device: true }, android: { emulator: true, device: true, unknown: true } },
+  open: { ios: { simulator: true, device: true }, android: { emulator: true, device: true, unknown: true } },
   reinstall: { ios: { simulator: true }, android: { emulator: true, device: true, unknown: true } },
-  press: { ios: { simulator: true }, android: { emulator: true, device: true, unknown: true } },
+  press: { ios: { simulator: true, device: true }, android: { emulator: true, device: true, unknown: true } },
   record: { ios: { simulator: true }, android: { emulator: true, device: true, unknown: true } },
-  screenshot: { ios: { simulator: true }, android: { emulator: true, device: true, unknown: true } },
-  scroll: { ios: { simulator: true }, android: { emulator: true, device: true, unknown: true } },
+  screenshot: { ios: { simulator: true, device: true }, android: { emulator: true, device: true, unknown: true } },
+  scroll: { ios: { simulator: true, device: true }, android: { emulator: true, device: true, unknown: true } },
+  scrollintoview: { ios: { simulator: true, device: true }, android: { emulator: true, device: true, unknown: true } },
   settings: { ios: { simulator: true }, android: { emulator: true, device: true, unknown: true } },
-  snapshot: { ios: { simulator: true }, android: { emulator: true, device: true, unknown: true } },
-  type: { ios: { simulator: true }, android: { emulator: true, device: true, unknown: true } },
-  wait: { ios: { simulator: true }, android: { emulator: true, device: true, unknown: true } },
+  snapshot: { ios: { simulator: true, device: true }, android: { emulator: true, device: true, unknown: true } },
+  type: { ios: { simulator: true, device: true }, android: { emulator: true, device: true, unknown: true } },
+  wait: { ios: { simulator: true, device: true }, android: { emulator: true, device: true, unknown: true } },
 };
 
 export function isCommandSupportedOnDevice(command: string, device: DeviceInfo): boolean {

src/core/dispatch.ts

@@ -239,6 +239,12 @@ export async function dispatchCommand(
     case 'snapshot': {
       const backend = context?.snapshotBackend ?? 'xctest';
       if (device.platform === 'ios') {
+        if (backend === 'ax' && device.kind !== 'simulator') {
+          throw new AppError(
+            'UNSUPPORTED_OPERATION',
+            'AX snapshot backend is not supported on iOS physical devices; use --backend xctest',
+          );
+        }
         if (backend === 'ax') {
           const ax = await snapshotAx(device, { traceLogPath: context?.traceLogPath });
           return { nodes: ax.nodes ?? [], truncated: false, backend: 'ax' };
@@ -257,7 +263,7 @@ export async function dispatchCommand(
           { verbose: context?.verbose, logPath: context?.logPath, traceLogPath: context?.traceLogPath },
         )) as { nodes?: RawSnapshotNode[]; truncated?: boolean };
         const nodes = result.nodes ?? [];
-        if (nodes.length === 0) {
+        if (nodes.length === 0 && device.kind === 'simulator') {
           try {
             const ax = await snapshotAx(device, { traceLogPath: context?.traceLogPath });
             return { nodes: ax.nodes ?? [], truncated: false, backend: 'ax' };

src/daemon.ts

@@ -175,7 +175,7 @@ function start(): void {
   const shutdown = async () => {
     const sessionsToStop = sessionStore.toArray();
     for (const session of sessionsToStop) {
-      if (session.device.platform === 'ios' && session.device.kind === 'simulator') {
+      if (session.device.platform === 'ios') {
         await stopIosRunnerSession(session.device.id);
       }
       sessionStore.writeSessionLog(session);