agent-device 0.3.1 → 0.3.2

package/skills/agent-device/SKILL.md

@@ -27,7 +27,7 @@ npx -y agent-device
 
 ## Core workflow
 
-1. Open app or just boot device: `open [app]`
+1. Open app: `open [app]` (`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
@@ -38,12 +38,19 @@ npx -y agent-device
 ### Navigation
 
 ```bash
+agent-device boot                 # Ensure target is booted/ready without opening app
+agent-device boot --platform ios  # Boot iOS simulator
+agent-device boot --platform android # Boot Android emulator/device target
 agent-device open [app]           # Boot device/simulator; optionally launch app
 agent-device open [app] --activity com.example/.MainActivity # Android: open specific activity
 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
 ```
 
+`boot` requires either an active session or an explicit selector (`--platform`, `--device`, `--udid`, or `--serial`).
+`boot` is a fallback, not a regular step: use it when starting a new session only if `open` cannot find/connect to an available target.
+
 ### Snapshot (page analysis)
 
 ```bash

package/src/cli.ts

@@ -105,6 +105,13 @@ export async function runCli(argv: string[]): Promise<void> {
         if (logTailStopper) logTailStopper();
         return;
       }
+      if (command === 'boot') {
+        const platform = (response.data as any)?.platform ?? 'unknown';
+        const device = (response.data as any)?.device ?? (response.data as any)?.id ?? 'unknown';
+        process.stdout.write(`Boot ready: ${device} (${platform})\n`);
+        if (logTailStopper) logTailStopper();
+        return;
+      }
       if (command === 'click') {
         const ref = (response.data as any)?.ref ?? '';
         const x = (response.data as any)?.x;

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

@@ -37,6 +37,7 @@ test('iOS simulator + Android commands reject iOS devices', () => {
     'app-switcher',
     'apps',
     'back',
+    'boot',
     'click',
     'close',
     'fill',
@@ -46,6 +47,7 @@ test('iOS simulator + Android commands reject iOS devices', () => {
     'home',
     'long-press',
     'open',
+    'reinstall',
     'press',
     'record',
     'screenshot',

package/src/core/capabilities.ts

@@ -19,6 +19,7 @@ const COMMAND_CAPABILITY_MATRIX: Record<string, CommandCapability> = {
   'app-switcher': { ios: { simulator: true }, android: { emulator: true, device: true, unknown: true } },
   apps: { ios: { simulator: true }, android: { emulator: true, device: true, unknown: true } },
   back: { ios: { simulator: true }, android: { emulator: true, device: true, unknown: true } },
+  boot: { ios: { simulator: true }, android: { emulator: true, device: true, unknown: true } },
   click: { ios: { simulator: true }, android: { emulator: true, device: true, unknown: true } },
   close: { ios: { simulator: true }, android: { emulator: true, device: true, unknown: true } },
   fill: { ios: { simulator: true }, android: { emulator: true, device: true, unknown: true } },
@@ -29,6 +30,7 @@ const COMMAND_CAPABILITY_MATRIX: Record<string, CommandCapability> = {
   home: { ios: { simulator: true }, android: { emulator: true, device: true, unknown: true } },
   'long-press': { ios: { simulator: true }, android: { emulator: true, device: true, unknown: true } },
   open: { ios: { simulator: true }, android: { emulator: true, device: true, unknown: true } },
+  reinstall: { ios: { simulator: true }, android: { emulator: true, device: true, unknown: true } },
   press: { ios: { simulator: true }, android: { emulator: true, device: true, unknown: true } },
   record: { ios: { simulator: true }, android: { emulator: true, device: true, unknown: true } },
   screenshot: { ios: { simulator: true }, android: { emulator: true, device: true, unknown: true } },

package/src/daemon/handlers/__tests__/replay-heal.test.ts

@@ -225,6 +225,11 @@ test('replay without --update does not heal or rewrite', async () => {
 
   assert.ok(response);
   assert.equal(response.ok, false);
+  if (!response.ok) {
+    assert.match(response.error.message, /Replay failed at step 1/);
+    assert.equal(response.error.details?.step, 1);
+    assert.equal(response.error.details?.action, 'click');
+  }
   assert.equal(snapshotDispatchCalls, 0);
   assert.equal(fs.readFileSync(replayPath, 'utf8'), originalPayload);
 });

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

@@ -0,0 +1,219 @@
+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 { handleSessionCommands } from '../session.ts';
+import { SessionStore } from '../../session-store.ts';
+import type { DaemonRequest, DaemonResponse, SessionState } from '../../types.ts';
+
+function makeStore(): SessionStore {
+  const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-device-session-reinstall-'));
+  return new SessionStore(path.join(tempRoot, 'sessions'));
+}
+
+function makeSession(name: string, device: SessionState['device']): SessionState {
+  return {
+    name,
+    device,
+    createdAt: Date.now(),
+    actions: [],
+  };
+}
+
+const invoke = async (_req: DaemonRequest): Promise<DaemonResponse> => {
+  return { ok: false, error: { code: 'INVALID_ARGS', message: 'invoke should not be called in reinstall tests' } };
+};
+
+test('reinstall requires active session or explicit device selector', async () => {
+  const sessionStore = makeStore();
+  const response = await handleSessionCommands({
+    req: {
+      token: 't',
+      session: 'default',
+      command: 'reinstall',
+      positionals: ['com.example.app', '/tmp/app.apk'],
+      flags: {},
+    },
+    sessionName: 'default',
+    logPath: '/tmp/daemon.log',
+    sessionStore,
+    invoke,
+  });
+  assert.ok(response);
+  assert.equal(response.ok, false);
+  if (!response.ok) {
+    assert.equal(response.error.code, 'INVALID_ARGS');
+    assert.match(response.error.message, /active session or an explicit device selector/i);
+  }
+});
+
+test('reinstall validates required args before device operations', async () => {
+  const sessionStore = makeStore();
+  sessionStore.set(
+    'default',
+    makeSession('default', {
+      platform: 'ios',
+      id: 'sim-1',
+      name: 'iPhone',
+      kind: 'simulator',
+      booted: true,
+    }),
+  );
+  const response = await handleSessionCommands({
+    req: {
+      token: 't',
+      session: 'default',
+      command: 'reinstall',
+      positionals: ['com.example.app'],
+      flags: {},
+    },
+    sessionName: 'default',
+    logPath: '/tmp/daemon.log',
+    sessionStore,
+    invoke,
+  });
+  assert.ok(response);
+  assert.equal(response.ok, false);
+  if (!response.ok) {
+    assert.equal(response.error.code, 'INVALID_ARGS');
+    assert.match(response.error.message, /reinstall <app> <path-to-app-binary>/i);
+  }
+});
+
+test('reinstall reports unsupported operation on iOS physical devices', async () => {
+  const sessionStore = makeStore();
+  sessionStore.set(
+    'default',
+    makeSession('default', {
+      platform: 'ios',
+      id: 'device-1',
+      name: 'iPhone Device',
+      kind: 'device',
+      booted: true,
+    }),
+  );
+  const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-device-reinstall-binary-'));
+  const appPath = path.join(tempRoot, 'Sample.app');
+  fs.writeFileSync(appPath, 'placeholder');
+
+  const response = await handleSessionCommands({
+    req: {
+      token: 't',
+      session: 'default',
+      command: 'reinstall',
+      positionals: ['com.example.app', appPath],
+      flags: {},
+    },
+    sessionName: 'default',
+    logPath: '/tmp/daemon.log',
+    sessionStore,
+    invoke,
+  });
+  assert.ok(response);
+  assert.equal(response.ok, false);
+  if (!response.ok) {
+    assert.equal(response.error.code, 'UNSUPPORTED_OPERATION');
+    assert.match(response.error.message, /reinstall is not supported/i);
+  }
+});
+
+test('reinstall succeeds on active iOS simulator session and records action', async () => {
+  const sessionStore = makeStore();
+  const session = makeSession('default', {
+    platform: 'ios',
+    id: 'sim-1',
+    name: 'iPhone',
+    kind: 'simulator',
+    booted: true,
+  });
+  sessionStore.set('default', session);
+  const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-device-reinstall-success-ios-'));
+  const appPath = path.join(tempRoot, 'Sample.app');
+  fs.writeFileSync(appPath, 'placeholder');
+
+  const response = await handleSessionCommands({
+    req: {
+      token: 't',
+      session: 'default',
+      command: 'reinstall',
+      positionals: ['com.example.app', appPath],
+      flags: {},
+    },
+    sessionName: 'default',
+    logPath: '/tmp/daemon.log',
+    sessionStore,
+    invoke,
+    reinstallOps: {
+      ios: async (_device, app, pathToBinary) => {
+        assert.equal(app, 'com.example.app');
+        assert.equal(pathToBinary, appPath);
+        return { bundleId: 'com.example.app' };
+      },
+      android: async () => {
+        throw new Error('unexpected android reinstall');
+      },
+    },
+  });
+
+  assert.ok(response);
+  assert.equal(response.ok, true);
+  if (response.ok) {
+    assert.equal(response.data?.platform, 'ios');
+    assert.equal(response.data?.appId, 'com.example.app');
+    assert.equal(response.data?.bundleId, 'com.example.app');
+    assert.equal(response.data?.appPath, appPath);
+  }
+  assert.equal(session.actions.length, 1);
+  assert.equal(session.actions[0]?.command, 'reinstall');
+});
+
+test('reinstall succeeds on active Android session with normalized appId', async () => {
+  const sessionStore = makeStore();
+  sessionStore.set(
+    'default',
+    makeSession('default', {
+      platform: 'android',
+      id: 'emulator-5554',
+      name: 'Pixel',
+      kind: 'emulator',
+      booted: true,
+    }),
+  );
+  const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-device-reinstall-success-android-'));
+  const appPath = path.join(tempRoot, 'Sample.apk');
+  fs.writeFileSync(appPath, 'placeholder');
+
+  const response = await handleSessionCommands({
+    req: {
+      token: 't',
+      session: 'default',
+      command: 'reinstall',
+      positionals: ['com.example.app', appPath],
+      flags: {},
+    },
+    sessionName: 'default',
+    logPath: '/tmp/daemon.log',
+    sessionStore,
+    invoke,
+    reinstallOps: {
+      ios: async () => {
+        throw new Error('unexpected ios reinstall');
+      },
+      android: async (_device, app, pathToBinary) => {
+        assert.equal(app, 'com.example.app');
+        assert.equal(pathToBinary, appPath);
+        return { package: 'com.example.app' };
+      },
+    },
+  });
+
+  assert.ok(response);
+  assert.equal(response.ok, true);
+  if (response.ok) {
+    assert.equal(response.data?.platform, 'android');
+    assert.equal(response.data?.appId, 'com.example.app');
+    assert.equal(response.data?.package, 'com.example.app');
+    assert.equal(response.data?.appPath, appPath);
+  }
+});

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

@@ -0,0 +1,122 @@
+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 { handleSessionCommands } from '../session.ts';
+import { SessionStore } from '../../session-store.ts';
+import type { DaemonRequest, DaemonResponse, SessionState } from '../../types.ts';
+
+function makeSessionStore(): SessionStore {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-device-session-handler-'));
+  return new SessionStore(path.join(root, 'sessions'));
+}
+
+function makeSession(name: string, device: SessionState['device']): SessionState {
+  return {
+    name,
+    device,
+    createdAt: Date.now(),
+    actions: [],
+  };
+}
+
+const noopInvoke = async (_req: DaemonRequest): Promise<DaemonResponse> => ({ ok: true, data: {} });
+
+test('boot requires session or explicit selector', async () => {
+  const sessionStore = makeSessionStore();
+  const response = await handleSessionCommands({
+    req: {
+      token: 't',
+      session: 'default',
+      command: 'boot',
+      positionals: [],
+      flags: {},
+    },
+    sessionName: 'default',
+    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, 'INVALID_ARGS');
+  }
+});
+
+test('boot rejects unsupported iOS device kind', 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,
+    }),
+  );
+  const response = await handleSessionCommands({
+    req: {
+      token: 't',
+      session: sessionName,
+      command: 'boot',
+      positionals: [],
+      flags: {},
+    },
+    sessionName,
+    logPath: path.join(os.tmpdir(), 'daemon.log'),
+    sessionStore,
+    invoke: noopInvoke,
+    ensureReady: async () => {
+      throw new Error('ensureReady should not be called for unsupported boot');
+    },
+  });
+  assert.ok(response);
+  assert.equal(response?.ok, false);
+  if (response && !response.ok) {
+    assert.equal(response.error.code, 'UNSUPPORTED_OPERATION');
+  }
+});
+
+test('boot succeeds for supported device in session', 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,
+    }),
+  );
+  let ensureCalls = 0;
+  const response = await handleSessionCommands({
+    req: {
+      token: 't',
+      session: sessionName,
+      command: 'boot',
+      positionals: [],
+      flags: {},
+    },
+    sessionName,
+    logPath: path.join(os.tmpdir(), 'daemon.log'),
+    sessionStore,
+    invoke: noopInvoke,
+    ensureReady: async () => {
+      ensureCalls += 1;
+    },
+  });
+  assert.ok(response);
+  assert.equal(response?.ok, true);
+  assert.equal(ensureCalls, 1);
+  if (response && response.ok) {
+    assert.equal(response.data?.platform, 'android');
+    assert.equal(response.data?.booted, true);
+  }
+});

package/src/daemon/handlers/find.ts

@@ -1,5 +1,5 @@
 import { dispatchCommand, resolveTargetDevice } from '../../core/dispatch.ts';
-import { findNodeByLocator, type FindLocator } from '../../utils/finders.ts';
+import { findBestMatchesByLocator, type FindLocator } from '../../utils/finders.ts';
 import { attachRefs, centerOfRect, type RawSnapshotNode, type SnapshotState } from '../../utils/snapshot.ts';
 import { AppError } from '../../utils/errors.ts';
 import type { DaemonRequest, DaemonResponse } from '../types.ts';
@@ -97,7 +97,7 @@ export async function handleFindCommands(params: {
     const start = Date.now();
     while (Date.now() - start < timeout) {
       const { nodes } = await fetchNodes();
-      const match = findNodeByLocator(nodes, locator, query, { requireRect: false });
+      const match = findBestMatchesByLocator(nodes, locator, query, { requireRect: false }).matches[0];
       if (match) {
         if (session) {
           sessionStore.recordAction(session, {
@@ -114,7 +114,27 @@ export async function handleFindCommands(params: {
     return { ok: false, error: { code: 'COMMAND_FAILED', message: 'find wait timed out' } };
   }
   const { nodes } = await fetchNodes();
-  const node = findNodeByLocator(nodes, locator, query, { requireRect: requiresRect });
+  const bestMatches = findBestMatchesByLocator(nodes, locator, query, { requireRect: requiresRect });
+  if (requiresRect && bestMatches.matches.length > 1) {
+    const candidates = bestMatches.matches.slice(0, 8).map((candidate) => {
+      const label = extractNodeText(candidate) || candidate.label || candidate.identifier || candidate.type || '';
+      return `@${candidate.ref}${label ? `(${label})` : ''}`;
+    });
+    return {
+      ok: false,
+      error: {
+        code: 'AMBIGUOUS_MATCH',
+        message: `find matched ${bestMatches.matches.length} elements for ${locator} "${query}". Use a more specific locator or selector.`,
+        details: {
+          locator,
+          query,
+          matches: bestMatches.matches.length,
+          candidates,
+        },
+      },
+    };
+  }
+  const node = bestMatches.matches[0] ?? null;
   if (!node) {
     return { ok: false, error: { code: 'COMMAND_FAILED', message: 'find did not match any element' } };
   }