agent-device 0.4.0 → 0.4.2

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

package/src/daemon/__tests__/session-store.test.ts

@@ -94,6 +94,29 @@ test('saveScript flag enables .ad session log writing', () => {
   assert.equal(files.filter((file) => file.endsWith('.ad')).length, 1);
 });
 
+test('saveScript path writes session log to custom location', () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-device-session-log-custom-path-'));
+  const store = new SessionStore(path.join(root, 'sessions'));
+  const session = makeSession('default');
+  const customPath = path.join(root, 'workflows', 'my-flow.ad');
+  store.recordAction(session, {
+    command: 'open',
+    positionals: ['Settings'],
+    flags: { platform: 'ios', saveScript: customPath },
+    result: {},
+  });
+  store.recordAction(session, {
+    command: 'close',
+    positionals: [],
+    flags: { platform: 'ios' },
+    result: {},
+  });
+
+  store.writeSessionLog(session);
+  assert.equal(fs.existsSync(customPath), true);
+  assert.equal(fs.existsSync(path.join(root, 'sessions')), false);
+});
+
 test('writeSessionLog persists open --relaunch in script output', () => {
   const root = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-device-session-log-relaunch-'));
   const store = new SessionStore(root);

package/src/daemon/device-ready.ts

@@ -1,13 +1,155 @@
 import type { DeviceInfo } from '../utils/device.ts';
+import os from 'node:os';
+import path from 'node:path';
+import { promises as fs } from 'node:fs';
+import { runCmd } from '../utils/exec.ts';
+import { AppError } from '../utils/errors.ts';
+import { resolveTimeoutMs } from '../utils/timeouts.ts';
+import { resolveIosDevicectlHint, IOS_DEVICECTL_DEFAULT_HINT } from '../platforms/ios/devicectl.ts';
+
+const IOS_DEVICE_READY_TIMEOUT_MS = resolveTimeoutMs(
+  process.env.AGENT_DEVICE_IOS_DEVICE_READY_TIMEOUT_MS,
+  15_000,
+  1_000,
+);
+const IOS_DEVICE_READY_COMMAND_TIMEOUT_BUFFER_MS = 3_000;
 
 export async function ensureDeviceReady(device: DeviceInfo): Promise<void> {
-  if (device.platform === 'ios' && device.kind === 'simulator') {
-    const { ensureBootedSimulator } = await import('../platforms/ios/index.ts');
-    await ensureBootedSimulator(device);
-    return;
+  if (device.platform === 'ios') {
+    if (device.kind === 'simulator') {
+      const { ensureBootedSimulator } = await import('../platforms/ios/index.ts');
+      await ensureBootedSimulator(device);
+      return;
+    }
+    if (device.kind === 'device') {
+      await ensureIosDeviceReady(device.id);
+      return;
+    }
   }
   if (device.platform === 'android') {
     const { waitForAndroidBoot } = await import('../platforms/android/devices.ts');
     await waitForAndroidBoot(device.id);
   }
 }
+
+async function ensureIosDeviceReady(deviceId: string): Promise<void> {
+  const jsonPath = path.join(
+    os.tmpdir(),
+    `agent-device-ready-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2)}.json`,
+  );
+  const timeoutSeconds = Math.max(1, Math.ceil(IOS_DEVICE_READY_TIMEOUT_MS / 1000));
+  try {
+    const result = await runCmd(
+      'xcrun',
+      [
+        'devicectl',
+        'device',
+        'info',
+        'details',
+        '--device',
+        deviceId,
+        '--json-output',
+        jsonPath,
+        '--timeout',
+        String(timeoutSeconds),
+      ],
+      {
+        allowFailure: true,
+        timeoutMs: IOS_DEVICE_READY_TIMEOUT_MS + IOS_DEVICE_READY_COMMAND_TIMEOUT_BUFFER_MS,
+      },
+    );
+    const stdout = String(result.stdout ?? '');
+    const stderr = String(result.stderr ?? '');
+    const parsed = await readIosReadyPayload(jsonPath);
+    if (result.exitCode === 0) {
+      if (!parsed.parsed) {
+        throw new AppError('COMMAND_FAILED', 'iOS device readiness probe failed', {
+          kind: 'probe_inconclusive',
+          deviceId,
+          stdout,
+          stderr,
+          hint: 'CoreDevice returned success but readiness JSON output was missing or invalid. Retry; if it persists restart Xcode and the iOS device.',
+        });
+      }
+      const tunnelState = parsed?.tunnelState?.toLowerCase();
+      if (tunnelState === 'connecting') {
+        throw new AppError('COMMAND_FAILED', 'iOS device is not ready for automation', {
+          kind: 'not_ready',
+          deviceId,
+          tunnelState,
+          hint: 'Device tunnel is still connecting. Keep the device unlocked and connected by cable until it is fully available in Xcode Devices, then retry.',
+        });
+      }
+      return;
+    }
+    throw new AppError('COMMAND_FAILED', 'iOS device is not ready for automation', {
+      kind: 'not_ready',
+      deviceId,
+      stdout,
+      stderr,
+      exitCode: result.exitCode,
+      tunnelState: parsed?.tunnelState,
+      hint: resolveIosReadyHint(stdout, stderr),
+    });
+  } catch (error) {
+    if (error instanceof AppError && error.code === 'COMMAND_FAILED') {
+      const kind = typeof error.details?.kind === 'string' ? error.details.kind : '';
+      if (kind === 'not_ready') {
+        throw error;
+      }
+      const details = (error.details ?? {}) as {
+        stdout?: string;
+        stderr?: string;
+        timeoutMs?: number;
+      };
+      const stdout = String(details.stdout ?? '');
+      const stderr = String(details.stderr ?? '');
+      const timeoutMs = Number(details.timeoutMs ?? IOS_DEVICE_READY_TIMEOUT_MS);
+      const timeoutHint = `CoreDevice did not respond within ${timeoutMs}ms. Keep the device unlocked and trusted, then retry; if it persists restart Xcode and the iOS device.`;
+      throw new AppError('COMMAND_FAILED', 'iOS device readiness probe failed', {
+        deviceId,
+        cause: error.message,
+        timeoutMs,
+        stdout,
+        stderr,
+        hint: stdout || stderr ? resolveIosReadyHint(stdout, stderr) : timeoutHint,
+      }, error);
+    }
+    throw new AppError('COMMAND_FAILED', 'iOS device readiness probe failed', {
+      deviceId,
+      hint: 'Reconnect the device, keep it unlocked, and retry.',
+    }, error instanceof Error ? error : undefined);
+  } finally {
+    await fs.rm(jsonPath, { force: true }).catch(() => {});
+  }
+}
+
+export function parseIosReadyPayload(payload: unknown): { tunnelState?: string } {
+  const result = (payload as { result?: unknown } | null | undefined)?.result;
+  if (!result || typeof result !== 'object') return {};
+  const direct = (result as { connectionProperties?: { tunnelState?: unknown } }).connectionProperties?.tunnelState;
+  const nested = (result as { device?: { connectionProperties?: { tunnelState?: unknown } } }).device?.connectionProperties?.tunnelState;
+  const tunnelState = typeof direct === 'string' ? direct : typeof nested === 'string' ? nested : undefined;
+  return tunnelState ? { tunnelState } : {};
+}
+
+async function readIosReadyPayload(jsonPath: string): Promise<{ parsed: boolean; tunnelState?: string }> {
+  try {
+    const payloadText = await fs.readFile(jsonPath, 'utf8');
+    const payload = JSON.parse(payloadText) as unknown;
+    const parsed = parseIosReadyPayload(payload);
+    return { parsed: true, tunnelState: parsed.tunnelState };
+  } catch {
+    return { parsed: false };
+  }
+}
+
+export function resolveIosReadyHint(stdout: string, stderr: string): string {
+  const devicectlHint = resolveIosDevicectlHint(stdout, stderr);
+  if (devicectlHint) return devicectlHint;
+  const text = `${stdout}\n${stderr}`.toLowerCase();
+  if (text.includes('timed out waiting for all destinations')) {
+    return 'Xcode destination did not become available in time. Keep device unlocked and retry.';
+  }
+  return IOS_DEVICECTL_DEFAULT_HINT;
+}