agent-device 0.4.1 → 0.4.2

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

@@ -216,14 +216,20 @@ final class RunnerTests: XCTestCase {
   }
 
   private func executeOnMain(command: Command) throws -> Response {
-    let bundleId = command.appBundleId ?? currentBundleId ?? "com.apple.Preferences"
-    if currentBundleId != bundleId {
+    let normalizedBundleId = command.appBundleId?
+      .trimmingCharacters(in: .whitespacesAndNewlines)
+    let requestedBundleId = (normalizedBundleId?.isEmpty == true) ? nil : normalizedBundleId
+    if let bundleId = requestedBundleId, currentBundleId != bundleId {
       let target = XCUIApplication(bundleIdentifier: bundleId)
       NSLog("AGENT_DEVICE_RUNNER_ACTIVATE bundle=%@ state=%d", bundleId, target.state.rawValue)
       // activate avoids terminating and relaunching the target app
       target.activate()
       currentApp = target
       currentBundleId = bundleId
+    } else if requestedBundleId == nil {
+      // Do not reuse stale bundle targets when the caller does not explicitly request one.
+      currentApp = nil
+      currentBundleId = nil
     }
     let activeApp = currentApp ?? app
     _ = activeApp.waitForExistence(timeout: 5)

package/package.json

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

package/skills/agent-device/SKILL.md

@@ -27,7 +27,7 @@ npx -y agent-device
 
 ## Core workflow
 
-1. Open app or deep link: `open [app|url]` (`open` handles target selection + boot/activation in the normal flow)
+1. Open app or deep link: `open [app|url] [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,13 +39,14 @@ npx -y agent-device
 
 ```bash
 agent-device boot                 # Ensure target is booted/ready without opening app
-agent-device boot --platform ios  # Boot iOS simulator/device target
+agent-device boot --platform ios  # Boot iOS target
 agent-device boot --platform android # Boot Android emulator/device target
-agent-device open [app|url]       # Boot device/simulator; optionally launch app or deep link URL
+agent-device open [app|url] [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 open "https://example.com" --platform ios       # iOS deep link (opens in browser)
+agent-device open MyApp "myapp://screen/to" --platform ios   # iOS deep link in app context
 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
@@ -101,10 +102,12 @@ iOS settings helpers are simulator-only.
 
 ```bash
 agent-device appstate
-agent-device apps --metadata --platform ios
-agent-device apps --metadata --platform android
 ```
 
+- Android: `appstate` reports live foreground package/activity.
+- iOS: `appstate` is session-scoped and reports the app tracked by the active session on the target device.
+- For iOS `appstate`, ensure a matching session exists (for example `open --session <name> --platform ios --device "<name>" <app>`).
+
 ### Interactions (use @refs from snapshot)
 
 ```bash
@@ -167,9 +170,11 @@ agent-device trace stop ./trace.log    # Stop and move trace log
 
 ```bash
 agent-device devices
-agent-device apps --platform ios
-agent-device apps --platform android          # default: launchable only
-agent-device apps --platform android --all
+agent-device apps --platform ios              # iOS simulator + iOS device, includes default/system apps
+agent-device apps --platform ios --all        # explicit include-all (same as default)
+agent-device apps --platform ios --user-installed
+agent-device apps --platform android          # includes default/system apps
+agent-device apps --platform android --all    # explicit include-all (same as default)
 agent-device apps --platform android --user-installed
 ```
 
@@ -184,15 +189,16 @@ agent-device apps --platform android --user-installed
 - 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), 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.
+- `open <app|url> [url]` can be used within an existing session to switch apps or open deep links.
+- `open <app>` updates session app bundle context; `open <app> <url>` opens a deep link on iOS.
 - 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); do not combine with URL opens.
-- iOS deep-link opens are simulator-only.
+- On iOS 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).
+- Default daemon request timeout is `45000`ms. For slow physical-device setup/build, increase `AGENT_DEVICE_DAEMON_TIMEOUT_MS` (for example `120000`).
+- For daemon startup troubleshooting, follow stale metadata hints for `~/.agent-device/daemon.json` / `~/.agent-device/daemon.lock`.
 - 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

@@ -24,9 +24,14 @@ Use Automatic Signing in Xcode, or provide optional overrides:
 - `AGENT_DEVICE_IOS_SIGNING_IDENTITY`
 - `AGENT_DEVICE_IOS_PROVISIONING_PROFILE`
 
-If first-run setup/build takes long, increase:
+If setup/build takes long, increase:
 
-- `AGENT_DEVICE_DAEMON_TIMEOUT_MS` (for example `180000`)
+- `AGENT_DEVICE_DAEMON_TIMEOUT_MS` (default `45000`, for example `120000`)
+
+If daemon startup fails with stale metadata hints, clean stale files and retry:
+
+- `~/.agent-device/daemon.json`
+- `~/.agent-device/daemon.lock`
 
 ## Simulator troubleshooting
 

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

@@ -14,7 +14,9 @@ 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.
+- In iOS sessions, use `open <app>`. `open <url>` opens deep links; on devices `http(s)://` opens Safari when no app is active, and custom schemes require an active app in the session.
+- In iOS sessions, `open <app> <url>` opens a deep link.
+- On iOS, `appstate` is session-scoped and requires a matching active session on the target device.
 - 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.
 - Use `--save-script [path]` to record replay scripts on `close`; path is a file path and parent directories are created automatically.
 - For ambiguous bare `--save-script` values, prefer `--save-script=workflow.ad` or `./workflow.ad`.

package/src/__tests__/cli-close.test.ts

@@ -0,0 +1,155 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { runCli } from '../cli.ts';
+import { AppError } from '../utils/errors.ts';
+import type { DaemonResponse } from '../daemon-client.ts';
+
+class ExitSignal extends Error {
+  public readonly code: number;
+
+  constructor(code: number) {
+    super(`EXIT_${code}`);
+    this.code = code;
+  }
+}
+
+type RunResult = {
+  code: number | null;
+  stdout: string;
+  stderr: string;
+  daemonCalls: number;
+};
+
+async function runCliCapture(argv: string[]): Promise<RunResult> {
+  let daemonCalls = 0;
+  let stdout = '';
+  let stderr = '';
+  let code: number | null = null;
+
+  const originalExit = process.exit;
+  const originalStdoutWrite = process.stdout.write.bind(process.stdout);
+  const originalStderrWrite = process.stderr.write.bind(process.stderr);
+
+  (process as any).exit = ((nextCode?: number) => {
+    throw new ExitSignal(nextCode ?? 0);
+  }) as typeof process.exit;
+  (process.stdout as any).write = ((chunk: unknown) => {
+    stdout += String(chunk);
+    return true;
+  }) as typeof process.stdout.write;
+  (process.stderr as any).write = ((chunk: unknown) => {
+    stderr += String(chunk);
+    return true;
+  }) as typeof process.stderr.write;
+
+  const sendToDaemon = async (): Promise<DaemonResponse> => {
+    daemonCalls += 1;
+    throw new AppError('COMMAND_FAILED', 'Failed to start daemon', {
+      infoPath: '/tmp/daemon.json',
+      hint: 'stale daemon info',
+    });
+  };
+
+  try {
+    await runCli(argv, { sendToDaemon });
+  } catch (error) {
+    if (error instanceof ExitSignal) code = error.code;
+    else throw error;
+  } finally {
+    process.exit = originalExit;
+    process.stdout.write = originalStdoutWrite;
+    process.stderr.write = originalStderrWrite;
+  }
+
+  return { code, stdout, stderr, daemonCalls };
+}
+
+async function runCliCaptureWithErrorDetails(
+  argv: string[],
+  details: Record<string, unknown>,
+  message = 'Failed to start daemon',
+): Promise<RunResult> {
+  let daemonCalls = 0;
+  let stdout = '';
+  let stderr = '';
+  let code: number | null = null;
+
+  const originalExit = process.exit;
+  const originalStdoutWrite = process.stdout.write.bind(process.stdout);
+  const originalStderrWrite = process.stderr.write.bind(process.stderr);
+
+  (process as any).exit = ((nextCode?: number) => {
+    throw new ExitSignal(nextCode ?? 0);
+  }) as typeof process.exit;
+  (process.stdout as any).write = ((chunk: unknown) => {
+    stdout += String(chunk);
+    return true;
+  }) as typeof process.stdout.write;
+  (process.stderr as any).write = ((chunk: unknown) => {
+    stderr += String(chunk);
+    return true;
+  }) as typeof process.stderr.write;
+
+  const sendToDaemon = async (): Promise<DaemonResponse> => {
+    daemonCalls += 1;
+    throw new AppError('COMMAND_FAILED', message, details);
+  };
+
+  try {
+    await runCli(argv, { sendToDaemon });
+  } catch (error) {
+    if (error instanceof ExitSignal) code = error.code;
+    else throw error;
+  } finally {
+    process.exit = originalExit;
+    process.stdout.write = originalStdoutWrite;
+    process.stderr.write = originalStderrWrite;
+  }
+
+  return { code, stdout, stderr, daemonCalls };
+}
+
+test('close treats daemon startup failure as no-op', async () => {
+  const result = await runCliCapture(['close']);
+  assert.equal(result.code, null);
+  assert.equal(result.daemonCalls, 1);
+  assert.equal(result.stdout, '');
+  assert.equal(result.stderr, '');
+});
+
+test('close --json treats daemon startup failure as no-op success', async () => {
+  const result = await runCliCapture(['close', '--json']);
+  assert.equal(result.code, null);
+  assert.equal(result.daemonCalls, 1);
+  const payload = JSON.parse(result.stdout);
+  assert.equal(payload.success, true);
+  assert.equal(payload.data.closed, 'session');
+  assert.equal(payload.data.source, 'no-daemon');
+  assert.equal(result.stderr, '');
+});
+
+test('close treats lock-only daemon startup failure as no-op', async () => {
+  const result = await runCliCaptureWithErrorDetails(['close'], {
+    lockPath: '/tmp/daemon.lock',
+    hint: 'stale daemon lock',
+  });
+  assert.equal(result.code, null);
+  assert.equal(result.daemonCalls, 1);
+  assert.equal(result.stdout, '');
+  assert.equal(result.stderr, '');
+});
+
+test('close treats structured daemon startup failure as no-op without relying on message text', async () => {
+  const result = await runCliCaptureWithErrorDetails(
+    ['close'],
+    {
+      kind: 'daemon_startup_failed',
+      lockPath: '/tmp/daemon.lock',
+    },
+    'daemon bootstrap failed',
+  );
+  assert.equal(result.code, null);
+  assert.equal(result.daemonCalls, 1);
+  assert.equal(result.stdout, '');
+  assert.equal(result.stderr, '');
+});

package/src/cli.ts

@@ -179,9 +179,6 @@ export async function runCli(argv: string[], deps: CliDeps = DEFAULT_CLI_DEPS):
               const bundleId = app.bundleId ?? app.package;
               const name = app.name ?? app.label;
               if (name && bundleId) return `${name} (${bundleId})`;
-              if (bundleId && typeof app.launchable === 'boolean') {
-                return `${bundleId} (launchable=${app.launchable})`;
-              }
               if (bundleId) return String(bundleId);
               return JSON.stringify(app);
             }
@@ -199,7 +196,7 @@ export async function runCli(argv: string[], deps: CliDeps = DEFAULT_CLI_DEPS):
           const pkg = (data as any)?.package;
           const activity = (data as any)?.activity;
           if (platform === 'ios') {
-            process.stdout.write(`Foreground app: ${appName ?? appBundleId}\n`);
+            process.stdout.write(`Foreground app: ${appName ?? appBundleId ?? 'unknown'}\n`);
             if (appBundleId) process.stdout.write(`Bundle: ${appBundleId}\n`);
             if (source) process.stdout.write(`Source: ${source}\n`);
             if (logTailStopper) logTailStopper();
@@ -220,6 +217,13 @@ export async function runCli(argv: string[], deps: CliDeps = DEFAULT_CLI_DEPS):
     throw new AppError(response.error.code as any, response.error.message, response.error.details);
   } catch (err) {
     const appErr = asAppError(err);
+    if (command === 'close' && isDaemonStartupFailure(appErr)) {
+      if (flags.json) {
+        printJson({ success: true, data: { closed: 'session', source: 'no-daemon' } });
+      }
+      if (logTailStopper) logTailStopper();
+      return;
+    }
     if (flags.json) {
       printJson({
         success: false,
@@ -229,9 +233,6 @@ export async function runCli(argv: string[], deps: CliDeps = DEFAULT_CLI_DEPS):
       printHumanError(appErr);
       if (flags.verbose) {
         try {
-          const fs = await import('node:fs');
-          const os = await import('node:os');
-          const path = await import('node:path');
           const logPath = path.join(os.homedir(), '.agent-device', 'daemon.log');
           if (fs.existsSync(logPath)) {
             const content = fs.readFileSync(logPath, 'utf8');
@@ -251,6 +252,13 @@ export async function runCli(argv: string[], deps: CliDeps = DEFAULT_CLI_DEPS):
   }
 }
 
+function isDaemonStartupFailure(error: AppError): boolean {
+  if (error.code !== 'COMMAND_FAILED') return false;
+  if (error.details?.kind === 'daemon_startup_failed') return true;
+  if (!error.message.toLowerCase().includes('failed to start daemon')) return false;
+  return typeof error.details?.infoPath === 'string' || typeof error.details?.lockPath === 'string';
+}
+
 const isDirectRun = pathToFileURL(process.argv[1] ?? '').href === import.meta.url;
 if (isDirectRun) {
   runCli(process.argv.slice(2)).catch((err) => {
@@ -268,15 +276,23 @@ function startDaemonLogTail(): (() => void) | null {
     const interval = setInterval(() => {
       if (stopped) return;
       if (!fs.existsSync(logPath)) return;
-      const stats = fs.statSync(logPath);
-      if (stats.size <= offset) return;
-      const fd = fs.openSync(logPath, 'r');
-      const buffer = Buffer.alloc(stats.size - offset);
-      fs.readSync(fd, buffer, 0, buffer.length, offset);
-      fs.closeSync(fd);
-      offset = stats.size;
-      if (buffer.length > 0) {
-        process.stdout.write(buffer.toString('utf8'));
+      try {
+        const stats = fs.statSync(logPath);
+        if (stats.size < offset) offset = 0;
+        if (stats.size <= offset) return;
+        const fd = fs.openSync(logPath, 'r');
+        try {
+          const buffer = Buffer.alloc(stats.size - offset);
+          fs.readSync(fd, buffer, 0, buffer.length, offset);
+          offset = stats.size;
+          if (buffer.length > 0) {
+            process.stdout.write(buffer.toString('utf8'));
+          }
+        } finally {
+          fs.closeSync(fd);
+        }
+      } catch {
+        // Best-effort tailing should not crash CLI flow.
       }
     }, 200);
     return () => {

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

@@ -33,7 +33,7 @@ test('iOS simulator-only commands reject iOS devices and Android', () => {
 });
 
 test('simulator-only iOS commands with Android support reject iOS devices', () => {
-  for (const cmd of ['apps', 'reinstall', 'record', 'settings', 'swipe']) {
+  for (const cmd of ['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`);
@@ -43,6 +43,7 @@ test('simulator-only iOS commands with Android support reject iOS devices', () =
 test('core commands support iOS simulator, iOS device, and Android', () => {
   for (const cmd of [
     'app-switcher',
+    'apps',
     'back',
     'boot',
     'click',

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

@@ -0,0 +1,25 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { dispatchCommand } from '../dispatch.ts';
+import { AppError } from '../../utils/errors.ts';
+import type { DeviceInfo } from '../../utils/device.ts';
+
+test('dispatch open rejects URL as first argument when second URL is provided', async () => {
+  const device: DeviceInfo = {
+    platform: 'ios',
+    id: 'sim-1',
+    name: 'iPhone 15',
+    kind: 'simulator',
+    booted: true,
+  };
+
+  await assert.rejects(
+    () => dispatchCommand(device, 'open', ['myapp://first', 'myapp://second']),
+    (error: unknown) => {
+      assert.equal(error instanceof AppError, true);
+      assert.equal((error as AppError).code, 'INVALID_ARGS');
+      assert.match((error as AppError).message, /requires an app target as the first argument/i);
+      return true;
+    },
+  );
+});

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

@@ -1,6 +1,11 @@
 import test from 'node:test';
 import assert from 'node:assert/strict';
-import { isDeepLinkTarget } from '../open-target.ts';
+import {
+  IOS_SAFARI_BUNDLE_ID,
+  isDeepLinkTarget,
+  isWebUrl,
+  resolveIosDeviceDeepLinkBundleId,
+} from '../open-target.ts';
 
 test('isDeepLinkTarget accepts URL-style deep links', () => {
   assert.equal(isDeepLinkTarget('myapp://home'), true);
@@ -14,3 +19,37 @@ 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);
+});
+
+test('resolveIosDeviceDeepLinkBundleId prefers active app context', () => {
+  assert.equal(
+    resolveIosDeviceDeepLinkBundleId('com.example.app', 'myapp://home'),
+    'com.example.app',
+  );
+});
+
+test('resolveIosDeviceDeepLinkBundleId falls back to Safari for web URLs', () => {
+  assert.equal(
+    resolveIosDeviceDeepLinkBundleId(undefined, 'https://example.com/path'),
+    IOS_SAFARI_BUNDLE_ID,
+  );
+});
+
+test('resolveIosDeviceDeepLinkBundleId returns undefined for custom scheme without app context', () => {
+  assert.equal(
+    resolveIosDeviceDeepLinkBundleId(undefined, 'myapp://home'),
+    undefined,
+  );
+});

package/src/core/capabilities.ts

@@ -17,7 +17,7 @@ const COMMAND_CAPABILITY_MATRIX: Record<string, CommandCapability> = {
   alert: { ios: { simulator: true }, android: {} },
   pinch: { ios: { simulator: true }, android: {} },
   '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 } },
+  apps: { ios: { simulator: true, device: 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 } },

package/src/core/dispatch.ts

@@ -16,6 +16,7 @@ import { getInteractor, type RunnerContext } from '../utils/interactors.ts';
 import { runIosRunnerCommand } from '../platforms/ios/runner-client.ts';
 import { snapshotAx } from '../platforms/ios/ax-snapshot.ts';
 import { setIosSetting } from '../platforms/ios/index.ts';
+import { isDeepLinkTarget } from './open-target.ts';
 import type { RawSnapshotNode } from '../utils/snapshot.ts';
 import type { CliFlags } from '../utils/command-schema.ts';
 
@@ -89,10 +90,31 @@ export async function dispatchCommand(
   switch (command) {
     case 'open': {
       const app = positionals[0];
+      const url = positionals[1];
+      if (positionals.length > 2) {
+        throw new AppError('INVALID_ARGS', 'open accepts at most two arguments: <app|url> [url]');
+      }
       if (!app) {
         await interactor.openDevice();
         return { app: null };
       }
+      if (url !== undefined) {
+        if (device.platform !== 'ios') {
+          throw new AppError('INVALID_ARGS', 'open <app> <url> is supported only on iOS');
+        }
+        if (isDeepLinkTarget(app)) {
+          throw new AppError('INVALID_ARGS', 'open <app> <url> requires an app target as the first argument');
+        }
+        if (!isDeepLinkTarget(url)) {
+          throw new AppError('INVALID_ARGS', 'open <app> <url> requires a valid URL target');
+        }
+        await interactor.open(app, {
+          activity: context?.activity,
+          appBundleId: context?.appBundleId,
+          url,
+        });
+        return { app, url };
+      }
       await interactor.open(app, { activity: context?.activity, appBundleId: context?.appBundleId });
       return { app };
     }

package/src/core/open-target.ts

@@ -11,3 +11,17 @@ 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';
+}
+
+export const IOS_SAFARI_BUNDLE_ID = 'com.apple.mobilesafari';
+
+export function resolveIosDeviceDeepLinkBundleId(appBundleId: string | undefined, url: string): string | undefined {
+  const bundleId = appBundleId?.trim();
+  if (bundleId) return bundleId;
+  if (isWebUrl(url)) return IOS_SAFARI_BUNDLE_ID;
+  return undefined;
+}

package/src/daemon/__tests__/device-ready.test.ts

@@ -0,0 +1,52 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { parseIosReadyPayload, resolveIosReadyHint } from '../device-ready.ts';
+
+test('parseIosReadyPayload reads tunnelState from direct connectionProperties', () => {
+  const parsed = parseIosReadyPayload({
+    result: {
+      connectionProperties: {
+        tunnelState: 'connected',
+      },
+    },
+  });
+  assert.equal(parsed.tunnelState, 'connected');
+});
+
+test('parseIosReadyPayload reads tunnelState from nested device connectionProperties', () => {
+  const parsed = parseIosReadyPayload({
+    result: {
+      device: {
+        connectionProperties: {
+          tunnelState: 'connecting',
+        },
+      },
+    },
+  });
+  assert.equal(parsed.tunnelState, 'connecting');
+});
+
+test('parseIosReadyPayload returns empty payload for malformed input', () => {
+  assert.deepEqual(parseIosReadyPayload(null), {});
+  assert.deepEqual(parseIosReadyPayload({}), {});
+  assert.deepEqual(
+    parseIosReadyPayload({
+      result: { connectionProperties: { tunnelState: 123 } },
+    }),
+    {},
+  );
+});
+
+test('resolveIosReadyHint maps known connection errors', () => {
+  const connecting = resolveIosReadyHint('', 'Device is busy (Connecting to iPhone)');
+  assert.match(connecting, /still connecting/i);
+
+  const coreDeviceTimeout = resolveIosReadyHint('CoreDeviceService timed out', '');
+  assert.match(coreDeviceTimeout, /coredevice service/i);
+});
+
+test('resolveIosReadyHint falls back to generic guidance', () => {
+  const hint = resolveIosReadyHint('unexpected failure', '');
+  assert.match(hint, /unlocked/i);
+  assert.match(hint, /xcode/i);
+});