refactor: unify apple target handling and tvOS capability gates

Author: thymikee

README.md

@@ -168,6 +168,7 @@ agent-device push com.example.app '{"action":"com.example.app.PUSH","extras":{"t
 
 Payload notes:
 - iOS uses `xcrun simctl push <device> <bundle> <payload>` and requires APNs-style JSON object (for example `{"aps":{"alert":"..."}}`).
+- tvOS is not supported for `push`.
 - Android uses `adb shell am broadcast` with payload JSON shape:
   `{"action":"<intent-action>","receiver":"<optional component>","extras":{"key":"value","flag":true,"count":3}}`.
 - Android extras support string/boolean/number values.
@@ -222,6 +223,7 @@ TV targets:
 - AndroidTV app launch/app listing use TV launcher discovery (`LEANBACK_LAUNCHER`) and fallback component resolution when needed.
 - tvOS uses the same runner-driven interaction/snapshot flow as iOS (`snapshot`, `wait`, `press`, `fill`, `get`, `scroll`, `back`, `home`, `app-switcher`, `record`, and related selector flows).
 - tvOS back/home/app-switcher use Siri Remote semantics in the runner (`menu`, `home`, double-home).
+- tvOS does not support iOS simulator-only helpers `pinch`, `settings`, or `push`.
 
 Examples:
 - `agent-device open YouTube --platform android --target tv`
@@ -230,7 +232,7 @@ Examples:
 - `agent-device screenshot ./apple-tv.png --platform ios --target tv`
 
 Pinch:
-- `pinch` is supported on iOS simulators.
+- `pinch` is supported on iOS simulators (mobile target).
 - On Android, `pinch` currently returns `UNSUPPORTED_OPERATION` in the adb backend.
 
 Swipe timing:
@@ -423,7 +425,7 @@ Environment selectors:
 - `AGENT_DEVICE_IOS_SIGNING_IDENTITY=<identity>` optional signing identity override.
 - `AGENT_DEVICE_IOS_PROVISIONING_PROFILE=<profile>` optional provisioning profile specifier for iOS device runner signing.
 - `AGENT_DEVICE_IOS_RUNNER_DERIVED_PATH=<path>` optional override for iOS runner derived data root. By default, simulator uses `~/.agent-device/ios-runner/derived` and physical device uses `~/.agent-device/ios-runner/derived/device`. If you set this override, use separate paths per kind to avoid simulator/device artifact collisions.
-- `AGENT_DEVICE_IOS_CLEAN_DERIVED=1` rebuild iOS runner artifacts from scratch for runtime daemon-triggered builds (`pnpm ad ...`) on the selected path. `pnpm build:xcuitest`/`pnpm build:all` already clear `~/.agent-device/ios-runner/derived/device` and do not require this variable. When `AGENT_DEVICE_IOS_RUNNER_DERIVED_PATH` is set, cleanup is blocked by default; set `AGENT_DEVICE_IOS_ALLOW_OVERRIDE_DERIVED_CLEAN=1` only for trusted custom paths.
+- `AGENT_DEVICE_IOS_CLEAN_DERIVED=1` rebuild iOS runner artifacts from scratch for runtime daemon-triggered builds (`pnpm ad ...`) on the selected path. `pnpm build:xcuitest` (alias of `pnpm build:xcuitest:ios`), `pnpm build:xcuitest:tvos`, and `pnpm build:all` already clear their default derived paths and do not require this variable. When `AGENT_DEVICE_IOS_RUNNER_DERIVED_PATH` is set, cleanup is blocked by default; set `AGENT_DEVICE_IOS_ALLOW_OVERRIDE_DERIVED_CLEAN=1` only for trusted custom paths.
 
 Test screenshots are written to:
 - `test/screenshots/android-settings.png`

ios-runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests.swift

@@ -990,42 +990,62 @@ final class RunnerTests: XCTestCase {
       back.tap()
       return true
     }
-#if os(tvOS)
-    XCUIRemote.shared.press(.menu)
-    return true
-#endif
-    return false
+    return pressTvRemoteMenuIfAvailable()
   }
 
   private func performBackGesture(app: XCUIApplication) {
-#if os(tvOS)
-    XCUIRemote.shared.press(.menu)
-#else
+    if pressTvRemoteMenuIfAvailable() {
+      return
+    }
     let target = app.windows.firstMatch.exists ? app.windows.firstMatch : app
     let start = target.coordinate(withNormalizedOffset: CGVector(dx: 0.05, dy: 0.5))
     let end = target.coordinate(withNormalizedOffset: CGVector(dx: 0.8, dy: 0.5))
     start.press(forDuration: 0.05, thenDragTo: end)
-#endif
   }
 
   private func performAppSwitcherGesture(app: XCUIApplication) {
-#if os(tvOS)
-    XCUIRemote.shared.press(.home)
-    usleep(120_000)
-    XCUIRemote.shared.press(.home)
-#else
+    if performTvRemoteAppSwitcherIfAvailable() {
+      return
+    }
     let target = app.windows.firstMatch.exists ? app.windows.firstMatch : app
     let start = target.coordinate(withNormalizedOffset: CGVector(dx: 0.5, dy: 0.99))
     let end = target.coordinate(withNormalizedOffset: CGVector(dx: 0.5, dy: 0.7))
     start.press(forDuration: 0.6, thenDragTo: end)
-#endif
   }
 
   private func pressHomeButton() {
+    if pressTvRemoteHomeIfAvailable() {
+      return
+    }
+    XCUIDevice.shared.press(.home)
+  }
+
+  private func pressTvRemoteMenuIfAvailable() -> Bool {
+#if os(tvOS)
+    XCUIRemote.shared.press(.menu)
+    return true
+#else
+    return false
+#endif
+  }
+
+  private func pressTvRemoteHomeIfAvailable() -> Bool {
 #if os(tvOS)
     XCUIRemote.shared.press(.home)
+    return true
 #else
-    XCUIDevice.shared.press(.home)
+    return false
+#endif
+  }
+
+  private func performTvRemoteAppSwitcherIfAvailable() -> Bool {
+#if os(tvOS)
+    XCUIRemote.shared.press(.home)
+    usleep(120_000)
+    XCUIRemote.shared.press(.home)
+    return true
+#else
+    return false
 #endif
   }
 
@@ -1131,19 +1151,9 @@ final class RunnerTests: XCTestCase {
   }
 
   private func swipe(app: XCUIApplication, direction: SwipeDirection) {
-#if os(tvOS)
-    switch direction {
-    case .up:
-      XCUIRemote.shared.press(.up)
-    case .down:
-      XCUIRemote.shared.press(.down)
-    case .left:
-      XCUIRemote.shared.press(.left)
-    case .right:
-      XCUIRemote.shared.press(.right)
+    if performTvRemoteSwipeIfAvailable(direction: direction) {
+      return
     }
-    return
-#endif
     let target = app.windows.firstMatch.exists ? app.windows.firstMatch : app
     let start = target.coordinate(withNormalizedOffset: CGVector(dx: 0.5, dy: 0.2))
     let end = target.coordinate(withNormalizedOffset: CGVector(dx: 0.5, dy: 0.8))
@@ -1162,6 +1172,24 @@ final class RunnerTests: XCTestCase {
     }
   }
 
+  private func performTvRemoteSwipeIfAvailable(direction: SwipeDirection) -> Bool {
+#if os(tvOS)
+    switch direction {
+    case .up:
+      XCUIRemote.shared.press(.up)
+    case .down:
+      XCUIRemote.shared.press(.down)
+    case .left:
+      XCUIRemote.shared.press(.left)
+    case .right:
+      XCUIRemote.shared.press(.right)
+    }
+    return true
+#else
+    return false
+#endif
+  }
+
   private func pinch(app: XCUIApplication, scale: Double, x: Double?, y: Double?) {
     let target = app.windows.firstMatch.exists ? app.windows.firstMatch : app
 

package.json

@@ -16,7 +16,9 @@
     "build": "rslib build",
     "clean:daemon": "rm -f ~/.agent-device/daemon.json && rm -f ~/.agent-device/daemon.lock",
     "build:node": "pnpm build && pnpm clean:daemon",
-    "build:xcuitest": "rm -rf ~/.agent-device/ios-runner/derived/device && xcodebuild build-for-testing -project ios-runner/AgentDeviceRunner/AgentDeviceRunner.xcodeproj -scheme AgentDeviceRunner -destination \"generic/platform=iOS Simulator\" -derivedDataPath ~/.agent-device/ios-runner/derived",
+    "build:xcuitest": "pnpm build:xcuitest:ios",
+    "build:xcuitest:ios": "rm -rf ~/.agent-device/ios-runner/derived/device && xcodebuild build-for-testing -project ios-runner/AgentDeviceRunner/AgentDeviceRunner.xcodeproj -scheme AgentDeviceRunner -destination \"generic/platform=iOS Simulator\" -derivedDataPath ~/.agent-device/ios-runner/derived",
+    "build:xcuitest:tvos": "rm -rf ~/.agent-device/ios-runner/derived/tvos && xcodebuild build-for-testing -project ios-runner/AgentDeviceRunner/AgentDeviceRunner.xcodeproj -scheme AgentDeviceRunner -destination \"generic/platform=tvOS Simulator\" -derivedDataPath ~/.agent-device/ios-runner/derived/tvos",
     "build:all": "pnpm build:node && pnpm build:xcuitest",
     "ad": "node bin/agent-device.mjs",
     "format": "prettier --write .",

skills/agent-device/SKILL.md

@@ -74,6 +74,7 @@ TV quick reference:
 - AndroidTV: `open`/`apps` use TV launcher discovery automatically.
 - tvOS: runner-driven interactions and snapshots are supported (`snapshot`, `wait`, `press`, `fill`, `get`, `scroll`, `back`, `home`, `app-switcher`, `record` and related selector flows).
 - tvOS `back`/`home`/`app-switcher` map to Siri Remote actions (`menu`, `home`, double-home) in the runner.
+- tvOS does not support iOS simulator-only helpers `pinch`, `settings`, or `push`.
 
 ### Snapshot and targeting
 
@@ -115,6 +116,7 @@ agent-device batch --steps-file /tmp/batch-steps.json --json
 - Use `fill` for clear-then-type semantics; use `type` for focused append typing.
 - iOS `appstate` is session-scoped; Android `appstate` is live foreground state.
 - iOS settings helpers are simulator-only; use `appearance light|dark|toggle` and faceid `match|nonmatch|enroll|unenroll`.
+- tvOS is excluded from iOS simulator-only helpers (`settings`, `push`, `pinch`).
 - For AndroidTV/tvOS selection, always pair `--target` with `--platform` (`ios`, `android`, or `apple` alias); target-only selection is invalid.
 - `push` simulates notification delivery:
   - iOS simulator uses APNs-style payload JSON.

src/core/__tests__/capabilities.test.ts

@@ -113,6 +113,9 @@ test('tvOS follows iOS capability matrix by device kind', () => {
   for (const cmd of ['snapshot', 'wait', 'press', 'get', 'fill', 'scroll', 'back', 'home', 'app-switcher', 'record']) {
     assert.equal(isCommandSupportedOnDevice(cmd, tvOsSimulator), true, `${cmd} on tvOS`);
   }
+  for (const cmd of ['pinch', 'push', 'settings']) {
+    assert.equal(isCommandSupportedOnDevice(cmd, tvOsSimulator), false, `${cmd} unsupported on tvOS`);
+  }
 });
 
 test('unknown commands default to supported', () => {

src/core/capabilities.ts

@@ -46,7 +46,17 @@ const COMMAND_CAPABILITY_MATRIX: Record<string, CommandCapability> = {
   wait: { ios: { simulator: true, device: true }, android: { emulator: true, device: true, unknown: true } },
 };
 
+const TVOS_UNSUPPORTED_COMMANDS = new Set<string>([
+  // tvOS does not expose these iOS simulator helpers.
+  'pinch',
+  'push',
+  'settings',
+]);
+
 export function isCommandSupportedOnDevice(command: string, device: DeviceInfo): boolean {
+  if (device.platform === 'ios' && device.target === 'tv' && TVOS_UNSUPPORTED_COMMANDS.has(command)) {
+    return false;
+  }
   const capability = COMMAND_CAPABILITY_MATRIX[command];
   if (!capability) return true;
   const byPlatform = capability[device.platform];

src/core/dispatch.ts

@@ -1,7 +1,7 @@
 import { promises as fs } from 'node:fs';
 import pathModule from 'node:path';
 import { AppError } from '../utils/errors.ts';
-import { selectDevice, type DeviceInfo } from '../utils/device.ts';
+import { normalizePlatformSelector, selectDevice, type DeviceInfo } from '../utils/device.ts';
 import { listAndroidDevices } from '../platforms/android/devices.ts';
 import {
   appSwitcherAndroid,
@@ -33,10 +33,10 @@ export type CommandFlags = Omit<CliFlags, 'json' | 'help' | 'version' | 'batchSt
 };
 
 export async function resolveTargetDevice(flags: CommandFlags): Promise<DeviceInfo> {
+  const normalizedPlatform = normalizePlatformSelector(flags.platform);
   return await withDiagnosticTimer(
     'resolve_target_device',
     async () => {
-      const normalizedPlatform = flags.platform === 'apple' ? 'ios' : flags.platform;
       const selector = {
         platform: normalizedPlatform,
         target: flags.target,
@@ -76,7 +76,7 @@ export async function resolveTargetDevice(flags: CommandFlags): Promise<DeviceIn
       return await selectDevice(devices, selector);
     },
     {
-      platform: flags.platform === 'apple' ? 'ios' : flags.platform,
+      platform: normalizedPlatform,
       target: flags.target,
     },
   );

src/daemon/handlers/session.ts

@@ -9,7 +9,7 @@ import {
 import { isCommandSupportedOnDevice } from '../../core/capabilities.ts';
 import { isDeepLinkTarget, resolveIosDeviceDeepLinkBundleId } from '../../core/open-target.ts';
 import { AppError, asAppError, normalizeError } from '../../utils/errors.ts';
-import type { DeviceInfo } from '../../utils/device.ts';
+import { normalizePlatformSelector, type DeviceInfo } from '../../utils/device.ts';
 import type { DaemonRequest, DaemonResponse, SessionAction, SessionState } from '../types.ts';
 import { SessionStore } from '../session-store.ts';
 import { contextFromFlags } from '../context.ts';
@@ -54,11 +54,6 @@ const REPLAY_PARENT_FLAG_KEYS: Array<keyof CommandFlags> = ['platform', 'target'
 const LOG_ACTIONS = ['path', 'start', 'stop', 'doctor', 'mark', 'clear'] as const;
 const LOG_ACTIONS_MESSAGE = `logs requires ${LOG_ACTIONS.slice(0, -1).join(', ')}, or ${LOG_ACTIONS.at(-1)}`;
 
-function normalizePlatformSelector(platform: CommandFlags['platform'] | undefined): DeviceInfo['platform'] | undefined {
-  if (platform === 'apple') return 'ios';
-  return platform;
-}
-
 function requireSessionOrExplicitSelector(
   command: string,
   session: SessionState | undefined,

src/daemon/session-selector.ts

@@ -1,11 +1,7 @@
 import { AppError } from '../utils/errors.ts';
 import type { CommandFlags } from '../core/dispatch.ts';
 import type { SessionState } from './types.ts';
-
-function normalizePlatformSelector(platform: CommandFlags['platform'] | undefined): SessionState['device']['platform'] | undefined {
-  if (platform === 'apple') return 'ios';
-  return platform;
-}
+import { normalizePlatformSelector } from '../utils/device.ts';
 
 export function assertSessionSelectorMatches(
   session: SessionState,

src/platforms/ios/runner-client.ts

@@ -5,7 +5,7 @@ import { fileURLToPath } from 'node:url';
 import { AppError } from '../../utils/errors.ts';
 import { runCmd, runCmdStreaming, runCmdBackground, type ExecResult, type ExecBackgroundResult } from '../../utils/exec.ts';
 import { Deadline, isEnvTruthy, retryWithPolicy, withRetry } from '../../utils/retry.ts';
-import type { DeviceInfo } from '../../utils/device.ts';
+import { resolveApplePlatformName, type DeviceInfo } from '../../utils/device.ts';
 import { withKeyedLock } from '../../utils/keyed-lock.ts';
 import { isProcessAlive } from '../../utils/process-identity.ts';
 import net from 'node:net';
@@ -506,34 +506,35 @@ function resolveRunnerDerivedPath(kind: DeviceInfo['kind']): string {
     return path.resolve(override);
   }
   if (kind === 'simulator') {
-    // Keep simulator runtime path aligned with pnpm build:xcuitest/build:all.
+    // Keep simulator runtime path aligned with pnpm build:xcuitest:ios/build:all.
     return path.join(RUNNER_DERIVED_ROOT, 'derived');
   }
   return path.join(RUNNER_DERIVED_ROOT, 'derived', kind);
 }
 
 export function resolveRunnerDestination(device: DeviceInfo): string {
-  if (device.platform !== 'ios') {
-    throw new AppError('UNSUPPORTED_PLATFORM', `Unsupported platform for iOS runner: ${device.platform}`);
-  }
-  const platformName = device.target === 'tv' ? 'tvOS' : 'iOS';
+  const platformName = resolveRunnerPlatformName(device);
   if (device.kind === 'simulator') {
     return `platform=${platformName} Simulator,id=${device.id}`;
   }
   return `platform=${platformName},id=${device.id}`;
 }
 
 export function resolveRunnerBuildDestination(device: DeviceInfo): string {
-  if (device.platform !== 'ios') {
-    throw new AppError('UNSUPPORTED_PLATFORM', `Unsupported platform for iOS runner: ${device.platform}`);
-  }
-  const platformName = device.target === 'tv' ? 'tvOS' : 'iOS';
+  const platformName = resolveRunnerPlatformName(device);
   if (device.kind === 'simulator') {
     return `platform=${platformName} Simulator,id=${device.id}`;
   }
   return `generic/platform=${platformName}`;
 }
 
+function resolveRunnerPlatformName(device: DeviceInfo): 'iOS' | 'tvOS' {
+  if (device.platform !== 'ios') {
+    throw new AppError('UNSUPPORTED_PLATFORM', `Unsupported platform for iOS runner: ${device.platform}`);
+  }
+  return resolveApplePlatformName(device.target);
+}
+
 function ensureBootedIfNeeded(device: DeviceInfo): Promise<void> {
   if (device.kind !== 'simulator') {
     return Promise.resolve();