agent-device 0.20.0 → 0.20.2

package/README.md

@@ -15,7 +15,7 @@
 
 Let your coding agent verify its changes in the running app.
 
-`agent-device` lets coding agents inspect, control, and verify apps on iOS, Android, TV, web, macOS, and Linux. Agents can read token-efficient accessibility snapshots, find elements by ref or selector, run device actions, and save evidence for review.
+`agent-device` lets coding agents inspect, control, and verify apps on iOS, Android, tvOS, Android TV, Amazon Vega OS TV through the Vega Virtual Device (VVD), web, macOS, and Linux. Agents can read token-efficient accessibility snapshots where supported, find elements by ref or selector, run device actions, and save evidence for review. Initial Vega OS support is VVD-only and covers discovery, app lifecycle, and complete TV-remote control; physical Fire TV, capture, and selector backends remain unsupported.
 
 Your coding agent or QA tool reads each result and chooses the next command. `agent-device` runs the command and saves evidence when asked.
 
@@ -28,7 +28,6 @@ Install the CLI and check setup. It requires Node.js 22.12 or newer; web automat
 ```bash
 npm install -g agent-device@latest
 agent-device doctor
-agent-device --version
 agent-device help workflow
 ```
 
@@ -108,7 +107,7 @@ See [Commands](https://oss.callstack.com/agent-device/docs/commands) for the com
 
 ## How it works
 
-`agent-device` keeps device state in sessions. It sends commands to XCTest on iOS and tvOS, ADB and the snapshot helper on Android, a local helper on macOS, and AT-SPI on Linux.
+`agent-device` keeps device state in sessions. It sends commands to XCTest on iOS and tvOS, ADB and the snapshot helper on Android, Vega CLI/VDA on the Vega Virtual Device, a local helper on macOS, and AT-SPI on Linux.
 
 Node.js apps can use the typed client or public subpaths. `agent-device/android-adb` provides the Android ADB provider interface, helpers for logcat, the clipboard, the keyboard, and apps, and port reverse management.
 

package/android/ime-helper/dist/agent-device-android-ime-helper-0.20.2.apk.sha256

@@ -0,0 +1 @@
+941f2997c4315e753fb2f5411562a2907b3a188370c3d52e762692843be1b50f  agent-device-android-ime-helper-0.20.2.apk

package/android/ime-helper/dist/{agent-device-android-ime-helper-0.20.0.manifest.json → agent-device-android-ime-helper-0.20.2.manifest.json}

@@ -1,10 +1,10 @@
 {
   "name": "android-ime-helper",
-  "version": "0.20.0",
-  "assetName": "agent-device-android-ime-helper-0.20.0.apk",
-  "sha256": "315907205b4d573cbfe4dfa4bcb7bafd360d9f6d93427f255574d7f02ea6656e",
+  "version": "0.20.2",
+  "assetName": "agent-device-android-ime-helper-0.20.2.apk",
+  "sha256": "941f2997c4315e753fb2f5411562a2907b3a188370c3d52e762692843be1b50f",
   "packageName": "com.callstack.agentdevice.imehelper",
-  "versionCode": 20000,
+  "versionCode": 20002,
   "serviceComponent": "com.callstack.agentdevice.imehelper/.TestInputMethodService",
   "broadcastProtocol": "android-ime-helper-v1"
 }

package/android/snapshot-helper/dist/agent-device-android-snapshot-helper-0.20.2.apk.sha256

@@ -0,0 +1 @@
+003859ea5dc5d1ed8ddc5daf786eacb790ff471bbb0c3b0e1239712f73f37684  agent-device-android-snapshot-helper-0.20.2.apk

package/android/snapshot-helper/dist/{agent-device-android-snapshot-helper-0.20.0.manifest.json → agent-device-android-snapshot-helper-0.20.2.manifest.json}

@@ -1,13 +1,13 @@
 {
   "name": "android-snapshot-helper",
-  "version": "0.20.0",
-  "releaseTag": "v0.20.0",
-  "assetName": "agent-device-android-snapshot-helper-0.20.0.apk",
+  "version": "0.20.2",
+  "releaseTag": "v0.20.2",
+  "assetName": "agent-device-android-snapshot-helper-0.20.2.apk",
   "apkUrl": null,
-  "sha256": "d635fe2e577ece9d5924719f907232693231644d69ba08b7d21d7bea04baa652",
-  "checksumName": "agent-device-android-snapshot-helper-0.20.0.apk.sha256",
+  "sha256": "003859ea5dc5d1ed8ddc5daf786eacb790ff471bbb0c3b0e1239712f73f37684",
+  "checksumName": "agent-device-android-snapshot-helper-0.20.2.apk.sha256",
   "packageName": "com.callstack.agentdevice.snapshothelper",
-  "versionCode": 20000,
+  "versionCode": 20002,
   "instrumentationRunner": "com.callstack.agentdevice.snapshothelper/.SnapshotInstrumentation",
   "minSdk": 23,
   "targetSdk": 36,

package/dist/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Alert.swift

@@ -220,10 +220,12 @@ extension RunnerTests {
       "yes",
       "continue",
       "done",
+      "open",
       "open settings"
     ].contains(normalized) || normalized.hasPrefix("confirm")
   }
 
+
   private func isDismissButton(_ label: String) -> Bool {
     [
       "cancel",

package/dist/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandExecution.swift

@@ -755,6 +755,28 @@ extension RunnerTests {
       }
     case .uptime:
       return executeUptime()
+    case .activate:
+      guard
+        let bundleId = command.appBundleId?.trimmingCharacters(in: .whitespacesAndNewlines),
+        !bundleId.isEmpty
+      else {
+        return Response(ok: false, error: ErrorPayload(message: "activate requires appBundleId"))
+      }
+      // prepareActiveCommandContext already activated this bundle. Keep this case as the
+      // explicit acknowledgement after that preflight, not as a second activation.
+      return Response(ok: true, data: DataPayload(message: "app activated"))
+    case .terminate:
+      guard
+        let bundleId = command.appBundleId?.trimmingCharacters(in: .whitespacesAndNewlines),
+        !bundleId.isEmpty
+      else {
+        return Response(ok: false, error: ErrorPayload(message: "terminate requires appBundleId"))
+      }
+      XCUIApplication(bundleIdentifier: bundleId).terminate()
+      if currentBundleId == bundleId {
+        invalidateCachedTarget(reason: "target_terminated")
+      }
+      return Response(ok: true, data: DataPayload(message: "app terminated"))
     default:
       break
     }
@@ -844,7 +866,7 @@ extension RunnerTests {
   ) throws -> Response {
     var activeApp = activeApp
     switch command.command {
-    case .status, .targetReset, .shutdown, .recordStart, .recordStop, .uptime:
+    case .status, .activate, .terminate, .targetReset, .shutdown, .recordStart, .recordStop, .uptime:
       return Response(
         ok: false,
         error: ErrorPayload(
@@ -1231,6 +1253,12 @@ extension RunnerTests {
       guard let pngData = runnerPngData(for: screenshot.image) else {
         return Response(ok: false, error: ErrorPayload(message: "Failed to encode screenshot as PNG"))
       }
+      if command.inlineScreenshot == true {
+        return Response(
+          ok: true,
+          data: DataPayload(imageBase64: pngData.base64EncodedString())
+        )
+      }
       let fileName = "screenshot-\(Int(Date().timeIntervalSince1970 * 1000)).png"
       let filePath = (NSTemporaryDirectory() as NSString).appendingPathComponent(fileName)
       do {
@@ -1259,21 +1287,7 @@ extension RunnerTests {
       pressHomeButton()
       return Response(ok: true, data: DataPayload(message: "home"))
     case .rotate:
-      guard let orientation = command.orientation?.trimmingCharacters(in: .whitespacesAndNewlines),
-        !orientation.isEmpty
-      else {
-        return Response(ok: false, error: ErrorPayload(message: "rotate requires orientation"))
-      }
-      if rotateDevice(to: orientation) {
-        return Response(
-          ok: true,
-          data: DataPayload(message: "rotate", orientation: orientation)
-        )
-      }
-      return Response(
-        ok: false,
-        error: ErrorPayload(message: "unsupported rotate orientation: \(orientation)")
-      )
+      return executeRotateCommand(command)
     case .appSwitcher:
       performAppSwitcherGesture(app: activeApp)
       return Response(ok: true, data: DataPayload(message: "appSwitcher"))

package/dist/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandJournal.swift

@@ -147,7 +147,7 @@ final class RunnerCommandJournal {
          .remotePress, .type, .swipe, .scroll, .desktopScroll, .findText, .querySelector, .readText, .back,
          .backInApp, .backSystem, .home, .rotate, .appSwitcher, .keyboardDismiss, .keyboardReturn,
          .alert, .sequence, .gesture, .gestureViewport, .recordStart, .recordStop,
-         .status, .uptime, .targetReset, .shutdown:
+         .status, .uptime, .activate, .terminate, .targetReset, .shutdown:
       return true
     }
   }

package/dist/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Interaction.swift

@@ -118,27 +118,6 @@ extension RunnerTests {
 #endif
   }
 
-  func rotateDevice(to orientationName: String) -> Bool {
-#if os(macOS) || os(tvOS) || os(visionOS)
-    return false
-#else
-    switch orientationName {
-    case "portrait":
-      XCUIDevice.shared.orientation = .portrait
-    case "portrait-upside-down":
-      XCUIDevice.shared.orientation = .portraitUpsideDown
-    case "landscape-left":
-      XCUIDevice.shared.orientation = .landscapeLeft
-    case "landscape-right":
-      XCUIDevice.shared.orientation = .landscapeRight
-    default:
-      return false
-    }
-    sleepFor(0.2)
-    return true
-#endif
-  }
-
   func findElement(app: XCUIApplication, text: String) -> XCUIElement? {
     let predicate = NSPredicate(format: "label CONTAINS[c] %@ OR identifier CONTAINS[c] %@ OR value CONTAINS[c] %@", text, text, text)
     let element = app.descendants(matching: .any).matching(predicate).firstMatch

package/dist/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Models.swift

@@ -31,6 +31,8 @@ enum CommandType: String, Codable {
   case recordStop
   case status
   case uptime
+  case activate
+  case terminate
   case targetReset
   case shutdown
 }
@@ -90,7 +92,7 @@ extension CommandType {
       return CommandTraits(isInteraction: false, readOnly: .conditional, isLifecycle: false)
 
     // Runner-lifecycle commands: skip the app-activation preflight.
-    case .recordStop, .uptime, .targetReset, .shutdown:
+    case .recordStop, .uptime, .terminate, .targetReset, .shutdown:
       return CommandTraits(isInteraction: false, readOnly: .never, isLifecycle: true)
 
     case .status:
@@ -101,7 +103,7 @@ extension CommandType {
     // guard interacts with bespoke macOS activation, so classifying it needs a macOS smoke
     // check first (tracked as a follow-up). Also preserved: querySelector is NOT read-only;
     // recordStart is NOT a lifecycle command; home/alert remain non-interaction by design.
-    case .mouseClick, .querySelector, .home, .recordStart:
+    case .mouseClick, .querySelector, .home, .recordStart, .activate:
       return CommandTraits(isInteraction: false, readOnly: .never, isLifecycle: false)
     }
   }
@@ -118,7 +120,6 @@ struct Command: Codable {
   let allowNonHittableCoordinateFallback: Bool?
   let delayMs: Int?
   let textEntryMode: String?
-  let clearFirst: Bool?
   let action: String?
   let x: Double?
   let y: Double?
@@ -141,6 +142,7 @@ struct Command: Codable {
   let scope: String?
   let raw: Bool?
   let fullscreen: Bool?
+  let inlineScreenshot: Bool?
   let synthesized: Bool?
   let steps: [SequenceStep]?
 }
@@ -228,6 +230,7 @@ extension Response {
 
 struct DataPayload: Codable {
   let message: String?
+  let imageBase64: String?
   let text: String?
   let found: Bool?
   let items: [String]?
@@ -267,6 +270,7 @@ struct DataPayload: Codable {
 
   init(
     message: String? = nil,
+    imageBase64: String? = nil,
     text: String? = nil,
     found: Bool? = nil,
     items: [String]? = nil,
@@ -305,6 +309,7 @@ struct DataPayload: Codable {
     sequenceResults: [SequenceStepResult]? = nil
   ) {
     self.message = message
+    self.imageBase64 = imageBase64
     self.text = text
     self.found = found
     self.items = items

package/dist/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Orientation.swift

@@ -0,0 +1,92 @@
+import XCTest
+
+private enum OrientationObservationTiming {
+  static let pollInterval: TimeInterval = 0.05
+  static let timeout: TimeInterval = 2
+}
+
+extension RunnerTests {
+  func executeRotateCommand(_ command: Command) -> Response {
+    guard let orientation = command.orientation?.trimmingCharacters(in: .whitespacesAndNewlines),
+      !orientation.isEmpty
+    else {
+      return Response(ok: false, error: ErrorPayload(message: "rotate requires orientation"))
+    }
+    let supportedOrientations = [
+      "portrait",
+      "portrait-upside-down",
+      "landscape-left",
+      "landscape-right",
+    ]
+    guard supportedOrientations.contains(orientation) else {
+      return Response(
+        ok: false,
+        error: ErrorPayload(message: "unsupported rotate orientation: \(orientation)")
+      )
+    }
+    guard let observedOrientation = rotateDevice(to: orientation) else {
+      return Response(
+        ok: false,
+        error: ErrorPayload(message: "unable to observe device orientation after rotate")
+      )
+    }
+    guard observedOrientation == orientation else {
+      return Response(
+        ok: false,
+        error: ErrorPayload(
+          message: "device orientation is \(observedOrientation), expected \(orientation)"
+        )
+      )
+    }
+    return Response(
+      ok: true,
+      data: DataPayload(message: "rotate", orientation: observedOrientation)
+    )
+  }
+
+  private func rotateDevice(to orientationName: String) -> String? {
+#if os(macOS) || os(tvOS) || os(visionOS)
+    return nil
+#else
+    switch orientationName {
+    case "portrait":
+      XCUIDevice.shared.orientation = .portrait
+    case "portrait-upside-down":
+      XCUIDevice.shared.orientation = .portraitUpsideDown
+    case "landscape-left":
+      XCUIDevice.shared.orientation = .landscapeLeft
+    case "landscape-right":
+      XCUIDevice.shared.orientation = .landscapeRight
+    default:
+      return nil
+    }
+    let deadline = Date().addingTimeInterval(OrientationObservationTiming.timeout)
+    repeat {
+      if observedDeviceOrientation() == orientationName {
+        return orientationName
+      }
+      sleepFor(OrientationObservationTiming.pollInterval)
+    } while Date() < deadline
+    return observedDeviceOrientation()
+#endif
+  }
+
+  private func observedDeviceOrientation() -> String? {
+#if os(macOS) || os(tvOS) || os(visionOS)
+    return nil
+#else
+    switch XCUIDevice.shared.orientation {
+    case .portrait:
+      return "portrait"
+    case .portraitUpsideDown:
+      return "portrait-upside-down"
+    case .landscapeLeft:
+      return "landscape-left"
+    case .landscapeRight:
+      return "landscape-right"
+    default:
+      return nil
+    }
+#endif
+  }
+}

package/dist/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Snapshot.swift

@@ -57,12 +57,16 @@ extension RunnerTests {
     case .collectionView: return "CollectionView"
     case .table: return "Table"
     case .scrollView: return "ScrollView"
+    case .toolbar: return "Toolbar"
     case .searchField: return "SearchField"
     case .segmentedControl: return "SegmentedControl"
     case .stepper: return "Stepper"
     case .picker: return "Picker"
+    case .activityIndicator: return "ActivityIndicator"
+    case .progressIndicator: return "ProgressIndicator"
     case .checkBox: return "CheckBox"
     case .menuItem: return "MenuItem"
+    case .webView: return "WebView"
     case .other: return "Other"
     default:
       switch type.rawValue {
@@ -70,8 +74,6 @@ extension RunnerTests {
         return "Keyboard"
       case 20:
         return "Key"
-      case 24:
-        return "SearchField"
       default:
         return "Element(\(type.rawValue))"
       }

package/dist/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+TextEntry.swift

@@ -240,7 +240,7 @@ extension RunnerTests {
     case "replace":
       return .replacement
     default:
-      return command.clearFirst == true ? .replacement : .none
+      return .none
     }
   }
 

package/dist/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests.swift

@@ -121,7 +121,8 @@ final class RunnerTests: XCTestCase {
     .tabBar,
     .textField,
     .secureTextField,
-    .textView
+    .textView,
+    .webView
   ]
   // Keep blocker actions narrow to avoid false positives from generic hittable containers.
   let actionableTypes: Set<XCUIElement.ElementType> = [