agent-device 0.14.8 → 0.15.0

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

@@ -72,6 +72,21 @@ extension RunnerTests {
 
   // MARK: - Target Activation
 
+  func ensureRunnerHostAppActive(reason: String) {
+    NSLog(
+      "AGENT_DEVICE_RUNNER_HOST_ACTIVATE state=%d reason=%@",
+      app.state.rawValue,
+      reason
+    )
+    if app.state == .unknown || app.state == .notRunning {
+      app.launch()
+    } else if app.state != .runningForeground {
+      app.activate()
+    }
+    currentApp = app
+    currentBundleId = nil
+  }
+
   func targetNeedsActivation(_ target: XCUIApplication) -> Bool {
     let state = target.state
 #if os(macOS)
@@ -88,6 +103,24 @@ extension RunnerTests {
     return false
   }
 
+  func canUseFastForegroundAppGuard(
+    activeApp: XCUIApplication,
+    requestedBundleId: String?,
+    command: CommandType
+  ) -> Bool {
+    guard let requestedBundleId, currentBundleId == requestedBundleId, currentApp != nil else {
+      return false
+    }
+    guard activeApp.state == .runningForeground else { return false }
+    NSLog(
+      "AGENT_DEVICE_RUNNER_FAST_APP_GUARD command=%@ bundle=%@ state=%d",
+      String(describing: command),
+      requestedBundleId,
+      activeApp.state.rawValue
+    )
+    return true
+  }
+
   func activateTarget(bundleId: String, reason: String) -> XCUIApplication {
     let target = XCUIApplication(bundleIdentifier: bundleId)
     NSLog(
@@ -109,18 +142,53 @@ extension RunnerTests {
     operation: () -> Void
   ) {
     let setter = NSSelectorFromString("setWaitForIdleTimeout:")
-    guard target.responds(to: setter) else {
-      operation()
-      return
+    let supportsWaitForIdleTimeout = target.responds(to: setter)
+    let previous = supportsWaitForIdleTimeout
+      ? (target.value(forKey: "waitForIdleTimeout") as? NSNumber)
+      : nil
+    if supportsWaitForIdleTimeout {
+      target.setValue(resolveScrollInteractionIdleTimeout(), forKey: "waitForIdleTimeout")
     }
-    let previous = target.value(forKey: "waitForIdleTimeout") as? NSNumber
-    target.setValue(resolveScrollInteractionIdleTimeout(), forKey: "waitForIdleTimeout")
     defer {
       if let previous {
         target.setValue(previous.doubleValue, forKey: "waitForIdleTimeout")
       }
     }
-    operation()
+    performWithQuiescenceSkippedIfSupported(target, operation: operation)
+  }
+
+  // Some apps never report post-gesture quiescence, even after XCTest has synthesized the event.
+  private func performWithQuiescenceSkippedIfSupported(
+    _ target: XCUIApplication,
+    operation: () -> Void
+  ) {
+    let selector = NSSelectorFromString("_performWithInteractionOptions:block:")
+    guard target.responds(to: selector) else {
+      operation()
+      return
+    }
+    typealias PerformWithInteractionOptions = @convention(c) (
+      NSObject,
+      Selector,
+      UInt,
+      @convention(block) () -> Void
+    ) -> Void
+    let implementation = target.method(for: selector)
+    let performWithOptions = unsafeBitCast(
+      implementation,
+      to: PerformWithInteractionOptions.self
+    )
+    let skipPreEventQuiescence = UInt(1)
+    let skipPostEventQuiescence = UInt(2)
+    withoutActuallyEscaping(operation) { escapableOperation in
+      let block: @convention(block) () -> Void = escapableOperation
+      performWithOptions(
+        target,
+        selector,
+        skipPreEventQuiescence | skipPostEventQuiescence,
+        block
+      )
+    }
   }
 
   private func resolveScrollInteractionIdleTimeout() -> TimeInterval {
@@ -184,6 +252,7 @@ extension RunnerTests {
       .tap,
       .longPress,
       .drag,
+      .remotePress,
       .type,
       .swipe,
       .back,
@@ -201,7 +270,7 @@ extension RunnerTests {
 
   func isRunnerLifecycleCommand(_ command: CommandType) -> Bool {
     switch command {
-    case .shutdown, .recordStop, .screenshot:
+    case .shutdown, .recordStop, .screenshot, .uptime:
       return true
     default:
       return false
@@ -223,6 +292,24 @@ extension RunnerTests {
 
   func sleepFor(_ delay: TimeInterval) {
     guard delay > 0 else { return }
+    // Keep XCTest/UI sources moving during command-local pauses such as delayed typing.
+    if Thread.isMainThread {
+      let deadline = Date().addingTimeInterval(delay)
+      while Date() < deadline {
+        let slice = min(max(deadline.timeIntervalSinceNow, 0), 0.02)
+        if slice <= 0 {
+          break
+        }
+        let handledSource = RunLoop.current.run(
+          mode: .default,
+          before: Date().addingTimeInterval(slice)
+        )
+        if !handledSource {
+          usleep(useconds_t(slice * 1_000_000))
+        }
+      }
+      return
+    }
     usleep(useconds_t(delay * 1_000_000))
   }
 }

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

@@ -8,9 +8,11 @@ enum CommandType: String, Codable {
   case interactionFrame
   case drag
   case dragSeries
+  case remotePress
   case type
   case swipe
   case findText
+  case querySelector
   case readText
   case snapshot
   case screenshot
@@ -33,12 +35,16 @@ struct Command: Codable {
   let command: CommandType
   let appBundleId: String?
   let text: String?
+  let selectorKey: String?
+  let selectorValue: String?
   let delayMs: Int?
+  let textEntryMode: String?
   let clearFirst: Bool?
   let action: String?
   let x: Double?
   let y: Double?
   let button: String?
+  let remoteButton: String?
   let count: Double?
   let intervalMs: Double?
   let doubleTap: Bool?
@@ -162,6 +168,8 @@ struct SnapshotNode: Codable {
   let value: String?
   let rect: SnapshotRect
   let enabled: Bool
+  let focused: Bool?
+  let selected: Bool?
   let hittable: Bool
   let depth: Int
   let parentIndex: Int?

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

@@ -28,6 +28,8 @@ extension RunnerTests {
     let identifier: String
     let valueText: String?
     let hittable: Bool
+    let focused: Bool
+    let selected: Bool
     let visible: Bool
   }
 
@@ -341,6 +343,8 @@ extension RunnerTests {
       identifier: identifier,
       valueText: valueText,
       hittable: computedSnapshotHittable(snapshot, viewport: context.viewport, laterNodes: laterNodes),
+      focused: snapshotHasFocus(snapshot),
+      selected: snapshotIsSelected(snapshot),
       visible: isVisibleInViewport(snapshot.frame, context.viewport)
     )
   }
@@ -360,6 +364,8 @@ extension RunnerTests {
       value: evaluation.valueText,
       rect: snapshotRect(from: snapshot.frame),
       enabled: snapshot.isEnabled,
+      focused: evaluation.focused ? true : nil,
+      selected: evaluation.selected ? true : nil,
       hittable: evaluation.hittable,
       depth: depth,
       parentIndex: parentIndex,
@@ -525,6 +531,8 @@ extension RunnerTests {
         value: node.value,
         rect: node.rect,
         enabled: node.enabled,
+        focused: node.focused,
+        selected: node.selected,
         hittable: node.hittable,
         depth: depth,
         parentIndex: parentIndex,
@@ -575,6 +583,8 @@ extension RunnerTests {
         value: valueText,
         rect: snapshotRect(from: frame),
         enabled: element.isEnabled,
+        focused: elementHasFocus(element) ? true : nil,
+        selected: element.isSelected ? true : nil,
         hittable: element.isHittable,
         depth: 0,
         parentIndex: nil,
@@ -592,6 +602,20 @@ 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 snapshotIsSelected(_ snapshot: XCUIElementSnapshot) -> Bool {
+    return snapshot.isSelected
+  }
+
   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,8 @@ extension RunnerTests {
       value: nil,
       rect: snapshotRect(from: element.frame),
       enabled: element.isEnabled,
+      focused: elementHasFocus(element) ? true : nil,
+      selected: element.isSelected ? 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/ios-runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests.swift

@@ -90,8 +90,7 @@ final class RunnerTests: XCTestCase {
   @MainActor
   func testCommand() throws {
     doneExpectation = expectation(description: "agent-device command handled")
-    app.launch()
-    currentApp = app
+    NSLog("AGENT_DEVICE_RUNNER_HEADLESS_STARTUP=1")
     let queue = DispatchQueue(label: "agent-device.runner")
     let desiredPort = RunnerEnv.resolvePort()
     NSLog("AGENT_DEVICE_RUNNER_DESIRED_PORT=%d", desiredPort)

package/ios-runner/AgentDeviceRunner/AgentDeviceRunnerUITests.xctestplan

@@ -0,0 +1,26 @@
+{
+  "configurations" : [
+    {
+      "id" : "916C7049-FE79-4C78-B55F-79242F92CB19",
+      "name" : "Configuration 1",
+      "options" : {
+
+      }
+    }
+  ],
+  "defaultOptions" : {
+    "preferredScreenCaptureFormat" : "screenshots",
+    "systemAttachmentLifetime" : "keepNever",
+    "userAttachmentLifetime" : "keepNever"
+  },
+  "testTargets" : [
+    {
+      "target" : {
+        "containerPath" : "container:AgentDeviceRunner.xcodeproj",
+        "identifier" : "20EA2EDC2F2CFC7C001CF0EF",
+        "name" : "AgentDeviceRunnerUITests"
+      }
+    }
+  ],
+  "version" : 1
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-device",
-  "version": "0.14.8",
+  "version": "0.15.0",
   "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",
@@ -14,7 +14,7 @@
     "url": "https://github.com/callstackincubator/agent-device/issues"
   },
   "type": "module",
-  "packageManager": "pnpm@10.33.2",
+  "packageManager": "pnpm@11.1.2",
   "main": "dist/src/index.js",
   "types": "dist/src/index.d.ts",
   "exports": {
@@ -76,11 +76,17 @@
   "scripts": {
     "build": "rslib build",
     "clean:daemon": "rm -f ~/.agent-device/daemon.json && rm -f ~/.agent-device/daemon.lock",
+    "clean:xcuitest": "node scripts/clean-xcuitest-derived.mjs",
+    "clean:xcuitest:ios": "node scripts/clean-xcuitest-derived.mjs ios",
+    "clean:xcuitest:macos": "node scripts/clean-xcuitest-derived.mjs macos",
+    "clean:xcuitest:tvos": "node scripts/clean-xcuitest-derived.mjs tvos",
     "build:node": "pnpm build && pnpm clean:daemon",
     "build:xcuitest": "pnpm build:xcuitest:ios && pnpm build:xcuitest:macos",
-    "build:xcuitest:ios": "AGENT_DEVICE_XCUITEST_PLATFORM=ios AGENT_DEVICE_IOS_CLEAN_DERIVED=1 sh ./scripts/build-xcuitest-apple.sh",
+    "build:xcuitest:ios": "AGENT_DEVICE_XCUITEST_PLATFORM=ios sh ./scripts/build-xcuitest-apple.sh",
+    "build:xcuitest:ios:clean": "pnpm clean:xcuitest:ios && pnpm build:xcuitest:ios",
     "build:xcuitest:macos": "AGENT_DEVICE_XCUITEST_PLATFORM=macos sh ./scripts/build-xcuitest-apple.sh",
-    "build:xcuitest:tvos": "AGENT_DEVICE_XCUITEST_PLATFORM=tvos AGENT_DEVICE_IOS_CLEAN_DERIVED=1 sh ./scripts/build-xcuitest-apple.sh",
+    "build:xcuitest:tvos": "AGENT_DEVICE_XCUITEST_PLATFORM=tvos sh ./scripts/build-xcuitest-apple.sh",
+    "build:xcuitest:tvos:clean": "pnpm clean:xcuitest:tvos && pnpm build:xcuitest:tvos",
     "build:android-snapshot-helper": "sh ./scripts/build-android-snapshot-helper.sh $(node -p \"require('./package.json').version\") .tmp/android-snapshot-helper",
     "package:android-snapshot-helper": "sh ./scripts/package-android-snapshot-helper.sh $(node -p \"require('./package.json').version\") v$(node -p \"require('./package.json').version\") .tmp/android-snapshot-helper",
     "package:android-snapshot-helper:npm": "rm -rf android-snapshot-helper/dist && sh ./scripts/package-android-snapshot-helper.sh $(node -p \"require('./package.json').version\") v$(node -p \"require('./package.json').version\") android-snapshot-helper/dist",
@@ -90,7 +96,7 @@
     "lint": "oxlint . --deny-warnings",
     "format": "oxfmt --write src test skills package.json tsconfig.json tsconfig.lib.json rslib.config.ts vitest.config.ts .github/actions/setup-node-pnpm/action.yml .oxlintrc.json .oxfmtrc.json '!test/skillgym/.skillgym-results/**'",
     "fallow": "fallow --summary",
-    "fallow:baseline": "(fallow dead-code --save-baseline fallow-baselines/dead-code.json --summary || true) && (fallow dupes --save-baseline fallow-baselines/dupes.json --summary || true) && (fallow health --save-baseline fallow-baselines/health.json --summary || true)",
+    "fallow:baseline": "(fallow dead-code --save-baseline fallow-baselines/dead-code.json --summary || true) && (fallow health --save-baseline fallow-baselines/health.json --summary || true)",
     "check:fallow": "fallow audit",
     "check:quick": "pnpm lint && pnpm typecheck",
     "sync:mcp-metadata": "node scripts/sync-mcp-metadata.mjs",
@@ -105,11 +111,16 @@
     "test-app:ios": "pnpm --dir examples/test-app ios",
     "test-app:android": "pnpm --dir examples/test-app android",
     "test-app:typecheck": "pnpm --dir examples/test-app typecheck",
-    "test": "vitest run",
-    "test:unit": "vitest run",
+    "test": "vitest run --project unit",
+    "test:unit": "vitest run --project unit",
+    "test:coverage": "vitest run --coverage",
+    "test:integration:provider": "vitest run --project provider-integration",
+    "test:integration:progress": "node scripts/integration-progress.mjs",
+    "test:integration:progress:check": "node scripts/integration-progress.mjs --check",
     "test:skillgym": "pnpm build && skillgym run ./test/skillgym/suites/agent-device-smoke-suite.ts --config ./test/skillgym/skillgym.config.ts",
     "test:smoke": "node --test test/integration/smoke-*.test.ts",
-    "test:integration": "node --test test/integration/*.test.ts",
+    "test:integration:node": "node --test test/integration/*.test.ts",
+    "test:integration": "pnpm test:integration:node && pnpm test:integration:provider",
     "test:replay:ios": "node --experimental-strip-types src/bin.ts test test/integration/replays/ios/simulator",
     "test:replay:ios-device": "node --experimental-strip-types src/bin.ts test test/integration/replays/ios/device",
     "test:replay:android": "node --experimental-strip-types src/bin.ts test test/integration/replays/android",
@@ -183,18 +194,21 @@
   ],
   "dependencies": {
     "fast-xml-parser": "^5.7.2",
-    "pngjs": "^7.0.0"
+    "pngjs": "^7.0.0",
+    "yaml": "^2.9.0"
   },
   "devDependencies": {
-    "vitest": "^4.1.2",
+    "@microsoft/api-extractor": "^7.58.7",
     "@rslib/core": "0.20.1",
     "@types/node": "^22.0.0",
     "@types/pngjs": "^6.0.5",
+    "@vitest/coverage-v8": "4.1.2",
     "fallow": "^2.52.0",
     "oxfmt": "^0.42.0",
     "oxlint": "^1.57.0",
     "skillgym": "^0.8.0",
     "typescript": "^6.0.2",
-    "vite": "^8.0.10"
+    "vite": "^8.0.10",
+    "vitest": "^4.1.2"
   }
 }

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": "Let AI agents inspect, control, and debug real iOS, Android, desktop, and TV apps",
   "repository": {
     "url": "https://github.com/callstackincubator/agent-device",
     "source": "github"
   },
-  "version": "0.14.8",
+  "version": "0.15.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "agent-device",
-      "version": "0.14.8",
+      "version": "0.15.0",
       "transport": {
         "type": "stdio"
       }

package/skills/agent-device/SKILL.md

@@ -11,7 +11,9 @@ 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 may have installed `agent-device` globally, check the user's configured login/interactive shell and environment before using `npx`. Resolve the command the same way the user would from a normal terminal session, then run the absolute binary path if found. This may require inspecting shell startup behavior or package-manager/global bin locations; do not assume the Codex process `PATH` is the user's `PATH`.
+
+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:
 
@@ -23,6 +25,7 @@ Escalate only when relevant:
 
 ```bash
 agent-device help debugging
+agent-device help react-native
 agent-device help react-devtools
 agent-device help remote
 agent-device help macos
@@ -32,3 +35,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/dist/src/180.js

@@ -1 +0,0 @@
-import e from"node:path";import t from"node:crypto";import n from"node:fs";import{resolveUserPath as a,expandUserHomePath as i}from"./3267.js";import{findProjectRoot as r}from"./9671.js";function o(t){let n,r=(n=(t??"").trim())?a(n):e.join(i("~"),".agent-device");return{baseDir:r,infoPath:e.join(r,"daemon.json"),lockPath:e.join(r,"daemon.lock"),logPath:e.join(r,"daemon.log"),sessionsDir:e.join(r,"sessions")}}function s(e){let t=(e??"").trim().toLowerCase();return"http"===t?"http":"dual"===t?"dual":"socket"}function l(e){let t=(e??"").trim().toLowerCase();return"auto"===t?"auto":"socket"===t?"socket":"http"===t?"http":"auto"}function d(e){return"tenant"===(e??"").trim().toLowerCase()?"tenant":"none"}function u(e){if(!e)return;let t=e.trim();if(t&&/^[a-zA-Z0-9._-]{1,128}$/.test(t))return t}let p=/(?:^|[^\w$.])(?:import|export)\s+(?:type\s+)?(?:[^'"`]*?\s+from\s+)?['"]([^'"]+)['"]/gm,c=/import\(\s*['"]([^'"]+)['"]\s*\)/gm,m=[".ts",".tsx",".js",".jsx",".mjs",".cjs"];function f(){let e=process.argv[1];return e?h(e):"unknown"}function h(a,i=r()){try{let r=e.resolve(i),o=[e.resolve(a)],s=new Set,l=[];for(;o.length>0;){let t=o.pop();if(!t||s.has(t))continue;s.add(t);let a=n.statSync(t);if(!a.isFile())continue;let i=e.relative(r,t)||t;l.push(`${i}:${a.size}:${Math.trunc(a.mtimeMs)}`);let d=n.readFileSync(t,"utf8");for(let n of function(e){let t=new Set;return g(e,p,t),g(e,c,t),[...t]}(d)){let a=function(t,n){let a=e.resolve(e.dirname(t),n),i=I(a);if(i)return i;for(let e of m){let t=I(`${a}${e}`);if(t)return t}for(let t of m){let n=I(e.join(a,`index${t}`));if(n)return n}return null}(t,n);a&&o.push(a)}}let d=l.sort().join("|"),u=t.createHash("sha1").update(d).digest("hex");return`graph:${l.length}:${u}`}catch{return"unknown"}}function g(e,t,n){t.lastIndex=0;let a=null;for(;null!==(a=t.exec(e));){let e=a[1]?.trim();e?.startsWith(".")&&n.add(e)}}function I(e){try{return n.statSync(e).isFile()?e:null}catch{return null}}function v(e){return e?{message:e}:{}}function S(e,t){return t?{...e,message:t}:e}function b(e){return"string"==typeof e?.message&&e.message.length>0?e.message:null}function k(e){let t=e.appId??e.bundleId??e.packageName;return{session:e.session,appId:t,appBundleId:e.bundleId,package:e.packageName}}function N(e,t,n){return{deviceId:t,deviceName:n,..."android"===e?{serial:t}:"ios"===e?{udid:t}:{}}}function $(e,t={}){let n=t.includeAndroidSerial??!0;return{platform:e.platform,target:e.target,device:e.name,id:e.id,..."ios"===e.platform?{device_udid:e.ios?.udid??e.id,ios_simulator_device_set:e.ios?.simulatorSetPath??null}:{},..."android"===e.platform&&n?{serial:e.android?.serial??e.id}:{}}}function _(e){return{name:e.name,...$(e.device,{includeAndroidSerial:!1}),createdAt:e.createdAt}}function z(e){return{platform:e.platform,id:e.id,name:e.name,kind:e.kind,target:e.target,..."boolean"==typeof e.booted?{booted:e.booted}:{}}}function w(e){let t=e.created?"Created":"Reused",n=e.booted?" (booted)":"";return S({udid:e.udid,device:e.device,runtime:e.runtime,ios_simulator_device_set:e.iosSimulatorDeviceSet??null,created:e.created,booted:e.booted},`${t}: ${e.device} ${e.udid}${n}`)}function P(e){return e.bundleId??e.package??e.app}function y(e){return S({app:e.app,appPath:e.appPath,platform:e.platform,...e.appId?{appId:e.appId}:{},...e.bundleId?{bundleId:e.bundleId}:{},...e.package?{package:e.package}:{}},`Installed: ${P(e)}`)}function C(e){return e.appName??e.bundleId??e.packageName??e.launchTarget}function x(e){return S({launchTarget:e.launchTarget,...e.appName?{appName:e.appName}:{},...e.appId?{appId:e.appId}:{},...e.bundleId?{bundleId:e.bundleId}:{},...e.packageName?{package:e.packageName}:{},...e.installablePath?{installablePath:e.installablePath}:{},...e.archivePath?{archivePath:e.archivePath}:{},...e.materializationId?{materializationId:e.materializationId}:{},...e.materializationExpiresAt?{materializationExpiresAt:e.materializationExpiresAt}:{}},`Installed: ${C(e)}`)}function j(e){let t=e.appName??e.appBundleId??e.session;return S({session:e.session,...e.appName?{appName:e.appName}:{},...e.appBundleId?{appBundleId:e.appBundleId}:{},...e.startup?{startup:e.startup}:{},...e.runtime?{runtime:e.runtime}:{},...e.device?$(e.device):{}},t?`Opened: ${t}`:"Opened")}function A(e){return{session:e.session,...e.shutdown?{shutdown:e.shutdown}:{},...v(e.session?`Closed: ${e.session}`:"Closed")}}function D(e){return{nodes:e.nodes,truncated:e.truncated,...e.appName?{appName:e.appName}:{},...e.appBundleId?{appBundleId:e.appBundleId}:{},...e.visibility?{visibility:e.visibility}:{},...e.androidSnapshot?{androidSnapshot:e.androidSnapshot}:{},...e.warnings&&e.warnings.length>0?{warnings:e.warnings}:{}}}export{k as buildAppIdentifiers,N as buildDeviceIdentifiers,h as computeDaemonCodeSignature,u as normalizeTenantId,b as readCommandMessage,f as resolveDaemonCodeSignature,o as resolveDaemonPaths,s as resolveDaemonServerMode,l as resolveDaemonTransportPreference,P as resolveDeployResultTarget,C as resolveInstallFromSourceResultTarget,d as resolveSessionIsolationMode,A as serializeCloseResult,y as serializeDeployResult,z as serializeDevice,w as serializeEnsureSimulatorResult,x as serializeInstallFromSourceResult,j as serializeOpenResult,_ as serializeSessionListEntry,D as serializeSnapshotResult,v as successText,S as withSuccessText};