agent-device 0.3.4 → 0.4.0

package/ios-runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests.swift

@@ -251,6 +251,13 @@ final class RunnerTests: XCTestCase {
       let duration = (command.durationMs ?? 800) / 1000.0
       longPressAt(app: activeApp, x: x, y: y, duration: duration)
       return Response(ok: true, data: DataPayload(message: "long pressed"))
+    case .drag:
+      guard let x = command.x, let y = command.y, let x2 = command.x2, let y2 = command.y2 else {
+        return Response(ok: false, error: ErrorPayload(message: "drag requires x, y, x2, and y2"))
+      }
+      let holdDuration = min(max((command.durationMs ?? 60) / 1000.0, 0.016), 10.0)
+      dragAt(app: activeApp, x: x, y: y, x2: x2, y2: y2, holdDuration: holdDuration)
+      return Response(ok: true, data: DataPayload(message: "dragged"))
     case .type:
       guard let text = command.text else {
         return Response(ok: false, error: ErrorPayload(message: "type requires text"))
@@ -436,6 +443,20 @@ final class RunnerTests: XCTestCase {
     coordinate.press(forDuration: duration)
   }
 
+  private func dragAt(
+    app: XCUIApplication,
+    x: Double,
+    y: Double,
+    x2: Double,
+    y2: Double,
+    holdDuration: TimeInterval
+  ) {
+    let origin = app.coordinate(withNormalizedOffset: CGVector(dx: 0, dy: 0))
+    let start = origin.withOffset(CGVector(dx: x, dy: y))
+    let end = origin.withOffset(CGVector(dx: x2, dy: y2))
+    start.press(forDuration: holdDuration, thenDragTo: end)
+  }
+
   private func swipe(app: XCUIApplication, direction: SwipeDirection) {
     let target = app.windows.firstMatch.exists ? app.windows.firstMatch : app
     let start = target.coordinate(withNormalizedOffset: CGVector(dx: 0.5, dy: 0.2))
@@ -956,6 +977,7 @@ private func resolveRunnerPort() -> UInt16 {
 enum CommandType: String, Codable {
   case tap
   case longPress
+  case drag
   case type
   case swipe
   case findText
@@ -984,6 +1006,8 @@ struct Command: Codable {
   let action: String?
   let x: Double?
   let y: Double?
+  let x2: Double?
+  let y2: Double?
   let durationMs: Double?
   let direction: SwipeDirection?
   let scale: Double?

package/ios-runner/README.md

@@ -8,4 +8,4 @@ This folder is reserved for the lightweight XCUITest runner used to provide elem
 - Support simulator prebuilds where compatible.
 
 ## Status
-Planned for v1 automation layer. See `docs/ios-automation.md` and `docs/ios-runner-protocol.md`.
+Planned for the automation layer. See `docs/ios-automation.md` and `docs/ios-runner-protocol.md`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-device",
-  "version": "0.3.4",
+  "version": "0.4.0",
   "description": "Unified control plane for physical and virtual devices via an agent-driven CLI.",
   "license": "MIT",
   "author": "Callstack",

package/skills/agent-device/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: agent-device
-description: Automates mobile and simulator interactions for iOS and Android devices. Use when navigating apps, taking snapshots/screenshots, tapping, typing, scrolling, pinching, or extracting UI info on mobile devices or simulators.
+description: Automates interactions for iOS simulators/devices and Android emulators/devices. Use when navigating apps, taking snapshots/screenshots, tapping, typing, scrolling, or extracting UI info on mobile targets.
 ---
 
 # Mobile Automation with agent-device
@@ -27,7 +27,7 @@ npx -y agent-device
 
 ## Core workflow
 
-1. Open app: `open [app]` (`open` handles target selection + boot/activation in the normal flow)
+1. Open app or deep link: `open [app|url]` (`open` handles target selection + boot/activation in the normal flow)
 2. Snapshot: `snapshot` to get refs from accessibility tree
 3. Interact using refs (`click @ref`, `fill @ref "text"`)
 4. Re-snapshot after navigation/UI changes
@@ -39,10 +39,13 @@ npx -y agent-device
 
 ```bash
 agent-device boot                 # Ensure target is booted/ready without opening app
-agent-device boot --platform ios  # Boot iOS simulator
+agent-device boot --platform ios  # Boot iOS simulator/device target
 agent-device boot --platform android # Boot Android emulator/device target
-agent-device open [app]           # Boot device/simulator; optionally launch app
-agent-device open [app] --activity com.example/.MainActivity # Android: open specific activity
+agent-device open [app|url]       # Boot device/simulator; optionally launch app or deep link URL
+agent-device open [app] --relaunch # Terminate app process first, then launch (fresh runtime)
+agent-device open [app] --activity com.example/.MainActivity # Android: open specific activity (app targets only)
+agent-device open "myapp://home" --platform android          # Android deep link
+agent-device open "https://example.com" --platform ios       # iOS simulator deep link (device unsupported)
 agent-device close [app]          # Close app or just end session
 agent-device reinstall <app> <path> # Uninstall + install app in one command
 agent-device session list         # List active sessions
@@ -61,10 +64,10 @@ agent-device snapshot -d 3             # Limit depth
 agent-device snapshot -s "Camera"      # Scope to label/identifier
 agent-device snapshot --raw            # Raw node output
 agent-device snapshot --backend xctest # default: XCTest snapshot (fast, complete, no permissions)
-agent-device snapshot --backend ax     # macOS Accessibility tree (fast, needs permissions, less fidelity, optional)
+agent-device snapshot --backend ax     # macOS Accessibility tree (manual diagnostics only; no automatic fallback)
 ```
 
-XCTest is the default: fast and complete and does not require permissions. Use it in most cases and only fall back to AX when something breaks.
+XCTest is the default: fast and complete and does not require permissions. Use AX only for manual diagnostics, and prefer XCTest for normal automation flows. agent-device does not automatically fall back to AX.
 
 ### Find (semantic)
 
@@ -79,7 +82,7 @@ agent-device find "Settings" wait 10000
 agent-device find "Settings" exists
 ```
 
-### Settings helpers (simulators)
+### Settings helpers
 
 ```bash
 agent-device settings wifi on
@@ -92,6 +95,7 @@ agent-device settings location off
 
 Note: iOS wifi/airplane toggles status bar indicators, not actual network state.
 Airplane off clears status bar overrides.
+iOS settings helpers are simulator-only.
 
 ### App state
 
@@ -109,10 +113,14 @@ agent-device focus @e2
 agent-device fill @e2 "text"           # Clear then type (Android: verifies value and retries once on mismatch)
 agent-device type "text"               # Type into focused field without clearing
 agent-device press 300 500             # Tap by coordinates
+agent-device press 300 500 --count 12 --interval-ms 45
+agent-device press 300 500 --count 6 --hold-ms 120 --interval-ms 30 --jitter-px 2
+agent-device swipe 540 1500 540 500 120
+agent-device swipe 540 1500 540 500 120 --count 8 --pause-ms 30 --pattern ping-pong
 agent-device long-press 300 500 800    # Long press (where supported)
 agent-device scroll down 0.5
-agent-device pinch 2.0              # Zoom in 2x (iOS simulator + Android)
-agent-device pinch 0.5 200 400     # Zoom out at coordinates
+agent-device pinch 2.0              # Zoom in 2x (iOS simulator only)
+agent-device pinch 0.5 200 400     # Zoom out at coordinates (iOS simulator only)
 agent-device back
 agent-device home
 agent-device app-switcher
@@ -134,12 +142,14 @@ agent-device screenshot out.png
 ### Deterministic replay and updating
 
 ```bash
+agent-device open App --relaunch      # Fresh app process restart in the current session
 agent-device open App --save-script   # Save session script (.ad) on close
 agent-device replay ./session.ad      # Run deterministic replay from .ad script
 agent-device replay -u ./session.ad   # Update selector drift and rewrite .ad script in place
 ```
 
 `replay` reads `.ad` recordings.
+`--relaunch` controls launch semantics; `--save-script` controls recording. Combine only when both are needed.
 
 ### Trace logs (AX/XCTest)
 
@@ -162,16 +172,24 @@ agent-device apps --platform android --user-installed
 
 ## Best practices
 
-- Pinch (`pinch <scale> [x y]`) is supported on iOS simulators and Android; scale > 1 zooms in, < 1 zooms out. On Android, pinch uses multi-touch `sendevent` injection.
+- `press` supports gesture series controls: `--count`, `--interval-ms`, `--hold-ms`, `--jitter-px`.
+- `swipe` supports coordinate + timing controls and repeat patterns: `swipe x1 y1 x2 y2 [durationMs] --count --pause-ms --pattern`.
+- `swipe` timing is platform-safe: Android uses requested duration; iOS uses normalized safe timing to avoid long-press side effects.
+- Pinch (`pinch <scale> [x y]`) is iOS simulator-only; scale > 1 zooms in, < 1 zooms out.
 - Snapshot refs are the core mechanism for interactive agent flows.
 - Use selectors for deterministic replay artifacts and assertions (e.g. in e2e test workflows).
 - Prefer `snapshot -i` to reduce output size.
 - On iOS, `xctest` is the default and does not require Accessibility permission.
-- If XCTest returns 0 nodes (foreground app changed), agent-device falls back to AX when available.
-- `open <app>` can be used within an existing session to switch apps and update the session bundle id.
+- If XCTest returns 0 nodes (foreground app changed), treat it as an explicit failure and retry the flow/app state.
+- `open <app|url>` can be used within an existing session to switch apps or open deep links.
+- `open <app>` updates session app bundle context; URL opens do not set an app bundle id.
+- Use `open <app> --relaunch` during React Native/Fast Refresh debugging when you need a fresh app process without ending the session.
 - If AX returns the Simulator window or empty tree, restart Simulator or use `--backend xctest`.
 - Use `--session <name>` for parallel sessions; avoid device contention.
-- Use `--activity <component>` on Android to launch a specific activity (e.g. TV apps with LEANBACK).
+- Use `--activity <component>` on Android to launch a specific activity (e.g. TV apps with LEANBACK); do not combine with URL opens.
+- iOS deep-link opens are simulator-only.
+- iOS physical-device runner requires Xcode signing/provisioning; optional overrides: `AGENT_DEVICE_IOS_TEAM_ID`, `AGENT_DEVICE_IOS_SIGNING_IDENTITY`, `AGENT_DEVICE_IOS_PROVISIONING_PROFILE`.
+- For long first-run physical-device setup/build, increase daemon timeout: `AGENT_DEVICE_DAEMON_TIMEOUT_MS=180000` (or higher).
 - Use `fill` when you want clear-then-type semantics.
 - Use `type` when you want to append/enter text without clearing.
 - On Android, prefer `fill` for important fields; it verifies entered text and retries once when IME reorders characters.

package/skills/agent-device/references/permissions.md

@@ -2,7 +2,7 @@
 
 ## iOS AX snapshot
 
-AX snapshot is an alternative to XCTest for when it fails (which shouldn't happen usually); it uses macOS Accessibility APIs and requires permission:
+AX snapshot is available for manual diagnostics when needed; it is not used as an automatic fallback. It uses macOS Accessibility APIs and requires permission:
 
 System Settings > Privacy & Security > Accessibility
 
@@ -13,6 +13,20 @@ agent-device snapshot --backend xctest --platform ios
 ```
 
 Hybrid/AX is fast; XCTest is equally fast but does not require permissions.
+AX backend is simulator-only.
+
+## iOS physical device runner
+
+For iOS physical devices, XCTest runner setup requires valid signing/provisioning.
+Use Automatic Signing in Xcode, or provide optional overrides:
+
+- `AGENT_DEVICE_IOS_TEAM_ID`
+- `AGENT_DEVICE_IOS_SIGNING_IDENTITY`
+- `AGENT_DEVICE_IOS_PROVISIONING_PROFILE`
+
+If first-run setup/build takes long, increase:
+
+- `AGENT_DEVICE_DAEMON_TIMEOUT_MS` (for example `180000`)
 
 ## Simulator troubleshooting
 

package/skills/agent-device/references/session-management.md

@@ -14,6 +14,8 @@ Sessions isolate device context. A device can only be held by one session at a t
 - Name sessions semantically.
 - Close sessions when done.
 - Use separate sessions for parallel work.
+- In iOS sessions, use `open <app>` for simulator/device. `open <url>` is simulator-only.
+- For dev loops where runtime state can persist (for example React Native Fast Refresh), use `open <app> --relaunch` to restart the app process in the same session.
 - For deterministic replay scripts, prefer selector-based actions and assertions.
 - Use `replay -u` to update selector drift during maintenance.
 

package/skills/agent-device/references/snapshot-refs.md

@@ -55,6 +55,8 @@ agent-device snapshot -i -s @e3
 - Ref not found: re-snapshot.
 - AX returns Simulator window: restart Simulator and re-run.
 - AX empty: verify Accessibility permission or use `--backend xctest` (XCTest is more complete).
+- AX backend is simulator-only; use `--backend xctest` on iOS devices.
+- agent-device does not automatically fall back to AX when XCTest fails.
 
 ## Replay note
 

package/skills/agent-device/references/video-recording.md

@@ -20,6 +20,8 @@ agent-device close
 agent-device record stop
 ```
 
+`record` is iOS simulator-only.
+
 ## Android Emulator/Device
 
 Use `agent-device record` commands (wrapper around adb):

package/src/cli.ts

@@ -1,4 +1,4 @@
-import { parseArgs, usage } from './utils/args.ts';
+import { parseArgs, toDaemonFlags, usage } from './utils/args.ts';
 import { asAppError, AppError } from './utils/errors.ts';
 import { formatSnapshotText, printHumanError, printJson } from './utils/output.ts';
 import { readVersion } from './utils/version.ts';
@@ -10,6 +10,9 @@ import path from 'node:path';
 
 export async function runCli(argv: string[]): Promise<void> {
   const parsed = parseArgs(argv);
+  for (const warning of parsed.warnings) {
+    process.stderr.write(`Warning: ${warning}\n`);
+  }
 
   if (parsed.flags.version) {
     process.stdout.write(`${readVersion()}\n`);
@@ -22,6 +25,7 @@ export async function runCli(argv: string[]): Promise<void> {
   }
 
   const { command, positionals, flags } = parsed;
+  const daemonFlags = toDaemonFlags(flags);
   const sessionName = flags.session ?? process.env.AGENT_DEVICE_SESSION ?? 'default';
   const logTailStopper = flags.verbose && !flags.json ? startDaemonLogTail() : null;
   try {
@@ -34,7 +38,7 @@ export async function runCli(argv: string[]): Promise<void> {
         session: sessionName,
         command: 'session_list',
         positionals: [],
-        flags: {},
+        flags: daemonFlags,
       });
       if (!response.ok) throw new AppError(response.error.code as any, response.error.message);
       if (flags.json) printJson({ success: true, data: response.data ?? {} });
@@ -47,7 +51,7 @@ export async function runCli(argv: string[]): Promise<void> {
       session: sessionName,
       command: command!,
       positionals,
-      flags,
+      flags: daemonFlags,
     });
 
     if (response.ok) {

package/src/core/__tests__/capabilities.test.ts

@@ -32,10 +32,17 @@ test('iOS simulator-only commands reject iOS devices and Android', () => {
   }
 });
 
-test('iOS simulator + Android commands reject iOS devices', () => {
+test('simulator-only iOS commands with Android support reject iOS devices', () => {
+  for (const cmd of ['apps', 'reinstall', 'record', 'settings', 'swipe']) {
+    assert.equal(isCommandSupportedOnDevice(cmd, iosSimulator), true, `${cmd} on iOS sim`);
+    assert.equal(isCommandSupportedOnDevice(cmd, iosDevice), false, `${cmd} on iOS device`);
+    assert.equal(isCommandSupportedOnDevice(cmd, androidDevice), true, `${cmd} on Android`);
+  }
+});
+
+test('core commands support iOS simulator, iOS device, and Android', () => {
   for (const cmd of [
     'app-switcher',
-    'apps',
     'back',
     'boot',
     'click',
@@ -47,18 +54,16 @@ test('iOS simulator + Android commands reject iOS devices', () => {
     'home',
     'long-press',
     'open',
-    'reinstall',
     'press',
-    'record',
     'screenshot',
     'scroll',
-    'settings',
+    'scrollintoview',
     'snapshot',
     'type',
     'wait',
   ]) {
     assert.equal(isCommandSupportedOnDevice(cmd, iosSimulator), true, `${cmd} on iOS sim`);
-    assert.equal(isCommandSupportedOnDevice(cmd, iosDevice), false, `${cmd} on iOS device`);
+    assert.equal(isCommandSupportedOnDevice(cmd, iosDevice), true, `${cmd} on iOS device`);
     assert.equal(isCommandSupportedOnDevice(cmd, androidDevice), true, `${cmd} on Android`);
   }
 });

package/src/core/__tests__/open-target.test.ts

@@ -0,0 +1,16 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { isDeepLinkTarget } from '../open-target.ts';
+
+test('isDeepLinkTarget accepts URL-style deep links', () => {
+  assert.equal(isDeepLinkTarget('myapp://home'), true);
+  assert.equal(isDeepLinkTarget('https://example.com'), true);
+  assert.equal(isDeepLinkTarget('tel:123456789'), true);
+  assert.equal(isDeepLinkTarget('mailto:test@example.com'), true);
+});
+
+test('isDeepLinkTarget rejects app identifiers and malformed URLs', () => {
+  assert.equal(isDeepLinkTarget('com.example.app'), false);
+  assert.equal(isDeepLinkTarget('settings'), false);
+  assert.equal(isDeepLinkTarget('http:/x'), false);
+});

package/src/core/capabilities.ts

@@ -13,32 +13,34 @@ type CommandCapability = {
 };
 
 const COMMAND_CAPABILITY_MATRIX: Record<string, CommandCapability> = {
-  // iOS simulator-only in v1.
+  // iOS simulator-only.
   alert: { ios: { simulator: true }, android: {} },
   pinch: { ios: { simulator: true }, android: {} },
-  'app-switcher': { ios: { simulator: true }, android: { emulator: true, device: true, unknown: true } },
+  'app-switcher': { ios: { simulator: true, device: true }, android: { emulator: true, device: true, unknown: true } },
   apps: { ios: { simulator: true }, android: { emulator: true, device: true, unknown: true } },
-  back: { ios: { simulator: true }, android: { emulator: true, device: true, unknown: true } },
-  boot: { ios: { simulator: true }, android: { emulator: true, device: true, unknown: true } },
-  click: { ios: { simulator: true }, android: { emulator: true, device: true, unknown: true } },
-  close: { ios: { simulator: true }, android: { emulator: true, device: true, unknown: true } },
-  fill: { ios: { simulator: true }, android: { emulator: true, device: true, unknown: true } },
-  find: { ios: { simulator: true }, android: { emulator: true, device: true, unknown: true } },
-  focus: { ios: { simulator: true }, android: { emulator: true, device: true, unknown: true } },
-  get: { ios: { simulator: true }, android: { emulator: true, device: true, unknown: true } },
-  is: { ios: { simulator: true }, android: { emulator: true, device: true, unknown: true } },
-  home: { ios: { simulator: true }, android: { emulator: true, device: true, unknown: true } },
-  'long-press': { ios: { simulator: true }, android: { emulator: true, device: true, unknown: true } },
-  open: { ios: { simulator: true }, android: { emulator: true, device: true, unknown: true } },
+  back: { ios: { simulator: true, device: true }, android: { emulator: true, device: true, unknown: true } },
+  boot: { ios: { simulator: true, device: true }, android: { emulator: true, device: true, unknown: true } },
+  click: { ios: { simulator: true, device: true }, android: { emulator: true, device: true, unknown: true } },
+  close: { ios: { simulator: true, device: true }, android: { emulator: true, device: true, unknown: true } },
+  fill: { ios: { simulator: true, device: true }, android: { emulator: true, device: true, unknown: true } },
+  find: { ios: { simulator: true, device: true }, android: { emulator: true, device: true, unknown: true } },
+  focus: { ios: { simulator: true, device: true }, android: { emulator: true, device: true, unknown: true } },
+  get: { ios: { simulator: true, device: true }, android: { emulator: true, device: true, unknown: true } },
+  is: { ios: { simulator: true, device: true }, android: { emulator: true, device: true, unknown: true } },
+  home: { ios: { simulator: true, device: true }, android: { emulator: true, device: true, unknown: true } },
+  'long-press': { ios: { simulator: true, device: true }, android: { emulator: true, device: true, unknown: true } },
+  open: { ios: { simulator: true, device: true }, android: { emulator: true, device: true, unknown: true } },
   reinstall: { ios: { simulator: true }, android: { emulator: true, device: true, unknown: true } },
-  press: { ios: { simulator: true }, android: { emulator: true, device: true, unknown: true } },
+  press: { ios: { simulator: true, device: true }, android: { emulator: true, device: true, unknown: true } },
   record: { ios: { simulator: true }, android: { emulator: true, device: true, unknown: true } },
-  screenshot: { ios: { simulator: true }, android: { emulator: true, device: true, unknown: true } },
-  scroll: { ios: { simulator: true }, android: { emulator: true, device: true, unknown: true } },
+  screenshot: { ios: { simulator: true, device: true }, android: { emulator: true, device: true, unknown: true } },
+  scroll: { ios: { simulator: true, device: true }, android: { emulator: true, device: true, unknown: true } },
+  scrollintoview: { ios: { simulator: true, device: true }, android: { emulator: true, device: true, unknown: true } },
+  swipe: { ios: { simulator: true }, android: { emulator: true, device: true, unknown: true } },
   settings: { ios: { simulator: true }, android: { emulator: true, device: true, unknown: true } },
-  snapshot: { ios: { simulator: true }, android: { emulator: true, device: true, unknown: true } },
-  type: { ios: { simulator: true }, android: { emulator: true, device: true, unknown: true } },
-  wait: { ios: { simulator: true }, android: { emulator: true, device: true, unknown: true } },
+  snapshot: { ios: { simulator: true, device: true }, android: { emulator: true, device: true, unknown: true } },
+  type: { ios: { simulator: true, device: true }, android: { emulator: true, device: true, unknown: true } },
+  wait: { ios: { simulator: true, device: true }, android: { emulator: true, device: true, unknown: true } },
 };
 
 export function isCommandSupportedOnDevice(command: string, device: DeviceInfo): boolean {
@@ -49,3 +51,7 @@ export function isCommandSupportedOnDevice(command: string, device: DeviceInfo):
   const kind = (device.kind ?? 'unknown') as keyof KindMatrix;
   return byPlatform[kind] === true;
 }
+
+export function listCapabilityCommands(): string[] {
+  return Object.keys(COMMAND_CAPABILITY_MATRIX).sort();
+}

package/src/core/dispatch.ts

@@ -17,28 +17,9 @@ import { runIosRunnerCommand } from '../platforms/ios/runner-client.ts';
 import { snapshotAx } from '../platforms/ios/ax-snapshot.ts';
 import { setIosSetting } from '../platforms/ios/index.ts';
 import type { RawSnapshotNode } from '../utils/snapshot.ts';
+import type { CliFlags } from '../utils/command-schema.ts';
 
-export type CommandFlags = {
-  session?: string;
-  platform?: 'ios' | 'android';
-  device?: string;
-  udid?: string;
-  serial?: string;
-  out?: string;
-  activity?: string;
-  verbose?: boolean;
-  snapshotInteractiveOnly?: boolean;
-  snapshotCompact?: boolean;
-  snapshotDepth?: number;
-  snapshotScope?: string;
-  snapshotRaw?: boolean;
-  snapshotBackend?: 'ax' | 'xctest';
-  saveScript?: boolean;
-  noRecord?: boolean;
-  appsFilter?: 'launchable' | 'user-installed' | 'all';
-  appsMetadata?: boolean;
-  replayUpdate?: boolean;
-};
+export type CommandFlags = Omit<CliFlags, 'json' | 'help' | 'version'>;
 
 export async function resolveTargetDevice(flags: CommandFlags): Promise<DeviceInfo> {
   const selector = {
@@ -90,6 +71,12 @@ export async function dispatchCommand(
     snapshotScope?: string;
     snapshotRaw?: boolean;
     snapshotBackend?: 'ax' | 'xctest';
+    count?: number;
+    intervalMs?: number;
+    holdMs?: number;
+    jitterPx?: number;
+    pauseMs?: number;
+    pattern?: 'one-way' | 'ping-pong';
   },
 ): Promise<Record<string, unknown> | void> {
   const runnerCtx: RunnerContext = {
@@ -106,7 +93,7 @@ export async function dispatchCommand(
         await interactor.openDevice();
         return { app: null };
       }
-      await interactor.open(app, { activity: context?.activity });
+      await interactor.open(app, { activity: context?.activity, appBundleId: context?.appBundleId });
       return { app };
     }
     case 'close': {
@@ -120,8 +107,60 @@ export async function dispatchCommand(
     case 'press': {
       const [x, y] = positionals.map(Number);
       if (Number.isNaN(x) || Number.isNaN(y)) throw new AppError('INVALID_ARGS', 'press requires x y');
-      await interactor.tap(x, y);
-      return { x, y };
+      const count = requireIntInRange(context?.count ?? 1, 'count', 1, 200);
+      const intervalMs = requireIntInRange(context?.intervalMs ?? 0, 'interval-ms', 0, 10_000);
+      const holdMs = requireIntInRange(context?.holdMs ?? 0, 'hold-ms', 0, 10_000);
+      const jitterPx = requireIntInRange(context?.jitterPx ?? 0, 'jitter-px', 0, 100);
+
+      for (let index = 0; index < count; index += 1) {
+        const [dx, dy] = computeDeterministicJitter(index, jitterPx);
+        const targetX = x + dx;
+        const targetY = y + dy;
+        if (holdMs > 0) await interactor.longPress(targetX, targetY, holdMs);
+        else await interactor.tap(targetX, targetY);
+        if (index < count - 1 && intervalMs > 0) await sleep(intervalMs);
+      }
+
+      return { x, y, count, intervalMs, holdMs, jitterPx };
+    }
+    case 'swipe': {
+      const x1 = Number(positionals[0]);
+      const y1 = Number(positionals[1]);
+      const x2 = Number(positionals[2]);
+      const y2 = Number(positionals[3]);
+      if ([x1, y1, x2, y2].some(Number.isNaN)) {
+        throw new AppError('INVALID_ARGS', 'swipe requires x1 y1 x2 y2 [durationMs]');
+      }
+
+      const requestedDurationMs = positionals[4] ? Number(positionals[4]) : 250;
+      const durationMs = requireIntInRange(requestedDurationMs, 'durationMs', 16, 10_000);
+      const effectiveDurationMs = device.platform === 'ios' ? 60 : durationMs;
+      const count = requireIntInRange(context?.count ?? 1, 'count', 1, 200);
+      const pauseMs = requireIntInRange(context?.pauseMs ?? 0, 'pause-ms', 0, 10_000);
+      const pattern = context?.pattern ?? 'one-way';
+      if (pattern !== 'one-way' && pattern !== 'ping-pong') {
+        throw new AppError('INVALID_ARGS', `Invalid pattern: ${pattern}`);
+      }
+
+      for (let index = 0; index < count; index += 1) {
+        const reverse = pattern === 'ping-pong' && index % 2 === 1;
+        if (reverse) await interactor.swipe(x2, y2, x1, y1, effectiveDurationMs);
+        else await interactor.swipe(x1, y1, x2, y2, effectiveDurationMs);
+        if (index < count - 1 && pauseMs > 0) await sleep(pauseMs);
+      }
+
+      return {
+        x1,
+        y1,
+        x2,
+        y2,
+        durationMs,
+        effectiveDurationMs,
+        timingMode: device.platform === 'ios' ? 'safe-normalized' : 'direct',
+        count,
+        pauseMs,
+        pattern,
+      };
     }
     case 'long-press': {
       const x = Number(positionals[0]);
@@ -170,6 +209,12 @@ export async function dispatchCommand(
       return { text };
     }
     case 'pinch': {
+      if (device.platform === 'android') {
+        throw new AppError(
+          'UNSUPPORTED_OPERATION',
+          'Android pinch is not supported in current adb backend; requires instrumentation-based backend.',
+        );
+      }
       const scale = Number(positionals[0]);
       const x = positionals[1] ? Number(positionals[1]) : undefined;
       const y = positionals[2] ? Number(positionals[2]) : undefined;
@@ -238,6 +283,13 @@ export async function dispatchCommand(
     case 'snapshot': {
       const backend = context?.snapshotBackend ?? 'xctest';
       if (device.platform === 'ios') {
+        // Keep this guard for non-daemon callers that invoke dispatch directly.
+        if (backend === 'ax' && device.kind !== 'simulator') {
+          throw new AppError(
+            'UNSUPPORTED_OPERATION',
+            'AX snapshot backend is not supported on iOS physical devices; use --backend xctest',
+          );
+        }
         if (backend === 'ax') {
           const ax = await snapshotAx(device, { traceLogPath: context?.traceLogPath });
           return { nodes: ax.nodes ?? [], truncated: false, backend: 'ax' };
@@ -256,13 +308,11 @@ export async function dispatchCommand(
           { verbose: context?.verbose, logPath: context?.logPath, traceLogPath: context?.traceLogPath },
         )) as { nodes?: RawSnapshotNode[]; truncated?: boolean };
         const nodes = result.nodes ?? [];
-        if (nodes.length === 0) {
-          try {
-            const ax = await snapshotAx(device, { traceLogPath: context?.traceLogPath });
-            return { nodes: ax.nodes ?? [], truncated: false, backend: 'ax' };
-          } catch {
-            // keep the empty XCTest snapshot if AX is unavailable
-          }
+        if (nodes.length === 0 && device.kind === 'simulator') {
+          throw new AppError(
+            'COMMAND_FAILED',
+            'XCTest snapshot returned 0 nodes on iOS simulator. You can try --backend ax for diagnostics, but AX snapshots are not recommended.',
+          );
         }
         return { nodes, truncated: result.truncated ?? false, backend: 'xctest' };
       }
@@ -279,3 +329,32 @@ export async function dispatchCommand(
       throw new AppError('INVALID_ARGS', `Unknown command: ${command}`);
   }
 }
+
+const DETERMINISTIC_JITTER_PATTERN: ReadonlyArray<readonly [number, number]> = [
+  [0, 0],
+  [1, 0],
+  [0, 1],
+  [-1, 0],
+  [0, -1],
+  [1, 1],
+  [-1, 1],
+  [1, -1],
+  [-1, -1],
+];
+
+function requireIntInRange(value: number, name: string, min: number, max: number): number {
+  if (!Number.isFinite(value) || !Number.isInteger(value) || value < min || value > max) {
+    throw new AppError('INVALID_ARGS', `${name} must be an integer between ${min} and ${max}`);
+  }
+  return value;
+}
+
+function computeDeterministicJitter(index: number, jitterPx: number): [number, number] {
+  if (jitterPx <= 0) return [0, 0];
+  const [dx, dy] = DETERMINISTIC_JITTER_PATTERN[index % DETERMINISTIC_JITTER_PATTERN.length];
+  return [dx * jitterPx, dy * jitterPx];
+}
+
+async function sleep(ms: number): Promise<void> {
+  await new Promise((resolve) => setTimeout(resolve, ms));
+}

package/src/core/open-target.ts

@@ -0,0 +1,13 @@
+export function isDeepLinkTarget(input: string): boolean {
+  const value = input.trim();
+  if (!value) return false;
+  if (/\s/.test(value)) return false;
+  const match = /^([A-Za-z][A-Za-z0-9+.-]*):(.+)$/.exec(value);
+  if (!match) return false;
+  const scheme = match[1]?.toLowerCase();
+  const rest = match[2] ?? '';
+  if (scheme === 'http' || scheme === 'https' || scheme === 'ws' || scheme === 'wss' || scheme === 'ftp' || scheme === 'ftps') {
+    return rest.startsWith('//');
+  }
+  return true;
+}