Add Touch ID and Android fingerprint simulation for settings (#135)

* fix: add touchid/fingerprint settings simulation and harden error handling

* chore: tighten agent docs and simplify iOS biometric settings flow

Author: thymikee

README.md

@@ -155,6 +155,8 @@ agent-device scrollintoview @e42
 - `settings wifi|airplane|location on|off`
 - `settings appearance light|dark|toggle`
 - `settings faceid match|nonmatch|enroll|unenroll` (iOS simulator only)
+- `settings touchid match|nonmatch|enroll|unenroll` (iOS simulator only)
+- `settings fingerprint match|nonmatch` (Android emulator/device where supported)
 - `settings permission grant|deny|reset camera|microphone|photos|contacts|notifications [full|limited]`
 - `appstate`, `apps`, `devices`, `session list`
 - `perf` (alias: `metrics`)
@@ -362,6 +364,9 @@ Settings helpers:
 - `settings airplane on|off`
 - `settings location on|off` (iOS uses per-app permission for the current session app)
 - `settings appearance light|dark|toggle` (iOS simulator appearance + Android night mode)
+- `settings faceid|touchid match|nonmatch|enroll|unenroll` (iOS simulator only)
+- `settings fingerprint match|nonmatch` (Android emulator/device where supported)
+  On physical Android devices, fingerprint simulation depends on `cmd fingerprint` support.
 - `settings permission grant|deny|reset <camera|microphone|photos|contacts|notifications> [full|limited]` (session app required)
 Note: iOS supports these only on simulators. iOS wifi/airplane toggles status bar indicators, not actual network state. Airplane off clears status bar overrides.
 - iOS permission targets map to `simctl privacy`: `camera`, `microphone`, `photos` (`full` => `photos`, `limited` => `photos-add`), `contacts`, `notifications`.

skills/agent-device/SKILL.md

@@ -129,7 +129,7 @@ agent-device batch --steps-file /tmp/batch-steps.json --json
 - iOS `appstate` is session-scoped; Android `appstate` is live foreground state.
 - Clipboard helpers: `clipboard read` / `clipboard write <text>` are supported on Android and iOS simulators; iOS physical devices are not supported yet.
 - `network dump` is best-effort and parses HTTP(s) entries from the session app log file.
-- iOS settings helpers are simulator-only; use `appearance light|dark|toggle` and faceid `match|nonmatch|enroll|unenroll`.
+- Biometric settings: iOS simulator supports `settings faceid|touchid <match|nonmatch|enroll|unenroll>`; Android supports `settings fingerprint <match|nonmatch>` where runtime tooling is available.
 - For AndroidTV/tvOS selection, always pair `--target` with `--platform` (`ios`, `android`, or `apple` alias); target-only selection is invalid.
 - `push` simulates notification delivery:
   - iOS simulator uses APNs-style payload JSON.

src/core/settings-contract.ts

@@ -1,15 +1,19 @@
 export const SETTINGS_WIFI_USAGE = '<wifi|airplane|location> <on|off>';
 export const SETTINGS_APPEARANCE_USAGE = 'appearance <light|dark|toggle>';
 export const SETTINGS_FACEID_USAGE = 'faceid <match|nonmatch|enroll|unenroll>';
+export const SETTINGS_TOUCHID_USAGE = 'touchid <match|nonmatch|enroll|unenroll>';
+export const SETTINGS_FINGERPRINT_USAGE = 'fingerprint <match|nonmatch>';
 export const SETTINGS_PERMISSION_USAGE =
   'permission <grant|deny|reset> <camera|microphone|photos|contacts|contacts-limited|notifications|calendar|location|location-always|media-library|motion|reminders|siri> [full|limited]';
 
 export const SETTINGS_USAGE_OVERRIDE = [
   `settings ${SETTINGS_WIFI_USAGE}`,
   `settings ${SETTINGS_APPEARANCE_USAGE}`,
   `settings ${SETTINGS_FACEID_USAGE}`,
+  `settings ${SETTINGS_TOUCHID_USAGE}`,
+  `settings ${SETTINGS_FINGERPRINT_USAGE}`,
   `settings ${SETTINGS_PERMISSION_USAGE}`,
 ].join(' | ');
 
 export const SETTINGS_INVALID_ARGS_MESSAGE =
-  `settings requires ${SETTINGS_WIFI_USAGE}, ${SETTINGS_APPEARANCE_USAGE}, ${SETTINGS_FACEID_USAGE}, or ${SETTINGS_PERMISSION_USAGE}`;
+  `settings requires ${SETTINGS_WIFI_USAGE}, ${SETTINGS_APPEARANCE_USAGE}, ${SETTINGS_FACEID_USAGE}, ${SETTINGS_TOUCHID_USAGE}, ${SETTINGS_FINGERPRINT_USAGE}, or ${SETTINGS_PERMISSION_USAGE}`;

src/platforms/android/__tests__/index.test.ts

@@ -392,6 +392,131 @@ test('setAndroidSetting appearance toggle rejects unknown current mode output',
   );
 });
 
+test('setAndroidSetting fingerprint match uses adb shell cmd fingerprint touch', async () => {
+  await withMockedAdb(
+    'agent-device-android-fingerprint-match-',
+    '#!/bin/sh\nprintf "__CMD__\\n" >> "$AGENT_DEVICE_TEST_ARGS_FILE"\nprintf "%s\\n" "$@" >> "$AGENT_DEVICE_TEST_ARGS_FILE"\nexit 0\n',
+    async ({ argsLogPath, device }) => {
+      await setAndroidSetting(device, 'fingerprint', 'match');
+      const logged = await fs.readFile(argsLogPath, 'utf8');
+      assert.match(logged, /shell\ncmd\nfingerprint\ntouch\n1/);
+    },
+  );
+});
+
+test('setAndroidSetting fingerprint retries emulator command when shell cmd fingerprint fails', async () => {
+  await withMockedAdb(
+    'agent-device-android-fingerprint-fallback-',
+    [
+      '#!/bin/sh',
+      'printf "__CMD__\\n" >> "$AGENT_DEVICE_TEST_ARGS_FILE"',
+      'printf "%s\\n" "$@" >> "$AGENT_DEVICE_TEST_ARGS_FILE"',
+      'if [ "$1" = "-s" ]; then',
+      '  shift',
+      '  shift',
+      'fi',
+      'if [ "$1" = "shell" ] && [ "$2" = "cmd" ] && [ "$3" = "fingerprint" ]; then',
+      '  echo "fingerprint cmd unavailable" >&2',
+      '  exit 1',
+      'fi',
+      'if [ "$1" = "emu" ] && [ "$2" = "finger" ] && [ "$3" = "touch" ] && [ "$4" = "1" ]; then',
+      '  exit 0',
+      'fi',
+      'echo "unexpected args: $@" >&2',
+      'exit 1',
+      '',
+    ].join('\n'),
+    async ({ argsLogPath, device }) => {
+      await setAndroidSetting(device, 'fingerprint', 'match');
+      const logged = await fs.readFile(argsLogPath, 'utf8');
+      assert.match(logged, /shell\ncmd\nfingerprint\ntouch\n1/);
+      assert.match(logged, /shell\ncmd\nfingerprint\nfinger\n1/);
+      assert.match(logged, /emu\nfinger\ntouch\n1/);
+    },
+  );
+});
+
+test('setAndroidSetting fingerprint rejects unsupported action', async () => {
+  const device: DeviceInfo = {
+    platform: 'android',
+    id: 'emulator-5554',
+    name: 'Pixel',
+    kind: 'emulator',
+    booted: true,
+  };
+  await assert.rejects(
+    () => setAndroidSetting(device, 'fingerprint', 'enroll'),
+    (error: unknown) => {
+      assert.equal(error instanceof AppError, true);
+      assert.equal((error as AppError).code, 'INVALID_ARGS');
+      assert.match((error as AppError).message, /Invalid fingerprint state/);
+      return true;
+    },
+  );
+});
+
+test('setAndroidSetting fingerprint returns COMMAND_FAILED for transport/runtime failures', async () => {
+  await withMockedAdb(
+    'agent-device-android-fingerprint-command-failed-',
+    [
+      '#!/bin/sh',
+      'echo "error: device offline" >&2',
+      'exit 1',
+      '',
+    ].join('\n'),
+    async ({ device }) => {
+      await assert.rejects(
+        () => setAndroidSetting(device, 'fingerprint', 'match'),
+        (error: unknown) => {
+          assert.equal(error instanceof AppError, true);
+          assert.equal((error as AppError).code, 'COMMAND_FAILED');
+          assert.match((error as AppError).message, /Failed to simulate Android fingerprint/);
+          return true;
+        },
+      );
+    },
+  );
+});
+
+test('setAndroidSetting fingerprint does not use adb emu command on physical devices', async () => {
+  const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'agent-device-android-fingerprint-device-'));
+  const adbPath = path.join(tmpDir, 'adb');
+  const argsLogPath = path.join(tmpDir, 'args.log');
+  await fs.writeFile(
+    adbPath,
+    '#!/bin/sh\nprintf "__CMD__\\n" >> "$AGENT_DEVICE_TEST_ARGS_FILE"\nprintf "%s\\n" "$@" >> "$AGENT_DEVICE_TEST_ARGS_FILE"\necho "unknown command" >&2\nexit 1\n',
+    'utf8',
+  );
+  await fs.chmod(adbPath, 0o755);
+
+  const previousPath = process.env.PATH;
+  const previousArgsFile = process.env.AGENT_DEVICE_TEST_ARGS_FILE;
+  process.env.PATH = `${tmpDir}${path.delimiter}${previousPath ?? ''}`;
+  process.env.AGENT_DEVICE_TEST_ARGS_FILE = argsLogPath;
+
+  const device: DeviceInfo = {
+    platform: 'android',
+    id: 'R5CT11',
+    name: 'Pixel Device',
+    kind: 'device',
+    booted: true,
+  };
+
+  try {
+    await assert.rejects(() => setAndroidSetting(device, 'fingerprint', 'match'));
+    const logged = await fs.readFile(argsLogPath, 'utf8');
+    assert.doesNotMatch(logged, /\nemu\nfinger\ntouch\n/);
+  } finally {
+    process.env.PATH = previousPath;
+    if (previousArgsFile === undefined) {
+      delete process.env.AGENT_DEVICE_TEST_ARGS_FILE;
+    } else {
+      process.env.AGENT_DEVICE_TEST_ARGS_FILE = previousArgsFile;
+    }
+    await fs.rm(tmpDir, { recursive: true, force: true });
+  }
+});
+
 test('swipeAndroid invokes adb input swipe with duration', async () => {
   const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'agent-device-swipe-test-'));
   const adbPath = path.join(tmpDir, 'adb');

src/platforms/android/index.ts

@@ -682,6 +682,11 @@ export async function setAndroidSetting(
       await runCmd('adb', adbArgs(device, ['shell', 'cmd', 'uimode', 'night', target === 'dark' ? 'yes' : 'no']));
       return;
     }
+    case 'fingerprint': {
+      const action = parseAndroidFingerprintAction(state);
+      await runAndroidFingerprintCommand(device, action);
+      return;
+    }
     case 'permission': {
       if (!appPackage) {
         throw new AppError(
@@ -708,6 +713,91 @@ export async function setAndroidSetting(
   }
 }
 
+type AndroidFingerprintAction = 'match' | 'nonmatch';
+
+function parseAndroidFingerprintAction(state: string): AndroidFingerprintAction {
+  const normalized = state.trim().toLowerCase();
+  if (normalized === 'match') return 'match';
+  if (normalized === 'nonmatch') return 'nonmatch';
+  throw new AppError(
+    'INVALID_ARGS',
+    `Invalid fingerprint state: ${state}. Use match|nonmatch.`,
+  );
+}
+
+async function runAndroidFingerprintCommand(
+  device: DeviceInfo,
+  action: AndroidFingerprintAction,
+): Promise<void> {
+  const attempts = androidFingerprintCommandAttempts(device, action);
+  const failures: Array<{ args: string[]; stdout: string; stderr: string; exitCode: number }> = [];
+
+  for (const args of attempts) {
+    const result = await runCmd('adb', adbArgs(device, args), { allowFailure: true });
+    if (result.exitCode === 0) return;
+    failures.push({
+      args,
+      stdout: result.stdout,
+      stderr: result.stderr,
+      exitCode: result.exitCode,
+    });
+  }
+
+  const attemptsPayload = failures.map((failure) => ({
+    args: failure.args.join(' '),
+    exitCode: failure.exitCode,
+    stderr: failure.stderr.slice(0, 400),
+  }));
+  const capabilityMissing = failures.length > 0 && failures.every((failure) =>
+    isAndroidFingerprintCapabilityMissing(failure.stdout, failure.stderr)
+  );
+  if (capabilityMissing) {
+    throw new AppError(
+      'UNSUPPORTED_OPERATION',
+      'Android fingerprint simulation is not supported on this target/runtime.',
+      {
+        deviceId: device.id,
+        action,
+        hint: 'Use an Android emulator with biometric support, or a device/runtime that exposes cmd fingerprint.',
+        attempts: attemptsPayload,
+      },
+    );
+  }
+  throw new AppError('COMMAND_FAILED', 'Failed to simulate Android fingerprint.', {
+    deviceId: device.id,
+    action,
+    attempts: attemptsPayload,
+  });
+}
+
+function androidFingerprintCommandAttempts(
+  device: DeviceInfo,
+  action: AndroidFingerprintAction,
+): string[][] {
+  const fingerprintId = action === 'match' ? '1' : '9999';
+  const attempts: string[][] = [
+    ['shell', 'cmd', 'fingerprint', 'touch', fingerprintId],
+    ['shell', 'cmd', 'fingerprint', 'finger', fingerprintId],
+  ];
+  if (device.kind === 'emulator') {
+    attempts.push(['emu', 'finger', 'touch', fingerprintId]);
+  }
+  return attempts;
+}
+
+function isAndroidFingerprintCapabilityMissing(stdout: string, stderr: string): boolean {
+  const text = `${stdout}\n${stderr}`.toLowerCase();
+  return (
+    text.includes('unknown command') ||
+    text.includes("can't find service: fingerprint") ||
+    text.includes('service fingerprint was not found') ||
+    text.includes('fingerprint cmd unavailable') ||
+    text.includes('emu command is not supported') ||
+    text.includes('emulator console is not running') ||
+    (text.includes('fingerprint') && text.includes('not found'))
+  );
+}
+
 export async function pushAndroidNotification(
   device: DeviceInfo,
   packageName: string,