agent-device 0.1.0

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "agent-device",
+  "version": "0.1.0",
+  "description": "Unified control plane for physical and virtual devices via an agent-driven CLI.",
+  "license": "MIT",
+  "author": "Callstack",
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "bin": {
+    "agent-device": "bin/agent-device.mjs"
+  },
+  "scripts": {
+    "lint": "node --eval \"console.log('no lint')\"",
+    "build": "rslib build",
+    "build:node": "pnpm build && rm -f ~/.agent-device/daemon.json",
+    "build:swift": "swift build -c release --package-path ios-runner/AXSnapshot",
+    "build:axsnapshot": "pnpm build:swift && mkdir -p bin && cp -f ios-runner/AXSnapshot/.build/release/axsnapshot bin/axsnapshot && chmod +x bin/axsnapshot",
+    "build:clis": "pnpm build:node && pnpm build:axsnapshot",
+    "format": "prettier --write .",
+    "prepublishOnly": "pnpm build:node && pnpm build:axsnapshot",
+    "typecheck": "tsc -p tsconfig.json",
+    "test": "node --test",
+    "test:smoke": "node --test test/smoke/*.test.ts",
+    "test:integration": "node --test test/integration/*.test.ts"
+  },
+  "files": [
+    "bin",
+    "dist",
+    "bin/axsnapshot",
+    "ios-runner",
+    "!ios-runner/**/.build",
+    "!ios-runner/**/.swiftpm",
+    "!ios-runner/**/xcuserdata",
+    "!ios-runner/**/*.xcuserstate",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "agent",
+    "device",
+    "cli",
+    "adb",
+    "simctl",
+    "devicectl",
+    "ios",
+    "android"
+  ],
+  "prettier": {
+    "singleQuote": true,
+    "semi": true,
+    "trailingComma": "all",
+    "printWidth": 100
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@rslib/core": "0.19.4",
+    "prettier": "^3.3.3",
+    "typescript": "^5.9.3"
+  }
+}

package/src/bin.ts

@@ -0,0 +1,3 @@
+import { runCli } from './cli.ts';
+
+runCli(process.argv.slice(2));

package/src/cli.ts

@@ -0,0 +1,160 @@
+import { parseArgs, usage } from './utils/args.ts';
+import { asAppError, AppError } from './utils/errors.ts';
+import { formatSnapshotText, printHumanError, printJson } from './utils/output.ts';
+import { pathToFileURL } from 'node:url';
+import { sendToDaemon } from './daemon-client.ts';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+export async function runCli(argv: string[]): Promise<void> {
+  const parsed = parseArgs(argv);
+
+  if (parsed.flags.help || !parsed.command) {
+    process.stdout.write(`${usage()}\n`);
+    process.exit(parsed.flags.help ? 0 : 1);
+  }
+
+  const { command, positionals, flags } = parsed;
+  const sessionName = flags.session ?? process.env.AGENT_DEVICE_SESSION ?? 'default';
+  const logTailStopper = flags.verbose && !flags.json ? startDaemonLogTail() : null;
+  try {
+    if (command === 'session') {
+      const sub = positionals[0] ?? 'list';
+      if (sub !== 'list') {
+        throw new AppError('INVALID_ARGS', 'session only supports list');
+      }
+      const response = await sendToDaemon({
+        session: sessionName,
+        command: 'session_list',
+        positionals: [],
+        flags: {},
+      });
+      if (!response.ok) throw new AppError(response.error.code as any, response.error.message);
+      if (flags.json) printJson({ success: true, data: response.data ?? {} });
+      else process.stdout.write(`${JSON.stringify(response.data ?? {}, null, 2)}\n`);
+      if (logTailStopper) logTailStopper();
+      return;
+    }
+
+    const response = await sendToDaemon({
+      session: sessionName,
+      command: command!,
+      positionals,
+      flags,
+    });
+
+    if (response.ok) {
+      if (flags.json) {
+        printJson({ success: true, data: response.data ?? {} });
+        if (logTailStopper) logTailStopper();
+        return;
+      }
+      if (command === 'snapshot') {
+        process.stdout.write(
+          formatSnapshotText((response.data ?? {}) as Record<string, unknown>, {
+            raw: flags.snapshotRaw,
+          }),
+        );
+        if (logTailStopper) logTailStopper();
+        return;
+      }
+      if (command === 'get') {
+        const sub = positionals[0];
+        if (sub === 'text') {
+          const text = (response.data as any)?.text ?? '';
+          process.stdout.write(`${text}\n`);
+          if (logTailStopper) logTailStopper();
+          return;
+        }
+        if (sub === 'attrs') {
+          const node = (response.data as any)?.node ?? {};
+          process.stdout.write(`${JSON.stringify(node, null, 2)}\n`);
+          if (logTailStopper) logTailStopper();
+          return;
+        }
+      }
+      if (command === 'click') {
+        const ref = (response.data as any)?.ref ?? '';
+        const x = (response.data as any)?.x;
+        const y = (response.data as any)?.y;
+        if (ref && typeof x === 'number' && typeof y === 'number') {
+          process.stdout.write(`Clicked @${ref} (${x}, ${y})\n`);
+        }
+        if (logTailStopper) logTailStopper();
+        return;
+      }
+      if (logTailStopper) logTailStopper();
+      return;
+    }
+
+    throw new AppError(response.error.code as any, response.error.message, response.error.details);
+  } catch (err) {
+    const appErr = asAppError(err);
+    if (flags.json) {
+      printJson({
+        success: false,
+        error: { code: appErr.code, message: appErr.message, details: appErr.details },
+      });
+    } else {
+      printHumanError(appErr);
+      if (flags.verbose) {
+        try {
+          const fs = await import('node:fs');
+          const os = await import('node:os');
+          const path = await import('node:path');
+          const logPath = path.join(os.homedir(), '.agent-device', 'daemon.log');
+          if (fs.existsSync(logPath)) {
+            const content = fs.readFileSync(logPath, 'utf8');
+            const lines = content.split('\n');
+            const tail = lines.slice(Math.max(0, lines.length - 200)).join('\n');
+            if (tail.trim().length > 0) {
+              process.stderr.write(`\n[daemon log]\n${tail}\n`);
+            }
+          }
+        } catch {
+          // ignore
+        }
+      }
+    }
+    if (logTailStopper) logTailStopper();
+    process.exit(1);
+  }
+}
+
+const isDirectRun = pathToFileURL(process.argv[1] ?? '').href === import.meta.url;
+if (isDirectRun) {
+  runCli(process.argv.slice(2)).catch((err) => {
+    const appErr = asAppError(err);
+    printHumanError(appErr);
+    process.exit(1);
+  });
+}
+
+function startDaemonLogTail(): (() => void) | null {
+  try {
+    const logPath = path.join(os.homedir(), '.agent-device', 'daemon.log');
+    let offset = 0;
+    let stopped = false;
+    const interval = setInterval(() => {
+      if (stopped) return;
+      if (!fs.existsSync(logPath)) return;
+      const stats = fs.statSync(logPath);
+      if (stats.size <= offset) return;
+      const fd = fs.openSync(logPath, 'r');
+      const buffer = Buffer.alloc(stats.size - offset);
+      fs.readSync(fd, buffer, 0, buffer.length, offset);
+      fs.closeSync(fd);
+      offset = stats.size;
+      if (buffer.length > 0) {
+        process.stdout.write(buffer.toString('utf8'));
+      }
+    }, 200);
+    return () => {
+      stopped = true;
+      clearInterval(interval);
+    };
+  } catch {
+    return null;
+  }
+}

package/src/core/dispatch.ts

@@ -0,0 +1,259 @@
+import { AppError } from '../utils/errors.ts';
+import { selectDevice, type DeviceInfo } from '../utils/device.ts';
+import { listAndroidDevices } from '../platforms/android/devices.ts';
+import { ensureAdb, snapshotAndroid } from '../platforms/android/index.ts';
+import { listIosDevices } from '../platforms/ios/devices.ts';
+import { getInteractor } from '../utils/interactors.ts';
+import { runIosRunnerCommand } from '../platforms/ios/runner-client.ts';
+import { snapshotAx } from '../platforms/ios/ax-snapshot.ts';
+import type { RawSnapshotNode } from '../utils/snapshot.ts';
+
+export type CommandFlags = {
+  platform?: 'ios' | 'android';
+  device?: string;
+  udid?: string;
+  serial?: string;
+  out?: string;
+  verbose?: boolean;
+  snapshotInteractiveOnly?: boolean;
+  snapshotCompact?: boolean;
+  snapshotDepth?: number;
+  snapshotScope?: string;
+  snapshotRaw?: boolean;
+  snapshotBackend?: 'ax' | 'xctest';
+  noRecord?: boolean;
+  recordJson?: boolean;
+};
+
+export async function resolveTargetDevice(flags: CommandFlags): Promise<DeviceInfo> {
+  const selector = {
+    platform: flags.platform,
+    deviceName: flags.device,
+    udid: flags.udid,
+    serial: flags.serial,
+  };
+
+  if (selector.platform === 'android') {
+    await ensureAdb();
+    const devices = await listAndroidDevices();
+    return await selectDevice(devices, selector);
+  }
+
+  if (selector.platform === 'ios') {
+    const devices = await listIosDevices();
+    return await selectDevice(devices, selector);
+  }
+
+  const devices: DeviceInfo[] = [];
+  try {
+    devices.push(...(await listAndroidDevices()));
+  } catch {
+    // ignore
+  }
+  try {
+    devices.push(...(await listIosDevices()));
+  } catch {
+    // ignore
+  }
+  return await selectDevice(devices, selector);
+}
+
+export async function dispatchCommand(
+  device: DeviceInfo,
+  command: string,
+  positionals: string[],
+  outPath?: string,
+  context?: {
+    appBundleId?: string;
+    verbose?: boolean;
+    logPath?: string;
+    snapshotInteractiveOnly?: boolean;
+    snapshotCompact?: boolean;
+    snapshotDepth?: number;
+    snapshotScope?: string;
+    snapshotRaw?: boolean;
+  },
+): Promise<Record<string, unknown> | void> {
+  const interactor = getInteractor(device);
+  switch (command) {
+    case 'open': {
+      const app = positionals[0];
+      if (!app) throw new AppError('INVALID_ARGS', 'open requires an app name or bundle/package id');
+      await interactor.open(app);
+      return { app };
+    }
+    case 'close': {
+      const app = positionals[0];
+      if (!app) {
+        return { closed: 'session' };
+      }
+      await interactor.close(app);
+      return { app };
+    }
+    case 'press': {
+      const [x, y] = positionals.map(Number);
+      if (Number.isNaN(x) || Number.isNaN(y)) throw new AppError('INVALID_ARGS', 'press requires x y');
+      if (device.platform === 'ios' && device.kind === 'simulator') {
+        await runIosRunnerCommand(
+          device,
+          { command: 'tap', x, y, appBundleId: context?.appBundleId },
+          { verbose: context?.verbose, logPath: context?.logPath },
+        );
+      } else {
+        await interactor.tap(x, y);
+      }
+      return { x, y };
+    }
+    case 'long-press': {
+      const x = Number(positionals[0]);
+      const y = Number(positionals[1]);
+      const durationMs = positionals[2] ? Number(positionals[2]) : undefined;
+      if (Number.isNaN(x) || Number.isNaN(y)) {
+        throw new AppError('INVALID_ARGS', 'long-press requires x y [durationMs]');
+      }
+      await interactor.longPress(x, y, durationMs);
+      return { x, y, durationMs };
+    }
+    case 'focus': {
+      const [x, y] = positionals.map(Number);
+      if (Number.isNaN(x) || Number.isNaN(y)) throw new AppError('INVALID_ARGS', 'focus requires x y');
+      if (device.platform === 'ios' && device.kind === 'simulator') {
+        await runIosRunnerCommand(
+          device,
+          { command: 'tap', x, y, appBundleId: context?.appBundleId },
+          { verbose: context?.verbose, logPath: context?.logPath },
+        );
+      } else {
+        await interactor.focus(x, y);
+      }
+      return { x, y };
+    }
+    case 'type': {
+      const text = positionals.join(' ');
+      if (!text) throw new AppError('INVALID_ARGS', 'type requires text');
+      if (device.platform === 'ios' && device.kind === 'simulator') {
+        await runIosRunnerCommand(
+          device,
+          { command: 'type', text, appBundleId: context?.appBundleId },
+          { verbose: context?.verbose, logPath: context?.logPath },
+        );
+      } else {
+        await interactor.type(text);
+      }
+      return { text };
+    }
+    case 'fill': {
+      const x = Number(positionals[0]);
+      const y = Number(positionals[1]);
+      const text = positionals.slice(2).join(' ');
+      if (Number.isNaN(x) || Number.isNaN(y) || !text) {
+        throw new AppError('INVALID_ARGS', 'fill requires x y text');
+      }
+      if (device.platform === 'ios' && device.kind === 'simulator') {
+        await runIosRunnerCommand(
+          device,
+          { command: 'tap', x, y, appBundleId: context?.appBundleId },
+          { verbose: context?.verbose, logPath: context?.logPath },
+        );
+        await runIosRunnerCommand(
+          device,
+          { command: 'type', text, appBundleId: context?.appBundleId },
+          { verbose: context?.verbose, logPath: context?.logPath },
+        );
+      } else {
+        await interactor.fill(x, y, text);
+      }
+      return { x, y, text };
+    }
+    case 'scroll': {
+      const direction = positionals[0];
+      const amount = positionals[1] ? Number(positionals[1]) : undefined;
+      if (!direction) throw new AppError('INVALID_ARGS', 'scroll requires direction');
+      if (device.platform === 'ios' && device.kind === 'simulator') {
+        if (!['up', 'down', 'left', 'right'].includes(direction)) {
+          throw new AppError('INVALID_ARGS', `Unknown direction: ${direction}`);
+        }
+        const inverted = invertScrollDirection(direction as 'up' | 'down' | 'left' | 'right');
+        await runIosRunnerCommand(
+          device,
+          { command: 'swipe', direction: inverted, appBundleId: context?.appBundleId },
+          { verbose: context?.verbose, logPath: context?.logPath },
+        );
+      } else {
+        await interactor.scroll(direction, amount);
+      }
+      return { direction, amount };
+    }
+    case 'scrollintoview': {
+      const text = positionals.join(' ');
+      if (!text) throw new AppError('INVALID_ARGS', 'scrollintoview requires text');
+      await interactor.scrollIntoView(text);
+      return { text };
+    }
+    case 'screenshot': {
+      const path = outPath ?? `./screenshot-${Date.now()}.png`;
+      await interactor.screenshot(path);
+      return { path };
+    }
+    case 'snapshot': {
+      const backend = context?.snapshotBackend ?? 'ax';
+      if (device.platform === 'ios') {
+        if (device.kind !== 'simulator') {
+          throw new AppError(
+            'UNSUPPORTED_OPERATION',
+            'snapshot is only supported on iOS simulators in v1',
+          );
+        }
+        if (backend === 'ax') {
+          try {
+            const ax = await snapshotAx(device);
+            return { nodes: ax.nodes ?? [], truncated: false, backend: 'ax', rootRect: ax.rootRect };
+          } catch (err) {
+            if (context?.snapshotBackend === 'ax') {
+              throw err;
+            }
+          }
+        }
+        const result = (await runIosRunnerCommand(
+          device,
+          {
+            command: 'snapshot',
+            appBundleId: context?.appBundleId,
+            interactiveOnly: context?.snapshotInteractiveOnly,
+            compact: context?.snapshotCompact,
+            depth: context?.snapshotDepth,
+            scope: context?.snapshotScope,
+            raw: context?.snapshotRaw,
+          },
+          { verbose: context?.verbose, logPath: context?.logPath },
+        )) as { nodes?: RawSnapshotNode[]; truncated?: boolean };
+        return { nodes: result.nodes ?? [], truncated: result.truncated ?? false, backend: 'xctest' };
+      }
+      const androidResult = await snapshotAndroid(device, {
+        interactiveOnly: context?.snapshotInteractiveOnly,
+        compact: context?.snapshotCompact,
+        depth: context?.snapshotDepth,
+        scope: context?.snapshotScope,
+        raw: context?.snapshotRaw,
+      });
+      return { nodes: androidResult.nodes ?? [], truncated: androidResult.truncated ?? false, backend: 'android' };
+    }
+    default:
+      throw new AppError('INVALID_ARGS', `Unknown command: ${command}`);
+  }
+}
+
+function invertScrollDirection(direction: 'up' | 'down' | 'left' | 'right'): 'up' | 'down' | 'left' | 'right' {
+  switch (direction) {
+    case 'up':
+      return 'down';
+    case 'down':
+      return 'up';
+    case 'left':
+      return 'right';
+    case 'right':
+      return 'left';
+  }
+}
+
+// Runner-only input on iOS simulators (simctl io input is not supported).

package/src/daemon-client.ts

@@ -0,0 +1,166 @@
+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';
+
+export type DaemonRequest = {
+  token: string;
+  session: string;
+  command: string;
+  positionals: string[];
+  flags?: CommandFlags;
+};
+
+export type DaemonResponse =
+  | { ok: true; data?: Record<string, unknown> }
+  | { ok: false; error: { code: string; message: string; details?: Record<string, unknown> } };
+
+type DaemonInfo = { port: number; token: string; pid: number; version?: string };
+
+const baseDir = path.join(os.homedir(), '.agent-device');
+const infoPath = path.join(baseDir, 'daemon.json');
+const REQUEST_TIMEOUT_MS = resolveRequestTimeoutMs();
+const DAEMON_STARTUP_TIMEOUT_MS = 5000;
+
+export async function sendToDaemon(req: Omit<DaemonRequest, 'token'>): Promise<DaemonResponse> {
+  const info = await ensureDaemon();
+  const request = { ...req, token: info.token };
+  return await sendRequest(info, request);
+}
+
+async function ensureDaemon(): Promise<DaemonInfo> {
+  const existing = readDaemonInfo();
+  const localVersion = readVersion();
+  if (existing && existing.version === localVersion && (await canConnect(existing))) return existing;
+  if (existing && (existing.version !== localVersion || !(await canConnect(existing)))) {
+    removeDaemonInfo();
+  }
+
+  await startDaemon();
+
+  const start = Date.now();
+  while (Date.now() - start < DAEMON_STARTUP_TIMEOUT_MS) {
+    const info = readDaemonInfo();
+    if (info && (await canConnect(info))) return info;
+    await new Promise((resolve) => setTimeout(resolve, 100));
+  }
+
+  throw new AppError('COMMAND_FAILED', 'Failed to start daemon', {
+    infoPath,
+    hint: 'Run pnpm build, or delete ~/.agent-device/daemon.json if stale.',
+  });
+}
+
+function readDaemonInfo(): DaemonInfo | null {
+  if (!fs.existsSync(infoPath)) return null;
+  try {
+    const data = JSON.parse(fs.readFileSync(infoPath, 'utf8')) as DaemonInfo;
+    if (!data.port || !data.token) return null;
+    return data;
+  } catch {
+    return null;
+  }
+}
+
+function removeDaemonInfo(): void {
+  if (fs.existsSync(infoPath)) fs.unlinkSync(infoPath);
+}
+
+async function canConnect(info: DaemonInfo): Promise<boolean> {
+  return new Promise((resolve) => {
+    const socket = net.createConnection({ host: '127.0.0.1', port: info.port }, () => {
+      socket.destroy();
+      resolve(true);
+    });
+    socket.on('error', () => {
+      resolve(false);
+    });
+  });
+}
+
+async function startDaemon(): Promise<void> {
+  const root = findProjectRoot();
+  const distPath = path.join(root, 'dist', 'src', 'daemon.js');
+  const srcPath = path.join(root, 'src', 'daemon.ts');
+
+  const useDist = fs.existsSync(distPath);
+  if (!useDist && !fs.existsSync(srcPath)) {
+    throw new AppError('COMMAND_FAILED', 'Daemon entry not found', { distPath, srcPath });
+  }
+  const args = useDist ? [distPath] : ['--experimental-strip-types', srcPath];
+
+  runCmdDetached(process.execPath, args);
+}
+
+async function sendRequest(info: DaemonInfo, req: DaemonRequest): Promise<DaemonResponse> {
+  return new Promise((resolve, reject) => {
+    const socket = net.createConnection({ host: '127.0.0.1', port: info.port }, () => {
+      socket.write(`${JSON.stringify(req)}\n`);
+    });
+    const timeout = setTimeout(() => {
+      socket.destroy();
+      reject(
+        new AppError('COMMAND_FAILED', 'Daemon request timed out', { timeoutMs: REQUEST_TIMEOUT_MS }),
+      );
+    }, REQUEST_TIMEOUT_MS);
+
+    let buffer = '';
+    socket.setEncoding('utf8');
+    socket.on('data', (chunk) => {
+      buffer += chunk;
+      const idx = buffer.indexOf('\n');
+      if (idx === -1) return;
+      const line = buffer.slice(0, idx).trim();
+      if (!line) return;
+      try {
+        const response = JSON.parse(line) as DaemonResponse;
+        socket.end();
+        clearTimeout(timeout);
+        resolve(response);
+      } catch (err) {
+        clearTimeout(timeout);
+        reject(err);
+      }
+    });
+
+    socket.on('error', (err) => {
+      clearTimeout(timeout);
+      reject(err);
+    });
+  });
+}
+
+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;
+  const parsed = Number(raw);
+  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;
+}