agent-device 0.20.0 → 0.20.1

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.
 
@@ -30,6 +30,7 @@ npm install -g agent-device@latest
 agent-device doctor
 agent-device --version
 agent-device help workflow
+agent-device help tv
 ```
 
 Run `agent-device doctor` yourself before handing the CLI to an agent. The installed CLI help defines current behavior. `agent-device help workflow` links to guides for debugging, replay, React Native profiling, and other tasks.
@@ -108,7 +109,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.1.apk.sha256

@@ -0,0 +1 @@
+8dc8135211465ef283d1c5175024638becb783b6975ecfd0b9a3ea38637eaa1c  agent-device-android-ime-helper-0.20.1.apk

package/android/ime-helper/dist/{agent-device-android-ime-helper-0.20.0.manifest.json → agent-device-android-ime-helper-0.20.1.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.1",
+  "assetName": "agent-device-android-ime-helper-0.20.1.apk",
+  "sha256": "8dc8135211465ef283d1c5175024638becb783b6975ecfd0b9a3ea38637eaa1c",
   "packageName": "com.callstack.agentdevice.imehelper",
-  "versionCode": 20000,
+  "versionCode": 20001,
   "serviceComponent": "com.callstack.agentdevice.imehelper/.TestInputMethodService",
   "broadcastProtocol": "android-ime-helper-v1"
 }

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

@@ -0,0 +1 @@
+26ae795374725ac91a513dc2943521fdc16bf67c25e91cb1f49d0fa62f61c85e  agent-device-android-snapshot-helper-0.20.1.apk

package/android/snapshot-helper/dist/{agent-device-android-snapshot-helper-0.20.0.manifest.json → agent-device-android-snapshot-helper-0.20.1.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.1",
+  "releaseTag": "v0.20.1",
+  "assetName": "agent-device-android-snapshot-helper-0.20.1.apk",
   "apkUrl": null,
-  "sha256": "d635fe2e577ece9d5924719f907232693231644d69ba08b7d21d7bea04baa652",
-  "checksumName": "agent-device-android-snapshot-helper-0.20.0.apk.sha256",
+  "sha256": "26ae795374725ac91a513dc2943521fdc16bf67c25e91cb1f49d0fa62f61c85e",
+  "checksumName": "agent-device-android-snapshot-helper-0.20.1.apk.sha256",
   "packageName": "com.callstack.agentdevice.snapshothelper",
-  "versionCode": 20000,
+  "versionCode": 20001,
   "instrumentationRunner": "com.callstack.agentdevice.snapshothelper/.SnapshotInstrumentation",
   "minSdk": 23,
   "targetSdk": 36,

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 {
@@ -1264,15 +1292,35 @@ extension RunnerTests {
       else {
         return Response(ok: false, error: ErrorPayload(message: "rotate requires orientation"))
       }
-      if rotateDevice(to: orientation) {
+      let supportedOrientations = [
+        "portrait",
+        "portrait-upside-down",
+        "landscape-left",
+        "landscape-right",
+      ]
+      guard supportedOrientations.contains(orientation) else {
         return Response(
-          ok: true,
-          data: DataPayload(message: "rotate", orientation: orientation)
+          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: false,
-        error: ErrorPayload(message: "unsupported rotate orientation: \(orientation)")
+        ok: true,
+        data: DataPayload(message: "rotate", orientation: observedOrientation)
       )
     case .appSwitcher:
       performAppSwitcherGesture(app: activeApp)

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,9 +118,9 @@ extension RunnerTests {
 #endif
   }
 
-  func rotateDevice(to orientationName: String) -> Bool {
+  func rotateDevice(to orientationName: String) -> String? {
 #if os(macOS) || os(tvOS) || os(visionOS)
-    return false
+    return nil
 #else
     switch orientationName {
     case "portrait":
@@ -132,10 +132,21 @@ extension RunnerTests {
     case "landscape-right":
       XCUIDevice.shared.orientation = .landscapeRight
     default:
-      return false
+      return nil
     }
     sleepFor(0.2)
-    return true
+    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+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+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> = [