agent-device 0.3.1 → 0.3.3

package/src/utils/args.ts

@@ -173,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

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 {

package/src/utils/retry.ts

@@ -22,6 +22,33 @@ export type RetryAttemptContext = {
   deadline?: Deadline;
 };
 
+export type TimeoutProfile = {
+  startupMs: number;
+  operationMs: number;
+  totalMs: number;
+};
+
+export type RetryTelemetryEvent = {
+  phase?: string;
+  event: 'attempt_failed' | 'retry_scheduled' | 'succeeded' | 'exhausted';
+  attempt: number;
+  maxAttempts: number;
+  delayMs?: number;
+  elapsedMs?: number;
+  remainingMs?: number;
+  reason?: string;
+};
+
+export function isEnvTruthy(value: string | undefined): boolean {
+  return ['1', 'true', 'yes', 'on'].includes((value ?? '').toLowerCase());
+}
+
+export const TIMEOUT_PROFILES: Record<string, TimeoutProfile> = {
+  ios_boot: { startupMs: 120_000, operationMs: 20_000, totalMs: 120_000 },
+  ios_runner_connect: { startupMs: 120_000, operationMs: 15_000, totalMs: 120_000 },
+  android_boot: { startupMs: 60_000, operationMs: 10_000, totalMs: 60_000 },
+};
+
 const defaultOptions: Required<Pick<RetryOptions, 'attempts' | 'baseDelayMs' | 'maxDelayMs' | 'jitter'>> = {
   attempts: 3,
   baseDelayMs: 200,
@@ -58,7 +85,12 @@ export class Deadline {
 export async function retryWithPolicy<T>(
   fn: (context: RetryAttemptContext) => Promise<T>,
   policy: Partial<RetryPolicy> = {},
-  options: { deadline?: Deadline } = {},
+  options: {
+    deadline?: Deadline;
+    phase?: string;
+    classifyReason?: (error: unknown) => string | undefined;
+    onEvent?: (event: RetryTelemetryEvent) => void;
+  } = {},
 ): Promise<T> {
   const merged: RetryPolicy = {
     maxAttempts: policy.maxAttempts ?? defaultOptions.attempts,
@@ -71,17 +103,55 @@ export async function retryWithPolicy<T>(
   for (let attempt = 1; attempt <= merged.maxAttempts; attempt += 1) {
     if (options.deadline?.isExpired() && attempt > 1) break;
     try {
-      return await fn({ attempt, maxAttempts: merged.maxAttempts, deadline: options.deadline });
+      const result = await fn({ attempt, maxAttempts: merged.maxAttempts, deadline: options.deadline });
+      options.onEvent?.({
+        phase: options.phase,
+        event: 'succeeded',
+        attempt,
+        maxAttempts: merged.maxAttempts,
+        elapsedMs: options.deadline?.elapsedMs(),
+        remainingMs: options.deadline?.remainingMs(),
+      });
+      return result;
     } catch (err) {
       lastError = err;
+      const reason = options.classifyReason?.(err);
+      options.onEvent?.({
+        phase: options.phase,
+        event: 'attempt_failed',
+        attempt,
+        maxAttempts: merged.maxAttempts,
+        elapsedMs: options.deadline?.elapsedMs(),
+        remainingMs: options.deadline?.remainingMs(),
+        reason,
+      });
       if (attempt >= merged.maxAttempts) break;
       if (merged.shouldRetry && !merged.shouldRetry(err, attempt)) break;
       const delay = computeDelay(merged.baseDelayMs, merged.maxDelayMs, merged.jitter, attempt);
       const boundedDelay = options.deadline ? Math.min(delay, options.deadline.remainingMs()) : delay;
       if (boundedDelay <= 0) break;
+      options.onEvent?.({
+        phase: options.phase,
+        event: 'retry_scheduled',
+        attempt,
+        maxAttempts: merged.maxAttempts,
+        delayMs: boundedDelay,
+        elapsedMs: options.deadline?.elapsedMs(),
+        remainingMs: options.deadline?.remainingMs(),
+        reason,
+      });
       await sleep(boundedDelay);
     }
   }
+  options.onEvent?.({
+    phase: options.phase,
+    event: 'exhausted',
+    attempt: merged.maxAttempts,
+    maxAttempts: merged.maxAttempts,
+    elapsedMs: options.deadline?.elapsedMs(),
+    remainingMs: options.deadline?.remainingMs(),
+    reason: options.classifyReason?.(lastError),
+  });
   if (lastError) throw lastError;
   throw new AppError('COMMAND_FAILED', 'retry failed');
 }