agent-device 0.3.3 → 0.3.5

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';
@@ -10,7 +11,7 @@ import { ensureDeviceReady } from '../device-ready.ts';
 import { resolveIosAppStateFromSnapshots } from '../app-state.ts';
 import { stopIosRunnerSession } from '../../platforms/ios/runner-client.ts';
 import { attachRefs, type RawSnapshotNode, type SnapshotState } from '../../utils/snapshot.ts';
-import { pruneGroupNodes } from '../snapshot-processing.ts';
+import { extractNodeText, normalizeType, pruneGroupNodes } from '../snapshot-processing.ts';
 import {
   buildSelectorChainForNode,
   resolveSelectorChain,
@@ -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: [],
     };
@@ -517,6 +565,10 @@ async function healReplayAction(params: {
   const session = sessionStore.get(sessionName);
   if (!session) return null;
   const requiresRect = action.command === 'click' || action.command === 'fill';
+  const allowDisambiguation =
+    action.command === 'click' ||
+    action.command === 'fill' ||
+    (action.command === 'get' && action.positionals?.[0] === 'text');
   const snapshot = await captureSnapshotForReplay(session, action, logPath, requiresRect, dispatch, sessionStore);
   const selectorCandidates = collectReplaySelectorCandidates(action);
   for (const candidate of selectorCandidates) {
@@ -526,7 +578,7 @@ async function healReplayAction(params: {
       platform: session.device.platform,
       requireRect: requiresRect,
       requireUnique: true,
-      disambiguateAmbiguous: requiresRect,
+      disambiguateAmbiguous: allowDisambiguation,
     });
     if (!resolved) continue;
     const selectorChain = buildSelectorChainForNode(resolved.node, session.device.platform, {
@@ -580,6 +632,10 @@ async function healReplayAction(params: {
       };
     }
   }
+  const numericDriftHeal = healNumericGetTextDrift(action, snapshot, session);
+  if (numericDriftHeal) {
+    return numericDriftHeal;
+  }
   return null;
 }
 
@@ -697,6 +753,56 @@ function parseSelectorWaitPositionals(positionals: string[]): {
   };
 }
 
+function healNumericGetTextDrift(
+  action: SessionAction,
+  snapshot: SnapshotState,
+  session: SessionState,
+): SessionAction | null {
+  if (action.command !== 'get') return null;
+  if (action.positionals?.[0] !== 'text') return null;
+  const selectorExpression = action.positionals?.[1];
+  if (!selectorExpression) return null;
+  const chain = tryParseSelectorChain(selectorExpression);
+  if (!chain) return null;
+
+  const roleFilters = new Set<string>();
+  let hasNumericTerm = false;
+  for (const selector of chain.selectors) {
+    for (const term of selector.terms) {
+      if (term.key === 'role' && typeof term.value === 'string') {
+        roleFilters.add(normalizeType(term.value));
+      }
+      if (
+        (term.key === 'text' || term.key === 'label' || term.key === 'value') &&
+        typeof term.value === 'string' &&
+        /^\d+$/.test(term.value.trim())
+      ) {
+        hasNumericTerm = true;
+      }
+    }
+  }
+  if (!hasNumericTerm) return null;
+
+  const numericNodes = snapshot.nodes.filter((node) => {
+    const text = extractNodeText(node).trim();
+    if (!/^\d+$/.test(text)) return false;
+    if (roleFilters.size === 0) return true;
+    return roleFilters.has(normalizeType(node.type ?? ''));
+  });
+  if (numericNodes.length === 0) return null;
+  const numericValues = uniqueStrings(numericNodes.map((node) => extractNodeText(node).trim()));
+  if (numericValues.length !== 1) return null;
+
+  const targetNode = numericNodes[0];
+  if (!targetNode) return null;
+  const selectorChain = buildSelectorChainForNode(targetNode, session.device.platform, { action: 'get' });
+  if (selectorChain.length === 0) return null;
+  return {
+    ...action,
+    positionals: ['text', selectorChain.join(' || ')],
+  };
+}
+
 function parseReplayScript(script: string): SessionAction[] {
   const actions: SessionAction[] = [];
   const lines = script.split(/\r?\n/);
@@ -764,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];
@@ -890,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/selectors.ts

@@ -483,7 +483,6 @@ function analyzeSelectorMatches(
     }
     if (!best) {
       best = node;
-      tie = false;
       continue;
     }
     const comparison = compareDisambiguationCandidates(node, best);

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/platforms/android/__tests__/index.test.ts

@@ -1,6 +1,8 @@
 import test from 'node:test';
 import assert from 'node:assert/strict';
-import { parseAndroidLaunchComponent } from '../index.ts';
+import { openAndroidApp, parseAndroidLaunchComponent } 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 +91,22 @@ 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;
+    },
+  );
+});

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) {

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;
+    },
+  );
+});

package/src/platforms/ios/index.ts

@@ -3,6 +3,7 @@ import type { ExecResult } from '../../utils/exec.ts';
 import { AppError } from '../../utils/errors.ts';
 import type { DeviceInfo } from '../../utils/device.ts';
 import { Deadline, isEnvTruthy, retryWithPolicy, TIMEOUT_PROFILES, type RetryTelemetryEvent } from '../../utils/retry.ts';
+import { isDeepLinkTarget } from '../../core/open-target.ts';
 import { bootFailureHint, classifyBootFailure } from '../boot-diagnostics.ts';
 
 const ALIASES: Record<string, string> = {
@@ -14,6 +15,16 @@ const IOS_BOOT_TIMEOUT_MS = resolveTimeoutMs(
   TIMEOUT_PROFILES.ios_boot.totalMs,
   5_000,
 );
+const IOS_SIMCTL_LIST_TIMEOUT_MS = resolveTimeoutMs(
+  process.env.AGENT_DEVICE_IOS_SIMCTL_LIST_TIMEOUT_MS,
+  TIMEOUT_PROFILES.ios_boot.operationMs,
+  1_000,
+);
+const IOS_APP_LAUNCH_TIMEOUT_MS = resolveTimeoutMs(
+  process.env.AGENT_DEVICE_IOS_APP_LAUNCH_TIMEOUT_MS,
+  30_000,
+  5_000,
+);
 const RETRY_LOGS_ENABLED = isEnvTruthy(process.env.AGENT_DEVICE_RETRY_LOGS);
 
 export async function resolveIosApp(device: DeviceInfo, app: string): Promise<string> {
@@ -35,12 +46,54 @@ export async function resolveIosApp(device: DeviceInfo, app: string): Promise<st
   throw new AppError('APP_NOT_INSTALLED', `No app found matching "${app}"`);
 }
 
-export async function openIosApp(device: DeviceInfo, app: string): Promise<void> {
-  const bundleId = await resolveIosApp(device, app);
+export async function openIosApp(
+  device: DeviceInfo,
+  app: string,
+  options?: { appBundleId?: string },
+): Promise<void> {
+  const deepLinkTarget = app.trim();
+  if (isDeepLinkTarget(deepLinkTarget)) {
+    if (device.kind !== 'simulator') {
+      throw new AppError('UNSUPPORTED_OPERATION', 'Deep link open is only supported on iOS simulators in v1');
+    }
+    await ensureBootedSimulator(device);
+    await runCmd('open', ['-a', 'Simulator'], { allowFailure: true });
+    await runCmd('xcrun', ['simctl', 'openurl', device.id, deepLinkTarget]);
+    return;
+  }
+  const bundleId = options?.appBundleId ?? (await resolveIosApp(device, app));
   if (device.kind === 'simulator') {
     await ensureBootedSimulator(device);
     await runCmd('open', ['-a', 'Simulator'], { allowFailure: true });
-    await runCmd('xcrun', ['simctl', 'launch', device.id, bundleId]);
+    const launchDeadline = Deadline.fromTimeoutMs(IOS_APP_LAUNCH_TIMEOUT_MS);
+    await retryWithPolicy(
+      async ({ deadline: attemptDeadline }) => {
+        if (attemptDeadline?.isExpired()) {
+          throw new AppError('COMMAND_FAILED', 'App launch deadline exceeded', {
+            timeoutMs: IOS_APP_LAUNCH_TIMEOUT_MS,
+          });
+        }
+        const result = await runCmd('xcrun', ['simctl', 'launch', device.id, bundleId], {
+          allowFailure: true,
+        });
+        if (result.exitCode === 0) return;
+        throw new AppError('COMMAND_FAILED', `xcrun exited with code ${result.exitCode}`, {
+          cmd: 'xcrun',
+          args: ['simctl', 'launch', device.id, bundleId],
+          stdout: result.stdout,
+          stderr: result.stderr,
+          exitCode: result.exitCode,
+        });
+      },
+      {
+        maxAttempts: 30,
+        baseDelayMs: 1_000,
+        maxDelayMs: 5_000,
+        jitter: 0.2,
+        shouldRetry: isTransientSimulatorLaunchFailure,
+      },
+      { deadline: launchDeadline },
+    );
     return;
   }
   await runCmd('xcrun', [
@@ -208,6 +261,18 @@ function parseSettingState(state: string): boolean {
   throw new AppError('INVALID_ARGS', `Invalid setting state: ${state}`);
 }
 
+function isTransientSimulatorLaunchFailure(error: unknown): boolean {
+  if (!(error instanceof AppError)) return false;
+  if (error.code !== 'COMMAND_FAILED') return false;
+  const details = (error.details ?? {}) as { exitCode?: number; stderr?: unknown };
+  if (details.exitCode !== 4) return false;
+  const stderr = String(details.stderr ?? '').toLowerCase();
+  return (
+    stderr.includes('fbsopenapplicationserviceerrordomain') &&
+    stderr.includes('the request to open')
+  );
+}
+
 export async function listSimulatorApps(
   device: DeviceInfo,
 ): Promise<{ bundleId: string; name: string }[]> {
@@ -365,7 +430,7 @@ export async function ensureBootedSimulator(device: DeviceInfo): Promise<void> {
 async function getSimulatorState(udid: string): Promise<string | null> {
   const result = await runCmd('xcrun', ['simctl', 'list', 'devices', '-j'], {
     allowFailure: true,
-    timeoutMs: TIMEOUT_PROFILES.ios_boot.operationMs,
+    timeoutMs: IOS_SIMCTL_LIST_TIMEOUT_MS,
   });
   if (result.exitCode !== 0) return null;
   try {

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

@@ -292,8 +292,7 @@ async function ensureXctestrun(
   udid: string,
   options: { verbose?: boolean; logPath?: string; traceLogPath?: string },
 ): Promise<string> {
-  const base = path.join(os.homedir(), '.agent-device', 'ios-runner');
-  const derived = path.join(base, 'derived');
+  const derived = resolveRunnerDerivedPath();
   if (shouldCleanDerived()) {
     try {
       fs.rmSync(derived, { recursive: true, force: true });
@@ -354,6 +353,15 @@ async function ensureXctestrun(
   return built;
 }
 
+function resolveRunnerDerivedPath(): string {
+  const override = process.env.AGENT_DEVICE_IOS_RUNNER_DERIVED_PATH?.trim();
+  if (override) {
+    return path.resolve(override);
+  }
+  const base = path.join(os.homedir(), '.agent-device', 'ios-runner');
+  return path.join(base, 'derived');
+}
+
 function findXctestrun(root: string): string | null {
   if (!fs.existsSync(root)) return null;
   const candidates: { path: string; mtimeMs: number }[] = [];

package/src/utils/__tests__/args.test.ts

@@ -0,0 +1,14 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { parseArgs, usage } from '../args.ts';
+
+test('parseArgs recognizes --relaunch', () => {
+  const parsed = parseArgs(['open', 'settings', '--relaunch']);
+  assert.equal(parsed.command, 'open');
+  assert.deepEqual(parsed.positionals, ['settings']);
+  assert.equal(parsed.flags.relaunch, true);
+});
+
+test('usage includes --relaunch flag', () => {
+  assert.match(usage(), /--relaunch/);
+});

package/src/utils/args.ts

@@ -22,6 +22,7 @@ export type ParsedArgs = {
     appsMetadata?: boolean;
     activity?: string;
     saveScript?: boolean;
+    relaunch?: boolean;
     noRecord?: boolean;
     replayUpdate?: boolean;
     help: boolean;
@@ -71,6 +72,10 @@ export function parseArgs(argv: string[]): ParsedArgs {
       flags.saveScript = true;
       continue;
     }
+    if (arg === '--relaunch') {
+      flags.relaunch = true;
+      continue;
+    }
     if (arg === '--update' || arg === '-u') {
       flags.replayUpdate = true;
       continue;
@@ -174,7 +179,7 @@ CLI to control iOS and Android devices for AI agents.
 
 Commands:
   boot                                      Ensure target device/simulator is booted and ready
-  open [app]                                 Boot device/simulator; optionally launch app
+  open [app|url]                             Boot device/simulator; optionally launch app or deep link URL
   close [app]                                Close app or just end session
   reinstall <app> <path>                     Uninstall + install app from binary path
   snapshot [-i] [-c] [-d <depth>] [-s <scope>] [--raw] [--backend ax|xctest]
@@ -227,11 +232,12 @@ Flags:
   --device <name>                            Device name to target
   --udid <udid>                              iOS device UDID
   --serial <serial>                          Android device serial
-  --activity <component>                     Android activity to launch (package/Activity)
+  --activity <component>                     Android app launch activity (package/Activity); not for URL opens
   --session <name>                           Named session
   --verbose                                  Stream daemon/runner logs
   --json                                     JSON output
   --save-script                             Save session script (.ad) on close
+  --relaunch                               open: terminate app process before launching it
   --no-record                                Do not record this action
   --update, -u                               Replay: update selectors and rewrite replay file in place
   --user-installed                           Apps: list user-installed packages (Android only)

package/src/utils/interactors.ts

@@ -29,7 +29,7 @@ export type RunnerContext = {
 };
 
 export type Interactor = {
-  open(app: string, options?: { activity?: string }): Promise<void>;
+  open(app: string, options?: { activity?: string; appBundleId?: string }): Promise<void>;
   openDevice(): Promise<void>;
   close(app: string): Promise<void>;
   tap(x: number, y: number): Promise<void>;
@@ -60,7 +60,7 @@ export function getInteractor(device: DeviceInfo, runnerContext: RunnerContext):
       };
     case 'ios':
       return {
-        open: (app) => openIosApp(device, app),
+        open: (app, options) => openIosApp(device, app, { appBundleId: options?.appBundleId }),
         openDevice: () => openIosDevice(device),
         close: (app) => closeIosApp(device, app),
         screenshot: (outPath) => screenshotIos(device, outPath),