agent-device 0.3.0 → 0.3.2

package/src/platforms/ios/index.ts

@@ -1,11 +1,21 @@
 import { runCmd } from '../../utils/exec.ts';
+import type { ExecResult } from '../../utils/exec.ts';
 import { AppError } from '../../utils/errors.ts';
 import type { DeviceInfo } from '../../utils/device.ts';
+import { Deadline, isEnvTruthy, retryWithPolicy, TIMEOUT_PROFILES, type RetryTelemetryEvent } from '../../utils/retry.ts';
+import { bootFailureHint, classifyBootFailure } from '../boot-diagnostics.ts';
 
 const ALIASES: Record<string, string> = {
   settings: 'com.apple.Preferences',
 };
 
+const IOS_BOOT_TIMEOUT_MS = resolveTimeoutMs(
+  process.env.AGENT_DEVICE_IOS_BOOT_TIMEOUT_MS,
+  TIMEOUT_PROFILES.ios_boot.totalMs,
+  5_000,
+);
+const RETRY_LOGS_ENABLED = isEnvTruthy(process.env.AGENT_DEVICE_RETRY_LOGS);
+
 export async function resolveIosApp(device: DeviceInfo, app: string): Promise<string> {
   const trimmed = app.trim();
   if (trimmed.includes('.')) return trimmed;
@@ -83,6 +93,42 @@ export async function closeIosApp(device: DeviceInfo, app: string): Promise<void
   ]);
 }
 
+export async function uninstallIosApp(device: DeviceInfo, app: string): Promise<{ bundleId: string }> {
+  ensureSimulator(device, 'reinstall');
+  const bundleId = await resolveIosApp(device, app);
+  await ensureBootedSimulator(device);
+  const result = await runCmd('xcrun', ['simctl', 'uninstall', device.id, bundleId], {
+    allowFailure: true,
+  });
+  if (result.exitCode !== 0) {
+    const output = `${result.stdout}\n${result.stderr}`.toLowerCase();
+    if (!output.includes('not installed') && !output.includes('not found') && !output.includes('no such file')) {
+      throw new AppError('COMMAND_FAILED', `simctl uninstall failed for ${bundleId}`, {
+        stdout: result.stdout,
+        stderr: result.stderr,
+        exitCode: result.exitCode,
+      });
+    }
+  }
+  return { bundleId };
+}
+
+export async function installIosApp(device: DeviceInfo, appPath: string): Promise<void> {
+  ensureSimulator(device, 'reinstall');
+  await ensureBootedSimulator(device);
+  await runCmd('xcrun', ['simctl', 'install', device.id, appPath]);
+}
+
+export async function reinstallIosApp(
+  device: DeviceInfo,
+  app: string,
+  appPath: string,
+): Promise<{ bundleId: string }> {
+  const { bundleId } = await uninstallIosApp(device, app);
+  await installIosApp(device, appPath);
+  return { bundleId };
+}
+
 export async function screenshotIos(device: DeviceInfo, outPath: string): Promise<void> {
   if (device.kind === 'simulator') {
     await ensureBootedSimulator(device);
@@ -207,13 +253,119 @@ export async function ensureBootedSimulator(device: DeviceInfo): Promise<void> {
   if (device.kind !== 'simulator') return;
   const state = await getSimulatorState(device.id);
   if (state === 'Booted') return;
-  await runCmd('xcrun', ['simctl', 'boot', device.id], { allowFailure: true });
-  await runCmd('xcrun', ['simctl', 'bootstatus', device.id, '-b'], { allowFailure: true });
+  const deadline = Deadline.fromTimeoutMs(IOS_BOOT_TIMEOUT_MS);
+  let bootResult: ExecResult | undefined;
+  let bootStatusResult: ExecResult | undefined;
+  try {
+    await retryWithPolicy(
+      async ({ deadline: attemptDeadline }) => {
+        if (attemptDeadline?.isExpired()) {
+          throw new AppError('COMMAND_FAILED', 'iOS simulator boot deadline exceeded', {
+            timeoutMs: IOS_BOOT_TIMEOUT_MS,
+          });
+        }
+        const remainingMs = Math.max(1_000, attemptDeadline?.remainingMs() ?? IOS_BOOT_TIMEOUT_MS);
+        bootResult = await runCmd('xcrun', ['simctl', 'boot', device.id], {
+          allowFailure: true,
+          timeoutMs: remainingMs,
+        });
+        const bootOutput = `${bootResult.stdout}\n${bootResult.stderr}`.toLowerCase();
+        const bootAlreadyDone =
+          bootOutput.includes('already booted') || bootOutput.includes('current state: booted');
+        if (bootResult.exitCode !== 0 && !bootAlreadyDone) {
+          throw new AppError('COMMAND_FAILED', 'simctl boot failed', {
+            stdout: bootResult.stdout,
+            stderr: bootResult.stderr,
+            exitCode: bootResult.exitCode,
+          });
+        }
+        bootStatusResult = await runCmd('xcrun', ['simctl', 'bootstatus', device.id, '-b'], {
+          allowFailure: true,
+          timeoutMs: remainingMs,
+        });
+        if (bootStatusResult.exitCode !== 0) {
+          throw new AppError('COMMAND_FAILED', 'simctl bootstatus failed', {
+            stdout: bootStatusResult.stdout,
+            stderr: bootStatusResult.stderr,
+            exitCode: bootStatusResult.exitCode,
+          });
+        }
+        const nextState = await getSimulatorState(device.id);
+        if (nextState !== 'Booted') {
+          throw new AppError('COMMAND_FAILED', 'Simulator is still booting', {
+            state: nextState,
+          });
+        }
+      },
+      {
+        maxAttempts: 3,
+        baseDelayMs: 500,
+        maxDelayMs: 2000,
+        jitter: 0.2,
+        shouldRetry: (error) => {
+          const reason = classifyBootFailure({
+            error,
+            stdout: bootStatusResult?.stdout ?? bootResult?.stdout,
+            stderr: bootStatusResult?.stderr ?? bootResult?.stderr,
+            context: { platform: 'ios', phase: 'boot' },
+          });
+          return reason !== 'IOS_BOOT_TIMEOUT' && reason !== 'CI_RESOURCE_STARVATION_SUSPECTED';
+        },
+      },
+      {
+        deadline,
+        phase: 'boot',
+        classifyReason: (error) =>
+          classifyBootFailure({
+            error,
+            stdout: bootStatusResult?.stdout ?? bootResult?.stdout,
+            stderr: bootStatusResult?.stderr ?? bootResult?.stderr,
+            context: { platform: 'ios', phase: 'boot' },
+          }),
+        onEvent: (event: RetryTelemetryEvent) => {
+          if (!RETRY_LOGS_ENABLED) return;
+          process.stderr.write(`[agent-device][retry] ${JSON.stringify(event)}\n`);
+        },
+      },
+    );
+  } catch (error) {
+    const bootStdout = bootResult?.stdout;
+    const bootStderr = bootResult?.stderr;
+    const bootExitCode = bootResult?.exitCode;
+    const bootstatusStdout = bootStatusResult?.stdout;
+    const bootstatusStderr = bootStatusResult?.stderr;
+    const bootstatusExitCode = bootStatusResult?.exitCode;
+    const reason = classifyBootFailure({
+      error,
+      stdout: bootstatusStdout ?? bootStdout,
+      stderr: bootstatusStderr ?? bootStderr,
+      context: { platform: 'ios', phase: 'boot' },
+    });
+    throw new AppError('COMMAND_FAILED', 'iOS simulator failed to boot', {
+      platform: 'ios',
+      deviceId: device.id,
+      timeoutMs: IOS_BOOT_TIMEOUT_MS,
+      elapsedMs: deadline.elapsedMs(),
+      reason,
+      hint: bootFailureHint(reason),
+      boot: bootResult
+        ? { exitCode: bootExitCode, stdout: bootStdout, stderr: bootStderr }
+        : undefined,
+      bootstatus: bootStatusResult
+        ? {
+          exitCode: bootstatusExitCode,
+          stdout: bootstatusStdout,
+          stderr: bootstatusStderr,
+        }
+        : undefined,
+    });
+  }
 }
 
 async function getSimulatorState(udid: string): Promise<string | null> {
   const result = await runCmd('xcrun', ['simctl', 'list', 'devices', '-j'], {
     allowFailure: true,
+    timeoutMs: TIMEOUT_PROFILES.ios_boot.operationMs,
   });
   if (result.exitCode !== 0) return null;
   try {
@@ -229,3 +381,10 @@ async function getSimulatorState(udid: string): Promise<string | null> {
   }
   return null;
 }
+
+function resolveTimeoutMs(raw: string | undefined, fallback: number, min: number): number {
+  if (!raw) return fallback;
+  const parsed = Number(raw);
+  if (!Number.isFinite(parsed)) return fallback;
+  return Math.max(min, Math.floor(parsed));
+}

package/src/platforms/ios/runner-client.ts

@@ -7,6 +7,7 @@ import { runCmd, runCmdStreaming, runCmdBackground, type ExecResult, type ExecBa
 import { withRetry } from '../../utils/retry.ts';
 import type { DeviceInfo } from '../../utils/device.ts';
 import net from 'node:net';
+import { bootFailureHint, classifyBootFailure } from '../boot-diagnostics.ts';
 
 export type RunnerCommand = {
   command:
@@ -204,7 +205,10 @@ export async function stopIosRunnerSession(deviceId: string): Promise<void> {
 }
 
 async function ensureBooted(udid: string): Promise<void> {
-  await runCmd('xcrun', ['simctl', 'bootstatus', udid, '-b'], { allowFailure: true });
+  await runCmd('xcrun', ['simctl', 'bootstatus', udid, '-b'], {
+    allowFailure: true,
+    timeoutMs: RUNNER_STARTUP_TIMEOUT_MS,
+  });
 }
 
 async function ensureRunnerSession(
@@ -449,6 +453,12 @@ async function waitForRunner(
     port,
     logPath,
     lastError: lastError ? String(lastError) : undefined,
+    reason: classifyBootFailure({
+      error: lastError,
+      message: 'Runner did not accept connection',
+      context: { platform: 'ios', phase: 'connect' },
+    }),
+    hint: bootFailureHint('IOS_RUNNER_CONNECT_TIMEOUT'),
   });
 }
 
@@ -478,11 +488,19 @@ async function postCommandViaSimulator(
   );
   const body = result.stdout as string;
   if (result.exitCode !== 0) {
+    const reason = classifyBootFailure({
+      message: 'Runner did not accept connection (simctl spawn)',
+      stdout: result.stdout,
+      stderr: result.stderr,
+      context: { platform: 'ios', phase: 'connect' },
+    });
     throw new AppError('COMMAND_FAILED', 'Runner did not accept connection (simctl spawn)', {
       port,
       stdout: result.stdout,
       stderr: result.stderr,
       exitCode: result.exitCode,
+      reason,
+      hint: bootFailureHint(reason),
     });
   }
   return { status: 200, body };

package/src/utils/__tests__/exec.test.ts

@@ -0,0 +1,16 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { runCmd } from '../exec.ts';
+
+test('runCmd enforces timeoutMs and rejects with COMMAND_FAILED', async () => {
+  await assert.rejects(
+    runCmd(process.execPath, ['-e', 'setTimeout(() => {}, 10_000)'], { timeoutMs: 100 }),
+    (error: unknown) => {
+      const err = error as { code?: string; message?: string; details?: Record<string, unknown> };
+      return err?.code === 'COMMAND_FAILED' &&
+        typeof err?.message === 'string' &&
+        err.message.includes('timed out') &&
+        err.details?.timeoutMs === 100;
+    },
+  );
+});

package/src/utils/__tests__/finders.test.ts

@@ -0,0 +1,34 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { findBestMatchesByLocator, findNodeByLocator } from '../finders.ts';
+import type { SnapshotNode } from '../snapshot.ts';
+
+function makeNode(ref: string, label?: string, identifier?: string): SnapshotNode {
+  return {
+    index: Number(ref.replace('e', '')) || 0,
+    ref,
+    type: 'android.widget.TextView',
+    label,
+    identifier,
+    rect: { x: 0, y: 0, width: 100, height: 20 },
+  };
+}
+
+test('findBestMatchesByLocator returns all best-scored matches', () => {
+  const nodes: SnapshotNode[] = [
+    makeNode('e1', 'Continue'),
+    makeNode('e2', 'Continue'),
+    makeNode('e3', 'Continue later'),
+  ];
+  const result = findBestMatchesByLocator(nodes, 'label', 'Continue', { requireRect: true });
+  assert.equal(result.score, 2);
+  assert.equal(result.matches.length, 2);
+  assert.equal(result.matches[0]?.ref, 'e1');
+  assert.equal(result.matches[1]?.ref, 'e2');
+});
+
+test('findNodeByLocator preserves first best match behavior', () => {
+  const nodes: SnapshotNode[] = [makeNode('e1', 'Continue'), makeNode('e2', 'Continue')];
+  const match = findNodeByLocator(nodes, 'label', 'Continue', { requireRect: true });
+  assert.equal(match?.ref, 'e1');
+});

package/src/utils/__tests__/retry.test.ts

@@ -0,0 +1,44 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { Deadline, retryWithPolicy } from '../retry.ts';
+
+test('Deadline tracks remaining and expiration', async () => {
+  const deadline = Deadline.fromTimeoutMs(25);
+  assert.equal(deadline.isExpired(), false);
+  await new Promise((resolve) => setTimeout(resolve, 30));
+  assert.equal(deadline.isExpired(), true);
+  assert.equal(deadline.remainingMs(), 0);
+});
+
+test('retryWithPolicy retries until success', async () => {
+  let attempts = 0;
+  const result = await retryWithPolicy(
+    async () => {
+      attempts += 1;
+      if (attempts < 3) {
+        throw new Error('transient');
+      }
+      return 'ok';
+    },
+    { maxAttempts: 3, baseDelayMs: 1, maxDelayMs: 1, jitter: 0 },
+  );
+  assert.equal(result, 'ok');
+  assert.equal(attempts, 3);
+});
+
+test('retryWithPolicy emits telemetry events', async () => {
+  const events: string[] = [];
+  await retryWithPolicy(
+    async ({ attempt }) => {
+      if (attempt === 1) throw new Error('transient');
+      return 'ok';
+    },
+    { maxAttempts: 2, baseDelayMs: 1, maxDelayMs: 1, jitter: 0 },
+    {
+      phase: 'boot',
+      classifyReason: () => 'ANDROID_BOOT_TIMEOUT',
+      onEvent: (event) => events.push(event.event),
+    },
+  );
+  assert.deepEqual(events, ['attempt_failed', 'retry_scheduled', 'succeeded']);
+});

package/src/utils/args.ts

@@ -25,11 +25,12 @@ export type ParsedArgs = {
     noRecord?: boolean;
     replayUpdate?: boolean;
     help: boolean;
+    version: boolean;
   };
 };
 
 export function parseArgs(argv: string[]): ParsedArgs {
-  const flags: ParsedArgs['flags'] = { json: false, help: false };
+  const flags: ParsedArgs['flags'] = { json: false, help: false, version: false };
   const positionals: string[] = [];
 
   for (let i = 0; i < argv.length; i += 1) {
@@ -42,6 +43,10 @@ export function parseArgs(argv: string[]): ParsedArgs {
       flags.help = true;
       continue;
     }
+    if (arg === '--version' || arg === '-V') {
+      flags.version = true;
+      continue;
+    }
     if (arg === '--verbose' || arg === '-v') {
       flags.verbose = true;
       continue;
@@ -168,8 +173,10 @@ export function usage(): string {
 CLI to control iOS and Android devices for AI agents.
 
 Commands:
+  boot                                      Ensure target device/simulator is booted and ready
   open [app]                                 Boot device/simulator; optionally launch app
   close [app]                                Close app or just end session
+  reinstall <app> <path>                     Uninstall + install app from binary path
   snapshot [-i] [-c] [-d <depth>] [-s <scope>] [--raw] [--backend ax|xctest]
                                              Capture accessibility tree
     -i                                       Interactive elements only
@@ -229,5 +236,6 @@ Flags:
   --update, -u                               Replay: update selectors and rewrite replay file in place
   --user-installed                           Apps: list user-installed packages (Android only)
   --all                                      Apps: list all packages (Android only)
+  --version, -V                              Print version and exit
 `;
 }

package/src/utils/exec.ts

@@ -14,6 +14,7 @@ export type ExecOptions = {
   allowFailure?: boolean;
   binaryStdout?: boolean;
   stdin?: string | Buffer;
+  timeoutMs?: number;
 };
 
 export type ExecStreamOptions = ExecOptions & {
@@ -41,6 +42,14 @@ export async function runCmd(
     let stdout = '';
     let stdoutBuffer: Buffer | undefined = options.binaryStdout ? Buffer.alloc(0) : undefined;
     let stderr = '';
+    let didTimeout = false;
+    const timeoutMs = normalizeTimeoutMs(options.timeoutMs);
+    const timeoutHandle = timeoutMs
+      ? setTimeout(() => {
+        didTimeout = true;
+        child.kill('SIGKILL');
+      }, timeoutMs)
+      : null;
 
     if (!options.binaryStdout) child.stdout.setEncoding('utf8');
     child.stderr.setEncoding('utf8');
@@ -66,6 +75,7 @@ export async function runCmd(
     });
 
     child.on('error', (err) => {
+      if (timeoutHandle) clearTimeout(timeoutHandle);
       const code = (err as NodeJS.ErrnoException).code;
       if (code === 'ENOENT') {
         reject(new AppError('TOOL_MISSING', `${cmd} not found in PATH`, { cmd }, err));
@@ -75,7 +85,21 @@ export async function runCmd(
     });
 
     child.on('close', (code) => {
+      if (timeoutHandle) clearTimeout(timeoutHandle);
       const exitCode = code ?? 1;
+      if (didTimeout && timeoutMs) {
+        reject(
+          new AppError('COMMAND_FAILED', `${cmd} timed out after ${timeoutMs}ms`, {
+            cmd,
+            args,
+            stdout,
+            stderr,
+            exitCode,
+            timeoutMs,
+          }),
+        );
+        return;
+      }
       if (exitCode !== 0 && !options.allowFailure) {
         reject(
           new AppError('COMMAND_FAILED', `${cmd} exited with code ${exitCode}`, {
@@ -110,10 +134,18 @@ export function runCmdSync(cmd: string, args: string[], options: ExecOptions = {
     stdio: ['pipe', 'pipe', 'pipe'],
     encoding: options.binaryStdout ? undefined : 'utf8',
     input: options.stdin,
+    timeout: normalizeTimeoutMs(options.timeoutMs),
   });
 
   if (result.error) {
     const code = (result.error as NodeJS.ErrnoException).code;
+    if (code === 'ETIMEDOUT') {
+      throw new AppError('COMMAND_FAILED', `${cmd} timed out after ${normalizeTimeoutMs(options.timeoutMs)}ms`, {
+        cmd,
+        args,
+        timeoutMs: normalizeTimeoutMs(options.timeoutMs),
+      }, result.error);
+    }
     if (code === 'ENOENT') {
       throw new AppError('TOOL_MISSING', `${cmd} not found in PATH`, { cmd }, result.error);
     }
@@ -298,3 +330,10 @@ function resolveWhichArgs(cmd: string): { shell: string; args: string[] } {
   }
   return { shell: 'bash', args: ['-lc', `command -v ${cmd}`] };
 }
+
+function normalizeTimeoutMs(value: number | undefined): number | undefined {
+  if (!Number.isFinite(value)) return undefined;
+  const timeout = Math.floor(value as number);
+  if (timeout <= 0) return undefined;
+  return timeout;
+}

package/src/utils/finders.ts

@@ -6,28 +6,46 @@ export type FindMatchOptions = {
   requireRect?: boolean;
 };
 
+export type FindBestMatches = {
+  matches: SnapshotNode[];
+  score: number;
+};
+
 export function findNodeByLocator(
   nodes: SnapshotNode[],
   locator: FindLocator,
   query: string,
   options: FindMatchOptions = {},
 ): SnapshotNode | null {
+  const best = findBestMatchesByLocator(nodes, locator, query, options);
+  return best.matches[0] ?? null;
+}
+
+export function findBestMatchesByLocator(
+  nodes: SnapshotNode[],
+  locator: FindLocator,
+  query: string,
+  options: FindMatchOptions = {},
+): FindBestMatches {
   const normalizedQuery = normalizeText(query);
-  if (!normalizedQuery) return null;
-  let best: { node: SnapshotNode; score: number } | null = null;
+  if (!normalizedQuery) return { matches: [], score: 0 };
+  let bestScore = 0;
+  const matches: SnapshotNode[] = [];
   for (const node of nodes) {
     if (options.requireRect && !node.rect) continue;
     const score = matchNode(node, locator, normalizedQuery);
     if (score <= 0) continue;
-    if (!best || score > best.score) {
-      best = { node, score };
-      if (score >= 2) {
-        // exact match, keep first exact match
-        break;
-      }
+    if (score > bestScore) {
+      bestScore = score;
+      matches.length = 0;
+      matches.push(node);
+      continue;
+    }
+    if (score === bestScore) {
+      matches.push(node);
     }
   }
-  return best?.node ?? null;
+  return { matches, score: bestScore };
 }
 
 function matchNode(node: SnapshotNode, locator: FindLocator, query: string): number {