agent-device 0.3.0 → 0.3.1

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

@@ -9,10 +9,12 @@ import XCTest
 import Network
 
 final class RunnerTests: XCTestCase {
+  private static let springboardBundleId = "com.apple.springboard"
   private var listener: NWListener?
   private var port: UInt16 = 0
   private var doneExpectation: XCTestExpectation?
   private let app = XCUIApplication()
+  private lazy var springboard = XCUIApplication(bundleIdentifier: Self.springboardBundleId)
   private var currentApp: XCUIApplication?
   private var currentBundleId: String?
   private let maxRequestBytes = 2 * 1024 * 1024
@@ -36,6 +38,15 @@ final class RunnerTests: XCTestCase {
     .secureTextField,
     .textView,
   ]
+  // Keep blocker actions narrow to avoid false positives from generic hittable containers.
+  private let actionableTypes: Set<XCUIElement.ElementType> = [
+    .button,
+    .cell,
+    .link,
+    .menuItem,
+    .checkBox,
+    .switch,
+  ]
 
   override func setUp() {
     continueAfterFailure = false
@@ -535,6 +546,10 @@ final class RunnerTests: XCTestCase {
   }
 
   private func snapshotFast(app: XCUIApplication, options: SnapshotOptions) -> DataPayload {
+    if let blocking = blockingSystemAlertSnapshot() {
+      return blocking
+    }
+
     var nodes: [SnapshotNode] = []
     var truncated = false
     let maxDepth = options.depth ?? Int.max
@@ -636,6 +651,10 @@ final class RunnerTests: XCTestCase {
   }
 
   private func snapshotRaw(app: XCUIApplication, options: SnapshotOptions) -> DataPayload {
+    if let blocking = blockingSystemAlertSnapshot() {
+      return blocking
+    }
+
     let root = options.scope.flatMap { findScopeElement(app: app, scope: $0) } ?? app
     var nodes: [SnapshotNode] = []
     var truncated = false
@@ -688,6 +707,136 @@ final class RunnerTests: XCTestCase {
     return DataPayload(nodes: nodes, truncated: truncated)
   }
 
+  private func blockingSystemAlertSnapshot() -> DataPayload? {
+    guard let modal = firstBlockingSystemModal(in: springboard) else {
+      return nil
+    }
+    let actions = actionableElements(in: modal)
+    guard !actions.isEmpty else {
+      return nil
+    }
+
+    let title = preferredSystemModalTitle(modal)
+
+    var nodes: [SnapshotNode] = [
+      makeSnapshotNode(
+        element: modal,
+        index: 0,
+        type: "Alert",
+        labelOverride: title,
+        identifierOverride: modal.identifier,
+        depth: 0,
+        hittableOverride: true
+      )
+    ]
+
+    for action in actions {
+      nodes.append(
+        makeSnapshotNode(
+          element: action,
+          index: nodes.count,
+          type: elementTypeName(action.elementType),
+          depth: 1,
+          hittableOverride: true
+        )
+      )
+    }
+
+    return DataPayload(nodes: nodes, truncated: false)
+  }
+
+  private func firstBlockingSystemModal(in springboard: XCUIApplication) -> XCUIElement? {
+    for alert in springboard.alerts.allElementsBoundByIndex {
+      if isBlockingSystemModal(alert, in: springboard) {
+        return alert
+      }
+    }
+
+    for sheet in springboard.sheets.allElementsBoundByIndex {
+      if isBlockingSystemModal(sheet, in: springboard) {
+        return sheet
+      }
+    }
+
+    return nil
+  }
+
+  private func isBlockingSystemModal(_ element: XCUIElement, in springboard: XCUIApplication) -> Bool {
+    guard element.exists else { return false }
+    let frame = element.frame
+    if frame.isNull || frame.isEmpty { return false }
+
+    let viewport = springboard.frame
+    if viewport.isNull || viewport.isEmpty { return false }
+
+    let center = CGPoint(x: frame.midX, y: frame.midY)
+    if !viewport.contains(center) { return false }
+
+    return true
+  }
+
+  private func actionableElements(in element: XCUIElement) -> [XCUIElement] {
+    var seen = Set<String>()
+    var actions: [XCUIElement] = []
+    let descendants = element.descendants(matching: .any).allElementsBoundByIndex
+    for candidate in descendants {
+      if !candidate.exists || !candidate.isHittable { continue }
+      if !actionableTypes.contains(candidate.elementType) { continue }
+      let frame = candidate.frame
+      if frame.isNull || frame.isEmpty { continue }
+      let key = "\(candidate.elementType.rawValue)-\(frame.origin.x)-\(frame.origin.y)-\(frame.size.width)-\(frame.size.height)-\(candidate.label)"
+      if seen.contains(key) { continue }
+      seen.insert(key)
+      actions.append(candidate)
+    }
+    return actions
+  }
+
+  private func preferredSystemModalTitle(_ element: XCUIElement) -> String {
+    let label = element.label
+    if !label.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty {
+      return label
+    }
+    let identifier = element.identifier
+    if !identifier.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty {
+      return identifier
+    }
+    return "System Alert"
+  }
+
+  private func makeSnapshotNode(
+    element: XCUIElement,
+    index: Int,
+    type: String,
+    labelOverride: String? = nil,
+    identifierOverride: String? = nil,
+    depth: Int,
+    hittableOverride: Bool? = nil
+  ) -> SnapshotNode {
+    let label = (labelOverride ?? element.label).trimmingCharacters(in: .whitespacesAndNewlines)
+    let identifier = (identifierOverride ?? element.identifier).trimmingCharacters(in: .whitespacesAndNewlines)
+    return SnapshotNode(
+      index: index,
+      type: type,
+      label: label.isEmpty ? nil : label,
+      identifier: identifier.isEmpty ? nil : identifier,
+      value: nil,
+      rect: snapshotRect(from: element.frame),
+      enabled: element.isEnabled,
+      hittable: hittableOverride ?? element.isHittable,
+      depth: depth
+    )
+  }
+
+  private func snapshotRect(from frame: CGRect) -> SnapshotRect {
+    return SnapshotRect(
+      x: Double(frame.origin.x),
+      y: Double(frame.origin.y),
+      width: Double(frame.size.width),
+      height: Double(frame.size.height)
+    )
+  }
+
   private func shouldInclude(
     element: XCUIElement,
     label: String,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-device",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Unified control plane for physical and virtual devices via an agent-driven CLI.",
   "license": "MIT",
   "author": "Callstack",
@@ -26,7 +26,7 @@
     "prepack": "pnpm build:node && pnpm build:axsnapshot",
     "typecheck": "tsc -p tsconfig.json",
     "test": "node --test",
-    "test:unit": "node --test src/core/__tests__/*.test.ts src/daemon/__tests__/*.test.ts src/daemon/handlers/__tests__/*.test.ts src/platforms/**/__tests__/*.test.ts",
+    "test:unit": "node --test src/core/__tests__/*.test.ts src/daemon/__tests__/*.test.ts src/daemon/handlers/__tests__/*.test.ts src/platforms/**/__tests__/*.test.ts src/utils/**/__tests__/*.test.ts",
     "test:smoke": "node --test test/integration/smoke-*.test.ts",
     "test:integration": "node --test test/integration/*.test.ts"
   },

package/src/cli.ts

@@ -1,6 +1,7 @@
 import { parseArgs, usage } from './utils/args.ts';
 import { asAppError, AppError } from './utils/errors.ts';
 import { formatSnapshotText, printHumanError, printJson } from './utils/output.ts';
+import { readVersion } from './utils/version.ts';
 import { pathToFileURL } from 'node:url';
 import { sendToDaemon } from './daemon-client.ts';
 import fs from 'node:fs';
@@ -10,6 +11,11 @@ import path from 'node:path';
 export async function runCli(argv: string[]): Promise<void> {
   const parsed = parseArgs(argv);
 
+  if (parsed.flags.version) {
+    process.stdout.write(`${readVersion()}\n`);
+    process.exit(0);
+  }
+
   if (parsed.flags.help || !parsed.command) {
     process.stdout.write(`${usage()}\n`);
     process.exit(parsed.flags.help ? 0 : 1);

package/src/daemon-client.ts

@@ -2,10 +2,10 @@ import net from 'node:net';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
-import { fileURLToPath } from 'node:url';
 import { AppError } from './utils/errors.ts';
 import type { CommandFlags } from './core/dispatch.ts';
 import { runCmdDetached } from './utils/exec.ts';
+import { findProjectRoot, readVersion } from './utils/version.ts';
 
 export type DaemonRequest = {
   token: string;
@@ -134,18 +134,6 @@ async function sendRequest(info: DaemonInfo, req: DaemonRequest): Promise<Daemon
   });
 }
 
-function readVersion(): string {
-  try {
-    const root = findProjectRoot();
-    const pkg = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8')) as {
-      version?: string;
-    };
-    return pkg.version ?? '0.0.0';
-  } catch {
-    return '0.0.0';
-  }
-}
-
 function resolveRequestTimeoutMs(): number {
   const raw = process.env.AGENT_DEVICE_DAEMON_TIMEOUT_MS;
   if (!raw) return 60000;
@@ -153,14 +141,3 @@ function resolveRequestTimeoutMs(): number {
   if (!Number.isFinite(parsed)) return 60000;
   return Math.max(1000, Math.floor(parsed));
 }
-
-function findProjectRoot(): string {
-  const start = path.dirname(fileURLToPath(import.meta.url));
-  let current = start;
-  for (let i = 0; i < 6; i += 1) {
-    const pkgPath = path.join(current, 'package.json');
-    if (fs.existsSync(pkgPath)) return current;
-    current = path.dirname(current);
-  }
-  return start;
-}

package/src/daemon.ts

@@ -3,10 +3,10 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import crypto from 'node:crypto';
-import { fileURLToPath } from 'node:url';
 import { dispatchCommand, type CommandFlags } from './core/dispatch.ts';
 import { isCommandSupportedOnDevice } from './core/capabilities.ts';
 import { asAppError, AppError } from './utils/errors.ts';
+import { readVersion } from './utils/version.ts';
 import { stopIosRunnerSession } from './platforms/ios/runner-client.ts';
 import type { DaemonRequest, DaemonResponse } from './daemon/types.ts';
 import { SessionStore } from './daemon/session-store.ts';
@@ -203,26 +203,3 @@ function start(): void {
 }
 
 start();
-
-function readVersion(): string {
-  try {
-    const root = findProjectRoot();
-    const pkg = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8')) as {
-      version?: string;
-    };
-    return pkg.version ?? '0.0.0';
-  } catch {
-    return '0.0.0';
-  }
-}
-
-function findProjectRoot(): string {
-  const start = path.dirname(fileURLToPath(import.meta.url));
-  let current = start;
-  for (let i = 0; i < 6; i += 1) {
-    const pkgPath = path.join(current, 'package.json');
-    if (fs.existsSync(pkgPath)) return current;
-    current = path.dirname(current);
-  }
-  return start;
-}

package/src/platforms/__tests__/boot-diagnostics.test.ts

@@ -0,0 +1,30 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { classifyBootFailure } from '../boot-diagnostics.ts';
+import { AppError } from '../../utils/errors.ts';
+
+test('classifyBootFailure maps timeout errors', () => {
+  const reason = classifyBootFailure({ message: 'bootstatus timed out after 120s' });
+  assert.equal(reason, 'BOOT_TIMEOUT');
+});
+
+test('classifyBootFailure maps adb offline errors', () => {
+  const reason = classifyBootFailure({ stderr: 'error: device offline' });
+  assert.equal(reason, 'DEVICE_OFFLINE');
+});
+
+test('classifyBootFailure maps tool missing from AppError code', () => {
+  const reason = classifyBootFailure({
+    error: new AppError('TOOL_MISSING', 'adb not found in PATH'),
+  });
+  assert.equal(reason, 'TOOL_MISSING');
+});
+
+test('classifyBootFailure reads stderr from AppError details', () => {
+  const reason = classifyBootFailure({
+    error: new AppError('COMMAND_FAILED', 'adb failed', {
+      stderr: 'error: device unauthorized',
+    }),
+  });
+  assert.equal(reason, 'PERMISSION_DENIED');
+});

package/src/platforms/android/devices.ts

@@ -1,6 +1,39 @@
 import { runCmd, whichCmd } from '../../utils/exec.ts';
-import { AppError } from '../../utils/errors.ts';
+import type { ExecResult } from '../../utils/exec.ts';
+import { AppError, asAppError } from '../../utils/errors.ts';
 import type { DeviceInfo } from '../../utils/device.ts';
+import { Deadline, retryWithPolicy } from '../../utils/retry.ts';
+import { classifyBootFailure } from '../boot-diagnostics.ts';
+
+const EMULATOR_SERIAL_PREFIX = 'emulator-';
+const ANDROID_BOOT_POLL_MS = 1000;
+
+function adbArgs(serial: string, args: string[]): string[] {
+  return ['-s', serial, ...args];
+}
+
+function isEmulatorSerial(serial: string): boolean {
+  return serial.startsWith(EMULATOR_SERIAL_PREFIX);
+}
+
+async function readAndroidBootProp(serial: string): Promise<ExecResult> {
+  return runCmd('adb', adbArgs(serial, ['shell', 'getprop', 'sys.boot_completed']), {
+    allowFailure: true,
+  });
+}
+
+async function resolveAndroidDeviceName(serial: string, rawModel: string): Promise<string> {
+  const modelName = rawModel.replace(/_/g, ' ').trim();
+  if (!isEmulatorSerial(serial)) return modelName || serial;
+  const avd = await runCmd('adb', adbArgs(serial, ['emu', 'avd', 'name']), {
+    allowFailure: true,
+  });
+  const avdName = avd.stdout.trim();
+  if (avd.exitCode === 0 && avdName) {
+    return avdName.replace(/_/g, ' ');
+  }
+  return modelName || serial;
+}
 
 export async function listAndroidDevices(): Promise<DeviceInfo[]> {
   const adbAvailable = await whichCmd('adb');
@@ -10,62 +43,121 @@ export async function listAndroidDevices(): Promise<DeviceInfo[]> {
 
   const result = await runCmd('adb', ['devices', '-l']);
   const lines = result.stdout.split('\n').map((l: string) => l.trim());
-  const devices: DeviceInfo[] = [];
+  const entries = lines
+    .filter((line) => line.length > 0 && !line.startsWith('List of devices'))
+    .map((line) => line.split(/\s+/))
+    .filter((parts) => parts[1] === 'device')
+    .map((parts) => ({
+      serial: parts[0],
+      rawModel: (parts.find((p: string) => p.startsWith('model:')) ?? '').replace('model:', ''),
+    }));
 
-  for (const line of lines) {
-    if (!line || line.startsWith('List of devices')) continue;
-    const parts = line.split(/\s+/);
-    const serial = parts[0];
-    const state = parts[1];
-    if (state !== 'device') continue;
-
-    const modelPart = parts.find((p: string) => p.startsWith('model:')) ?? '';
-    const rawModel = modelPart.replace('model:', '').replace(/_/g, ' ').trim();
-    let name = rawModel || serial;
-
-    if (serial.startsWith('emulator-')) {
-      const avd = await runCmd('adb', ['-s', serial, 'emu', 'avd', 'name'], {
-        allowFailure: true,
-      });
-      const avdName = (avd.stdout as string).trim();
-      if (avd.exitCode === 0 && avdName) {
-        name = avdName.replace(/_/g, ' ');
-      }
-    }
-
-    const booted = await isAndroidBooted(serial);
-
-    devices.push({
+  const devices = await Promise.all(entries.map(async ({ serial, rawModel }) => {
+    const [name, booted] = await Promise.all([
+      resolveAndroidDeviceName(serial, rawModel),
+      isAndroidBooted(serial),
+    ]);
+    return {
       platform: 'android',
       id: serial,
       name,
-      kind: serial.startsWith('emulator-') ? 'emulator' : 'device',
+      kind: isEmulatorSerial(serial) ? 'emulator' : 'device',
       booted,
-    });
-  }
+    } satisfies DeviceInfo;
+  }));
 
   return devices;
 }
 
 export async function isAndroidBooted(serial: string): Promise<boolean> {
   try {
-    const result = await runCmd('adb', ['-s', serial, 'shell', 'getprop', 'sys.boot_completed'], {
-      allowFailure: true,
-    });
-    return (result.stdout as string).trim() === '1';
+    const result = await readAndroidBootProp(serial);
+    return result.stdout.trim() === '1';
   } catch {
     return false;
   }
 }
 
 export async function waitForAndroidBoot(serial: string, timeoutMs = 60000): Promise<void> {
-  const start = Date.now();
-  while (Date.now() - start < timeoutMs) {
-    if (await isAndroidBooted(serial)) return;
-    await new Promise((resolve) => setTimeout(resolve, 1000));
+  const deadline = Deadline.fromTimeoutMs(timeoutMs);
+  const maxAttempts = Math.max(1, Math.ceil(timeoutMs / ANDROID_BOOT_POLL_MS));
+  let lastBootResult: ExecResult | undefined;
+  let timedOut = false;
+  try {
+    await retryWithPolicy(
+      async ({ deadline: attemptDeadline }) => {
+        if (attemptDeadline?.isExpired()) {
+          timedOut = true;
+          throw new AppError('COMMAND_FAILED', 'Android boot deadline exceeded', {
+            serial,
+            timeoutMs,
+            elapsedMs: deadline.elapsedMs(),
+            message: 'timeout',
+          });
+        }
+        const result = await readAndroidBootProp(serial);
+        lastBootResult = result;
+        if (result.stdout.trim() === '1') return;
+        throw new AppError('COMMAND_FAILED', 'Android device is still booting', {
+          serial,
+          stdout: result.stdout,
+          stderr: result.stderr,
+          exitCode: result.exitCode,
+        });
+      },
+      {
+        maxAttempts,
+        baseDelayMs: ANDROID_BOOT_POLL_MS,
+        maxDelayMs: ANDROID_BOOT_POLL_MS,
+        jitter: 0,
+        shouldRetry: (error) => {
+          const reason = classifyBootFailure({
+            error,
+            stdout: lastBootResult?.stdout,
+            stderr: lastBootResult?.stderr,
+          });
+          return reason !== 'PERMISSION_DENIED' && reason !== 'TOOL_MISSING' && reason !== 'BOOT_TIMEOUT';
+        },
+      },
+      { deadline },
+    );
+  } catch (error) {
+    const appErr = asAppError(error);
+    const stdout = lastBootResult?.stdout;
+    const stderr = lastBootResult?.stderr;
+    const exitCode = lastBootResult?.exitCode;
+    const reason = classifyBootFailure({
+      error,
+      stdout,
+      stderr,
+    });
+    const baseDetails = {
+      serial,
+      timeoutMs,
+      elapsedMs: deadline.elapsedMs(),
+      reason,
+      stdout,
+      stderr,
+      exitCode,
+    };
+    if (timedOut || reason === 'BOOT_TIMEOUT') {
+      throw new AppError('COMMAND_FAILED', 'Android device did not finish booting in time', baseDetails);
+    }
+    if (appErr.code === 'TOOL_MISSING' || reason === 'TOOL_MISSING') {
+      throw new AppError('TOOL_MISSING', appErr.message, {
+        ...baseDetails,
+        ...(appErr.details ?? {}),
+      });
+    }
+    if (reason === 'PERMISSION_DENIED' || reason === 'DEVICE_UNAVAILABLE' || reason === 'DEVICE_OFFLINE') {
+      throw new AppError('COMMAND_FAILED', appErr.message, {
+        ...baseDetails,
+        ...(appErr.details ?? {}),
+      });
+    }
+    throw new AppError(appErr.code, appErr.message, {
+      ...baseDetails,
+      ...(appErr.details ?? {}),
+    }, appErr.cause);
   }
-  throw new AppError('COMMAND_FAILED', 'Android device did not finish booting in time', {
-    serial,
-    timeoutMs,
-  });
 }

package/src/platforms/boot-diagnostics.ts

@@ -0,0 +1,67 @@
+import { asAppError } from '../utils/errors.ts';
+
+export type BootFailureReason =
+  | 'BOOT_TIMEOUT'
+  | 'DEVICE_UNAVAILABLE'
+  | 'DEVICE_OFFLINE'
+  | 'PERMISSION_DENIED'
+  | 'TOOL_MISSING'
+  | 'BOOT_COMMAND_FAILED'
+  | 'UNKNOWN';
+
+export function classifyBootFailure(input: {
+  error?: unknown;
+  message?: string;
+  stdout?: string;
+  stderr?: string;
+}): BootFailureReason {
+  const appErr = input.error ? asAppError(input.error) : null;
+  if (appErr?.code === 'TOOL_MISSING') return 'TOOL_MISSING';
+  const details = (appErr?.details ?? {}) as Record<string, unknown>;
+  const detailMessage = typeof details.message === 'string' ? details.message : undefined;
+  const detailStdout = typeof details.stdout === 'string' ? details.stdout : undefined;
+  const detailStderr = typeof details.stderr === 'string' ? details.stderr : undefined;
+  const nestedBoot = details.boot && typeof details.boot === 'object'
+    ? (details.boot as Record<string, unknown>)
+    : null;
+  const nestedBootstatus = details.bootstatus && typeof details.bootstatus === 'object'
+    ? (details.bootstatus as Record<string, unknown>)
+    : null;
+
+  const haystack = [
+    input.message,
+    appErr?.message,
+    input.stdout,
+    input.stderr,
+    detailMessage,
+    detailStdout,
+    detailStderr,
+    typeof nestedBoot?.stdout === 'string' ? nestedBoot.stdout : undefined,
+    typeof nestedBoot?.stderr === 'string' ? nestedBoot.stderr : undefined,
+    typeof nestedBootstatus?.stdout === 'string' ? nestedBootstatus.stdout : undefined,
+    typeof nestedBootstatus?.stderr === 'string' ? nestedBootstatus.stderr : undefined,
+  ]
+    .filter(Boolean)
+    .join('\n')
+    .toLowerCase();
+
+  if (haystack.includes('timed out') || haystack.includes('timeout')) return 'BOOT_TIMEOUT';
+  if (
+    haystack.includes('device not found') ||
+    haystack.includes('no devices') ||
+    haystack.includes('unable to locate device') ||
+    haystack.includes('invalid device')
+  ) {
+    return 'DEVICE_UNAVAILABLE';
+  }
+  if (haystack.includes('offline')) return 'DEVICE_OFFLINE';
+  if (
+    haystack.includes('permission denied') ||
+    haystack.includes('not authorized') ||
+    haystack.includes('unauthorized')
+  ) {
+    return 'PERMISSION_DENIED';
+  }
+  if (appErr?.code === 'COMMAND_FAILED' || haystack.length > 0) return 'BOOT_COMMAND_FAILED';
+  return 'UNKNOWN';
+}