agent-device 0.14.8 → 0.14.9

package/ios-runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Snapshot.swift

@@ -28,6 +28,7 @@ extension RunnerTests {
     let identifier: String
     let valueText: String?
     let hittable: Bool
+    let focused: Bool
     let visible: Bool
   }
 
@@ -341,6 +342,7 @@ extension RunnerTests {
       identifier: identifier,
       valueText: valueText,
       hittable: computedSnapshotHittable(snapshot, viewport: context.viewport, laterNodes: laterNodes),
+      focused: snapshotHasFocus(snapshot),
       visible: isVisibleInViewport(snapshot.frame, context.viewport)
     )
   }
@@ -360,6 +362,7 @@ extension RunnerTests {
       value: evaluation.valueText,
       rect: snapshotRect(from: snapshot.frame),
       enabled: snapshot.isEnabled,
+      focused: evaluation.focused ? true : nil,
       hittable: evaluation.hittable,
       depth: depth,
       parentIndex: parentIndex,
@@ -525,6 +528,7 @@ extension RunnerTests {
         value: node.value,
         rect: node.rect,
         enabled: node.enabled,
+        focused: node.focused,
         hittable: node.hittable,
         depth: depth,
         parentIndex: parentIndex,
@@ -575,6 +579,7 @@ extension RunnerTests {
         value: valueText,
         rect: snapshotRect(from: frame),
         enabled: element.isEnabled,
+        focused: elementHasFocus(element) ? true : nil,
         hittable: element.isHittable,
         depth: 0,
         parentIndex: nil,
@@ -592,6 +597,16 @@ extension RunnerTests {
     return node
   }
 
+  private func snapshotHasFocus(_ snapshot: XCUIElementSnapshot) -> Bool {
+    var focused = false
+    _ = RunnerObjCExceptionCatcher.catchException({
+      if let value = (snapshot as! NSObject).value(forKey: "hasFocus") as? Bool {
+        focused = value
+      }
+    })
+    return focused
+  }
+
   private func shouldExpandCollapsedTabContainer(_ snapshot: XCUIElementSnapshot) -> Bool {
     let frame = snapshot.frame
     if frame.isNull || frame.isEmpty { return false }

package/ios-runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+SystemModal.swift

@@ -186,6 +186,7 @@ extension RunnerTests {
       value: nil,
       rect: snapshotRect(from: element.frame),
       enabled: element.isEnabled,
+      focused: elementHasFocus(element) ? true : nil,
       hittable: hittableOverride ?? element.isHittable,
       depth: depth,
       parentIndex: nil,

package/ios-runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+TvRemote.swift

@@ -0,0 +1,185 @@
+import XCTest
+
+enum RunnerInteractionOutcome {
+  case performed
+  case unsupported(String)
+}
+
+enum TvRemoteButton {
+  case select
+  case menu
+  case home
+  case up
+  case down
+  case left
+  case right
+}
+
+extension RunnerTests {
+  func resolveTvRemoteDoublePressDelay() -> TimeInterval {
+    guard
+      let raw = ProcessInfo.processInfo.environment["AGENT_DEVICE_TV_REMOTE_DOUBLE_PRESS_DELAY_MS"],
+      !raw.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty
+    else {
+      return tvRemoteDoublePressDelayDefault
+    }
+    guard let parsedMs = Double(raw), parsedMs >= 0 else {
+      return tvRemoteDoublePressDelayDefault
+    }
+    return min(parsedMs, 1000) / 1000.0
+  }
+
+  @discardableResult
+  func pressTvRemote(_ button: TvRemoteButton, duration: TimeInterval? = nil) -> Bool {
+#if os(tvOS)
+    let remoteButton = xcuiRemoteButton(button)
+    if let duration, duration > 0 {
+      XCUIRemote.shared.press(remoteButton, forDuration: duration)
+    } else {
+      XCUIRemote.shared.press(remoteButton)
+    }
+    return true
+#else
+    return false
+#endif
+  }
+
+  func tvRemoteButton(from raw: String?) -> TvRemoteButton? {
+    switch raw?.lowercased() {
+    case "select":
+      return .select
+    case "menu":
+      return .menu
+    case "home":
+      return .home
+    case "up":
+      return .up
+    case "down":
+      return .down
+    case "left":
+      return .left
+    case "right":
+      return .right
+    default:
+      return nil
+    }
+  }
+
+  func elementHasFocus(_ element: XCUIElement) -> Bool {
+    var focused = false
+    _ = RunnerObjCExceptionCatcher.catchException({
+      if let value = (element as NSObject).value(forKey: "hasFocus") as? Bool {
+        focused = value
+      }
+    })
+    return focused
+  }
+
+  func activateElement(app: XCUIApplication, element: XCUIElement, action: String) -> RunnerInteractionOutcome {
+    if let outcome = selectFocusedTvElement(app: app, element: element, action: action) {
+      return outcome
+    }
+    return performElementTap(element)
+  }
+
+  func selectFocusedTvElement(app: XCUIApplication, point: CGPoint, action: String) -> RunnerInteractionOutcome? {
+#if os(tvOS)
+    guard let focused = focusedTvElement(app: app), !focused.frame.isEmpty, focused.frame.contains(point) else {
+      return .unsupported("\(action) is supported on tvOS only when the requested point is inside the focused element")
+    }
+    _ = pressTvRemote(.select)
+    return .performed
+#else
+    return nil
+#endif
+  }
+
+  func longSelectFocusedTvElement(app: XCUIApplication, point: CGPoint, duration: TimeInterval) -> RunnerInteractionOutcome? {
+#if os(tvOS)
+    guard let focused = focusedTvElement(app: app), !focused.frame.isEmpty, focused.frame.contains(point) else {
+      return .unsupported("long press is supported on tvOS only when the requested point is inside the focused element")
+    }
+    _ = pressTvRemote(.select, duration: duration)
+    return .performed
+#else
+    return nil
+#endif
+  }
+
+  private func performElementTap(_ element: XCUIElement) -> RunnerInteractionOutcome {
+#if os(tvOS)
+    return .unsupported("element tap is not supported on tvOS; move focus with swipe or scroll, then select the focused element")
+#else
+    element.tap()
+    return .performed
+#endif
+  }
+
+  private func selectFocusedTvElement(app: XCUIApplication, element: XCUIElement, action: String) -> RunnerInteractionOutcome? {
+#if os(tvOS)
+    guard tvFocusedElementMatches(app: app, target: element) else {
+      return .unsupported("\(action) is supported on tvOS only when the requested element is focused")
+    }
+    _ = pressTvRemote(.select)
+    return .performed
+#else
+    return nil
+#endif
+  }
+
+  private func tvFocusedElementMatches(app: XCUIApplication, target: XCUIElement) -> Bool {
+#if os(tvOS)
+    if target.hasFocus {
+      return true
+    }
+    guard let focused = focusedTvElement(app: app) else {
+      return false
+    }
+    let targetFrame = target.frame
+    let focusedFrame = focused.frame
+    guard !targetFrame.isEmpty && !focusedFrame.isEmpty else {
+      return false
+    }
+    let focusedCenter = CGPoint(x: focusedFrame.midX, y: focusedFrame.midY)
+    let targetCenter = CGPoint(x: targetFrame.midX, y: targetFrame.midY)
+    return targetFrame.contains(focusedCenter)
+      || focusedFrame.contains(targetCenter)
+      || targetFrame.intersects(focusedFrame)
+#else
+    return false
+#endif
+  }
+
+  private func focusedTvElement(app: XCUIApplication) -> XCUIElement? {
+#if os(tvOS)
+    let focused = app
+      .descendants(matching: .any)
+      .matching(NSPredicate(format: "hasFocus == true"))
+      .firstMatch
+    return focused.exists ? focused : nil
+#else
+    return nil
+#endif
+  }
+
+#if os(tvOS)
+  private func xcuiRemoteButton(_ button: TvRemoteButton) -> XCUIRemote.Button {
+    switch button {
+    case .select:
+      return .select
+    case .menu:
+      return .menu
+    case .home:
+      return .home
+    case .up:
+      return .up
+    case .down:
+      return .down
+    case .left:
+      return .left
+    case .right:
+      return .right
+    }
+  }
+#endif
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-device",
-  "version": "0.14.8",
+  "version": "0.14.9",
   "description": "Agent-native CLI for AI mobile testing and app automation across iOS, Android, tvOS, Android TV, macOS, and Linux.",
   "mcpName": "io.github.callstackincubator/agent-device",
   "license": "MIT",

package/server.json

@@ -2,17 +2,17 @@
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
   "name": "io.github.callstackincubator/agent-device",
   "title": "agent-device",
-  "description": "Official MCP discovery router for the agent-device CLI. It exposes status, install guidance, version-matched CLI help, prompts, and resources without exposing device automation over MCP.",
+  "description": "Discovery router for the agent-device CLI with status, install, help, prompts, and resources.",
   "repository": {
     "url": "https://github.com/callstackincubator/agent-device",
     "source": "github"
   },
-  "version": "0.14.8",
+  "version": "0.14.9",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "agent-device",
-      "version": "0.14.8",
+      "version": "0.14.9",
       "transport": {
         "type": "stdio"
       }

package/skills/agent-device/SKILL.md

@@ -11,7 +11,15 @@ Router only. Private setup before using this skill:
 agent-device --version
 ```
 
-Require `agent-device >= 0.14.0`; older CLIs lack these help topics. If older, run `npm install -g agent-device@latest`, recheck, then continue. If you cannot upgrade, stop and tell the user. Do not include version/upgrade commands in final plans.
+If that fails but the user installed `agent-device` globally, try the user's login shell before using `npx`:
+
+```bash
+zsh -lic 'command -v agent-device'
+```
+
+If it prints a path, run that absolute path instead of `agent-device`. For non-zsh shells, use the equivalent login-shell command.
+
+Require `agent-device >= 0.14.0`; older CLIs lack these help topics. If older, stop and tell the user to upgrade the trusted install or approve an exact-version npm command. Do not run `npm install -g agent-device@latest` or `npx -y agent-device@latest` autonomously, and do not include version/upgrade commands in final plans.
 
 Before your first agent-device command or plan, read the version-matched CLI guide:
 
@@ -32,3 +40,5 @@ agent-device help dogfood
 Default loop: `open -> snapshot/-i -> get/is/find or press/fill/scroll/wait -> verify -> close`.
 
 Use this skill only to route into version-matched CLI help. Let `help workflow` provide exact command shapes, platform limits, and current workflow guidance.
+
+For precise location workflows, read the installed `settings` help before planning so coordinate support and platform limits come from the active CLI version.

package/skills/dogfood/SKILL.md

@@ -12,7 +12,9 @@ Router for exploratory QA. Private setup before using this skill:
 agent-device --version
 ```
 
-Require `agent-device >= 0.14.0`; older CLIs lack these help topics. If older, run `npm install -g agent-device@latest`, recheck, then continue. If you cannot upgrade, stop and tell the user. Do not include version/upgrade commands in final plans.
+If that fails, stop and tell the user to expose a trusted `agent-device` binary on PATH or approve an exact-version npm command. This skill intentionally keeps allowed tools restricted to `agent-device` and `npx agent-device`.
+
+Require `agent-device >= 0.14.0`; older CLIs lack these help topics. If older, stop and tell the user to upgrade the trusted install or approve an exact-version npm command. Do not run `npm install -g agent-device@latest` or `npx -y agent-device@latest` autonomously, and do not include version/upgrade commands in final plans.
 
 Read current CLI guidance:
 

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

@@ -1 +0,0 @@
-0669bbeb4c3b549a9084dc3d75e4afa8f055408424c40c2fd9db4b75eb1f6e53  agent-device-android-snapshot-helper-0.14.8.apk

package/skills/react-devtools/SKILL.md

@@ -1,48 +0,0 @@
----
-name: react-devtools
-description: Inspect and profile React Native component trees from agent-device. Use for React Native performance, profiling, props, state, hooks, render causes, slow components, excessive rerenders, or questions like why a component rerendered.
----
-
-# react-devtools
-
-Router for React Native internals. Private setup before using this skill:
-
-```bash
-agent-device --version
-```
-
-Require `agent-device >= 0.14.0`; older CLIs lack these help topics. If older, run `npm install -g agent-device@latest`, recheck, then continue. If you cannot upgrade, stop and tell the user. Do not include version/upgrade commands in final plans.
-
-Read current CLI guidance:
-
-```bash
-agent-device help react-devtools
-```
-
-Use `agent-device react-devtools ...` for component tree, props, state, hooks, render ownership, performance profiling, slow components, or rerenders. It dynamically runs pinned `agent-react-devtools@0.4.0`. Use normal `agent-device` commands for visible UI, refs, screenshots, logs, network, or device-level perf.
-
-Core loop:
-
-```bash
-agent-device react-devtools status
-agent-device react-devtools wait --connected
-agent-device react-devtools get tree --depth 3
-agent-device react-devtools profile start
-# perform the interaction with normal agent-device commands
-agent-device react-devtools profile stop
-agent-device react-devtools profile slow --limit 5
-agent-device react-devtools profile rerenders --limit 5
-```
-
-Remote iOS bridge order:
-
-```bash
-agent-device open <bundle-id> --platform ios --relaunch
-agent-device react-devtools start
-agent-device open <bundle-id> --platform ios --relaunch
-agent-device react-devtools wait --connected
-```
-
-Rules:
-
-Keep reads bounded with `--depth`/`find`, treat `@c` refs as reload-local, profile only the investigated interaction, and run the same command in remote Android sessions; the CLI manages the needed local service tunnel. For remote iOS, relaunch after `react-devtools start` because React Native opens the legacy DevTools websocket during JavaScript startup.