agent-device 0.3.0 → 0.3.2

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

package/src/daemon/handlers/session.ts

@@ -14,6 +14,39 @@ import { pruneGroupNodes } from '../snapshot-processing.ts';
 import { buildSelectorChainForNode, parseSelectorChain, resolveSelectorChain, splitSelectorFromArgs } from '../selectors.ts';
 import { inferFillText, uniqueStrings } from '../action-utils.ts';
 
+type ReinstallOps = {
+  ios: (device: DeviceInfo, app: string, appPath: string) => Promise<{ bundleId: string }>;
+  android: (device: DeviceInfo, app: string, appPath: string) => Promise<{ package: string }>;
+};
+
+function hasExplicitDeviceSelector(flags: DaemonRequest['flags'] | undefined): boolean {
+  return Boolean(flags?.platform || flags?.device || flags?.udid || flags?.serial);
+}
+
+async function resolveCommandDevice(params: {
+  session: SessionState | undefined;
+  flags: DaemonRequest['flags'] | undefined;
+  ensureReadyFn: typeof ensureDeviceReady;
+  ensureReady?: boolean;
+}): Promise<DeviceInfo> {
+  const device = params.session?.device ?? (await resolveTargetDevice(params.flags ?? {}));
+  if (params.ensureReady !== false) {
+    await params.ensureReadyFn(device);
+  }
+  return device;
+}
+
+const defaultReinstallOps: ReinstallOps = {
+  ios: async (device, app, appPath) => {
+    const { reinstallIosApp } = await import('../../platforms/ios/index.ts');
+    return await reinstallIosApp(device, app, appPath);
+  },
+  android: async (device, app, appPath) => {
+    const { reinstallAndroidApp } = await import('../../platforms/android/index.ts');
+    return await reinstallAndroidApp(device, app, appPath);
+  },
+};
+
 export async function handleSessionCommands(params: {
   req: DaemonRequest;
   sessionName: string;
@@ -21,9 +54,21 @@ export async function handleSessionCommands(params: {
   sessionStore: SessionStore;
   invoke: (req: DaemonRequest) => Promise<DaemonResponse>;
   dispatch?: typeof dispatchCommand;
+  ensureReady?: typeof ensureDeviceReady;
+  reinstallOps?: ReinstallOps;
 }): Promise<DaemonResponse | null> {
-  const { req, sessionName, logPath, sessionStore, invoke, dispatch: dispatchOverride } = params;
+  const {
+    req,
+    sessionName,
+    logPath,
+    sessionStore,
+    invoke,
+    dispatch: dispatchOverride,
+    ensureReady: ensureReadyOverride,
+    reinstallOps = defaultReinstallOps,
+  } = params;
   const dispatch = dispatchOverride ?? dispatchCommand;
+  const ensureReady = ensureReadyOverride ?? ensureDeviceReady;
   const command = req.command;
 
   if (command === 'session_list') {
@@ -72,7 +117,7 @@ export async function handleSessionCommands(params: {
   if (command === 'apps') {
     const session = sessionStore.get(sessionName);
     const flags = req.flags ?? {};
-    if (!session && !flags.platform && !flags.device && !flags.udid && !flags.serial) {
+    if (!session && !hasExplicitDeviceSelector(flags)) {
       return {
         ok: false,
         error: {
@@ -81,8 +126,7 @@ export async function handleSessionCommands(params: {
         },
       };
     }
-    const device = session?.device ?? (await resolveTargetDevice(flags));
-    await ensureDeviceReady(device);
+    const device = await resolveCommandDevice({ session, flags, ensureReadyFn: ensureReady, ensureReady: true });
     if (!isCommandSupportedOnDevice('apps', device)) {
       return { ok: false, error: { code: 'UNSUPPORTED_OPERATION', message: 'apps is not supported on this device' } };
     }
@@ -106,11 +150,39 @@ export async function handleSessionCommands(params: {
     return { ok: true, data: { apps } };
   }
 
-  if (command === 'appstate') {
+  if (command === 'boot') {
     const session = sessionStore.get(sessionName);
     const flags = req.flags ?? {};
+    if (!session && !hasExplicitDeviceSelector(flags)) {
+      return {
+        ok: false,
+        error: {
+          code: 'INVALID_ARGS',
+          message: 'boot requires an active session or an explicit device selector (e.g. --platform ios).',
+        },
+      };
+    }
     const device = session?.device ?? (await resolveTargetDevice(flags));
-    await ensureDeviceReady(device);
+    if (!isCommandSupportedOnDevice('boot', device)) {
+      return { ok: false, error: { code: 'UNSUPPORTED_OPERATION', message: 'boot is not supported on this device' } };
+    }
+    await ensureReady(device);
+    return {
+      ok: true,
+      data: {
+        platform: device.platform,
+        device: device.name,
+        id: device.id,
+        kind: device.kind,
+        booted: true,
+      },
+    };
+  }
+
+  if (command === 'appstate') {
+    const session = sessionStore.get(sessionName);
+    const flags = req.flags ?? {};
+    const device = await resolveCommandDevice({ session, flags, ensureReadyFn: ensureReady, ensureReady: true });
     if (device.platform === 'ios') {
       if (session?.appBundleId) {
         return {
@@ -151,6 +223,62 @@ export async function handleSessionCommands(params: {
     };
   }
 
+  if (command === 'reinstall') {
+    const session = sessionStore.get(sessionName);
+    const flags = req.flags ?? {};
+    if (!session && !hasExplicitDeviceSelector(flags)) {
+      return {
+        ok: false,
+        error: {
+          code: 'INVALID_ARGS',
+          message: 'reinstall requires an active session or an explicit device selector (e.g. --platform ios).',
+        },
+      };
+    }
+    const app = req.positionals?.[0]?.trim();
+    const appPathInput = req.positionals?.[1]?.trim();
+    if (!app || !appPathInput) {
+      return {
+        ok: false,
+        error: { code: 'INVALID_ARGS', message: 'reinstall requires: reinstall <app> <path-to-app-binary>' },
+      };
+    }
+    const appPath = SessionStore.expandHome(appPathInput);
+    if (!fs.existsSync(appPath)) {
+      return {
+        ok: false,
+        error: { code: 'INVALID_ARGS', message: `App binary not found: ${appPath}` },
+      };
+    }
+    const device = await resolveCommandDevice({ session, flags, ensureReadyFn: ensureReady, ensureReady: false });
+    if (!isCommandSupportedOnDevice('reinstall', device)) {
+      return {
+        ok: false,
+        error: { code: 'UNSUPPORTED_OPERATION', message: 'reinstall is not supported on this device' },
+      };
+    }
+    let reinstallData:
+      | { platform: 'ios'; appId: string; bundleId: string }
+      | { platform: 'android'; appId: string; package: string };
+    if (device.platform === 'ios') {
+      const iosResult = await reinstallOps.ios(device, app, appPath);
+      reinstallData = { platform: 'ios', appId: iosResult.bundleId, bundleId: iosResult.bundleId };
+    } else {
+      const androidResult = await reinstallOps.android(device, app, appPath);
+      reinstallData = { platform: 'android', appId: androidResult.package, package: androidResult.package };
+    }
+    const result = { app, appPath, ...reinstallData };
+    if (session) {
+      sessionStore.recordAction(session, {
+        command,
+        positionals: req.positionals ?? [],
+        flags: req.flags ?? {},
+        result,
+      });
+    }
+    return { ok: true, data: result };
+  }
+
   if (command === 'open') {
     if (sessionStore.has(sessionName)) {
       const session = sessionStore.get(sessionName);
@@ -193,7 +321,6 @@ export async function handleSessionCommands(params: {
       return { ok: true, data: { session: sessionName, appName, appBundleId } };
     }
     const device = await resolveTargetDevice(req.flags ?? {});
-    await ensureDeviceReady(device);
     const inUse = sessionStore.toArray().find((s) => s.device.id === device.id);
     if (inUse) {
       return {
@@ -269,7 +396,9 @@ export async function handleSessionCommands(params: {
           flags: action.flags ?? {},
         });
         if (response.ok) continue;
-        if (!shouldUpdate) return response;
+        if (!shouldUpdate) {
+          return withReplayFailureContext(response, action, index, resolved);
+        }
         const nextAction = await healReplayAction({
           action,
           sessionName,
@@ -278,7 +407,7 @@ export async function handleSessionCommands(params: {
           dispatch,
         });
         if (!nextAction) {
-          return response;
+          return withReplayFailureContext(response, action, index, resolved);
         }
         actions[index] = nextAction;
         response = await invoke({
@@ -289,7 +418,7 @@ export async function handleSessionCommands(params: {
           flags: nextAction.flags ?? {},
         });
         if (!response.ok) {
-          return response;
+          return withReplayFailureContext(response, nextAction, index, resolved);
         }
         healed += 1;
       }
@@ -334,6 +463,42 @@ export async function handleSessionCommands(params: {
   return null;
 }
 
+function withReplayFailureContext(
+  response: DaemonResponse,
+  action: SessionAction,
+  index: number,
+  replayPath: string,
+): DaemonResponse {
+  if (response.ok) return response;
+  const step = index + 1;
+  const summary = formatReplayActionSummary(action);
+  const details = {
+    ...(response.error.details ?? {}),
+    replayPath,
+    step,
+    action: action.command,
+    positionals: action.positionals ?? [],
+  };
+  return {
+    ok: false,
+    error: {
+      code: response.error.code,
+      message: `Replay failed at step ${step} (${summary}): ${response.error.message}`,
+      details,
+    },
+  };
+}
+
+function formatReplayActionSummary(action: SessionAction): string {
+  const values = (action.positionals ?? []).map((value) => {
+    const trimmed = value.trim();
+    if (/^-?\d+(\.\d+)?$/.test(trimmed)) return trimmed;
+    if (trimmed.startsWith('@')) return trimmed;
+    return JSON.stringify(trimmed);
+  });
+  return [action.command, ...values].join(' ');
+}
+
 async function healReplayAction(params: {
   action: SessionAction;
   sessionName: string;

package/src/daemon-client.ts

@@ -2,10 +2,10 @@ import net from 'node:net';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
-import { fileURLToPath } from 'node:url';
 import { AppError } from './utils/errors.ts';
 import type { CommandFlags } from './core/dispatch.ts';
 import { runCmdDetached } from './utils/exec.ts';
+import { findProjectRoot, readVersion } from './utils/version.ts';
 
 export type DaemonRequest = {
   token: string;
@@ -134,18 +134,6 @@ async function sendRequest(info: DaemonInfo, req: DaemonRequest): Promise<Daemon
   });
 }
 
-function readVersion(): string {
-  try {
-    const root = findProjectRoot();
-    const pkg = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8')) as {
-      version?: string;
-    };
-    return pkg.version ?? '0.0.0';
-  } catch {
-    return '0.0.0';
-  }
-}
-
 function resolveRequestTimeoutMs(): number {
   const raw = process.env.AGENT_DEVICE_DAEMON_TIMEOUT_MS;
   if (!raw) return 60000;
@@ -153,14 +141,3 @@ function resolveRequestTimeoutMs(): number {
   if (!Number.isFinite(parsed)) return 60000;
   return Math.max(1000, Math.floor(parsed));
 }
-
-function findProjectRoot(): string {
-  const start = path.dirname(fileURLToPath(import.meta.url));
-  let current = start;
-  for (let i = 0; i < 6; i += 1) {
-    const pkgPath = path.join(current, 'package.json');
-    if (fs.existsSync(pkgPath)) return current;
-    current = path.dirname(current);
-  }
-  return start;
-}

package/src/daemon.ts

@@ -3,10 +3,10 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import crypto from 'node:crypto';
-import { fileURLToPath } from 'node:url';
 import { dispatchCommand, type CommandFlags } from './core/dispatch.ts';
 import { isCommandSupportedOnDevice } from './core/capabilities.ts';
 import { asAppError, AppError } from './utils/errors.ts';
+import { readVersion } from './utils/version.ts';
 import { stopIosRunnerSession } from './platforms/ios/runner-client.ts';
 import type { DaemonRequest, DaemonResponse } from './daemon/types.ts';
 import { SessionStore } from './daemon/session-store.ts';
@@ -203,26 +203,3 @@ function start(): void {
 }
 
 start();
-
-function readVersion(): string {
-  try {
-    const root = findProjectRoot();
-    const pkg = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8')) as {
-      version?: string;
-    };
-    return pkg.version ?? '0.0.0';
-  } catch {
-    return '0.0.0';
-  }
-}
-
-function findProjectRoot(): string {
-  const start = path.dirname(fileURLToPath(import.meta.url));
-  let current = start;
-  for (let i = 0; i < 6; i += 1) {
-    const pkgPath = path.join(current, 'package.json');
-    if (fs.existsSync(pkgPath)) return current;
-    current = path.dirname(current);
-  }
-  return start;
-}

package/src/platforms/__tests__/boot-diagnostics.test.ts

@@ -0,0 +1,59 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { bootFailureHint, classifyBootFailure } from '../boot-diagnostics.ts';
+import { AppError } from '../../utils/errors.ts';
+
+test('classifyBootFailure maps timeout errors', () => {
+  const reason = classifyBootFailure({
+    message: 'bootstatus timed out after 120s',
+    context: { platform: 'ios', phase: 'boot' },
+  });
+  assert.equal(reason, 'IOS_BOOT_TIMEOUT');
+});
+
+test('classifyBootFailure maps adb offline errors', () => {
+  const reason = classifyBootFailure({
+    stderr: 'error: device offline',
+    context: { platform: 'android', phase: 'transport' },
+  });
+  assert.equal(reason, 'ADB_TRANSPORT_UNAVAILABLE');
+});
+
+test('classifyBootFailure maps tool missing from AppError code (android)', () => {
+  const reason = classifyBootFailure({
+    error: new AppError('TOOL_MISSING', 'adb not found in PATH'),
+    context: { platform: 'android', phase: 'transport' },
+  });
+  assert.equal(reason, 'ADB_TRANSPORT_UNAVAILABLE');
+});
+
+test('classifyBootFailure maps tool missing from AppError code (ios)', () => {
+  const reason = classifyBootFailure({
+    error: new AppError('TOOL_MISSING', 'xcrun not found in PATH'),
+    context: { platform: 'ios', phase: 'boot' },
+  });
+  assert.equal(reason, 'IOS_TOOL_MISSING');
+});
+
+test('classifyBootFailure reads stderr from AppError details', () => {
+  const reason = classifyBootFailure({
+    error: new AppError('COMMAND_FAILED', 'adb failed', {
+      stderr: 'error: device unauthorized',
+    }),
+    context: { platform: 'android', phase: 'transport' },
+  });
+  assert.equal(reason, 'ADB_TRANSPORT_UNAVAILABLE');
+});
+
+test('bootFailureHint returns actionable guidance', () => {
+  const hint = bootFailureHint('IOS_RUNNER_CONNECT_TIMEOUT');
+  assert.equal(hint.includes('xcodebuild logs'), true);
+});
+
+test('connect phase does not classify non-timeout errors as connect timeout', () => {
+  const reason = classifyBootFailure({
+    message: 'Runner returned malformed JSON payload',
+    context: { platform: 'ios', phase: 'connect' },
+  });
+  assert.equal(reason, 'BOOT_COMMAND_FAILED');
+});

package/src/platforms/android/__tests__/index.test.ts

@@ -1,5 +1,6 @@
 import test from 'node:test';
 import assert from 'node:assert/strict';
+import { parseAndroidLaunchComponent } from '../index.ts';
 import { findBounds, parseUiHierarchy } from '../ui-hierarchy.ts';
 
 test('parseUiHierarchy reads double-quoted Android node attributes', () => {
@@ -72,3 +73,19 @@ test('findBounds ignores bounds-like fragments inside other attribute values', (
 
   assert.deepEqual(findBounds(xml, 'target'), { x: 200, y: 350 });
 });
+
+test('parseAndroidLaunchComponent extracts final resolved component', () => {
+  const stdout = [
+    'priority=0 preferredOrder=0 match=0x108000 specificIndex=-1 isDefault=true',
+    'com.boatsgroup.boattrader/com.boatsgroup.boattrader.MainActivity',
+  ].join('\n');
+  assert.equal(
+    parseAndroidLaunchComponent(stdout),
+    'com.boatsgroup.boattrader/com.boatsgroup.boattrader.MainActivity',
+  );
+});
+
+test('parseAndroidLaunchComponent returns null when no component is present', () => {
+  const stdout = 'No activity found';
+  assert.equal(parseAndroidLaunchComponent(stdout), null);
+});