Fix Android boot completion and headless emulator launch

Author: thymikee

README.md

@@ -414,6 +414,8 @@ Boot diagnostics:
 - Reason codes: `IOS_BOOT_TIMEOUT`, `IOS_RUNNER_CONNECT_TIMEOUT`, `ANDROID_BOOT_TIMEOUT`, `ADB_TRANSPORT_UNAVAILABLE`, `CI_RESOURCE_STARVATION_SUSPECTED`, `BOOT_COMMAND_FAILED`, `UNKNOWN`.
 - Android boot waits fail fast for permission/tooling issues and do not always collapse into timeout errors.
 - Use `agent-device boot --platform ios|android|apple` when starting a new session only if `open` cannot find/connect to an available target.
+- Android emulator boot by AVD name (GUI): `agent-device boot --platform android --device Pixel_9_Pro_XL`.
+- Android headless emulator boot: `agent-device boot --platform android --device Pixel_9_Pro_XL --headless`.
 - `--debug` captures retry telemetry in diagnostics logs.
 - Set `AGENT_DEVICE_RETRY_LOGS=1` to also print retry telemetry directly to stderr (ad-hoc troubleshooting).
 

skills/agent-device/SKILL.md

@@ -99,6 +99,8 @@ agent-device session list
 ```
 
 Use `boot` only as fallback when `open` cannot find/connect to a ready target.
+For Android emulators by AVD name, use `boot --platform android --device <avd-name>`.
+For Android emulators without GUI, add `--headless`.
 Use `--target mobile|tv` with `--platform` (required) to pick phone/tablet vs TV targets (AndroidTV/tvOS).
 
 TV quick reference:

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

@@ -6,6 +6,7 @@ import path from 'node:path';
 import { handleSessionCommands } from '../session.ts';
 import { SessionStore } from '../../session-store.ts';
 import type { DaemonRequest, DaemonResponse, SessionState } from '../../types.ts';
+import { AppError } from '../../../utils/errors.ts';
 
 function makeSessionStore(): SessionStore {
   const root = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-device-session-handler-'));
@@ -312,7 +313,7 @@ test('boot succeeds for supported device in session', async () => {
   });
   assert.ok(response);
   assert.equal(response?.ok, true);
-  assert.equal(ensureCalls, 1);
+  assert.equal(ensureCalls, 0);
   if (response && response.ok) {
     assert.equal(response.data?.platform, 'android');
     assert.equal(response.data?.booted, true);
@@ -368,6 +369,128 @@ test('boot prefers explicit device selector over active session device', async (
   }
 });
 
+test('boot --headless launches Android emulator when no running device matches', async () => {
+  const sessionStore = makeSessionStore();
+  const ensured: string[] = [];
+  const launchCalls: Array<{ avdName: string; serial?: string; headless?: boolean }> = [];
+  const response = await handleSessionCommands({
+    req: {
+      token: 't',
+      session: 'default',
+      command: 'boot',
+      positionals: [],
+      flags: { platform: 'android', target: 'mobile', device: 'Pixel_9_Pro_XL', headless: true },
+    },
+    sessionName: 'default',
+    logPath: path.join(os.tmpdir(), 'daemon.log'),
+    sessionStore,
+    invoke: noopInvoke,
+    ensureReady: async (device) => {
+      ensured.push(device.id);
+    },
+    resolveTargetDevice: async () => {
+      throw new AppError('DEVICE_NOT_FOUND', 'No devices found');
+    },
+    ensureAndroidEmulatorBoot: async ({ avdName, serial, headless }) => {
+      launchCalls.push({ avdName, serial, headless });
+      return {
+        platform: 'android',
+        id: 'emulator-5554',
+        name: 'Pixel_9_Pro_XL',
+        kind: 'emulator',
+        target: 'mobile',
+        booted: true,
+      };
+    },
+  });
+
+  assert.ok(response);
+  assert.equal(response?.ok, true);
+  assert.deepEqual(launchCalls, [{ avdName: 'Pixel_9_Pro_XL', serial: undefined, headless: true }]);
+  assert.deepEqual(ensured, ['emulator-5554']);
+  if (response && response.ok) {
+    assert.equal(response.data?.platform, 'android');
+    assert.equal(response.data?.id, 'emulator-5554');
+    assert.equal(response.data?.device, 'Pixel_9_Pro_XL');
+  }
+});
+
+test('boot launches Android emulator with GUI when no running device matches', async () => {
+  const sessionStore = makeSessionStore();
+  const launchCalls: Array<{ avdName: string; serial?: string; headless?: boolean }> = [];
+  const response = await handleSessionCommands({
+    req: {
+      token: 't',
+      session: 'default',
+      command: 'boot',
+      positionals: [],
+      flags: { platform: 'android', target: 'mobile', device: 'Pixel_9_Pro_XL' },
+    },
+    sessionName: 'default',
+    logPath: path.join(os.tmpdir(), 'daemon.log'),
+    sessionStore,
+    invoke: noopInvoke,
+    ensureReady: async () => {},
+    resolveTargetDevice: async () => {
+      throw new AppError('DEVICE_NOT_FOUND', 'No devices found');
+    },
+    ensureAndroidEmulatorBoot: async ({ avdName, serial, headless }) => {
+      launchCalls.push({ avdName, serial, headless });
+      return {
+        platform: 'android',
+        id: 'emulator-5554',
+        name: 'Pixel_9_Pro_XL',
+        kind: 'emulator',
+        target: 'mobile',
+        booted: true,
+      };
+    },
+  });
+
+  assert.ok(response);
+  assert.equal(response?.ok, true);
+  assert.deepEqual(launchCalls, [{ avdName: 'Pixel_9_Pro_XL', serial: undefined, headless: false }]);
+  if (response && response.ok) {
+    assert.equal(response.data?.platform, 'android');
+    assert.equal(response.data?.id, 'emulator-5554');
+    assert.equal(response.data?.device, 'Pixel_9_Pro_XL');
+  }
+});
+
+test('boot --headless requires avd selector when device cannot be resolved', async () => {
+  const sessionStore = makeSessionStore();
+  let bootCalled = false;
+  const response = await handleSessionCommands({
+    req: {
+      token: 't',
+      session: 'default',
+      command: 'boot',
+      positionals: [],
+      flags: { platform: 'android', target: 'mobile', serial: 'emulator-5554', headless: true },
+    },
+    sessionName: 'default',
+    logPath: path.join(os.tmpdir(), 'daemon.log'),
+    sessionStore,
+    invoke: noopInvoke,
+    ensureReady: async () => {},
+    resolveTargetDevice: async () => {
+      throw new AppError('DEVICE_NOT_FOUND', 'No devices found');
+    },
+    ensureAndroidEmulatorBoot: async () => {
+      bootCalled = true;
+      throw new Error('unexpected');
+    },
+  });
+
+  assert.ok(response);
+  assert.equal(response?.ok, false);
+  assert.equal(bootCalled, false);
+  if (response && !response.ok) {
+    assert.equal(response.error.code, 'INVALID_ARGS');
+    assert.match(response.error.message, /boot --headless requires --device <avd-name>/);
+  }
+});
+
 test('appstate on iOS requires active session on selected device', async () => {
   const sessionStore = makeSessionStore();
   const sessionName = 'default';

src/daemon/handlers/session.ts

@@ -48,6 +48,12 @@ type ReinstallOps = {
   android: (device: DeviceInfo, app: string, appPath: string) => Promise<{ package: string }>;
 };
 
+type EnsureAndroidEmulatorBoot = (params: {
+  avdName: string;
+  serial?: string;
+  headless?: boolean;
+}) => Promise<DeviceInfo>;
+
 const IOS_APPSTATE_SESSION_REQUIRED_MESSAGE =
   'iOS appstate requires an active session on the target device. Run open first (for example: open --session sim --platform ios --device "<name>" <app>).';
 const BATCH_PARENT_FLAG_KEYS: Array<keyof CommandFlags> = ['platform', 'target', 'device', 'udid', 'serial', 'verbose', 'out'];
@@ -226,6 +232,27 @@ async function resolveCommandDevice(params: {
   return device;
 }
 
+function resolveAndroidEmulatorAvdName(params: {
+  flags: DaemonRequest['flags'] | undefined;
+  sessionDevice?: DeviceInfo;
+  resolvedDevice?: DeviceInfo;
+}): string | undefined {
+  const explicit = params.flags?.device?.trim();
+  if (explicit) return explicit;
+  if (params.resolvedDevice?.platform === 'android' && params.resolvedDevice.kind === 'emulator') {
+    return params.resolvedDevice.name;
+  }
+  if (params.sessionDevice?.platform === 'android' && params.sessionDevice.kind === 'emulator') {
+    return params.sessionDevice.name;
+  }
+  return undefined;
+}
+
+const defaultEnsureAndroidEmulatorBoot: EnsureAndroidEmulatorBoot = async ({ avdName, serial, headless }) => {
+  const { ensureAndroidEmulatorBooted } = await import('../../platforms/android/devices.ts');
+  return await ensureAndroidEmulatorBooted({ avdName, serial, headless });
+};
+
 const defaultReinstallOps: ReinstallOps = {
   ios: async (device, app, appPath) => {
     const { reinstallIosApp } = await import('../../platforms/ios/index.ts');
@@ -442,6 +469,7 @@ export async function handleSessionCommands(params: {
     start: typeof startAppLog;
     stop: typeof stopAppLog;
   };
+  ensureAndroidEmulatorBoot?: EnsureAndroidEmulatorBoot;
   resolveAndroidPackageForOpen?: (
     device: DeviceInfo,
     openTarget: string | undefined,
@@ -462,6 +490,7 @@ export async function handleSessionCommands(params: {
       start: startAppLog,
       stop: stopAppLog,
     },
+    ensureAndroidEmulatorBoot: ensureAndroidEmulatorBootOverride = defaultEnsureAndroidEmulatorBoot,
     resolveAndroidPackageForOpen: resolveAndroidPackageForOpenOverride = resolveAndroidPackageForOpen,
   } = params;
   const dispatch = dispatchOverride ?? dispatchCommand;
@@ -555,13 +584,94 @@ export async function handleSessionCommands(params: {
     const flags = req.flags ?? {};
     const guard = requireSessionOrExplicitSelector(command, session, flags);
     if (guard) return guard;
-    const device = await resolveCommandDevice({
-      session,
+    const normalizedPlatform = normalizePlatformSelector(flags.platform) ?? session?.device.platform;
+    const targetsAndroid = normalizedPlatform === 'android';
+    const wantsAndroidHeadless = flags.headless === true;
+    const shouldUseFastAndroidSelectorLookup = targetsAndroid && !flags.target && Boolean(flags.device || flags.serial);
+    const fallbackAvdName = resolveAndroidEmulatorAvdName({
       flags,
-      ensureReadyFn: ensureReady,
-      resolveTargetDeviceFn: resolveDevice,
-      ensureReady: true,
+      sessionDevice: session?.device,
     });
+    const canFallbackLaunchAndroidEmulator = targetsAndroid && Boolean(fallbackAvdName);
+    let device: DeviceInfo;
+    let launchedAndroidEmulator = false;
+    const fastLookupDevice = shouldUseFastAndroidSelectorLookup
+      ? await (async () => {
+        const { resolveAndroidBootSelectorDevice } = await import('../../platforms/android/devices.ts');
+        return await resolveAndroidBootSelectorDevice({
+          deviceName: flags.device,
+          serial: flags.serial,
+        });
+      })()
+      : undefined;
+    try {
+      device = fastLookupDevice
+        ?? (await resolveCommandDevice({
+          session,
+          flags,
+          ensureReadyFn: ensureReady,
+          resolveTargetDeviceFn: resolveDevice,
+          ensureReady: false,
+        }));
+    } catch (error) {
+      const appErr = asAppError(error);
+      if (targetsAndroid && wantsAndroidHeadless && !fallbackAvdName && appErr.code === 'DEVICE_NOT_FOUND') {
+        return {
+          ok: false,
+          error: {
+            code: 'INVALID_ARGS',
+            message: 'boot --headless requires --device <avd-name> (or an Android emulator session target).',
+          },
+        };
+      }
+      if (!canFallbackLaunchAndroidEmulator || appErr.code !== 'DEVICE_NOT_FOUND' || !fallbackAvdName) {
+        throw error;
+      }
+      device = await ensureAndroidEmulatorBootOverride({
+        avdName: fallbackAvdName,
+        serial: flags.serial,
+        headless: wantsAndroidHeadless,
+      });
+      launchedAndroidEmulator = true;
+    }
+    if (targetsAndroid && wantsAndroidHeadless) {
+      if (device.platform !== 'android' || device.kind !== 'emulator') {
+        return {
+          ok: false,
+          error: {
+            code: 'INVALID_ARGS',
+            message: 'boot --headless is supported only for Android emulators.',
+          },
+        };
+      }
+      if (!launchedAndroidEmulator) {
+        const avdName = resolveAndroidEmulatorAvdName({
+          flags,
+          sessionDevice: session?.device,
+          resolvedDevice: device,
+        });
+        if (!avdName) {
+          return {
+            ok: false,
+            error: {
+              code: 'INVALID_ARGS',
+              message: 'boot --headless requires --device <avd-name> (or an Android emulator session target).',
+            },
+          };
+        }
+        device = await ensureAndroidEmulatorBootOverride({
+          avdName,
+          serial: flags.serial,
+          headless: true,
+        });
+      }
+      await ensureReady(device);
+    } else {
+      const shouldEnsureReady = device.platform !== 'android' || device.booted !== true;
+      if (shouldEnsureReady) {
+        await ensureReady(device);
+      }
+    }
     if (!isCommandSupportedOnDevice('boot', device)) {
       return { ok: false, error: { code: 'UNSUPPORTED_OPERATION', message: 'boot is not supported on this device' } };
     }