agent-device 0.4.1 → 0.4.2

package/src/platforms/ios/simulator.ts

@@ -0,0 +1,164 @@
+import type { DeviceInfo } from '../../utils/device.ts';
+import { AppError } from '../../utils/errors.ts';
+import { runCmd } from '../../utils/exec.ts';
+import { Deadline, retryWithPolicy, type RetryTelemetryEvent } from '../../utils/retry.ts';
+import { bootFailureHint, classifyBootFailure } from '../boot-diagnostics.ts';
+
+import { IOS_BOOT_TIMEOUT_MS, IOS_SIMCTL_LIST_TIMEOUT_MS, RETRY_LOGS_ENABLED } from './config.ts';
+
+export function ensureSimulator(device: DeviceInfo, command: string): void {
+  if (device.kind !== 'simulator') {
+    throw new AppError('UNSUPPORTED_OPERATION', `${command} is only supported on iOS simulators`);
+  }
+}
+
+export async function ensureBootedSimulator(device: DeviceInfo): Promise<void> {
+  if (device.kind !== 'simulator') return;
+
+  const state = await getSimulatorState(device.id);
+  if (state === 'Booted') return;
+
+  const deadline = Deadline.fromTimeoutMs(IOS_BOOT_TIMEOUT_MS);
+  let bootResult:
+    | {
+      stdout: string;
+      stderr: string;
+      exitCode: number;
+    }
+    | undefined;
+  let bootStatusResult:
+    | {
+      stdout: string;
+      stderr: string;
+      exitCode: number;
+    }
+    | undefined;
+
+  try {
+    await retryWithPolicy(
+      async ({ deadline: attemptDeadline }) => {
+        if (attemptDeadline?.isExpired()) {
+          throw new AppError('COMMAND_FAILED', 'iOS simulator boot deadline exceeded', {
+            timeoutMs: IOS_BOOT_TIMEOUT_MS,
+          });
+        }
+
+        const remainingMs = Math.max(1_000, attemptDeadline?.remainingMs() ?? IOS_BOOT_TIMEOUT_MS);
+        const boot = await runCmd('xcrun', ['simctl', 'boot', device.id], {
+          allowFailure: true,
+          timeoutMs: remainingMs,
+        });
+        bootResult = {
+          stdout: String(boot.stdout ?? ''),
+          stderr: String(boot.stderr ?? ''),
+          exitCode: boot.exitCode,
+        };
+
+        const bootOutput = `${bootResult.stdout}\n${bootResult.stderr}`.toLowerCase();
+        const bootAlreadyDone =
+          bootOutput.includes('already booted') || bootOutput.includes('current state: booted');
+
+        if (bootResult.exitCode !== 0 && !bootAlreadyDone) {
+          throw new AppError('COMMAND_FAILED', 'simctl boot failed', {
+            stdout: bootResult.stdout,
+            stderr: bootResult.stderr,
+            exitCode: bootResult.exitCode,
+          });
+        }
+
+        const bootStatus = await runCmd('xcrun', ['simctl', 'bootstatus', device.id, '-b'], {
+          allowFailure: true,
+          timeoutMs: remainingMs,
+        });
+        bootStatusResult = {
+          stdout: String(bootStatus.stdout ?? ''),
+          stderr: String(bootStatus.stderr ?? ''),
+          exitCode: bootStatus.exitCode,
+        };
+
+        if (bootStatusResult.exitCode !== 0) {
+          throw new AppError('COMMAND_FAILED', 'simctl bootstatus failed', {
+            stdout: bootStatusResult.stdout,
+            stderr: bootStatusResult.stderr,
+            exitCode: bootStatusResult.exitCode,
+          });
+        }
+
+        const nextState = await getSimulatorState(device.id);
+        if (nextState !== 'Booted') {
+          throw new AppError('COMMAND_FAILED', 'Simulator is still booting', { state: nextState });
+        }
+      },
+      {
+        maxAttempts: 3,
+        baseDelayMs: 500,
+        maxDelayMs: 2000,
+        jitter: 0.2,
+        shouldRetry: (error) => {
+          const reason = classifyBootFailure({
+            error,
+            stdout: bootStatusResult?.stdout ?? bootResult?.stdout,
+            stderr: bootStatusResult?.stderr ?? bootResult?.stderr,
+            context: { platform: 'ios', phase: 'boot' },
+          });
+          return reason !== 'IOS_BOOT_TIMEOUT' && reason !== 'CI_RESOURCE_STARVATION_SUSPECTED';
+        },
+      },
+      {
+        deadline,
+        phase: 'boot',
+        classifyReason: (error) =>
+          classifyBootFailure({
+            error,
+            stdout: bootStatusResult?.stdout ?? bootResult?.stdout,
+            stderr: bootStatusResult?.stderr ?? bootResult?.stderr,
+            context: { platform: 'ios', phase: 'boot' },
+          }),
+        onEvent: (event: RetryTelemetryEvent) => {
+          if (!RETRY_LOGS_ENABLED) return;
+          process.stderr.write(`[agent-device][retry] ${JSON.stringify(event)}\n`);
+        },
+      },
+    );
+  } catch (error) {
+    const reason = classifyBootFailure({
+      error,
+      stdout: bootStatusResult?.stdout ?? bootResult?.stdout,
+      stderr: bootStatusResult?.stderr ?? bootResult?.stderr,
+      context: { platform: 'ios', phase: 'boot' },
+    });
+
+    throw new AppError('COMMAND_FAILED', 'iOS simulator failed to boot', {
+      platform: 'ios',
+      deviceId: device.id,
+      timeoutMs: IOS_BOOT_TIMEOUT_MS,
+      elapsedMs: deadline.elapsedMs(),
+      reason,
+      hint: bootFailureHint(reason),
+      boot: bootResult,
+      bootstatus: bootStatusResult,
+    });
+  }
+}
+
+export async function getSimulatorState(udid: string): Promise<string | null> {
+  const result = await runCmd('xcrun', ['simctl', 'list', 'devices', '-j'], {
+    allowFailure: true,
+    timeoutMs: IOS_SIMCTL_LIST_TIMEOUT_MS,
+  });
+  if (result.exitCode !== 0) return null;
+
+  try {
+    const payload = JSON.parse(String(result.stdout ?? '')) as {
+      devices: Record<string, { udid: string; state: string }[]>;
+    };
+
+    for (const runtime of Object.values(payload.devices ?? {})) {
+      const match = runtime.find((entry) => entry.udid === udid);
+      if (match) return match.state;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}

package/src/utils/__tests__/args.test.ts

@@ -1,6 +1,6 @@
 import test from 'node:test';
 import assert from 'node:assert/strict';
-import { parseArgs, usage, usageForCommand } from '../args.ts';
+import { parseArgs, toDaemonFlags, usage, usageForCommand } from '../args.ts';
 import { AppError } from '../errors.ts';
 import { getCliCommandNames, getSchemaCapabilityKeys } from '../command-schema.ts';
 import { listCapabilityCommands } from '../../core/capabilities.ts';
@@ -12,6 +12,14 @@ test('parseArgs recognizes --relaunch', () => {
   assert.equal(parsed.flags.relaunch, true);
 });
 
+test('toDaemonFlags strips CLI-only flags', () => {
+  const parsed = parseArgs(['open', 'settings', '--json']);
+  const daemonFlags = toDaemonFlags(parsed.flags);
+  assert.equal(Object.hasOwn(daemonFlags, 'json'), false);
+  assert.equal(Object.hasOwn(daemonFlags, 'help'), false);
+  assert.equal(Object.hasOwn(daemonFlags, 'version'), false);
+});
+
 test('parseArgs accepts --save-script with optional path value', () => {
   const withoutPath = parseArgs(['open', 'settings', '--save-script']);
   assert.equal(withoutPath.command, 'open');
@@ -93,7 +101,17 @@ test('usage includes --relaunch flag', () => {
   assert.match(usage(), /--relaunch/);
   assert.match(usage(), /--save-script \[path\]/);
   assert.match(usage(), /pinch <scale> \[x\] \[y\]/);
-  assert.match(usage(), /--metadata/);
+  assert.doesNotMatch(usage(), /--metadata/);
+});
+
+test('apps defaults to --all filter and allows overrides', () => {
+  const defaultFilter = parseArgs(['apps'], { strictFlags: true });
+  assert.equal(defaultFilter.command, 'apps');
+  assert.equal(defaultFilter.flags.appsFilter, 'all');
+
+  const userInstalled = parseArgs(['apps', '--user-installed'], { strictFlags: true });
+  assert.equal(userInstalled.command, 'apps');
+  assert.equal(userInstalled.flags.appsFilter, 'user-installed');
 });
 
 test('every capability command has a parser schema entry', () => {

package/src/utils/__tests__/daemon-client.test.ts

@@ -4,7 +4,7 @@ import { spawn } from 'node:child_process';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
-import { resolveDaemonRequestTimeoutMs } from '../../daemon-client.ts';
+import { resolveDaemonRequestTimeoutMs, resolveDaemonStartupHint } from '../../daemon-client.ts';
 import {
   isProcessAlive,
   readProcessCommand,
@@ -12,14 +12,31 @@ import {
   waitForProcessExit,
 } from '../process-identity.ts';
 
-test('resolveDaemonRequestTimeoutMs defaults to 180000', () => {
-  assert.equal(resolveDaemonRequestTimeoutMs(undefined), 180000);
+test('resolveDaemonRequestTimeoutMs defaults to 90000', () => {
+  assert.equal(resolveDaemonRequestTimeoutMs(undefined), 90000);
 });
 
 test('resolveDaemonRequestTimeoutMs enforces minimum timeout', () => {
   assert.equal(resolveDaemonRequestTimeoutMs('100'), 1000);
   assert.equal(resolveDaemonRequestTimeoutMs('2500'), 2500);
-  assert.equal(resolveDaemonRequestTimeoutMs('invalid'), 180000);
+  assert.equal(resolveDaemonRequestTimeoutMs('invalid'), 90000);
+});
+
+test('resolveDaemonStartupHint prefers stale lock guidance when lock exists without info', () => {
+  const hint = resolveDaemonStartupHint({ hasInfo: false, hasLock: true });
+  assert.match(hint, /daemon\.lock/i);
+  assert.match(hint, /delete/i);
+});
+
+test('resolveDaemonStartupHint covers stale info+lock pair', () => {
+  const hint = resolveDaemonStartupHint({ hasInfo: true, hasLock: true });
+  assert.match(hint, /daemon\.json/i);
+  assert.match(hint, /daemon\.lock/i);
+});
+
+test('resolveDaemonStartupHint falls back to daemon.json guidance', () => {
+  const hint = resolveDaemonStartupHint({ hasInfo: true, hasLock: false });
+  assert.match(hint, /daemon\.json/i);
 });
 
 test('stopDaemonProcessForTakeover terminates a matching daemon process', async (t) => {

package/src/utils/args.ts

@@ -221,7 +221,12 @@ function formatUnsupportedFlagMessage(command: string | null, unsupported: strin
 }
 
 export function toDaemonFlags(flags: CliFlags): Omit<CliFlags, 'json' | 'help' | 'version'> {
-  const { json: _json, help: _help, version: _version, ...daemonFlags } = flags;
+  const {
+    json: _json,
+    help: _help,
+    version: _version,
+    ...daemonFlags
+  } = flags;
   return daemonFlags;
 }
 

package/src/utils/command-schema.ts

@@ -13,8 +13,7 @@ export type CliFlags = {
   snapshotScope?: string;
   snapshotRaw?: boolean;
   snapshotBackend?: 'ax' | 'xctest';
-  appsFilter?: 'launchable' | 'user-installed' | 'all';
-  appsMetadata?: boolean;
+  appsFilter?: 'user-installed' | 'all';
   count?: number;
   intervalMs?: number;
   holdMs?: number;
@@ -232,7 +231,7 @@ export const FLAG_DEFINITIONS: readonly FlagDefinition[] = [
     type: 'enum',
     setValue: 'user-installed',
     usageLabel: '--user-installed',
-    usageDescription: 'Apps: list user-installed packages (Android only)',
+    usageDescription: 'Apps: list user-installed apps',
   },
   {
     key: 'appsFilter',
@@ -240,14 +239,7 @@ export const FLAG_DEFINITIONS: readonly FlagDefinition[] = [
     type: 'enum',
     setValue: 'all',
     usageLabel: '--all',
-    usageDescription: 'Apps: list all packages (Android only)',
-  },
-  {
-    key: 'appsMetadata',
-    names: ['--metadata'],
-    type: 'boolean',
-    usageLabel: '--metadata',
-    usageDescription: 'Apps: return metadata objects',
+    usageDescription: 'Apps: list all apps (include system/default apps)',
   },
   {
     key: 'snapshotInteractiveOnly',
@@ -323,7 +315,7 @@ export const COMMAND_SCHEMAS: Record<string, CommandSchema> = {
   },
   open: {
     description: 'Boot device/simulator; optionally launch app or deep link URL',
-    positionalArgs: ['appOrUrl?'],
+    positionalArgs: ['appOrUrl?', 'url?'],
     allowedFlags: ['activity', 'saveScript', 'relaunch'],
   },
   close: {
@@ -348,9 +340,10 @@ export const COMMAND_SCHEMAS: Record<string, CommandSchema> = {
     skipCapabilityCheck: true,
   },
   apps: {
-    description: 'List installed apps (Android launchable by default, iOS simulator)',
+    description: 'List installed apps (includes default/system apps by default)',
     positionalArgs: [],
-    allowedFlags: ['appsFilter', 'appsMetadata'],
+    allowedFlags: ['appsFilter'],
+    defaults: { appsFilter: 'all' },
   },
   appstate: {
     description: 'Show foreground app/activity',

package/src/utils/interactors.ts

@@ -30,7 +30,7 @@ export type RunnerContext = {
 };
 
 export type Interactor = {
-  open(app: string, options?: { activity?: string; appBundleId?: string }): Promise<void>;
+  open(app: string, options?: { activity?: string; appBundleId?: string; url?: string }): Promise<void>;
   openDevice(): Promise<void>;
   close(app: string): Promise<void>;
   tap(x: number, y: number): Promise<void>;
@@ -63,7 +63,7 @@ export function getInteractor(device: DeviceInfo, runnerContext: RunnerContext):
       };
     case 'ios':
       return {
-        open: (app, options) => openIosApp(device, app, { appBundleId: options?.appBundleId }),
+        open: (app, options) => openIosApp(device, app, { appBundleId: options?.appBundleId, url: options?.url }),
         openDevice: () => openIosDevice(device),
         close: (app) => closeIosApp(device, app),
         screenshot: (outPath) => screenshotIos(device, outPath),

package/src/utils/timeouts.ts

@@ -0,0 +1,9 @@
+export function resolveTimeoutMs(raw: string | undefined, fallback: number, min: number): number {
+  if (!raw) return fallback;
+  const parsed = Number(raw);
+  if (!Number.isFinite(parsed)) return fallback;
+  return Math.max(min, Math.floor(parsed));
+}
+
+/** Alias for `resolveTimeoutMs` — semantically marks the caller expects seconds. */
+export const resolveTimeoutSeconds = resolveTimeoutMs;

package/src/daemon/__tests__/app-state.test.ts

@@ -1,138 +0,0 @@
-import test from 'node:test';
-import assert from 'node:assert/strict';
-import type { DeviceInfo } from '../../utils/device.ts';
-import { resolveIosAppStateFromSnapshots } from '../app-state.ts';
-import type { CommandFlags, dispatchCommand } from '../../core/dispatch.ts';
-
-const iosSimulator: DeviceInfo = {
-  platform: 'ios',
-  id: 'sim-1',
-  name: 'iPhone Simulator',
-  kind: 'simulator',
-  booted: true,
-};
-
-const iosDevice: DeviceInfo = {
-  platform: 'ios',
-  id: '00008110-000E12341234002E',
-  name: 'iPhone',
-  kind: 'device',
-  booted: true,
-};
-
-test('appstate uses xctest first on iOS simulator', async () => {
-  const backends: string[] = [];
-  const fakeDispatch: typeof dispatchCommand = async (_device, _command, _positionals, _outPath, context) => {
-    backends.push(context?.snapshotBackend ?? 'unknown');
-    return {
-      nodes: [
-        {
-          type: 'XCUIElementTypeApplication',
-          label: 'Settings',
-          identifier: 'com.apple.Preferences',
-        },
-      ],
-    };
-  };
-
-  const result = await resolveIosAppStateFromSnapshots(
-    iosSimulator,
-    '/tmp/daemon.log',
-    undefined,
-    {} as CommandFlags,
-    fakeDispatch,
-  );
-
-  assert.deepEqual(backends, ['xctest']);
-  assert.equal(result.source, 'snapshot-xctest');
-  assert.equal(result.appBundleId, 'com.apple.Preferences');
-});
-
-test('appstate does not try ax on iOS device when xctest succeeds', async () => {
-  const backends: string[] = [];
-  const fakeDispatch: typeof dispatchCommand = async (_device, _command, _positionals, _outPath, context) => {
-    backends.push(context?.snapshotBackend ?? 'unknown');
-    return {
-      nodes: [
-        {
-          type: 'XCUIElementTypeApplication',
-          label: 'Settings',
-          identifier: 'com.apple.Preferences',
-        },
-      ],
-    };
-  };
-
-  const result = await resolveIosAppStateFromSnapshots(
-    iosDevice,
-    '/tmp/daemon.log',
-    undefined,
-    {} as CommandFlags,
-    fakeDispatch,
-  );
-
-  assert.deepEqual(backends, ['xctest']);
-  assert.equal(result.source, 'snapshot-xctest');
-  assert.equal(result.appName, 'Settings');
-});
-
-test('appstate fails on simulator when xctest is empty', async () => {
-  const backends: string[] = [];
-  const fakeDispatch: typeof dispatchCommand = async (_device, _command, _positionals, _outPath, context) => {
-    backends.push(context?.snapshotBackend ?? 'unknown');
-    return { nodes: [] };
-  };
-
-  await assert.rejects(
-    resolveIosAppStateFromSnapshots(
-      iosSimulator,
-      '/tmp/daemon.log',
-      undefined,
-      {} as CommandFlags,
-      fakeDispatch,
-    ),
-    /not recommended/,
-  );
-  assert.deepEqual(backends, ['xctest']);
-});
-
-test('appstate fails on simulator when xctest throws', async () => {
-  const backends: string[] = [];
-  const fakeDispatch: typeof dispatchCommand = async (_device, _command, _positionals, _outPath, context) => {
-    const backend = context?.snapshotBackend ?? 'unknown';
-    backends.push(backend);
-    throw new Error('xctest failed');
-  };
-
-  await assert.rejects(
-    resolveIosAppStateFromSnapshots(
-      iosSimulator,
-      '/tmp/daemon.log',
-      undefined,
-      {} as CommandFlags,
-      fakeDispatch,
-    ),
-    /not recommended/,
-  );
-  assert.deepEqual(backends, ['xctest']);
-});
-
-test('appstate fails on device when xctest throws', async () => {
-  const backends: string[] = [];
-  const fakeDispatch: typeof dispatchCommand = async (_device, _command, _positionals, _outPath, context) => {
-    backends.push(context?.snapshotBackend ?? 'unknown');
-    throw new Error('xctest failed');
-  };
-
-  await assert.rejects(
-    resolveIosAppStateFromSnapshots(
-      iosDevice,
-      '/tmp/daemon.log',
-      undefined,
-      {} as CommandFlags,
-      fakeDispatch,
-    ),
-    /not recommended/,
-  );
-  assert.deepEqual(backends, ['xctest']);
-});

package/src/daemon/app-state.ts

@@ -1,65 +0,0 @@
-import { dispatchCommand, type CommandFlags } from '../core/dispatch.ts';
-import type { DeviceInfo } from '../utils/device.ts';
-import { attachRefs, type RawSnapshotNode } from '../utils/snapshot.ts';
-import { AppError } from '../utils/errors.ts';
-import { contextFromFlags } from './context.ts';
-import { normalizeType } from './snapshot-processing.ts';
-
-export async function resolveIosAppStateFromSnapshots(
-  device: DeviceInfo,
-  logPath: string,
-  traceLogPath: string | undefined,
-  flags: CommandFlags | undefined,
-  dispatch: typeof dispatchCommand = dispatchCommand,
-): Promise<{ appName: string; appBundleId?: string; source: 'snapshot-xctest' }> {
-  let xctestResult: { nodes?: RawSnapshotNode[] } | undefined;
-  try {
-    xctestResult = (await dispatch(device, 'snapshot', [], flags?.out, {
-      ...contextFromFlags(
-        logPath,
-        {
-          ...flags,
-          snapshotDepth: 1,
-          snapshotCompact: true,
-          snapshotBackend: 'xctest',
-        },
-        undefined,
-        traceLogPath,
-      ),
-    })) as { nodes?: RawSnapshotNode[] };
-  } catch (error) {
-    const cause = error instanceof Error ? error.message : String(error);
-    throw new AppError(
-      'COMMAND_FAILED',
-      'Unable to resolve iOS app state from XCTest snapshot. You can try snapshot --backend ax for diagnostics, but AX snapshots are not recommended.',
-      { cause },
-    );
-  }
-
-  const xcNode = extractAppNodeFromSnapshot(xctestResult);
-  if (xcNode?.appName || xcNode?.appBundleId) {
-    return {
-      appName: xcNode.appName ?? xcNode.appBundleId ?? 'unknown',
-      appBundleId: xcNode.appBundleId,
-      source: 'snapshot-xctest',
-    };
-  }
-
-  throw new AppError(
-    'COMMAND_FAILED',
-    'Unable to resolve iOS app state from XCTest snapshot (0 nodes or missing application node). You can try snapshot --backend ax for diagnostics, but AX snapshots are not recommended.',
-  );
-}
-
-function extractAppNodeFromSnapshot(
-  data: { nodes?: RawSnapshotNode[] } | undefined,
-): { appName?: string; appBundleId?: string } | null {
-  const rawNodes = data?.nodes ?? [];
-  const nodes = attachRefs(rawNodes);
-  const appNode = nodes.find((node) => normalizeType(node.type ?? '') === 'application') ?? nodes[0];
-  if (!appNode) return null;
-  const appName = appNode.label?.trim();
-  const appBundleId = appNode.identifier?.trim();
-  if (!appName && !appBundleId) return null;
-  return { appName: appName || undefined, appBundleId: appBundleId || undefined };
-}