agent-device 0.3.4 → 0.4.0

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

@@ -0,0 +1,138 @@
+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/__tests__/session-store.test.ts

@@ -93,3 +93,27 @@ test('saveScript flag enables .ad session log writing', () => {
   const files = fs.readdirSync(root);
   assert.equal(files.filter((file) => file.endsWith('.ad')).length, 1);
 });
+
+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);
+  const session = makeSession('default');
+  store.recordAction(session, {
+    command: 'open',
+    positionals: ['Settings'],
+    flags: { platform: 'ios', saveScript: true, relaunch: true },
+    result: {},
+  });
+  store.recordAction(session, {
+    command: 'close',
+    positionals: [],
+    flags: { platform: 'ios' },
+    result: {},
+  });
+
+  store.writeSessionLog(session);
+  const scriptFile = fs.readdirSync(root).find((file) => file.endsWith('.ad'));
+  assert.ok(scriptFile);
+  const script = fs.readFileSync(path.join(root, scriptFile!), 'utf8');
+  assert.match(script, /open "Settings" --relaunch/);
+});

package/src/daemon/app-state.ts

@@ -1,6 +1,7 @@
 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';
 
@@ -9,47 +10,45 @@ export async function resolveIosAppStateFromSnapshots(
   logPath: string,
   traceLogPath: string | undefined,
   flags: CommandFlags | undefined,
-): Promise<{ appName: string; appBundleId?: string; source: 'snapshot-ax' | 'snapshot-xctest' }> {
-  const axResult = await dispatchCommand(device, 'snapshot', [], flags?.out, {
-    ...contextFromFlags(
-      logPath,
-      {
-        ...flags,
-        snapshotDepth: 1,
-        snapshotCompact: true,
-        snapshotBackend: 'ax',
-      },
-      undefined,
-      traceLogPath,
-    ),
-  });
-  const axNode = extractAppNodeFromSnapshot(axResult as { nodes?: RawSnapshotNode[] });
-  if (axNode?.appName || axNode?.appBundleId) {
+  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: axNode.appName ?? axNode.appBundleId ?? 'unknown',
-      appBundleId: axNode.appBundleId,
-      source: 'snapshot-ax',
+      appName: xcNode.appName ?? xcNode.appBundleId ?? 'unknown',
+      appBundleId: xcNode.appBundleId,
+      source: 'snapshot-xctest',
     };
   }
-  const xctestResult = await dispatchCommand(device, 'snapshot', [], flags?.out, {
-    ...contextFromFlags(
-      logPath,
-      {
-        ...flags,
-        snapshotDepth: 1,
-        snapshotCompact: true,
-        snapshotBackend: 'xctest',
-      },
-      undefined,
-      traceLogPath,
-    ),
-  });
-  const xcNode = extractAppNodeFromSnapshot(xctestResult as { nodes?: RawSnapshotNode[] });
-  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(

package/src/daemon/context.ts

@@ -12,6 +12,12 @@ export type DaemonCommandContext = {
   snapshotScope?: string;
   snapshotBackend?: 'ax' | 'xctest';
   snapshotRaw?: boolean;
+  count?: number;
+  intervalMs?: number;
+  holdMs?: number;
+  jitterPx?: number;
+  pauseMs?: number;
+  pattern?: 'one-way' | 'ping-pong';
 };
 
 export function contextFromFlags(
@@ -32,5 +38,11 @@ export function contextFromFlags(
     snapshotScope: flags?.snapshotScope,
     snapshotRaw: flags?.snapshotRaw,
     snapshotBackend: flags?.snapshotBackend,
+    count: flags?.count,
+    intervalMs: flags?.intervalMs,
+    holdMs: flags?.holdMs,
+    jitterPx: flags?.jitterPx,
+    pauseMs: flags?.pauseMs,
+    pattern: flags?.pattern,
   };
 }

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

@@ -0,0 +1,22 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { unsupportedRefSnapshotFlags } from '../interaction.ts';
+
+test('unsupportedRefSnapshotFlags returns unsupported snapshot flags for @ref flows', () => {
+  const unsupported = unsupportedRefSnapshotFlags({
+    snapshotDepth: 2,
+    snapshotScope: 'Login',
+    snapshotRaw: true,
+    snapshotBackend: 'ax',
+  });
+  assert.deepEqual(unsupported, ['--depth', '--scope', '--raw', '--backend']);
+});
+
+test('unsupportedRefSnapshotFlags returns empty when no ref-unsupported flags are present', () => {
+  const unsupported = unsupportedRefSnapshotFlags({
+    platform: 'ios',
+    session: 'default',
+    verbose: true,
+  });
+  assert.deepEqual(unsupported, []);
+});

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

@@ -46,7 +46,7 @@ test('boot requires session or explicit selector', async () => {
   }
 });
 
-test('boot rejects unsupported iOS device kind', async () => {
+test('boot succeeds for iOS physical devices', async () => {
   const sessionStore = makeSessionStore();
   const sessionName = 'ios-device-session';
   sessionStore.set(
@@ -59,6 +59,7 @@ test('boot rejects unsupported iOS device kind', async () => {
       booted: true,
     }),
   );
+  let ensureCalls = 0;
   const response = await handleSessionCommands({
     req: {
       token: 't',
@@ -72,13 +73,15 @@ test('boot rejects unsupported iOS device kind', async () => {
     sessionStore,
     invoke: noopInvoke,
     ensureReady: async () => {
-      throw new Error('ensureReady should not be called for unsupported boot');
+      ensureCalls += 1;
     },
   });
   assert.ok(response);
-  assert.equal(response?.ok, false);
-  if (response && !response.ok) {
-    assert.equal(response.error.code, 'UNSUPPORTED_OPERATION');
+  assert.equal(response?.ok, true);
+  assert.equal(ensureCalls, 1);
+  if (response && response.ok) {
+    assert.equal(response.data?.platform, 'ios');
+    assert.equal(response.data?.booted, true);
   }
 });
 
@@ -120,3 +123,221 @@ test('boot succeeds for supported device in session', async () => {
     assert.equal(response.data?.booted, true);
   }
 });
+
+test('open URL on existing iOS session clears stale app bundle id', async () => {
+  const sessionStore = makeSessionStore();
+  const sessionName = 'ios-session';
+  sessionStore.set(
+    sessionName,
+    {
+      ...makeSession(sessionName, {
+        platform: 'ios',
+        id: 'sim-1',
+        name: 'iPhone 15',
+        kind: 'simulator',
+        booted: true,
+      }),
+      appBundleId: 'com.example.old',
+      appName: 'Old App',
+    },
+  );
+
+  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, undefined);
+  assert.equal(updated?.appName, 'https://example.com/path');
+  assert.equal(dispatchedContext?.appBundleId, undefined);
+});
+
+test('open app on existing iOS session resolves and stores bundle id', async () => {
+  const sessionStore = makeSessionStore();
+  const sessionName = 'ios-session';
+  sessionStore.set(
+    sessionName,
+    {
+      ...makeSession(sessionName, {
+        platform: 'ios',
+        id: 'sim-1',
+        name: 'iPhone 15',
+        kind: 'simulator',
+        booted: true,
+      }),
+      appBundleId: 'com.example.old',
+      appName: 'Old App',
+    },
+  );
+
+  let dispatchedContext: Record<string, unknown> | undefined;
+  const response = await handleSessionCommands({
+    req: {
+      token: 't',
+      session: sessionName,
+      command: 'open',
+      positionals: ['settings'],
+      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.Preferences');
+  assert.equal(updated?.appName, 'settings');
+  assert.equal(dispatchedContext?.appBundleId, 'com.apple.Preferences');
+});
+
+test('open --relaunch closes and reopens active session app', async () => {
+  const sessionStore = makeSessionStore();
+  const sessionName = 'android-session';
+  sessionStore.set(
+    sessionName,
+    {
+      ...makeSession(sessionName, {
+        platform: 'android',
+        id: 'emulator-5554',
+        name: 'Pixel Emulator',
+        kind: 'emulator',
+        booted: true,
+      }),
+      appName: 'com.example.app',
+    },
+  );
+
+  const calls: Array<{ command: string; positionals: string[] }> = [];
+  const response = await handleSessionCommands({
+    req: {
+      token: 't',
+      session: sessionName,
+      command: 'open',
+      positionals: [],
+      flags: { relaunch: true },
+    },
+    sessionName,
+    logPath: path.join(os.tmpdir(), 'daemon.log'),
+    sessionStore,
+    invoke: noopInvoke,
+    dispatch: async (_device, command, positionals) => {
+      calls.push({ command, positionals });
+      return {};
+    },
+  });
+
+  assert.ok(response);
+  assert.equal(response?.ok, true);
+  assert.equal(calls.length, 2);
+  assert.deepEqual(calls[0], { command: 'close', positionals: ['com.example.app'] });
+  assert.deepEqual(calls[1], { command: 'open', positionals: ['com.example.app'] });
+});
+
+test('open --relaunch rejects URL targets', async () => {
+  const sessionStore = makeSessionStore();
+  const response = await handleSessionCommands({
+    req: {
+      token: 't',
+      session: 'default',
+      command: 'open',
+      positionals: ['https://example.com/path'],
+      flags: { relaunch: true },
+    },
+    sessionName: 'default',
+    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, 'INVALID_ARGS');
+    assert.match(response.error.message, /does not support URL targets/i);
+  }
+});
+
+test('open --relaunch fails without app when no session exists', async () => {
+  const sessionStore = makeSessionStore();
+  const response = await handleSessionCommands({
+    req: {
+      token: 't',
+      session: 'default',
+      command: 'open',
+      positionals: [],
+      flags: { relaunch: true },
+    },
+    sessionName: 'default',
+    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, 'INVALID_ARGS');
+    assert.match(response.error.message, /requires an app argument/i);
+  }
+});
+
+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-'));
+  const replayPath = path.join(replayRoot, 'relaunch.ad');
+  fs.writeFileSync(replayPath, 'open "Settings" --relaunch\n');
+
+  const invoked: DaemonRequest[] = [];
+  const response = await handleSessionCommands({
+    req: {
+      token: 't',
+      session: 'default',
+      command: 'replay',
+      positionals: [replayPath],
+      flags: {},
+    },
+    sessionName: 'default',
+    logPath: path.join(os.tmpdir(), 'daemon.log'),
+    sessionStore,
+    invoke: async (req) => {
+      invoked.push(req);
+      return { ok: true, data: {} };
+    },
+  });
+
+  assert.ok(response);
+  assert.equal(response?.ok, true);
+  if (response && response.ok) {
+    assert.equal(response.data?.replayed, 1);
+  }
+  assert.equal(invoked.length, 1);
+  assert.equal(invoked[0]?.command, 'open');
+  assert.deepEqual(invoked[0]?.positionals, ['Settings']);
+  assert.equal(invoked[0]?.flags?.relaunch, true);
+});

package/src/daemon/handlers/__tests__/snapshot-handler.test.ts

@@ -0,0 +1,92 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { handleSnapshotCommands } from '../snapshot.ts';
+import { SessionStore } from '../../session-store.ts';
+import type { SessionState } from '../../types.ts';
+
+function makeSessionStore(): SessionStore {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-device-snapshot-handler-'));
+  return new SessionStore(path.join(root, 'sessions'));
+}
+
+function makeSession(name: string, device: SessionState['device']): SessionState {
+  return {
+    name,
+    device,
+    createdAt: Date.now(),
+    actions: [],
+  };
+}
+
+test('snapshot rejects AX backend on iOS physical devices', async () => {
+  const sessionStore = makeSessionStore();
+  const sessionName = 'ios-device';
+  sessionStore.set(
+    sessionName,
+    makeSession(sessionName, {
+      platform: 'ios',
+      id: 'ios-device-1',
+      name: 'My iPhone',
+      kind: 'device',
+      booted: true,
+    }),
+  );
+
+  const response = await handleSnapshotCommands({
+    req: {
+      token: 't',
+      session: sessionName,
+      command: 'snapshot',
+      positionals: [],
+      flags: { snapshotBackend: 'ax' },
+    },
+    sessionName,
+    logPath: '/tmp/daemon.log',
+    sessionStore,
+  });
+
+  assert.ok(response);
+  assert.equal(response?.ok, false);
+  if (response && !response.ok) {
+    assert.equal(response.error.code, 'UNSUPPORTED_OPERATION');
+    assert.match(response.error.message, /AX snapshot backend is not supported/i);
+  }
+});
+
+test('settings rejects unsupported iOS physical devices', async () => {
+  const sessionStore = makeSessionStore();
+  const sessionName = 'ios-device';
+  sessionStore.set(
+    sessionName,
+    makeSession(sessionName, {
+      platform: 'ios',
+      id: 'ios-device-1',
+      name: 'My iPhone',
+      kind: 'device',
+      booted: true,
+    }),
+  );
+
+  const response = await handleSnapshotCommands({
+    req: {
+      token: 't',
+      session: sessionName,
+      command: 'settings',
+      positionals: ['wifi', 'on'],
+      flags: {},
+    },
+    sessionName,
+    logPath: '/tmp/daemon.log',
+    sessionStore,
+  });
+
+  assert.ok(response);
+  assert.equal(response?.ok, false);
+  if (response && !response.ok) {
+    assert.equal(response.error.code, 'UNSUPPORTED_OPERATION');
+    assert.match(response.error.message, /settings is not supported/i);
+  }
+});