agent-device 0.18.3 → 0.19.1

package/README.md

@@ -52,11 +52,15 @@ Install the CLI:
 
 ```bash
 npm install -g agent-device@latest
+agent-device doctor
 agent-device --version
 agent-device help workflow
 ```
 
-The installed CLI help is the source of truth for agents. Start with `agent-device help workflow`, then follow the topic-specific help when a task needs dogfooding, debugging, replay, or React Native profiling.
+Run `agent-device doctor` yourself after installation to check local setup before
+handing the CLI to an agent. The installed CLI help is the source of truth for
+agents. Start with `agent-device help workflow`, then follow the topic-specific
+help when a task needs dogfooding, debugging, replay, or React Native profiling.
 
 Prerequisites depend on the target platform: Node.js 22+, Xcode for iOS/tvOS/macOS targets, Android SDK + ADB for Android, and macOS Accessibility permission for desktop automation. Web automation requires Node 24+. See [Installation](https://oss.callstack.com/agent-device/docs/installation) for platform setup.
 

package/android-multitouch-helper/dist/agent-device-android-multitouch-helper-0.19.1.apk.sha256

@@ -0,0 +1 @@
+047938649fa5a1be4959384c3a6b64443cf4135567fb8f72cfb1107375b0eec7  agent-device-android-multitouch-helper-0.19.1.apk

package/android-multitouch-helper/dist/{agent-device-android-multitouch-helper-0.18.3.manifest.json → agent-device-android-multitouch-helper-0.19.1.manifest.json}

@@ -1,10 +1,10 @@
 {
   "name": "android-multitouch-helper",
-  "version": "0.18.3",
-  "assetName": "agent-device-android-multitouch-helper-0.18.3.apk",
-  "sha256": "ace47651ae6742d57cae188bf9fc23a24fccc4a19973a051f948f84dbd2ac8f7",
+  "version": "0.19.1",
+  "assetName": "agent-device-android-multitouch-helper-0.19.1.apk",
+  "sha256": "047938649fa5a1be4959384c3a6b64443cf4135567fb8f72cfb1107375b0eec7",
   "packageName": "com.callstack.agentdevice.multitouchhelper",
-  "versionCode": 18003,
+  "versionCode": 19001,
   "instrumentationRunner": "com.callstack.agentdevice.multitouchhelper/.MultiTouchInstrumentation",
   "statusProtocol": "android-multitouch-helper-v1"
 }

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

@@ -0,0 +1 @@
+e6e5119b4b2ef7d67b8e50acc745f0ffec78951be2094a9198cb491c5e078b22  agent-device-android-snapshot-helper-0.19.1.apk

package/android-snapshot-helper/dist/{agent-device-android-snapshot-helper-0.18.3.manifest.json → agent-device-android-snapshot-helper-0.19.1.manifest.json}

@@ -1,13 +1,13 @@
 {
   "name": "android-snapshot-helper",
-  "version": "0.18.3",
-  "releaseTag": "v0.18.3",
-  "assetName": "agent-device-android-snapshot-helper-0.18.3.apk",
+  "version": "0.19.1",
+  "releaseTag": "v0.19.1",
+  "assetName": "agent-device-android-snapshot-helper-0.19.1.apk",
   "apkUrl": null,
-  "sha256": "89d37238a2ff1daeecff94ac48434047d2d9e9e591fb2d97b2901cb937c20ffa",
-  "checksumName": "agent-device-android-snapshot-helper-0.18.3.apk.sha256",
+  "sha256": "e6e5119b4b2ef7d67b8e50acc745f0ffec78951be2094a9198cb491c5e078b22",
+  "checksumName": "agent-device-android-snapshot-helper-0.19.1.apk.sha256",
   "packageName": "com.callstack.agentdevice.snapshothelper",
-  "versionCode": 18003,
+  "versionCode": 19001,
   "instrumentationRunner": "com.callstack.agentdevice.snapshothelper/.SnapshotInstrumentation",
   "minSdk": 23,
   "targetSdk": 36,

package/dist/apple-runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTapPointPolicy.swift

@@ -0,0 +1,28 @@
+import XCTest
+
+// The tap-point rule the runner shares with the TS runtime (ADR 0011 Layer 2).
+//
+// RULE: the tap point is the element frame's CENTER; a tap is allowed iff that
+// center lies inside the window frame, edges inclusive. An empty or invalid
+// window frame fails open (allowed): resolving the best available frame is the
+// impure caller's job (onScreenWindowFrame / app.frame), and the policy must
+// not turn a missing frame into a refusal.
+//
+// This is pure geometry on purpose — no XCUIElement — so the exact decision
+// can be proven against the golden fixture table shared with the TS twin:
+//   table:   contracts/fixtures/tap-point-policy.json
+//   TS twin: src/snapshot/mobile-snapshot-semantics.ts#isTapPointInsideViewport
+//   TS test: src/snapshot/__tests__/tap-point-policy-parity.test.ts
+// Drift on either side turns CI red without needing a simulator.
+enum TapPointPolicy {
+  static func isAllowed(elementFrame: CGRect, windowFrame: CGRect) -> Bool {
+    if windowFrame.isNull || windowFrame.isEmpty || windowFrame.isInfinite {
+      return true
+    }
+    let centerX = elementFrame.midX
+    let centerY = elementFrame.midY
+    return centerX >= windowFrame.minX && centerX <= windowFrame.maxX
+      && centerY >= windowFrame.minY && centerY <= windowFrame.maxY
+  }
+}
+

package/{apple-runner → dist/apple-runner}/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+AXSnapshotFallback.swift

@@ -12,7 +12,8 @@ extension RunnerTests {
 
   func privateAXSnapshotCapture(
     app: XCUIApplication,
-    options: SnapshotOptions
+    options: SnapshotOptions,
+    deadline: Date = .distantFuture
   ) -> SnapshotBackendCapture? {
     #if os(iOS) && targetEnvironment(simulator)
       let requestedDepth = options.depth ?? 64
@@ -24,6 +25,13 @@ extension RunnerTests {
       var effectiveDepth = requestedDepth
       var lastError = "unknown private AX snapshot failure"
       for depth in attemptDepths {
+        // The first rung always runs (the plan gated entry on its own budget); later rungs
+        // stop when the capture-plan deadline is spent so ladder retries can never stack
+        // past the runner's main-thread watchdog (#1105).
+        if depth != attemptDepths.first, Date() >= deadline {
+          NSLog("AGENT_DEVICE_RUNNER_PRIVATE_AX_SNAPSHOT_BUDGET_EXHAUSTED depth=%ld", depth)
+          break
+        }
         response = RunnerAXSnapshotBridge.snapshotTree(
           for: app,
           maxDepth: depth,
@@ -49,14 +57,8 @@ extension RunnerTests {
         return nil
       }
 
-      // If the app frame is unavailable, the private root's own frame is the reliable screen
-      // rect here. Avoid public window queries: stale transient windows can record XCTest
-      // failures after the runner already returned a successful command response.
-      var viewport = safeSnapshotViewport(app: app)
       let rootFrame = privateAXRect(root["frame"])
-      if viewport.isInfinite || viewport.isNull || viewport.isEmpty, !rootFrame.isEmpty {
-        viewport = rootFrame
-      }
+      let viewport = privateAXSnapshotViewport(app: app, rootFrame: rootFrame)
       var nodes: [SnapshotNode] = []
       appendPrivateAXNode(
         root,
@@ -87,6 +89,29 @@ extension RunnerTests {
     #endif
   }
 
+  private func privateAXSnapshotViewport(app: XCUIApplication, rootFrame: CGRect) -> CGRect {
+    let fallback = rootFrame.isEmpty ? CGRect.infinite : rootFrame
+    guard !hasAbandonedTreeCapture() else {
+      return fallback
+    }
+    do {
+      let viewport = try runMainThreadWork(
+        command: nil,
+        timeout: 1,
+        timeoutError: snapshotMainThreadTimeoutError("reading private AX viewport")
+      ) {
+        self.safeSnapshotViewport(app: app)
+      }
+      if viewport.isInfinite || viewport.isNull || viewport.isEmpty {
+        return fallback
+      }
+      return viewport
+    } catch {
+      NSLog("AGENT_DEVICE_RUNNER_PRIVATE_AX_VIEWPORT_FALLBACK=%@", String(describing: error))
+      return fallback
+    }
+  }
+
   private func appendPrivateAXNode(
     _ rawNode: [String: Any],
     to nodes: inout [SnapshotNode],
@@ -208,122 +233,3 @@ extension RunnerTests {
   }
 }
 
-#if AGENT_DEVICE_RUNNER_UNIT_TESTS
-// MARK: - In-bundle unit tests
-
-extension RunnerTests {
-  func testPrivateAXScopeSelectsSubtreeNotMatchingLabels() {
-    let tree: [String: Any] = [
-      "type": 1, "label": "App",
-      "children": [
-        [
-          "type": 9, "identifier": "homeScreen",
-          "children": [
-            ["type": 48, "label": "Post body without the scope text", "children": []]
-          ],
-        ],
-        ["type": 9, "label": "unrelated sibling", "children": []],
-      ],
-    ]
-    var nodes: [SnapshotNode] = []
-    appendPrivateAXNode(
-      tree,
-      to: &nodes,
-      options: SnapshotOptions(interactiveOnly: false, depth: nil, scope: "homeScreen", raw: false),
-      viewport: .infinite,
-      depth: 0,
-      parentIndex: nil,
-      insideMatchedScope: false
-    )
-
-    let labels = nodes.compactMap { $0.label ?? $0.identifier }
-    XCTAssertTrue(labels.contains("homeScreen"))
-    // Descendants of the matched scope are included even when they do not contain the text.
-    XCTAssertTrue(labels.contains("Post body without the scope text"))
-    XCTAssertFalse(labels.contains("unrelated sibling"))
-  }
-
-  func testPrivateAXInteractiveFiltersLoginLikeHiddenDrawer() {
-    let tree: [String: Any] = [
-      "type": Int(XCUIElement.ElementType.application.rawValue),
-      "label": "Blue Sky",
-      "frame": ["x": 0, "y": 0, "width": 390, "height": 844],
-      "children": [
-        [
-          "type": Int(XCUIElement.ElementType.scrollView.rawValue),
-          "frame": ["x": 0, "y": 0, "width": 390, "height": 844],
-          "children": [
-            [
-              "type": Int(XCUIElement.ElementType.image.rawValue),
-              "label": "Callstack",
-              "frame": ["x": 145, "y": 104, "width": 100, "height": 100],
-              "children": [],
-            ],
-            [
-              "type": Int(XCUIElement.ElementType.staticText.rawValue),
-              "label": "Welcome back",
-              "frame": ["x": 32, "y": 260, "width": 326, "height": 32],
-              "children": [],
-            ],
-            [
-              "type": Int(XCUIElement.ElementType.textField.rawValue),
-              "label": "Email",
-              "identifier": "login.email",
-              "frame": ["x": 32, "y": 348, "width": 326, "height": 48],
-              "children": [],
-            ],
-            [
-              "type": Int(XCUIElement.ElementType.secureTextField.rawValue),
-              "label": "Password",
-              "identifier": "login.password",
-              "frame": ["x": 32, "y": 412, "width": 326, "height": 48],
-              "children": [],
-            ],
-            [
-              "type": Int(XCUIElement.ElementType.button.rawValue),
-              "label": "Sign in",
-              "identifier": "login.submit",
-              "frame": ["x": 32, "y": 492, "width": 326, "height": 52],
-              "children": [],
-            ],
-            [
-              "type": Int(XCUIElement.ElementType.link.rawValue),
-              "label": "Forgot password?",
-              "frame": ["x": 128, "y": 568, "width": 134, "height": 32],
-              "children": [],
-            ],
-            [
-              "type": Int(XCUIElement.ElementType.button.rawValue),
-              "label": "Admin settings",
-              "frame": ["x": -260, "y": 184, "width": 220, "height": 44],
-              "children": [],
-            ],
-            [
-              "type": Int(XCUIElement.ElementType.other.rawValue),
-              "frame": ["x": 16, "y": 184, "width": 220, "height": 44],
-              "children": [],
-            ],
-          ],
-        ]
-      ],
-    ]
-    var nodes: [SnapshotNode] = []
-    appendPrivateAXNode(
-      tree,
-      to: &nodes,
-      options: SnapshotOptions(interactiveOnly: true, depth: nil, scope: nil, raw: false),
-      viewport: CGRect(x: 0, y: 0, width: 390, height: 844),
-      depth: 0,
-      parentIndex: nil,
-      insideMatchedScope: false
-    )
-
-    let labels = nodes.compactMap { $0.label }
-    XCTAssertEqual(
-      labels,
-      ["Blue Sky", "Callstack", "Welcome back", "Email", "Password", "Sign in", "Forgot password?"]
-    )
-    XCTAssertFalse(labels.contains("Admin settings"))
-  }
-}
-#endif