agent-device 0.3.4 → 0.3.5

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