agent-device 0.4.1 → 0.4.2

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

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

@@ -124,6 +124,299 @@ test('boot succeeds for supported device in session', async () => {
   }
 });
 
+test('boot prefers explicit device selector over active session device', async () => {
+  const sessionStore = makeSessionStore();
+  const sessionName = 'default';
+  sessionStore.set(
+    sessionName,
+    makeSession(sessionName, {
+      platform: 'android',
+      id: 'emulator-5554',
+      name: 'Pixel Emulator',
+      kind: 'emulator',
+      booted: true,
+    }),
+  );
+  const selectedDevice: SessionState['device'] = {
+    platform: 'ios',
+    id: 'sim-2',
+    name: 'iPhone 17 Pro',
+    kind: 'simulator',
+    booted: true,
+  };
+
+  const ensured: string[] = [];
+  const response = await handleSessionCommands({
+    req: {
+      token: 't',
+      session: sessionName,
+      command: 'boot',
+      positionals: [],
+      flags: { platform: 'ios', device: 'iPhone 17 Pro' },
+    },
+    sessionName,
+    logPath: path.join(os.tmpdir(), 'daemon.log'),
+    sessionStore,
+    invoke: noopInvoke,
+    ensureReady: async (device) => {
+      ensured.push(device.id);
+    },
+    resolveTargetDevice: async () => selectedDevice,
+  });
+
+  assert.ok(response);
+  assert.equal(response?.ok, true);
+  assert.deepEqual(ensured, ['sim-2']);
+  if (response && response.ok) {
+    assert.equal(response.data?.platform, 'ios');
+    assert.equal(response.data?.id, 'sim-2');
+  }
+});
+
+test('appstate on iOS requires active session on selected device', async () => {
+  const sessionStore = makeSessionStore();
+  const sessionName = 'default';
+  sessionStore.set(
+    sessionName,
+    {
+      ...makeSession(sessionName, {
+        platform: 'ios',
+        id: 'sim-1',
+        name: 'iPhone 15',
+        kind: 'simulator',
+        booted: true,
+      }),
+      appBundleId: 'com.apple.Preferences',
+      appName: 'Settings',
+    },
+  );
+  const selectedDevice: SessionState['device'] = {
+    platform: 'ios',
+    id: 'sim-2',
+    name: 'iPhone 17 Pro',
+    kind: 'simulator',
+    booted: true,
+  };
+
+  const response = await handleSessionCommands({
+    req: {
+      token: 't',
+      session: sessionName,
+      command: 'appstate',
+      positionals: [],
+      flags: { platform: 'ios', device: 'iPhone 17 Pro' },
+    },
+    sessionName,
+    logPath: path.join(os.tmpdir(), 'daemon.log'),
+    sessionStore,
+    invoke: noopInvoke,
+    ensureReady: async () => {},
+    resolveTargetDevice: async () => selectedDevice,
+    dispatch: async () => {
+      throw new Error('snapshot dispatch should not run');
+    },
+  });
+
+  assert.ok(response);
+  assert.equal(response?.ok, false);
+  if (response && !response.ok) {
+    assert.equal(response.error.code, 'SESSION_NOT_FOUND');
+    assert.match(response.error.message, /requires an active session/i);
+  }
+});
+
+test('appstate with explicit selector matching session returns session state', async () => {
+  const sessionStore = makeSessionStore();
+  const sessionName = 'sim';
+  sessionStore.set(
+    sessionName,
+    {
+      ...makeSession(sessionName, {
+        platform: 'ios',
+        id: 'sim-1',
+        name: 'iPhone 17 Pro',
+        kind: 'simulator',
+        booted: true,
+      }),
+      appBundleId: 'com.apple.Maps',
+      appName: 'Maps',
+    },
+  );
+
+  const response = await handleSessionCommands({
+    req: {
+      token: 't',
+      session: sessionName,
+      command: 'appstate',
+      positionals: [],
+      flags: { platform: 'ios', device: 'iPhone 17 Pro' },
+    },
+    sessionName,
+    logPath: path.join(os.tmpdir(), 'daemon.log'),
+    sessionStore,
+    invoke: noopInvoke,
+    ensureReady: async () => {},
+    dispatch: async () => {
+      throw new Error('snapshot dispatch should not run');
+    },
+    resolveTargetDevice: async () => {
+      throw new Error('resolveTargetDevice should not run');
+    },
+  });
+
+  assert.ok(response);
+  assert.equal(response?.ok, true);
+  if (response && response.ok) {
+    assert.equal(response.data?.platform, 'ios');
+    assert.equal(response.data?.appName, 'Maps');
+    assert.equal(response.data?.appBundleId, 'com.apple.Maps');
+    assert.equal(response.data?.source, 'session');
+  }
+});
+
+test('appstate returns session appName when bundle id is unavailable', async () => {
+  const sessionStore = makeSessionStore();
+  const sessionName = 'sim';
+  sessionStore.set(
+    sessionName,
+    {
+      ...makeSession(sessionName, {
+        platform: 'ios',
+        id: 'sim-1',
+        name: 'iPhone 17 Pro',
+        kind: 'simulator',
+        booted: true,
+      }),
+      appName: 'Maps',
+    },
+  );
+
+  const response = await handleSessionCommands({
+    req: {
+      token: 't',
+      session: sessionName,
+      command: 'appstate',
+      positionals: [],
+      flags: { platform: 'ios', device: 'iPhone 17 Pro' },
+    },
+    sessionName,
+    logPath: path.join(os.tmpdir(), 'daemon.log'),
+    sessionStore,
+    invoke: noopInvoke,
+    ensureReady: async () => {},
+    dispatch: async () => {
+      throw new Error('snapshot dispatch should not run');
+    },
+    resolveTargetDevice: async () => {
+      throw new Error('resolveTargetDevice should not run');
+    },
+  });
+
+  assert.ok(response);
+  assert.equal(response?.ok, true);
+  if (response && response.ok) {
+    assert.equal(response.data?.platform, 'ios');
+    assert.equal(response.data?.appName, 'Maps');
+    assert.equal(response.data?.appBundleId, undefined);
+    assert.equal(response.data?.source, 'session');
+  }
+});
+
+test('appstate fails when iOS session has no tracked app', async () => {
+  const sessionStore = makeSessionStore();
+  const sessionName = 'sim';
+  sessionStore.set(
+    sessionName,
+    makeSession(sessionName, {
+      platform: 'ios',
+      id: 'sim-1',
+      name: 'iPhone 17 Pro',
+      kind: 'simulator',
+      booted: true,
+    }),
+  );
+
+  const response = await handleSessionCommands({
+    req: {
+      token: 't',
+      session: sessionName,
+      command: 'appstate',
+      positionals: [],
+      flags: { platform: 'ios', device: 'iPhone 17 Pro' },
+    },
+    sessionName,
+    logPath: path.join(os.tmpdir(), 'daemon.log'),
+    sessionStore,
+    invoke: noopInvoke,
+    ensureReady: async () => {},
+  });
+
+  assert.ok(response);
+  assert.equal(response?.ok, false);
+  if (response && !response.ok) {
+    assert.equal(response.error.code, 'COMMAND_FAILED');
+    assert.match(response.error.message, /no foreground app is tracked/i);
+  }
+});
+
+test('appstate without session on iOS selector returns SESSION_NOT_FOUND', async () => {
+  const sessionStore = makeSessionStore();
+  const selectedDevice: SessionState['device'] = {
+    platform: 'ios',
+    id: 'sim-2',
+    name: 'iPhone 17 Pro',
+    kind: 'simulator',
+    booted: true,
+  };
+
+  const response = await handleSessionCommands({
+    req: {
+      token: 't',
+      session: 'default',
+      command: 'appstate',
+      positionals: [],
+      flags: { platform: 'ios', device: 'iPhone 17 Pro' },
+    },
+    sessionName: 'default',
+    logPath: path.join(os.tmpdir(), 'daemon.log'),
+    sessionStore,
+    invoke: noopInvoke,
+    ensureReady: async () => {},
+    resolveTargetDevice: async () => selectedDevice,
+  });
+
+  assert.ok(response);
+  assert.equal(response?.ok, false);
+  if (response && !response.ok) {
+    assert.equal(response.error.code, 'SESSION_NOT_FOUND');
+  }
+});
+
+test('appstate with explicit missing session returns SESSION_NOT_FOUND', async () => {
+  const sessionStore = makeSessionStore();
+  const response = await handleSessionCommands({
+    req: {
+      token: 't',
+      session: 'sim',
+      command: 'appstate',
+      positionals: [],
+      flags: { session: 'sim', platform: 'ios', device: 'iPhone 17 Pro' },
+    },
+    sessionName: 'sim',
+    logPath: path.join(os.tmpdir(), 'daemon.log'),
+    sessionStore,
+    invoke: noopInvoke,
+  });
+
+  assert.ok(response);
+  assert.equal(response?.ok, false);
+  if (response && !response.ok) {
+    assert.equal(response.error.code, 'SESSION_NOT_FOUND');
+    assert.match(response.error.message, /no active session "sim"/i);
+    assert.doesNotMatch(response.error.message, /omit --session/i);
+  }
+});
+
 test('open URL on existing iOS session clears stale app bundle id', async () => {
   const sessionStore = makeSessionStore();
   const sessionName = 'ios-session';
@@ -170,6 +463,143 @@ 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 and URL on existing iOS device session keeps app 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.previous',
+      appName: 'Previous App',
+    },
+  );
+
+  let dispatchedPositionals: string[] | undefined;
+  let dispatchedContext: Record<string, unknown> | undefined;
+  const response = await handleSessionCommands({
+    req: {
+      token: 't',
+      session: sessionName,
+      command: 'open',
+      positionals: ['Settings', 'myapp://screen/to'],
+      flags: {},
+    },
+    sessionName,
+    logPath: path.join(os.tmpdir(), 'daemon.log'),
+    sessionStore,
+    invoke: noopInvoke,
+    dispatch: async (_device, _command, positionals, _out, context) => {
+      dispatchedPositionals = positionals;
+      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.Preferences');
+  assert.equal(updated?.appName, 'Settings');
+  assert.deepEqual(dispatchedPositionals, ['Settings', 'myapp://screen/to']);
+  assert.equal(dispatchedContext?.appBundleId, 'com.apple.Preferences');
+});
+
 test('open app on existing iOS session resolves and stores bundle id', async () => {
   const sessionStore = makeSessionStore();
   const sessionName = 'ios-session';
@@ -250,6 +680,7 @@ test('open --relaunch closes and reopens active session app', async () => {
       calls.push({ command, positionals });
       return {};
     },
+    ensureReady: async () => {},
   });
 
   assert.ok(response);
@@ -307,6 +738,52 @@ test('open --relaunch fails without app when no session exists', async () => {
   }
 });
 
+test('open on in-use device returns DEVICE_IN_USE before readiness checks', async () => {
+  const sessionStore = makeSessionStore();
+  sessionStore.set(
+    'busy-session',
+    makeSession('busy-session', {
+      platform: 'ios',
+      id: 'ios-device-1',
+      name: 'iPhone Device',
+      kind: 'device',
+      booted: true,
+    }),
+  );
+
+  let ensureReadyCalls = 0;
+  const response = await handleSessionCommands({
+    req: {
+      token: 't',
+      session: 'default',
+      command: 'open',
+      positionals: ['settings'],
+      flags: { platform: 'ios' },
+    },
+    sessionName: 'default',
+    logPath: path.join(os.tmpdir(), 'daemon.log'),
+    sessionStore,
+    invoke: noopInvoke,
+    ensureReady: async () => {
+      ensureReadyCalls += 1;
+    },
+    resolveTargetDevice: async () => ({
+      platform: 'ios',
+      id: 'ios-device-1',
+      name: 'iPhone Device',
+      kind: 'device',
+      booted: true,
+    }),
+  });
+
+  assert.ok(response);
+  assert.equal(response?.ok, false);
+  if (response && !response.ok) {
+    assert.equal(response.error.code, 'DEVICE_IN_USE');
+  }
+  assert.equal(ensureReadyCalls, 0);
+});
+
 test('replay parses open --relaunch flag and replays open with relaunch semantics', async () => {
   const sessionStore = makeSessionStore();
   const replayRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-device-replay-relaunch-'));