agent-device 0.3.0 → 0.3.2

package/src/platforms/android/devices.ts

@@ -1,6 +1,45 @@
 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, isEnvTruthy, retryWithPolicy, TIMEOUT_PROFILES, type RetryTelemetryEvent } from '../../utils/retry.ts';
+import { bootFailureHint, classifyBootFailure } from '../boot-diagnostics.ts';
+
+const EMULATOR_SERIAL_PREFIX = 'emulator-';
+const ANDROID_BOOT_POLL_MS = 1000;
+const RETRY_LOGS_ENABLED = isEnvTruthy(process.env.AGENT_DEVICE_RETRY_LOGS);
+
+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,
+  timeoutMs = TIMEOUT_PROFILES.android_boot.operationMs,
+): Promise<ExecResult> {
+  return runCmd('adb', adbArgs(serial, ['shell', 'getprop', 'sys.boot_completed']), {
+    allowFailure: true,
+    timeoutMs,
+  });
+}
+
+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,
+    timeoutMs: TIMEOUT_PROFILES.android_boot.operationMs,
+  });
+  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');
@@ -8,64 +47,150 @@ export async function listAndroidDevices(): Promise<DeviceInfo[]> {
     throw new AppError('TOOL_MISSING', 'adb not found in PATH');
   }
 
-  const result = await runCmd('adb', ['devices', '-l']);
+  const result = await runCmd('adb', ['devices', '-l'], {
+    timeoutMs: TIMEOUT_PROFILES.android_boot.operationMs,
+  });
   const lines = result.stdout.split('\n').map((l: string) => l.trim());
-  const devices: DeviceInfo[] = [];
-
-  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 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:', ''),
+    }));
 
-    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 timeoutBudget = timeoutMs;
+  const deadline = Deadline.fromTimeoutMs(timeoutBudget);
+  const maxAttempts = Math.max(1, Math.ceil(timeoutBudget / 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 remainingMs = Math.max(1_000, attemptDeadline?.remainingMs() ?? timeoutBudget);
+        const result = await readAndroidBootProp(
+          serial,
+          Math.min(remainingMs, TIMEOUT_PROFILES.android_boot.operationMs),
+        );
+        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,
+            context: { platform: 'android', phase: 'boot' },
+          });
+          return reason !== 'ADB_TRANSPORT_UNAVAILABLE' && reason !== 'ANDROID_BOOT_TIMEOUT';
+        },
+      },
+      {
+        deadline,
+        phase: 'boot',
+        classifyReason: (error) =>
+          classifyBootFailure({
+            error,
+            stdout: lastBootResult?.stdout,
+            stderr: lastBootResult?.stderr,
+            context: { platform: 'android', phase: 'boot' },
+          }),
+        onEvent: (event: RetryTelemetryEvent) => {
+          if (!RETRY_LOGS_ENABLED) return;
+          process.stderr.write(`[agent-device][retry] ${JSON.stringify(event)}\n`);
+        },
+      },
+    );
+  } catch (error) {
+    const appErr = asAppError(error);
+    const stdout = lastBootResult?.stdout;
+    const stderr = lastBootResult?.stderr;
+    const exitCode = lastBootResult?.exitCode;
+    let reason = classifyBootFailure({
+      error,
+      stdout,
+      stderr,
+      context: { platform: 'android', phase: 'boot' },
+    });
+    if (reason === 'BOOT_COMMAND_FAILED' && appErr.message === 'Android device is still booting') {
+      reason = 'ANDROID_BOOT_TIMEOUT';
+    }
+    const baseDetails = {
+      serial,
+      timeoutMs: timeoutBudget,
+      elapsedMs: deadline.elapsedMs(),
+      reason,
+      hint: bootFailureHint(reason),
+      stdout,
+      stderr,
+      exitCode,
+    };
+    if (timedOut || reason === 'ANDROID_BOOT_TIMEOUT') {
+      throw new AppError('COMMAND_FAILED', 'Android device did not finish booting in time', baseDetails);
+    }
+    if (appErr.code === 'TOOL_MISSING') {
+      throw new AppError('TOOL_MISSING', appErr.message, {
+        ...baseDetails,
+        ...(appErr.details ?? {}),
+      });
+    }
+    if (reason === 'ADB_TRANSPORT_UNAVAILABLE') {
+      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/android/index.ts

@@ -187,22 +187,70 @@ export async function openAndroidApp(
     );
     return;
   }
-  await runCmd(
+  try {
+    await runCmd(
+      'adb',
+      adbArgs(device, [
+        'shell',
+        'am',
+        'start',
+        '-a',
+        'android.intent.action.MAIN',
+        '-c',
+        'android.intent.category.DEFAULT',
+        '-c',
+        'android.intent.category.LAUNCHER',
+        '-p',
+        resolved.value,
+      ]),
+    );
+    return;
+  } catch (initialError) {
+    const component = await resolveAndroidLaunchComponent(device, resolved.value);
+    if (!component) throw initialError;
+    await runCmd(
+      'adb',
+      adbArgs(device, [
+        'shell',
+        'am',
+        'start',
+        '-a',
+        'android.intent.action.MAIN',
+        '-c',
+        'android.intent.category.DEFAULT',
+        '-c',
+        'android.intent.category.LAUNCHER',
+        '-n',
+        component,
+      ]),
+    );
+  }
+}
+
+async function resolveAndroidLaunchComponent(
+  device: DeviceInfo,
+  packageName: string,
+): Promise<string | null> {
+  const result = await runCmd(
     'adb',
-    adbArgs(device, [
-      'shell',
-      'am',
-      'start',
-      '-a',
-      'android.intent.action.MAIN',
-      '-c',
-      'android.intent.category.DEFAULT',
-      '-c',
-      'android.intent.category.LAUNCHER',
-      '-p',
-      resolved.value,
-    ]),
+    adbArgs(device, ['shell', 'cmd', 'package', 'resolve-activity', '--brief', packageName]),
+    { allowFailure: true },
   );
+  if (result.exitCode !== 0) return null;
+  return parseAndroidLaunchComponent(result.stdout);
+}
+
+export function parseAndroidLaunchComponent(stdout: string): string | null {
+  const lines = stdout
+    .split('\n')
+    .map((line: string) => line.trim())
+    .filter(Boolean);
+  for (let index = lines.length - 1; index >= 0; index -= 1) {
+    const line = lines[index];
+    if (!line.includes('/')) continue;
+    return line.split(/\s+/)[0];
+  }
+  return null;
 }
 
 export async function openAndroidDevice(device: DeviceInfo): Promise<void> {
@@ -224,6 +272,45 @@ export async function closeAndroidApp(device: DeviceInfo, app: string): Promise<
   await runCmd('adb', adbArgs(device, ['shell', 'am', 'force-stop', resolved.value]));
 }
 
+export async function uninstallAndroidApp(
+  device: DeviceInfo,
+  app: string,
+): Promise<{ package: string }> {
+  const resolved = await resolveAndroidApp(device, app);
+  if (resolved.type === 'intent') {
+    throw new AppError('INVALID_ARGS', 'reinstall requires a package name, not an intent');
+  }
+  const result = await runCmd('adb', adbArgs(device, ['uninstall', resolved.value]), { allowFailure: true });
+  if (result.exitCode !== 0) {
+    const output = `${result.stdout}\n${result.stderr}`.toLowerCase();
+    if (!output.includes('unknown package') && !output.includes('not installed')) {
+      throw new AppError('COMMAND_FAILED', `adb uninstall failed for ${resolved.value}`, {
+        stdout: result.stdout,
+        stderr: result.stderr,
+        exitCode: result.exitCode,
+      });
+    }
+  }
+  return { package: resolved.value };
+}
+
+export async function installAndroidApp(device: DeviceInfo, appPath: string): Promise<void> {
+  await runCmd('adb', adbArgs(device, ['install', appPath]));
+}
+
+export async function reinstallAndroidApp(
+  device: DeviceInfo,
+  app: string,
+  appPath: string,
+): Promise<{ package: string }> {
+  if (!device.booted) {
+    await waitForAndroidBoot(device.id);
+  }
+  const { package: pkg } = await uninstallAndroidApp(device, app);
+  await installAndroidApp(device, appPath);
+  return { package: pkg };
+}
+
 export async function pressAndroid(device: DeviceInfo, x: number, y: number): Promise<void> {
   await runCmd('adb', adbArgs(device, ['shell', 'input', 'tap', String(x), String(y)]));
 }

package/src/platforms/boot-diagnostics.ts

@@ -0,0 +1,128 @@
+import { asAppError } from '../utils/errors.ts';
+
+export type BootFailureReason =
+  | 'IOS_BOOT_TIMEOUT'
+  | 'IOS_RUNNER_CONNECT_TIMEOUT'
+  | 'IOS_TOOL_MISSING'
+  | 'ANDROID_BOOT_TIMEOUT'
+  | 'ADB_TRANSPORT_UNAVAILABLE'
+  | 'CI_RESOURCE_STARVATION_SUSPECTED'
+  | 'BOOT_COMMAND_FAILED'
+  | 'UNKNOWN';
+
+type BootDiagnosticContext = {
+  platform?: 'ios' | 'android';
+  phase?: 'boot' | 'connect' | 'transport';
+};
+
+export function classifyBootFailure(input: {
+  error?: unknown;
+  message?: string;
+  stdout?: string;
+  stderr?: string;
+  context?: BootDiagnosticContext;
+}): BootFailureReason {
+  const appErr = input.error ? asAppError(input.error) : null;
+  const platform = input.context?.platform;
+  const phase = input.context?.phase;
+  if (appErr?.code === 'TOOL_MISSING') {
+    return platform === 'android' ? 'ADB_TRANSPORT_UNAVAILABLE' : 'IOS_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 (
+    platform === 'ios' &&
+    (
+      haystack.includes('runner did not accept connection') ||
+      (phase === 'connect' &&
+        (
+          haystack.includes('timed out') ||
+          haystack.includes('timeout') ||
+          haystack.includes('econnrefused') ||
+          haystack.includes('connection refused') ||
+          haystack.includes('fetch failed') ||
+          haystack.includes('socket hang up')
+        ))
+    )
+  ) {
+    return 'IOS_RUNNER_CONNECT_TIMEOUT';
+  }
+  if (platform === 'ios' && phase === 'boot' && (haystack.includes('timed out') || haystack.includes('timeout'))) {
+    return 'IOS_BOOT_TIMEOUT';
+  }
+  if (platform === 'android' && phase === 'boot' && (haystack.includes('timed out') || haystack.includes('timeout'))) {
+    return 'ANDROID_BOOT_TIMEOUT';
+  }
+  if (
+    haystack.includes('resource temporarily unavailable') ||
+    haystack.includes('killed: 9') ||
+    haystack.includes('cannot allocate memory') ||
+    haystack.includes('system is low on memory')
+  ) {
+    return 'CI_RESOURCE_STARVATION_SUSPECTED';
+  }
+  if (
+    platform === 'android' &&
+    (
+      haystack.includes('device not found') ||
+      haystack.includes('no devices') ||
+      haystack.includes('device offline') ||
+      haystack.includes('offline') ||
+      haystack.includes('unauthorized') ||
+      haystack.includes('not authorized') ||
+      haystack.includes('unable to locate device') ||
+      haystack.includes('invalid device')
+    )
+  ) {
+    return 'ADB_TRANSPORT_UNAVAILABLE';
+  }
+  if (appErr?.code === 'COMMAND_FAILED' || haystack.length > 0) return 'BOOT_COMMAND_FAILED';
+  return 'UNKNOWN';
+}
+
+export function bootFailureHint(reason: BootFailureReason): string {
+  switch (reason) {
+    case 'IOS_BOOT_TIMEOUT':
+      return 'Retry simulator boot and inspect simctl bootstatus logs; in CI consider increasing AGENT_DEVICE_IOS_BOOT_TIMEOUT_MS.';
+    case 'IOS_RUNNER_CONNECT_TIMEOUT':
+      return 'Retry runner startup, inspect xcodebuild logs, and verify simulator responsiveness before command execution.';
+    case 'ANDROID_BOOT_TIMEOUT':
+      return 'Retry emulator startup and verify sys.boot_completed reaches 1; consider increasing startup budget in CI.';
+    case 'ADB_TRANSPORT_UNAVAILABLE':
+      return 'Check adb server/device transport (adb devices -l), restart adb, and ensure the target device is online and authorized.';
+    case 'CI_RESOURCE_STARVATION_SUSPECTED':
+      return 'CI machine may be resource constrained; reduce parallel jobs or use a larger runner.';
+    case 'IOS_TOOL_MISSING':
+      return 'Xcode command-line tools are missing or not in PATH; run xcode-select --install and verify xcrun works.';
+    case 'BOOT_COMMAND_FAILED':
+      return 'Inspect command stderr/stdout for the failing boot phase and retry after environment validation.';
+    default:
+      return 'Retry once and inspect verbose logs for the failing phase.';
+  }
+}