feat: add iOS device URL session fallback behavior

Author: thymikee

README.md

@@ -159,12 +159,16 @@ Navigation helpers:
 Deep links:
 - `open <url>` supports deep links with `scheme://...`.
 - Android opens deep links via `VIEW` intent.
-- iOS deep link open is simulator-only.
+- iOS simulator opens deep links via `simctl openurl`.
+- iOS device opens deep links via `devicectl --payload-url`. For `http(s)://` URLs, Safari is used automatically if no app is active in the session. Custom scheme URLs (`myapp://`) require an active app.
 - `--activity` cannot be combined with URL opens.
 
 ```bash
 agent-device open "myapp://home" --platform android
-agent-device open "https://example.com" --platform ios
+agent-device open "https://example.com" --platform ios          # Safari on device, simctl on simulator
+# iOS device custom scheme: open the app first, then deep link in the same session
+agent-device open com.example.app --session dev --platform ios --device "iPhone"
+agent-device open "myapp://home" --session dev
 ```
 
 Find (semantic):

skills/agent-device/SKILL.md

@@ -45,7 +45,7 @@ agent-device open [app|url]       # Boot device/simulator; optionally launch app
 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 open "https://example.com" --platform ios       # iOS deep link (simulator: simctl, device: devicectl --payload-url)
 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
@@ -190,7 +190,7 @@ agent-device apps --platform android --user-installed
 - 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); do not combine with URL opens.
-- iOS deep-link opens are simulator-only.
+- iOS deep-link opens work on simulators and devices. On devices, `http(s)://` URLs fall back to Safari automatically; custom scheme URLs require an active app in the session.
 - 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.

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

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

src/core/open-target.ts

@@ -11,3 +11,8 @@ export function isDeepLinkTarget(input: string): boolean {
   }
   return true;
 }
+
+export function isWebUrl(input: string): boolean {
+  const scheme = input.trim().split(':')[0]?.toLowerCase();
+  return scheme === 'http' || scheme === 'https';
+}

src/daemon/handlers/__tests__/session.test.ts

@@ -170,6 +170,94 @@ test('open URL on existing iOS session clears stale app bundle id', async () =>
   assert.equal(dispatchedContext?.appBundleId, undefined);
 });
 
+test('open URL on existing iOS device session preserves app bundle id context', async () => {
+  const sessionStore = makeSessionStore();
+  const sessionName = 'ios-device-session';
+  sessionStore.set(
+    sessionName,
+    {
+      ...makeSession(sessionName, {
+        platform: 'ios',
+        id: 'ios-device-1',
+        name: 'iPhone Device',
+        kind: 'device',
+        booted: true,
+      }),
+      appBundleId: 'com.example.app',
+      appName: 'Example App',
+    },
+  );
+
+  let dispatchedContext: Record<string, unknown> | undefined;
+  const response = await handleSessionCommands({
+    req: {
+      token: 't',
+      session: sessionName,
+      command: 'open',
+      positionals: ['myapp://item/42'],
+      flags: {},
+    },
+    sessionName,
+    logPath: path.join(os.tmpdir(), 'daemon.log'),
+    sessionStore,
+    invoke: noopInvoke,
+    dispatch: async (_device, _command, _positionals, _out, context) => {
+      dispatchedContext = context as Record<string, unknown> | undefined;
+      return {};
+    },
+    ensureReady: async () => {},
+  });
+
+  assert.ok(response);
+  assert.equal(response?.ok, true);
+  const updated = sessionStore.get(sessionName);
+  assert.equal(updated?.appBundleId, 'com.example.app');
+  assert.equal(updated?.appName, 'myapp://item/42');
+  assert.equal(dispatchedContext?.appBundleId, 'com.example.app');
+});
+
+test('open web URL on iOS device session without active app falls back to Safari', async () => {
+  const sessionStore = makeSessionStore();
+  const sessionName = 'ios-device-session';
+  sessionStore.set(
+    sessionName,
+    makeSession(sessionName, {
+      platform: 'ios',
+      id: 'ios-device-1',
+      name: 'iPhone Device',
+      kind: 'device',
+      booted: true,
+    }),
+  );
+
+  let dispatchedContext: Record<string, unknown> | undefined;
+  const response = await handleSessionCommands({
+    req: {
+      token: 't',
+      session: sessionName,
+      command: 'open',
+      positionals: ['https://example.com/path'],
+      flags: {},
+    },
+    sessionName,
+    logPath: path.join(os.tmpdir(), 'daemon.log'),
+    sessionStore,
+    invoke: noopInvoke,
+    dispatch: async (_device, _command, _positionals, _out, context) => {
+      dispatchedContext = context as Record<string, unknown> | undefined;
+      return {};
+    },
+    ensureReady: async () => {},
+  });
+
+  assert.ok(response);
+  assert.equal(response?.ok, true);
+  const updated = sessionStore.get(sessionName);
+  assert.equal(updated?.appBundleId, 'com.apple.mobilesafari');
+  assert.equal(updated?.appName, 'https://example.com/path');
+  assert.equal(dispatchedContext?.appBundleId, 'com.apple.mobilesafari');
+});
+
 test('open app on existing iOS session resolves and stores bundle id', async () => {
   const sessionStore = makeSessionStore();
   const sessionName = 'ios-session';
@@ -250,6 +338,7 @@ test('open --relaunch closes and reopens active session app', async () => {
       calls.push({ command, positionals });
       return {};
     },
+    ensureReady: async () => {},
   });
 
   assert.ok(response);

src/daemon/handlers/session.ts

@@ -1,7 +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 { isDeepLinkTarget, isWebUrl } 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';
@@ -54,10 +54,22 @@ const defaultReinstallOps: ReinstallOps = {
   },
 };
 
-async function resolveIosBundleIdForOpen(device: DeviceInfo, openTarget: string | undefined): Promise<string | undefined> {
-  if (device.platform !== 'ios' || !openTarget || isDeepLinkTarget(openTarget)) {
+async function resolveIosBundleIdForOpen(
+  device: DeviceInfo,
+  openTarget: string | undefined,
+  currentAppBundleId?: string,
+): Promise<string | undefined> {
+  if (device.platform !== 'ios' || !openTarget) return undefined;
+  if (isDeepLinkTarget(openTarget)) {
+    if (device.kind === 'device') {
+      return currentAppBundleId ?? (isWebUrl(openTarget) ? 'com.apple.mobilesafari' : undefined);
+    }
     return undefined;
   }
+  return await tryResolveIosAppBundleId(device, openTarget);
+}
+
+async function tryResolveIosAppBundleId(device: DeviceInfo, openTarget: string): Promise<string | undefined> {
   try {
     const { resolveIosApp } = await import('../../platforms/ios/index.ts');
     return await resolveIosApp(device, openTarget);
@@ -331,7 +343,8 @@ export async function handleSessionCommands(params: {
           },
         };
       }
-      const appBundleId = await resolveIosBundleIdForOpen(session.device, openTarget);
+      await ensureReady(session.device);
+      const appBundleId = await resolveIosBundleIdForOpen(session.device, openTarget, session.appBundleId);
       const openPositionals = requestedOpenTarget ? (req.positionals ?? []) : [openTarget];
       if (shouldRelaunch) {
         const closeTarget = appBundleId ?? openTarget;

website/docs/docs/commands.md

@@ -23,7 +23,7 @@ agent-device app-switcher
 - `boot` requires either an active session or an explicit device selector.
 - `boot` is mainly needed when starting a new session and `open` fails because no booted simulator/emulator is available.
 - `open [app]` already boots/activates the selected target when needed.
-- `open <url>` deep links are supported on Android; iOS deep-link open is simulator-only.
+- `open <url>` deep links are supported on Android and iOS. On iOS devices, `http(s)://` URLs fall back to Safari automatically; custom scheme URLs require an active app in the session.
 
 ## Snapshot and inspect