agent-device 0.3.4 → 0.4.0

package/src/daemon/handlers/interaction.ts

@@ -41,6 +41,8 @@ export async function handleInteractionCommands(params: {
     }
     const refInput = req.positionals?.[0] ?? '';
     if (refInput.startsWith('@')) {
+      const invalidRefFlagsResponse = refSnapshotFlagGuardResponse('click', req.flags);
+      if (invalidRefFlagsResponse) return invalidRefFlagsResponse;
       if (!session.snapshot) {
         return { ok: false, error: { code: 'INVALID_ARGS', message: 'No snapshot in session. Run snapshot first.' } };
       }
@@ -126,6 +128,8 @@ export async function handleInteractionCommands(params: {
   if (command === 'fill') {
     const session = sessionStore.get(sessionName);
     if (req.positionals?.[0]?.startsWith('@')) {
+      const invalidRefFlagsResponse = refSnapshotFlagGuardResponse('fill', req.flags);
+      if (invalidRefFlagsResponse) return invalidRefFlagsResponse;
       if (!session?.snapshot) {
         return { ok: false, error: { code: 'INVALID_ARGS', message: 'No snapshot in session. Run snapshot first.' } };
       }
@@ -258,6 +262,8 @@ export async function handleInteractionCommands(params: {
     }
     const refInput = req.positionals?.[1] ?? '';
     if (refInput.startsWith('@')) {
+      const invalidRefFlagsResponse = refSnapshotFlagGuardResponse('get', req.flags);
+      if (invalidRefFlagsResponse) return invalidRefFlagsResponse;
       if (!session.snapshot) {
         return { ok: false, error: { code: 'INVALID_ARGS', message: 'No snapshot in session. Run snapshot first.' } };
       }
@@ -511,3 +517,34 @@ async function captureSnapshotForSession(
   sessionStore.set(session.name, session);
   return session.snapshot;
 }
+
+const REF_UNSUPPORTED_FLAG_MAP: ReadonlyArray<[keyof CommandFlags, string]> = [
+  ['snapshotDepth', '--depth'],
+  ['snapshotScope', '--scope'],
+  ['snapshotRaw', '--raw'],
+  ['snapshotBackend', '--backend'],
+];
+
+function refSnapshotFlagGuardResponse(
+  command: 'click' | 'fill' | 'get',
+  flags: CommandFlags | undefined,
+): DaemonResponse | null {
+  const unsupported = unsupportedRefSnapshotFlags(flags);
+  if (unsupported.length === 0) return null;
+  return {
+    ok: false,
+    error: {
+      code: 'INVALID_ARGS',
+      message: `${command} @ref does not support ${unsupported.join(', ')}.`,
+    },
+  };
+}
+
+export function unsupportedRefSnapshotFlags(flags: CommandFlags | undefined): string[] {
+  if (!flags) return [];
+  const unsupported: string[] = [];
+  for (const [key, label] of REF_UNSUPPORTED_FLAG_MAP) {
+    if (flags[key] !== undefined) unsupported.push(label);
+  }
+  return unsupported;
+}

package/src/daemon/handlers/record-trace.ts

@@ -47,7 +47,7 @@ export async function handleRecordTraceCommands(params: {
       if (!isCommandSupportedOnDevice('record', device)) {
         return {
           ok: false,
-          error: { code: 'UNSUPPORTED_OPERATION', message: 'record is only supported on iOS simulators in v1' },
+          error: { code: 'UNSUPPORTED_OPERATION', message: 'record is only supported on iOS simulators' },
         };
       }
       if (device.platform === 'ios') {

package/src/daemon/handlers/session.ts

@@ -1,6 +1,7 @@
 import fs from 'node:fs';
 import { dispatchCommand, resolveTargetDevice } from '../../core/dispatch.ts';
 import { isCommandSupportedOnDevice } from '../../core/capabilities.ts';
+import { isDeepLinkTarget } from '../../core/open-target.ts';
 import { AppError, asAppError } from '../../utils/errors.ts';
 import type { DeviceInfo } from '../../utils/device.ts';
 import type { DaemonRequest, DaemonResponse, SessionAction, SessionState } from '../types.ts';
@@ -53,6 +54,18 @@ const defaultReinstallOps: ReinstallOps = {
   },
 };
 
+async function resolveIosBundleIdForOpen(device: DeviceInfo, openTarget: string | undefined): Promise<string | undefined> {
+  if (device.platform !== 'ios' || !openTarget || isDeepLinkTarget(openTarget)) {
+    return undefined;
+  }
+  try {
+    const { resolveIosApp } = await import('../../platforms/ios/index.ts');
+    return await resolveIosApp(device, openTarget);
+  } catch {
+    return undefined;
+  }
+}
+
 export async function handleSessionCommands(params: {
   req: DaemonRequest;
   sessionName: string;
@@ -286,10 +299,21 @@ export async function handleSessionCommands(params: {
   }
 
   if (command === 'open') {
+    const shouldRelaunch = req.flags?.relaunch === true;
     if (sessionStore.has(sessionName)) {
       const session = sessionStore.get(sessionName);
-      const appName = req.positionals?.[0];
-      if (!session || !appName) {
+      const requestedOpenTarget = req.positionals?.[0];
+      const openTarget = requestedOpenTarget ?? (shouldRelaunch ? session?.appName : undefined);
+      if (!session || !openTarget) {
+        if (shouldRelaunch) {
+          return {
+            ok: false,
+            error: {
+              code: 'INVALID_ARGS',
+              message: 'open --relaunch requires an app name or an active session app.',
+            },
+          };
+        }
         return {
           ok: false,
           error: {
@@ -298,33 +322,60 @@ export async function handleSessionCommands(params: {
           },
         };
       }
-      let appBundleId: string | undefined;
-      if (session.device.platform === 'ios') {
-        try {
-          const { resolveIosApp } = await import('../../platforms/ios/index.ts');
-          appBundleId = await resolveIosApp(session.device, appName);
-        } catch {
-          appBundleId = undefined;
-        }
+      if (shouldRelaunch && isDeepLinkTarget(openTarget)) {
+        return {
+          ok: false,
+          error: {
+            code: 'INVALID_ARGS',
+            message: 'open --relaunch does not support URL targets.',
+          },
+        };
+      }
+      const appBundleId = await resolveIosBundleIdForOpen(session.device, openTarget);
+      const openPositionals = requestedOpenTarget ? (req.positionals ?? []) : [openTarget];
+      if (shouldRelaunch) {
+        const closeTarget = appBundleId ?? openTarget;
+        await dispatch(session.device, 'close', [closeTarget], req.flags?.out, {
+          ...contextFromFlags(logPath, req.flags, appBundleId ?? session.appBundleId, session.trace?.outPath),
+        });
       }
-      await dispatch(session.device, 'open', req.positionals ?? [], req.flags?.out, {
+      await dispatch(session.device, 'open', openPositionals, req.flags?.out, {
         ...contextFromFlags(logPath, req.flags, appBundleId),
       });
       const nextSession: SessionState = {
         ...session,
         appBundleId,
-        appName,
+        appName: openTarget,
         recordSession: session.recordSession || req.flags?.saveScript === true,
         snapshot: undefined,
       };
       sessionStore.recordAction(nextSession, {
         command,
-        positionals: req.positionals ?? [],
+        positionals: openPositionals,
         flags: req.flags ?? {},
-        result: { session: sessionName, appName, appBundleId },
+        result: { session: sessionName, appName: openTarget, appBundleId },
       });
       sessionStore.set(sessionName, nextSession);
-      return { ok: true, data: { session: sessionName, appName, appBundleId } };
+      return { ok: true, data: { session: sessionName, appName: openTarget, appBundleId } };
+    }
+    const openTarget = req.positionals?.[0];
+    if (shouldRelaunch && !openTarget) {
+      return {
+        ok: false,
+        error: {
+          code: 'INVALID_ARGS',
+          message: 'open --relaunch requires an app argument.',
+        },
+      };
+    }
+    if (shouldRelaunch && openTarget && isDeepLinkTarget(openTarget)) {
+      return {
+        ok: false,
+        error: {
+          code: 'INVALID_ARGS',
+          message: 'open --relaunch does not support URL targets.',
+        },
+      };
     }
     const device = await resolveTargetDevice(req.flags ?? {});
     const inUse = sessionStore.toArray().find((s) => s.device.id === device.id);
@@ -338,15 +389,12 @@ export async function handleSessionCommands(params: {
         },
       };
     }
-    let appBundleId: string | undefined;
-    const appName = req.positionals?.[0];
-    if (device.platform === 'ios') {
-      try {
-        const { resolveIosApp } = await import('../../platforms/ios/index.ts');
-        appBundleId = await resolveIosApp(device, req.positionals?.[0] ?? '');
-      } catch {
-        appBundleId = undefined;
-      }
+    const appBundleId = await resolveIosBundleIdForOpen(device, openTarget);
+    if (shouldRelaunch && openTarget) {
+      const closeTarget = appBundleId ?? openTarget;
+      await dispatch(device, 'close', [closeTarget], req.flags?.out, {
+        ...contextFromFlags(logPath, req.flags, appBundleId),
+      });
     }
     await dispatch(device, 'open', req.positionals ?? [], req.flags?.out, {
       ...contextFromFlags(logPath, req.flags, appBundleId),
@@ -356,7 +404,7 @@ export async function handleSessionCommands(params: {
       device,
       createdAt: Date.now(),
       appBundleId,
-      appName,
+      appName: openTarget,
       recordSession: req.flags?.saveScript === true,
       actions: [],
     };
@@ -449,7 +497,7 @@ export async function handleSessionCommands(params: {
         ...contextFromFlags(logPath, req.flags, session.appBundleId, session.trace?.outPath),
       });
     }
-    if (session.device.platform === 'ios' && session.device.kind === 'simulator') {
+    if (session.device.platform === 'ios') {
       await stopIosRunnerSession(session.device.id);
     }
     sessionStore.recordAction(session, {
@@ -822,6 +870,19 @@ function parseReplayScriptLine(line: string): SessionAction | null {
     return action;
   }
 
+  if (command === 'open') {
+    action.positionals = [];
+    for (let index = 0; index < args.length; index += 1) {
+      const token = args[index];
+      if (token === '--relaunch') {
+        action.flags.relaunch = true;
+        continue;
+      }
+      action.positionals.push(token);
+    }
+    return action;
+  }
+
   if (command === 'click') {
     if (args.length === 0) return action;
     const target = args[0];
@@ -948,6 +1009,15 @@ function formatReplayActionLine(action: SessionAction): string {
     }
     return parts.join(' ');
   }
+  if (action.command === 'open') {
+    for (const positional of action.positionals ?? []) {
+      parts.push(formatReplayArg(positional));
+    }
+    if (action.flags?.relaunch) {
+      parts.push('--relaunch');
+    }
+    return parts.join(' ');
+  }
   for (const positional of action.positionals ?? []) {
     parts.push(formatReplayArg(positional));
   }

package/src/daemon/handlers/snapshot.ts

@@ -33,7 +33,16 @@ export async function handleSnapshotCommands(params: {
         ok: false,
         error: {
           code: 'UNSUPPORTED_OPERATION',
-          message: 'snapshot is only supported on iOS simulators in v1',
+          message: 'snapshot is not supported on this device',
+        },
+      };
+    }
+    if (device.platform === 'ios' && device.kind === 'device' && req.flags?.snapshotBackend === 'ax') {
+      return {
+        ok: false,
+        error: {
+          code: 'UNSUPPORTED_OPERATION',
+          message: 'AX snapshot backend is not supported on iOS physical devices; use --backend xctest',
         },
       };
     }
@@ -227,7 +236,7 @@ export async function handleSnapshotCommands(params: {
     const timeout = timeoutMs ?? DEFAULT_TIMEOUT_MS;
     const start = Date.now();
     while (Date.now() - start < timeout) {
-      if (device.platform === 'ios' && device.kind === 'simulator') {
+      if (device.platform === 'ios') {
         const result = (await runIosRunnerCommand(
           device,
           { command: 'findText', text, appBundleId: session?.appBundleId },
@@ -260,7 +269,7 @@ export async function handleSnapshotCommands(params: {
         ok: false,
         error: {
           code: 'UNSUPPORTED_OPERATION',
-          message: 'alert is only supported on iOS simulators in v1',
+          message: 'alert is only supported on iOS simulators',
         },
       };
     }
@@ -310,6 +319,15 @@ export async function handleSnapshotCommands(params: {
       };
     }
     const { session, device } = await resolveSessionDevice(sessionStore, sessionName, req.flags);
+    if (!isCommandSupportedOnDevice('settings', device)) {
+      return {
+        ok: false,
+        error: {
+          code: 'UNSUPPORTED_OPERATION',
+          message: 'settings is not supported on this device',
+        },
+      };
+    }
     const appBundleId = session?.appBundleId;
     const data = await dispatchCommand(
       device,

package/src/daemon/session-store.ts

@@ -166,6 +166,7 @@ function sanitizeFlags(flags: CommandFlags | undefined): SessionAction['flags']
     snapshotRaw,
     snapshotBackend,
     appsMetadata,
+    relaunch,
     saveScript,
     noRecord,
   } = flags;
@@ -183,6 +184,7 @@ function sanitizeFlags(flags: CommandFlags | undefined): SessionAction['flags']
     snapshotRaw,
     snapshotBackend,
     appsMetadata,
+    relaunch,
     saveScript,
     noRecord,
   };
@@ -261,6 +263,15 @@ function formatActionLine(action: SessionAction): string {
     }
     return parts.join(' ');
   }
+  if (action.command === 'open') {
+    for (const positional of action.positionals ?? []) {
+      parts.push(formatArg(positional));
+    }
+    if (action.flags?.relaunch) {
+      parts.push('--relaunch');
+    }
+    return parts.join(' ');
+  }
   for (const positional of action.positionals ?? []) {
     parts.push(formatArg(positional));
   }

package/src/daemon-client.ts

@@ -35,8 +35,9 @@ export async function sendToDaemon(req: Omit<DaemonRequest, 'token'>): Promise<D
 async function ensureDaemon(): Promise<DaemonInfo> {
   const existing = readDaemonInfo();
   const localVersion = readVersion();
-  if (existing && existing.version === localVersion && (await canConnect(existing))) return existing;
-  if (existing && (existing.version !== localVersion || !(await canConnect(existing)))) {
+  const existingReachable = existing ? await canConnect(existing) : false;
+  if (existing && existing.version === localVersion && existingReachable) return existing;
+  if (existing && (existing.version !== localVersion || !existingReachable)) {
     removeDaemonInfo();
   }
 
@@ -67,7 +68,11 @@ function readDaemonInfo(): DaemonInfo | null {
 }
 
 function removeDaemonInfo(): void {
-  if (fs.existsSync(infoPath)) fs.unlinkSync(infoPath);
+  try {
+    if (fs.existsSync(infoPath)) fs.unlinkSync(infoPath);
+  } catch {
+    // Best-effort cleanup only; daemon can still overwrite this file on startup.
+  }
 }
 
 async function canConnect(info: DaemonInfo): Promise<boolean> {
@@ -87,11 +92,14 @@ async function startDaemon(): Promise<void> {
   const distPath = path.join(root, 'dist', 'src', 'daemon.js');
   const srcPath = path.join(root, 'src', 'daemon.ts');
 
-  const useDist = fs.existsSync(distPath);
-  if (!useDist && !fs.existsSync(srcPath)) {
+  const hasDist = fs.existsSync(distPath);
+  const hasSrc = fs.existsSync(srcPath);
+  if (!hasDist && !hasSrc) {
     throw new AppError('COMMAND_FAILED', 'Daemon entry not found', { distPath, srcPath });
   }
-  const args = useDist ? [distPath] : ['--experimental-strip-types', srcPath];
+  const runningFromSource = process.execArgv.includes('--experimental-strip-types');
+  const useSrc = runningFromSource ? hasSrc : !hasDist && hasSrc;
+  const args = useSrc ? ['--experimental-strip-types', srcPath] : [distPath];
 
   runCmdDetached(process.execPath, args);
 }

package/src/daemon.ts

@@ -175,7 +175,7 @@ function start(): void {
   const shutdown = async () => {
     const sessionsToStop = sessionStore.toArray();
     for (const session of sessionsToStop) {
-      if (session.device.platform === 'ios' && session.device.kind === 'simulator') {
+      if (session.device.platform === 'ios') {
         await stopIosRunnerSession(session.device.id);
       }
       sessionStore.writeSessionLog(session);

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

@@ -1,6 +1,11 @@
 import test from 'node:test';
 import assert from 'node:assert/strict';
-import { parseAndroidLaunchComponent } from '../index.ts';
+import { promises as fs } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { openAndroidApp, parseAndroidLaunchComponent, swipeAndroid } from '../index.ts';
+import type { DeviceInfo } from '../../../utils/device.ts';
+import { AppError } from '../../../utils/errors.ts';
 import { findBounds, parseUiHierarchy } from '../ui-hierarchy.ts';
 
 test('parseUiHierarchy reads double-quoted Android node attributes', () => {
@@ -89,3 +94,64 @@ test('parseAndroidLaunchComponent returns null when no component is present', ()
   const stdout = 'No activity found';
   assert.equal(parseAndroidLaunchComponent(stdout), null);
 });
+
+test('openAndroidApp rejects activity override for deep link URLs', async () => {
+  const device: DeviceInfo = {
+    platform: 'android',
+    id: 'emulator-5554',
+    name: 'Pixel',
+    kind: 'emulator',
+    booted: true,
+  };
+
+  await assert.rejects(
+    () => openAndroidApp(device, '  https://example.com/path  ', '.MainActivity'),
+    (error: unknown) => {
+      assert.equal(error instanceof AppError, true);
+      assert.equal((error as AppError).code, 'INVALID_ARGS');
+      return 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');
+  const argsLogPath = path.join(tmpDir, 'args.log');
+  await fs.writeFile(
+    adbPath,
+    '#!/bin/sh\nprintf "%s\\n" "$@" > "$AGENT_DEVICE_TEST_ARGS_FILE"\nexit 0\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: 'emulator-5554',
+    name: 'Pixel',
+    kind: 'emulator',
+    booted: true,
+  };
+
+  try {
+    await swipeAndroid(device, 10, 20, 30, 40, 250);
+    const args = (await fs.readFile(argsLogPath, 'utf8'))
+      .trim()
+      .split('\n')
+      .filter(Boolean);
+    assert.deepEqual(args, ['-s', 'emulator-5554', 'shell', 'input', 'swipe', '10', '20', '30', '40', '250']);
+  } 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 });
+  }
+});

package/src/platforms/android/index.ts

@@ -4,6 +4,7 @@ import { withRetry } from '../../utils/retry.ts';
 import { AppError } from '../../utils/errors.ts';
 import type { DeviceInfo } from '../../utils/device.ts';
 import type { RawSnapshotNode, SnapshotOptions } from '../../utils/snapshot.ts';
+import { isDeepLinkTarget } from '../../core/open-target.ts';
 import { waitForAndroidBoot } from './devices.ts';
 import { findBounds, parseBounds, parseUiHierarchy, readNodeAttributes } from './ui-hierarchy.ts';
 
@@ -157,6 +158,23 @@ export async function openAndroidApp(
   if (!device.booted) {
     await waitForAndroidBoot(device.id);
   }
+  const deepLinkTarget = app.trim();
+  if (isDeepLinkTarget(deepLinkTarget)) {
+    if (activity) {
+      throw new AppError('INVALID_ARGS', 'Activity override is not supported when opening a deep link URL');
+    }
+    await runCmd('adb', adbArgs(device, [
+      'shell',
+      'am',
+      'start',
+      '-W',
+      '-a',
+      'android.intent.action.VIEW',
+      '-d',
+      deepLinkTarget,
+    ]));
+    return;
+  }
   const resolved = await resolveAndroidApp(device, app);
   if (resolved.type === 'intent') {
     if (activity) {
@@ -315,6 +333,29 @@ 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 swipeAndroid(
+  device: DeviceInfo,
+  x1: number,
+  y1: number,
+  x2: number,
+  y2: number,
+  durationMs = 250,
+): Promise<void> {
+  await runCmd(
+    'adb',
+    adbArgs(device, [
+      'shell',
+      'input',
+      'swipe',
+      String(x1),
+      String(y1),
+      String(x2),
+      String(y2),
+      String(durationMs),
+    ]),
+  );
+}
+
 export async function backAndroid(device: DeviceInfo): Promise<void> {
   await runCmd('adb', adbArgs(device, ['shell', 'input', 'keyevent', '4']));
 }

package/src/platforms/ios/__tests__/index.test.ts

@@ -0,0 +1,24 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { openIosApp } from '../index.ts';
+import type { DeviceInfo } from '../../../utils/device.ts';
+import { AppError } from '../../../utils/errors.ts';
+
+test('openIosApp rejects deep links on iOS physical devices', async () => {
+  const device: DeviceInfo = {
+    platform: 'ios',
+    id: 'ios-device-1',
+    name: 'iPhone Device',
+    kind: 'device',
+    booted: true,
+  };
+
+  await assert.rejects(
+    () => openIosApp(device, 'https://example.com/path'),
+    (error: unknown) => {
+      assert.equal(error instanceof AppError, true);
+      assert.equal((error as AppError).code, 'UNSUPPORTED_OPERATION');
+      return true;
+    },
+  );
+});