agent-device 0.3.0 → 0.3.2

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.2",
   "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/skills/agent-device/SKILL.md

@@ -27,7 +27,7 @@ npx -y agent-device
 
 ## Core workflow
 
-1. Open app or just boot device: `open [app]`
+1. Open app: `open [app]` (`open` handles target selection + boot/activation in the normal flow)
 2. Snapshot: `snapshot` to get refs from accessibility tree
 3. Interact using refs (`click @ref`, `fill @ref "text"`)
 4. Re-snapshot after navigation/UI changes
@@ -38,12 +38,19 @@ npx -y agent-device
 ### Navigation
 
 ```bash
+agent-device boot                 # Ensure target is booted/ready without opening app
+agent-device boot --platform ios  # Boot iOS simulator
+agent-device boot --platform android # Boot Android emulator/device target
 agent-device open [app]           # Boot device/simulator; optionally launch app
 agent-device open [app] --activity com.example/.MainActivity # Android: open specific activity
 agent-device close [app]          # Close app or just end session
+agent-device reinstall <app> <path> # Uninstall + install app in one command
 agent-device session list         # List active sessions
 ```
 
+`boot` requires either an active session or an explicit selector (`--platform`, `--device`, `--udid`, or `--serial`).
+`boot` is a fallback, not a regular step: use it when starting a new session only if `open` cannot find/connect to an available target.
+
 ### Snapshot (page analysis)
 
 ```bash

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);
@@ -99,6 +105,13 @@ export async function runCli(argv: string[]): Promise<void> {
         if (logTailStopper) logTailStopper();
         return;
       }
+      if (command === 'boot') {
+        const platform = (response.data as any)?.platform ?? 'unknown';
+        const device = (response.data as any)?.device ?? (response.data as any)?.id ?? 'unknown';
+        process.stdout.write(`Boot ready: ${device} (${platform})\n`);
+        if (logTailStopper) logTailStopper();
+        return;
+      }
       if (command === 'click') {
         const ref = (response.data as any)?.ref ?? '';
         const x = (response.data as any)?.x;

package/src/core/__tests__/capabilities.test.ts

@@ -37,6 +37,7 @@ test('iOS simulator + Android commands reject iOS devices', () => {
     'app-switcher',
     'apps',
     'back',
+    'boot',
     'click',
     'close',
     'fill',
@@ -46,6 +47,7 @@ test('iOS simulator + Android commands reject iOS devices', () => {
     'home',
     'long-press',
     'open',
+    'reinstall',
     'press',
     'record',
     'screenshot',

package/src/core/capabilities.ts

@@ -19,6 +19,7 @@ const COMMAND_CAPABILITY_MATRIX: Record<string, CommandCapability> = {
   'app-switcher': { ios: { simulator: true }, android: { emulator: true, device: true, unknown: true } },
   apps: { ios: { simulator: true }, android: { emulator: true, device: true, unknown: true } },
   back: { ios: { simulator: true }, android: { emulator: true, device: true, unknown: true } },
+  boot: { ios: { simulator: true }, android: { emulator: true, device: true, unknown: true } },
   click: { ios: { simulator: true }, android: { emulator: true, device: true, unknown: true } },
   close: { ios: { simulator: true }, android: { emulator: true, device: true, unknown: true } },
   fill: { ios: { simulator: true }, android: { emulator: true, device: true, unknown: true } },
@@ -29,6 +30,7 @@ const COMMAND_CAPABILITY_MATRIX: Record<string, CommandCapability> = {
   home: { ios: { simulator: true }, android: { emulator: true, device: true, unknown: true } },
   'long-press': { ios: { simulator: true }, android: { emulator: true, device: true, unknown: true } },
   open: { ios: { simulator: true }, android: { emulator: true, device: true, unknown: true } },
+  reinstall: { ios: { simulator: true }, android: { emulator: true, device: true, unknown: true } },
   press: { ios: { simulator: true }, android: { emulator: true, device: true, unknown: true } },
   record: { ios: { simulator: true }, android: { emulator: true, device: true, unknown: true } },
   screenshot: { ios: { simulator: true }, android: { emulator: true, device: true, unknown: true } },

package/src/daemon/handlers/__tests__/replay-heal.test.ts

@@ -225,6 +225,11 @@ test('replay without --update does not heal or rewrite', async () => {
 
   assert.ok(response);
   assert.equal(response.ok, false);
+  if (!response.ok) {
+    assert.match(response.error.message, /Replay failed at step 1/);
+    assert.equal(response.error.details?.step, 1);
+    assert.equal(response.error.details?.action, 'click');
+  }
   assert.equal(snapshotDispatchCalls, 0);
   assert.equal(fs.readFileSync(replayPath, 'utf8'), originalPayload);
 });

package/src/daemon/handlers/__tests__/session-reinstall.test.ts

@@ -0,0 +1,219 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { handleSessionCommands } from '../session.ts';
+import { SessionStore } from '../../session-store.ts';
+import type { DaemonRequest, DaemonResponse, SessionState } from '../../types.ts';
+
+function makeStore(): SessionStore {
+  const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-device-session-reinstall-'));
+  return new SessionStore(path.join(tempRoot, 'sessions'));
+}
+
+function makeSession(name: string, device: SessionState['device']): SessionState {
+  return {
+    name,
+    device,
+    createdAt: Date.now(),
+    actions: [],
+  };
+}
+
+const invoke = async (_req: DaemonRequest): Promise<DaemonResponse> => {
+  return { ok: false, error: { code: 'INVALID_ARGS', message: 'invoke should not be called in reinstall tests' } };
+};
+
+test('reinstall requires active session or explicit device selector', async () => {
+  const sessionStore = makeStore();
+  const response = await handleSessionCommands({
+    req: {
+      token: 't',
+      session: 'default',
+      command: 'reinstall',
+      positionals: ['com.example.app', '/tmp/app.apk'],
+      flags: {},
+    },
+    sessionName: 'default',
+    logPath: '/tmp/daemon.log',
+    sessionStore,
+    invoke,
+  });
+  assert.ok(response);
+  assert.equal(response.ok, false);
+  if (!response.ok) {
+    assert.equal(response.error.code, 'INVALID_ARGS');
+    assert.match(response.error.message, /active session or an explicit device selector/i);
+  }
+});
+
+test('reinstall validates required args before device operations', async () => {
+  const sessionStore = makeStore();
+  sessionStore.set(
+    'default',
+    makeSession('default', {
+      platform: 'ios',
+      id: 'sim-1',
+      name: 'iPhone',
+      kind: 'simulator',
+      booted: true,
+    }),
+  );
+  const response = await handleSessionCommands({
+    req: {
+      token: 't',
+      session: 'default',
+      command: 'reinstall',
+      positionals: ['com.example.app'],
+      flags: {},
+    },
+    sessionName: 'default',
+    logPath: '/tmp/daemon.log',
+    sessionStore,
+    invoke,
+  });
+  assert.ok(response);
+  assert.equal(response.ok, false);
+  if (!response.ok) {
+    assert.equal(response.error.code, 'INVALID_ARGS');
+    assert.match(response.error.message, /reinstall <app> <path-to-app-binary>/i);
+  }
+});
+
+test('reinstall reports unsupported operation on iOS physical devices', async () => {
+  const sessionStore = makeStore();
+  sessionStore.set(
+    'default',
+    makeSession('default', {
+      platform: 'ios',
+      id: 'device-1',
+      name: 'iPhone Device',
+      kind: 'device',
+      booted: true,
+    }),
+  );
+  const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-device-reinstall-binary-'));
+  const appPath = path.join(tempRoot, 'Sample.app');
+  fs.writeFileSync(appPath, 'placeholder');
+
+  const response = await handleSessionCommands({
+    req: {
+      token: 't',
+      session: 'default',
+      command: 'reinstall',
+      positionals: ['com.example.app', appPath],
+      flags: {},
+    },
+    sessionName: 'default',
+    logPath: '/tmp/daemon.log',
+    sessionStore,
+    invoke,
+  });
+  assert.ok(response);
+  assert.equal(response.ok, false);
+  if (!response.ok) {
+    assert.equal(response.error.code, 'UNSUPPORTED_OPERATION');
+    assert.match(response.error.message, /reinstall is not supported/i);
+  }
+});
+
+test('reinstall succeeds on active iOS simulator session and records action', async () => {
+  const sessionStore = makeStore();
+  const session = makeSession('default', {
+    platform: 'ios',
+    id: 'sim-1',
+    name: 'iPhone',
+    kind: 'simulator',
+    booted: true,
+  });
+  sessionStore.set('default', session);
+  const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-device-reinstall-success-ios-'));
+  const appPath = path.join(tempRoot, 'Sample.app');
+  fs.writeFileSync(appPath, 'placeholder');
+
+  const response = await handleSessionCommands({
+    req: {
+      token: 't',
+      session: 'default',
+      command: 'reinstall',
+      positionals: ['com.example.app', appPath],
+      flags: {},
+    },
+    sessionName: 'default',
+    logPath: '/tmp/daemon.log',
+    sessionStore,
+    invoke,
+    reinstallOps: {
+      ios: async (_device, app, pathToBinary) => {
+        assert.equal(app, 'com.example.app');
+        assert.equal(pathToBinary, appPath);
+        return { bundleId: 'com.example.app' };
+      },
+      android: async () => {
+        throw new Error('unexpected android reinstall');
+      },
+    },
+  });
+
+  assert.ok(response);
+  assert.equal(response.ok, true);
+  if (response.ok) {
+    assert.equal(response.data?.platform, 'ios');
+    assert.equal(response.data?.appId, 'com.example.app');
+    assert.equal(response.data?.bundleId, 'com.example.app');
+    assert.equal(response.data?.appPath, appPath);
+  }
+  assert.equal(session.actions.length, 1);
+  assert.equal(session.actions[0]?.command, 'reinstall');
+});
+
+test('reinstall succeeds on active Android session with normalized appId', async () => {
+  const sessionStore = makeStore();
+  sessionStore.set(
+    'default',
+    makeSession('default', {
+      platform: 'android',
+      id: 'emulator-5554',
+      name: 'Pixel',
+      kind: 'emulator',
+      booted: true,
+    }),
+  );
+  const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-device-reinstall-success-android-'));
+  const appPath = path.join(tempRoot, 'Sample.apk');
+  fs.writeFileSync(appPath, 'placeholder');
+
+  const response = await handleSessionCommands({
+    req: {
+      token: 't',
+      session: 'default',
+      command: 'reinstall',
+      positionals: ['com.example.app', appPath],
+      flags: {},
+    },
+    sessionName: 'default',
+    logPath: '/tmp/daemon.log',
+    sessionStore,
+    invoke,
+    reinstallOps: {
+      ios: async () => {
+        throw new Error('unexpected ios reinstall');
+      },
+      android: async (_device, app, pathToBinary) => {
+        assert.equal(app, 'com.example.app');
+        assert.equal(pathToBinary, appPath);
+        return { package: 'com.example.app' };
+      },
+    },
+  });
+
+  assert.ok(response);
+  assert.equal(response.ok, true);
+  if (response.ok) {
+    assert.equal(response.data?.platform, 'android');
+    assert.equal(response.data?.appId, 'com.example.app');
+    assert.equal(response.data?.package, 'com.example.app');
+    assert.equal(response.data?.appPath, appPath);
+  }
+});

package/src/daemon/handlers/__tests__/session.test.ts

@@ -0,0 +1,122 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { handleSessionCommands } from '../session.ts';
+import { SessionStore } from '../../session-store.ts';
+import type { DaemonRequest, DaemonResponse, SessionState } from '../../types.ts';
+
+function makeSessionStore(): SessionStore {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-device-session-handler-'));
+  return new SessionStore(path.join(root, 'sessions'));
+}
+
+function makeSession(name: string, device: SessionState['device']): SessionState {
+  return {
+    name,
+    device,
+    createdAt: Date.now(),
+    actions: [],
+  };
+}
+
+const noopInvoke = async (_req: DaemonRequest): Promise<DaemonResponse> => ({ ok: true, data: {} });
+
+test('boot requires session or explicit selector', async () => {
+  const sessionStore = makeSessionStore();
+  const response = await handleSessionCommands({
+    req: {
+      token: 't',
+      session: 'default',
+      command: 'boot',
+      positionals: [],
+      flags: {},
+    },
+    sessionName: 'default',
+    logPath: path.join(os.tmpdir(), 'daemon.log'),
+    sessionStore,
+    invoke: noopInvoke,
+    ensureReady: async () => {},
+  });
+  assert.ok(response);
+  assert.equal(response?.ok, false);
+  if (response && !response.ok) {
+    assert.equal(response.error.code, 'INVALID_ARGS');
+  }
+});
+
+test('boot rejects unsupported iOS device kind', async () => {
+  const sessionStore = makeSessionStore();
+  const sessionName = 'ios-device-session';
+  sessionStore.set(
+    sessionName,
+    makeSession(sessionName, {
+      platform: 'ios',
+      id: 'ios-device-1',
+      name: 'iPhone Device',
+      kind: 'device',
+      booted: true,
+    }),
+  );
+  const response = await handleSessionCommands({
+    req: {
+      token: 't',
+      session: sessionName,
+      command: 'boot',
+      positionals: [],
+      flags: {},
+    },
+    sessionName,
+    logPath: path.join(os.tmpdir(), 'daemon.log'),
+    sessionStore,
+    invoke: noopInvoke,
+    ensureReady: async () => {
+      throw new Error('ensureReady should not be called for unsupported boot');
+    },
+  });
+  assert.ok(response);
+  assert.equal(response?.ok, false);
+  if (response && !response.ok) {
+    assert.equal(response.error.code, 'UNSUPPORTED_OPERATION');
+  }
+});
+
+test('boot succeeds for supported device in session', async () => {
+  const sessionStore = makeSessionStore();
+  const sessionName = 'android-session';
+  sessionStore.set(
+    sessionName,
+    makeSession(sessionName, {
+      platform: 'android',
+      id: 'emulator-5554',
+      name: 'Pixel Emulator',
+      kind: 'emulator',
+      booted: true,
+    }),
+  );
+  let ensureCalls = 0;
+  const response = await handleSessionCommands({
+    req: {
+      token: 't',
+      session: sessionName,
+      command: 'boot',
+      positionals: [],
+      flags: {},
+    },
+    sessionName,
+    logPath: path.join(os.tmpdir(), 'daemon.log'),
+    sessionStore,
+    invoke: noopInvoke,
+    ensureReady: async () => {
+      ensureCalls += 1;
+    },
+  });
+  assert.ok(response);
+  assert.equal(response?.ok, true);
+  assert.equal(ensureCalls, 1);
+  if (response && response.ok) {
+    assert.equal(response.data?.platform, 'android');
+    assert.equal(response.data?.booted, true);
+  }
+});