agent-device 0.1.2 → 0.1.3

package/src/daemon.ts

@@ -16,6 +16,8 @@ import {
   type RawSnapshotNode,
 } from './utils/snapshot.ts';
 import { runIosRunnerCommand, stopIosRunnerSession } from './platforms/ios/runner-client.ts';
+import { runCmd, runCmdBackground } from './utils/exec.ts';
+import { snapshotAndroid } from './platforms/android/index.ts';
 
 type DaemonRequest = {
   token: string;
@@ -37,6 +39,13 @@ type SessionState = {
   appName?: string;
   snapshot?: SnapshotState;
   actions: SessionAction[];
+  recording?: {
+    platform: 'ios' | 'android';
+    outPath: string;
+    remotePath?: string;
+    child: ReturnType<typeof import('node:child_process').spawn>;
+    wait: Promise<import('./utils/exec.ts').ExecResult>;
+  };
 };
 
 type SessionAction = {
@@ -112,6 +121,71 @@ async function handleRequest(req: DaemonRequest): Promise<DaemonResponse> {
     return { ok: true, data };
   }
 
+  if (command === 'devices') {
+    try {
+      const devices: DeviceInfo[] = [];
+      if (req.flags?.platform === 'android') {
+        const { listAndroidDevices } = await import('./platforms/android/devices.ts');
+        devices.push(...(await listAndroidDevices()));
+      } else if (req.flags?.platform === 'ios') {
+        const { listIosDevices } = await import('./platforms/ios/devices.ts');
+        devices.push(...(await listIosDevices()));
+      } else {
+        const { listAndroidDevices } = await import('./platforms/android/devices.ts');
+        const { listIosDevices } = await import('./platforms/ios/devices.ts');
+        try {
+          devices.push(...(await listAndroidDevices()));
+        } catch {
+          // ignore
+        }
+        try {
+          devices.push(...(await listIosDevices()));
+        } catch {
+          // ignore
+        }
+      }
+      return { ok: true, data: { devices } };
+    } catch (err) {
+      const appErr = asAppError(err);
+      return { ok: false, error: { code: appErr.code, message: appErr.message, details: appErr.details } };
+    }
+  }
+
+  if (command === 'apps') {
+    const session = sessions.get(sessionName);
+    const flags = req.flags ?? {};
+    if (
+      !session &&
+      !flags.platform &&
+      !flags.device &&
+      !flags.udid &&
+      !flags.serial
+    ) {
+      return {
+        ok: false,
+        error: {
+          code: 'INVALID_ARGS',
+          message: 'apps requires an active session or an explicit device selector (e.g. --platform ios).',
+        },
+      };
+    }
+    const device = session?.device ?? (await resolveTargetDevice(flags));
+    await ensureDeviceReady(device);
+    if (device.platform === 'ios') {
+      if (device.kind !== 'simulator') {
+        return { ok: false, error: { code: 'UNSUPPORTED_OPERATION', message: 'apps list is only supported on iOS simulators' } };
+      }
+      const { listSimulatorApps } = await import('./platforms/ios/index.ts');
+      const apps = (await listSimulatorApps(device)).map((app) =>
+        app.name && app.name !== app.bundleId ? `${app.name} (${app.bundleId})` : app.bundleId,
+      );
+      return { ok: true, data: { apps } };
+    }
+    const { listAndroidApps } = await import('./platforms/android/index.ts');
+    const apps = await listAndroidApps(device, req.flags?.appsFilter);
+    return { ok: true, data: { apps } };
+  }
+
   if (command === 'open') {
     if (sessions.has(sessionName)) {
       return {
@@ -226,15 +300,31 @@ async function handleRequest(req: DaemonRequest): Promise<DaemonResponse> {
       await ensureDeviceReady(device);
     }
     const appBundleId = session?.appBundleId;
+    let snapshotScope = req.flags?.snapshotScope;
+    if (snapshotScope && snapshotScope.trim().startsWith('@')) {
+      if (!session?.snapshot) {
+        return { ok: false, error: { code: 'INVALID_ARGS', message: 'Ref scope requires an existing snapshot in session.' } };
+      }
+      const ref = normalizeRef(snapshotScope.trim());
+      if (!ref) {
+        return { ok: false, error: { code: 'INVALID_ARGS', message: `Invalid ref scope: ${snapshotScope}` } };
+      }
+      const node = findNodeByRef(session.snapshot.nodes, ref);
+      const resolved = node ? resolveRefLabel(node, session.snapshot.nodes) : undefined;
+      if (!resolved) {
+        return { ok: false, error: { code: 'COMMAND_FAILED', message: `Ref ${snapshotScope} not found or has no label` } };
+      }
+      snapshotScope = resolved;
+    }
     const data = (await dispatchCommand(device, 'snapshot', [], req.flags?.out, {
-      ...contextFromFlags(req.flags, appBundleId),
+      ...contextFromFlags({ ...req.flags, snapshotScope }, appBundleId),
     })) as {
       nodes?: RawSnapshotNode[];
       truncated?: boolean;
       backend?: 'ax' | 'xctest' | 'android';
     };
-    const pruned = pruneGroupNodes(data?.nodes ?? []);
-    const nodes = attachRefs(pruned);
+    const rawNodes = data?.nodes ?? [];
+    const nodes = attachRefs(req.flags?.snapshotRaw ? rawNodes : pruneGroupNodes(rawNodes));
     const snapshot: SnapshotState = {
       nodes,
       truncated: data?.truncated,
@@ -267,6 +357,229 @@ async function handleRequest(req: DaemonRequest): Promise<DaemonResponse> {
     };
   }
 
+  if (command === 'wait') {
+    const session = sessions.get(sessionName);
+    const device = session?.device ?? (await resolveTargetDevice(req.flags ?? {}));
+    if (!session) {
+      await ensureDeviceReady(device);
+    }
+    const args = req.positionals ?? [];
+    if (args.length === 0) {
+      return { ok: false, error: { code: 'INVALID_ARGS', message: 'wait requires a duration or text' } };
+    }
+    const parseTimeout = (value: string | undefined): number | null => {
+      if (!value) return null;
+      const parsed = Number(value);
+      return Number.isFinite(parsed) ? parsed : null;
+    };
+    const sleepMs = parseTimeout(args[0]);
+    if (sleepMs !== null) {
+      await new Promise((resolve) => setTimeout(resolve, sleepMs));
+      if (session) {
+        recordAction(session, { command, positionals: req.positionals ?? [], flags: req.flags ?? {}, result: { waitedMs: sleepMs } });
+      }
+      return { ok: true, data: { waitedMs: sleepMs } };
+    }
+    let text = '';
+    let timeoutMs: number | null = null;
+    if (args[0] === 'text') {
+      timeoutMs = parseTimeout(args[args.length - 1]);
+      text = timeoutMs !== null ? args.slice(1, -1).join(' ') : args.slice(1).join(' ');
+    } else if (args[0].startsWith('@')) {
+      if (!session?.snapshot) {
+        return { ok: false, error: { code: 'INVALID_ARGS', message: 'Ref wait requires an existing snapshot in session.' } };
+      }
+      const ref = normalizeRef(args[0]);
+      if (!ref) {
+        return { ok: false, error: { code: 'INVALID_ARGS', message: `Invalid ref: ${args[0]}` } };
+      }
+      const node = findNodeByRef(session.snapshot.nodes, ref);
+      const resolved = node ? resolveRefLabel(node, session.snapshot.nodes) : undefined;
+      if (!resolved) {
+        return { ok: false, error: { code: 'COMMAND_FAILED', message: `Ref ${args[0]} not found or has no label` } };
+      }
+      timeoutMs = parseTimeout(args[args.length - 1]);
+      text = resolved;
+    } else {
+      timeoutMs = parseTimeout(args[args.length - 1]);
+      text = timeoutMs !== null ? args.slice(0, -1).join(' ') : args.join(' ');
+    }
+    text = text.trim();
+    if (!text) {
+      return { ok: false, error: { code: 'INVALID_ARGS', message: 'wait requires text' } };
+    }
+    const timeout = timeoutMs ?? 10000;
+    const start = Date.now();
+    while (Date.now() - start < timeout) {
+      if (device.platform === 'ios' && device.kind === 'simulator') {
+        const result = (await runIosRunnerCommand(
+          device,
+          { command: 'findText', text, appBundleId: session?.appBundleId },
+          { verbose: req.flags?.verbose, logPath },
+        )) as { found?: boolean };
+        if (result?.found) {
+          if (session) {
+            recordAction(session, { command, positionals: req.positionals ?? [], flags: req.flags ?? {}, result: { text, waitedMs: Date.now() - start } });
+          }
+          return { ok: true, data: { text, waitedMs: Date.now() - start } };
+        }
+      } else if (device.platform === 'android') {
+        const androidResult = await snapshotAndroid(device, { scope: text });
+        if (findNodeByLabel(attachRefs(androidResult.nodes ?? []), text)) {
+          if (session) {
+            recordAction(session, { command, positionals: req.positionals ?? [], flags: req.flags ?? {}, result: { text, waitedMs: Date.now() - start } });
+          }
+          return { ok: true, data: { text, waitedMs: Date.now() - start } };
+        }
+      } else {
+        return { ok: false, error: { code: 'UNSUPPORTED_OPERATION', message: 'wait is not supported on this device' } };
+      }
+      await new Promise((resolve) => setTimeout(resolve, 300));
+    }
+    return { ok: false, error: { code: 'COMMAND_FAILED', message: `wait timed out for text: ${text}` } };
+  }
+
+  if (command === 'alert') {
+    const session = sessions.get(sessionName);
+    const device = session?.device ?? (await resolveTargetDevice(req.flags ?? {}));
+    if (!session) {
+      await ensureDeviceReady(device);
+    }
+    const action = (req.positionals?.[0] ?? 'get').toLowerCase();
+    const parseTimeout = (value: string | undefined): number | null => {
+      if (!value) return null;
+      const parsed = Number(value);
+      return Number.isFinite(parsed) ? parsed : null;
+    };
+    if (device.platform !== 'ios' || device.kind !== 'simulator') {
+      return { ok: false, error: { code: 'UNSUPPORTED_OPERATION', message: 'alert is only supported on iOS simulators in v1' } };
+    }
+    if (action === 'wait') {
+      const timeout = parseTimeout(req.positionals?.[1]) ?? 10000;
+      const start = Date.now();
+      while (Date.now() - start < timeout) {
+        try {
+          const data = await runIosRunnerCommand(
+            device,
+            { command: 'alert', action: 'get', appBundleId: session?.appBundleId },
+            { verbose: req.flags?.verbose, logPath },
+          );
+          if (session) {
+            recordAction(session, {
+              command,
+              positionals: req.positionals ?? [],
+              flags: req.flags ?? {},
+              result: data,
+            });
+          }
+          return { ok: true, data };
+        } catch {
+          // keep waiting
+        }
+        await new Promise((resolve) => setTimeout(resolve, 300));
+      }
+      return { ok: false, error: { code: 'COMMAND_FAILED', message: 'alert wait timed out' } };
+    }
+    const data = await runIosRunnerCommand(
+      device,
+      {
+        command: 'alert',
+        action: action === 'accept' || action === 'dismiss' ? (action as 'accept' | 'dismiss') : 'get',
+        appBundleId: session?.appBundleId,
+      },
+      { verbose: req.flags?.verbose, logPath },
+    );
+    if (session) {
+      recordAction(session, {
+        command,
+        positionals: req.positionals ?? [],
+        flags: req.flags ?? {},
+        result: data,
+      });
+    }
+    return { ok: true, data };
+  }
+
+  if (command === 'record') {
+    const action = (req.positionals?.[0] ?? '').toLowerCase();
+    if (!['start', 'stop'].includes(action)) {
+      return { ok: false, error: { code: 'INVALID_ARGS', message: 'record requires start|stop' } };
+    }
+    const session = sessions.get(sessionName);
+    const device = session?.device ?? (await resolveTargetDevice(req.flags ?? {}));
+    if (!session) {
+      await ensureDeviceReady(device);
+    }
+    const activeSession = session ?? {
+      name: sessionName,
+      device,
+      createdAt: Date.now(),
+      actions: [],
+    };
+
+    if (action === 'start') {
+      if (activeSession.recording) {
+        return { ok: false, error: { code: 'INVALID_ARGS', message: 'recording already in progress' } };
+      }
+      const outPath = req.positionals?.[1] ?? `./recording-${Date.now()}.mp4`;
+      const resolvedOut = path.resolve(outPath);
+      const outDir = path.dirname(resolvedOut);
+      if (!fs.existsSync(outDir)) {
+        fs.mkdirSync(outDir, { recursive: true });
+      }
+      if (device.platform === 'ios') {
+        if (device.kind !== 'simulator') {
+          return { ok: false, error: { code: 'UNSUPPORTED_OPERATION', message: 'record is only supported on iOS simulators in v1' } };
+        }
+        const { child, wait } = runCmdBackground('xcrun', ['simctl', 'io', device.id, 'recordVideo', resolvedOut], {
+          allowFailure: true,
+        });
+        activeSession.recording = { platform: 'ios', outPath: resolvedOut, child, wait };
+      } else {
+        const remotePath = `/sdcard/agent-device-recording-${Date.now()}.mp4`;
+        const { child, wait } = runCmdBackground('adb', ['-s', device.id, 'shell', 'screenrecord', remotePath], {
+          allowFailure: true,
+        });
+        activeSession.recording = { platform: 'android', outPath: resolvedOut, remotePath, child, wait };
+      }
+      sessions.set(sessionName, activeSession);
+      recordAction(activeSession, {
+        command,
+        positionals: req.positionals ?? [],
+        flags: req.flags ?? {},
+        result: { action: 'start' },
+      });
+      return { ok: true, data: { recording: 'started', outPath } };
+    }
+
+    if (!activeSession.recording) {
+      return { ok: false, error: { code: 'INVALID_ARGS', message: 'no active recording' } };
+    }
+    const recording = activeSession.recording;
+    recording.child.kill('SIGINT');
+    try {
+      await recording.wait;
+    } catch {
+      // ignore
+    }
+    if (recording.platform === 'android' && recording.remotePath) {
+      try {
+        await runCmd('adb', ['-s', device.id, 'pull', recording.remotePath, recording.outPath], { allowFailure: true });
+        await runCmd('adb', ['-s', device.id, 'shell', 'rm', '-f', recording.remotePath], { allowFailure: true });
+      } catch {
+        // ignore
+      }
+    }
+    activeSession.recording = undefined;
+    recordAction(activeSession, {
+      command,
+      positionals: req.positionals ?? [],
+      flags: req.flags ?? {},
+      result: { action: 'stop', outPath: recording.outPath },
+    });
+    return { ok: true, data: { recording: 'stopped', outPath: recording.outPath } };
+  }
+
   if (command === 'click') {
     const session = sessions.get(sessionName);
     if (!session?.snapshot) {
@@ -410,39 +723,6 @@ async function handleRequest(req: DaemonRequest): Promise<DaemonResponse> {
     return { ok: true, data: { ref, text, node } };
   }
 
-  if (command === 'rect') {
-    const session = sessions.get(sessionName);
-    if (!session?.snapshot) {
-      return { ok: false, error: { code: 'INVALID_ARGS', message: 'No snapshot in session. Run snapshot first.' } };
-    }
-    const target = req.positionals?.[0] ?? '';
-    const ref = normalizeRef(target);
-    let label = '';
-    if (ref) {
-      const node = findNodeByRef(session.snapshot.nodes, ref);
-      label = node?.label?.trim() ?? '';
-    } else {
-      label = req.positionals.join(' ').trim();
-    }
-    if (!label) {
-      return { ok: false, error: { code: 'INVALID_ARGS', message: 'rect requires a label or ref with label' } };
-    }
-    if (session.device.platform !== 'ios' || session.device.kind !== 'simulator') {
-      return { ok: false, error: { code: 'UNSUPPORTED_OPERATION', message: 'rect is only supported on iOS simulators' } };
-    }
-    const data = await runIosRunnerCommand(
-      session.device,
-      { command: 'rect', text: label, appBundleId: session.appBundleId },
-      { verbose: req.flags?.verbose, logPath },
-    );
-    recordAction(session, {
-      command,
-      positionals: req.positionals ?? [],
-      flags: req.flags ?? {},
-      result: { label, rect: data?.rect },
-    });
-    return { ok: true, data: { label, rect: data?.rect } };
-  }
 
   const session = sessions.get(sessionName);
   if (!session) {
@@ -836,7 +1116,11 @@ function pruneGroupNodes(nodes: RawSnapshotNode[]): RawSnapshotNode[] {
       skippedDepths.pop();
     }
     const type = normalizeType(node.type ?? '');
-    if (type === 'group' || type === 'ioscontentgroup') {
+    const labelCandidate = [node.label, node.value, node.identifier]
+      .map((value) => (typeof value === 'string' ? value.trim() : ''))
+      .find((value) => value && value.length > 0);
+    const hasMeaningfulLabel = labelCandidate ? isMeaningfulLabel(labelCandidate) : false;
+    if ((type === 'group' || type === 'ioscontentgroup') && !hasMeaningfulLabel) {
       skippedDepths.push(depth);
       continue;
     }

package/src/platforms/android/index.ts

@@ -43,6 +43,53 @@ export async function resolveAndroidApp(
   throw new AppError('APP_NOT_INSTALLED', `No package found matching "${app}"`);
 }
 
+export async function listAndroidApps(
+  device: DeviceInfo,
+  filter: 'launchable' | 'user-installed' | 'all' = 'launchable',
+): Promise<string[]> {
+  if (filter === 'launchable') {
+    const result = await runCmd(
+      'adb',
+      adbArgs(device, [
+        'shell',
+        'cmd',
+        'package',
+        'query-activities',
+        '--brief',
+        '-a',
+        'android.intent.action.MAIN',
+        '-c',
+        'android.intent.category.LAUNCHER',
+      ]),
+      { allowFailure: true },
+    );
+    if (result.exitCode === 0 && result.stdout.trim().length > 0) {
+      const packages = new Set<string>();
+      for (const line of result.stdout.split('\n')) {
+        const trimmed = line.trim();
+        if (!trimmed) continue;
+        const firstToken = trimmed.split(/\s+/)[0];
+        const pkg = firstToken.includes('/') ? firstToken.split('/')[0] : firstToken;
+        if (pkg) packages.add(pkg);
+      }
+      if (packages.size > 0) {
+        return Array.from(packages);
+      }
+    }
+    // fallback: list all if query-activities not available
+  }
+
+  const args =
+    filter === 'user-installed'
+      ? ['shell', 'pm', 'list', 'packages', '-3']
+      : ['shell', 'pm', 'list', 'packages'];
+  const result = await runCmd('adb', adbArgs(device, args));
+  return result.stdout
+    .split('\n')
+    .map((line: string) => line.replace('package:', '').trim())
+    .filter(Boolean);
+}
+
 export async function openAndroidApp(device: DeviceInfo, app: string): Promise<void> {
   if (!device.booted) {
     await waitForAndroidBoot(device.id);
@@ -89,6 +136,18 @@ export async function pressAndroid(device: DeviceInfo, x: number, y: number): Pr
   await runCmd('adb', adbArgs(device, ['shell', 'input', 'tap', String(x), String(y)]));
 }
 
+export async function backAndroid(device: DeviceInfo): Promise<void> {
+  await runCmd('adb', adbArgs(device, ['shell', 'input', 'keyevent', '4']));
+}
+
+export async function homeAndroid(device: DeviceInfo): Promise<void> {
+  await runCmd('adb', adbArgs(device, ['shell', 'input', 'keyevent', '3']));
+}
+
+export async function appSwitcherAndroid(device: DeviceInfo): Promise<void> {
+  await runCmd('adb', adbArgs(device, ['shell', 'input', 'keyevent', '187']));
+}
+
 export async function longPressAndroid(
   device: DeviceInfo,
   x: number,

package/src/platforms/ios/ax-snapshot.ts

@@ -32,6 +32,10 @@ export async function snapshotAx(
         ' Enable Accessibility for your terminal in System Settings > Privacy & Security > Accessibility, ' +
         'or use --backend xctest (slower snapshots via XCTest).';
     }
+    if (stderrText.toLowerCase().includes('could not find ios app content')) {
+      hint =
+        ' AX snapshot sometimes caches empty content. Try restarting the Simulator app.';
+    }
     throw new AppError('COMMAND_FAILED', 'AX snapshot failed', {
       stderr: `${stderrText}${hint}`,
       stdout: result.stdout,
@@ -127,14 +131,8 @@ async function ensureAxSnapshotBinary(): Promise<string> {
   const packageDir = path.join(projectRoot, 'ios-runner', 'AXSnapshot');
   const envPath = process.env.AGENT_DEVICE_AX_BINARY;
   if (envPath && fs.existsSync(envPath)) return envPath;
-  const packagedCandidates = [
-    path.join(projectRoot, 'bin', 'axsnapshot'),
-    path.join(projectRoot, 'dist', 'bin', 'axsnapshot'),
-    path.join(projectRoot, 'dist', 'axsnapshot'),
-  ];
-  for (const candidate of packagedCandidates) {
-    if (fs.existsSync(candidate)) return candidate;
-  }
+  const packagedPath = path.join(projectRoot, 'dist', 'bin', 'axsnapshot');
+  if (fs.existsSync(packagedPath)) return packagedPath;
   const binaryPath = path.join(packageDir, '.build', 'release', 'axsnapshot');
   if (fs.existsSync(binaryPath)) return binaryPath;
   const result = await runCmd('swift', ['build', '-c', 'release'], {

package/src/platforms/ios/index.ts

@@ -163,24 +163,45 @@ function ensureSimulator(device: DeviceInfo, command: string): void {
   }
 }
 
-async function listSimulatorApps(
+export async function listSimulatorApps(
   device: DeviceInfo,
 ): Promise<{ bundleId: string; name: string }[]> {
   const result = await runCmd('xcrun', ['simctl', 'listapps', device.id], { allowFailure: true });
   const stdout = result.stdout as string;
-  if (!stdout.trim().startsWith('{')) return [];
-  try {
-    const payload = JSON.parse(stdout) as Record<
-      string,
-      { CFBundleDisplayName?: string; CFBundleName?: string }
-    >;
-    return Object.entries(payload).map(([bundleId, info]) => ({
-      bundleId,
-      name: info.CFBundleDisplayName ?? info.CFBundleName ?? bundleId,
-    }));
-  } catch {
-    return [];
+  const trimmed = stdout.trim();
+  if (!trimmed) return [];
+  let parsed: Record<string, { CFBundleDisplayName?: string; CFBundleName?: string }> | null = null;
+  if (trimmed.startsWith('{')) {
+    try {
+      parsed = JSON.parse(trimmed) as Record<
+        string,
+        { CFBundleDisplayName?: string; CFBundleName?: string }
+      >;
+    } catch {
+      parsed = null;
+    }
   }
+  if (!parsed && trimmed.startsWith('{')) {
+    try {
+      const converted = await runCmd('plutil', ['-convert', 'json', '-o', '-', '-'], {
+        allowFailure: true,
+        stdin: trimmed,
+      });
+      if (converted.exitCode === 0 && converted.stdout.trim().startsWith('{')) {
+        parsed = JSON.parse(converted.stdout) as Record<
+          string,
+          { CFBundleDisplayName?: string; CFBundleName?: string }
+        >;
+      }
+    } catch {
+      parsed = null;
+    }
+  }
+  if (!parsed) return [];
+  return Object.entries(parsed).map(([bundleId, info]) => ({
+    bundleId,
+    name: info.CFBundleDisplayName ?? info.CFBundleName ?? bundleId,
+  }));
 }
 
 export async function ensureBootedSimulator(device: DeviceInfo): Promise<void> {

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

@@ -8,9 +8,21 @@ import type { DeviceInfo } from '../../utils/device.ts';
 import net from 'node:net';
 
 export type RunnerCommand = {
-  command: 'tap' | 'type' | 'swipe' | 'findText' | 'listTappables' | 'snapshot' | 'rect' | 'shutdown';
+  command:
+    | 'tap'
+    | 'type'
+    | 'swipe'
+    | 'findText'
+    | 'listTappables'
+    | 'snapshot'
+    | 'back'
+    | 'home'
+    | 'appSwitcher'
+    | 'alert'
+    | 'shutdown';
   appBundleId?: string;
   text?: string;
+  action?: 'get' | 'accept' | 'dismiss';
   x?: number;
   y?: number;
   direction?: 'up' | 'down' | 'left' | 'right';

package/src/utils/args.ts

@@ -18,6 +18,7 @@ export type ParsedArgs = {
     snapshotScope?: string;
     snapshotRaw?: boolean;
     snapshotBackend?: 'ax' | 'xctest';
+    appsFilter?: 'launchable' | 'user-installed' | 'all';
     noRecord?: boolean;
     recordJson?: boolean;
     help: boolean;
@@ -62,6 +63,14 @@ export function parseArgs(argv: string[]): ParsedArgs {
       flags.recordJson = true;
       continue;
     }
+    if (arg === '--user-installed') {
+      flags.appsFilter = 'user-installed';
+      continue;
+    }
+    if (arg === '--all') {
+      flags.appsFilter = 'all';
+      continue;
+    }
     if (arg.startsWith('--backend')) {
       const value = arg.includes('=')
         ? arg.split('=')[1]
@@ -156,8 +165,14 @@ Commands:
     --raw                                    Raw node output
     --backend ax|xctest                       ax: macOS Accessibility tree (fast, recommended, needs permissions)
                                              xctest: XCTest snapshot (slower, no permissions)
+  devices                                   List available devices
+  apps [--user-installed|--all]             List installed apps (Android launchable by default, iOS simulator)
+  back                                      Navigate back (where supported)
+  home                                      Go to home screen (where supported)
+  app-switcher                              Open app switcher (where supported)
+  wait <ms>|text <text>|@ref [timeoutMs]     Wait for duration or text to appear
+  alert [get|accept|dismiss|wait] [timeout] Inspect or handle alert (iOS simulator)
   click <@ref>                               Click element by snapshot ref
-  rect <label|@ref>                          Fetch element frame by label or ref (iOS sim)
   get text <@ref>                            Return element text by ref
   get attrs <@ref>                           Return element attributes by ref
   replay <path>                              Replay a recorded session
@@ -169,6 +184,8 @@ Commands:
   scroll <direction> [amount]                Scroll in direction (0-1 amount)
   scrollintoview <text>                      Scroll until text appears (Android only)
   screenshot [--out path]                    Capture screenshot
+  record start [path]                        Start screen recording
+  record stop                                Stop screen recording
   session list                               List active sessions
 
 Flags:
@@ -182,5 +199,7 @@ Flags:
   --json                                     JSON output
   --no-record                                Do not record this action
   --record-json                              Record JSON session log
+  --user-installed                           Apps: list user-installed packages (Android only)
+  --all                                      Apps: list all packages (Android only)
 `;
 }