android-agent-bridge 0.0.0-stage → 0.1.0

package/AI_SETUP.md

@@ -0,0 +1,10 @@
+# Setting up android-agent-bridge (for AI agents)
+
+Follow these steps when the user asks you to give yourself access to their Android phone.
+
+1. In the user's project, run `npx -y android-agent-bridge init`. It writes `.mcp.json` (server name `phone`) and an agent guide. Tell the user to restart the agent so the `phone_*` tools load.
+2. The phone needs the **Agent Bridge** app. If the phone is plugged in with USB debugging on, `npx -y android-agent-bridge usb` installs and sets everything up. Otherwise the user installs `apk/agent-bridge.apk` from the package.
+3. Pairing over Wi-Fi: the user runs `npx -y android-agent-bridge start`, opens the app, taps **Scan QR code** and turns on the accessibility service. With the MCP server running, the pairing page is at http://localhost:8350/pair.
+4. Call `phone_status` to confirm. Then follow `skill/SKILL.md`.
+
+Without MCP, use the CLI from the shell: `npx android-agent-bridge screen --out shot.jpg`, `tap 12`, `type "hello" --into 3 --submit`, and so on (`npx android-agent-bridge help`). Read the saved screenshot file to see it.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 android-agent-bridge contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,119 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# android-agent-bridge
+
+Give your AI agent (Claude Code, Cursor, Antigravity, or anything that speaks MCP or runs shell commands) your **whole Android phone**: it sees the screen, taps, types, scrolls and opens apps — in any app, not just your own.
+
+- **Pair once by QR code** over Wi-Fi, or plug in **USB**. Both work, and the phone switches to Wi-Fi when you unplug.
+- **Screenshots with numbered elements** so the agent says "tap 12" instead of guessing pixels, plus a **lettered grid** ("tap C7") for maps, games and images.
+- **Typing without the keyboard**: text goes straight into the field.
+- **Android 5.0 and newer** (phones from 2015 on).
+
+```
+ ┌──────────────┐  MCP / CLI   ┌───────────────────┐  Wi-Fi or USB  ┌──────────────────┐
+ │ Claude Code, │ ───────────▶ │ android-agent-    │ ◀────────────▶ │ Agent Bridge app │
+ │ Cursor, …    │              │ bridge (computer) │   WebSocket    │ (phone)          │
+ └──────────────┘              └───────────────────┘                └──────────────────┘
+```
+
+## 1. Install the app on the phone
+
+**Install it over USB (step 2b).** `usb` installs the app for you.
+
+Opening the APK from WhatsApp, a browser or a file manager often fails with Google Play Protect's **"App blocked to protect your device"**. In some countries (India and others), Play Protect blocks sideloaded apps that use accessibility, with no "install anyway" option. Installs over USB with adb aren't blocked, so use `usb` once. After that the phone also works over Wi-Fi.
+
+## 2a. Pair over Wi-Fi
+
+```bash
+npx android-agent-bridge start
+```
+
+Open **Agent Bridge** on the phone → **Scan QR code** → point it at the QR code in the terminal (or the bigger one at http://localhost:8350/pair). Then turn on the app's **accessibility service** with the button in the app.
+
+Phone and computer must be on the same Wi-Fi. On Windows, allow Node.js through the firewall when asked.
+
+## 2b. Or set up over USB
+
+Turn on USB debugging (Settings → About phone → tap Build number 7 times → Developer options → USB debugging), plug in, then:
+
+```bash
+npx android-agent-bridge usb
+```
+
+This installs the app if needed, turns on its accessibility service, pairs it and starts the bridge. No QR code.
+
+## 3. Connect your agent
+
+```bash
+npx android-agent-bridge init
+```
+
+Run it in your project: it adds the MCP server to `.mcp.json` (and `.cursor/mcp.json` with `--cursor`), plus a short guide for the agent. For other agents, add an MCP server with the command `npx -y android-agent-bridge`.
+
+Then ask: *"Open WhatsApp on my phone and read the last message from Mom."*
+
+## Tools
+
+| MCP tool | CLI | What it does |
+|---|---|---|
+| `phone_status` | `status` | connected phone, Android version, capabilities |
+| `phone_screen` | `screen [--mode marks\|grid\|both\|plain]` | screenshot with numbered elements / grid + element list |
+| `phone_elements` | `elements [--all] [--ocr]` | element list only (cheap, text); `--all` includes covered elements, `--ocr` adds screen text |
+| `phone_ocr` | `ocr` | text read from the screen pixels with positions (on-device ML Kit, offline) — finds controls apps hide from accessibility |
+| `phone_tap` | `tap <target> [--long]` | tap or long-press |
+| `phone_type` | `type <text> [--into t] [--submit]` | type into a field |
+| `phone_scroll` | `scroll <dir> [--in t]` | scroll the screen or a list |
+| `phone_swipe` | `swipe <from> <to>` | drag between two points |
+| `phone_key` | `key <name>` | back, home, recents, notifications, quick_settings, enter, lock |
+| `phone_open_app` | `open <app>` | open an app by name or package |
+| `phone_apps` | `apps [filter]` | list installed apps |
+| `phone_wait_for` | `wait <text>` | wait for text to appear |
+| `phone_open_app` `store` | `launch <app> --store` | open an app, or its Play Store page if it isn't installed |
+| `phone_volume` | `volume [stream] [up\|down\|mute\|40%\|…]` | media, ring, notification, alarm, call volume |
+| `phone_brightness` | `brightness [0-100\|auto]` | screen brightness |
+| `phone_toggle` | `flashlight` · `rotation` · `dnd` · `ringer` | quick switches |
+| `phone_settings` | `settings <page>` | open wifi, bluetooth, display, battery… or an app's info page |
+| `phone_open_link` | `url <link>` | web pages and deep links |
+| `phone_dial` | `dial <number>` | dialer with the number filled in (never calls) |
+| `phone_web_search` | `search <query>` | web search on the phone |
+| `phone_device_info` | `battery` · `current` · `permissions` | battery, app in front, what the app may do |
+| `phone_notifications` | `notifications` | notifications received since the service started |
+| `phone_clipboard` | `clipboard [set <text>]` | read / set the clipboard |
+| `phone_wake` | `wake` | turn the screen on (stays PIN-locked) |
+| `phone_permissions` | `permissions grant` | switch on the one-time permissions over USB |
+| `phone_stop_app` | `stop <package>` | force-stop an app (USB) |
+
+A **target** is an element number (`12`), visible text (`Sign in`), a grid cell (`C7`) or pixels (`540,1200`). Text is matched in this order: exact or starts-with in the app → exact or starts-with in the screen text (OCR) → contains → the Android system bar.
+
+The CLI commands need a running bridge: `start`, `usb`, or an agent's MCP session. All of them share one bridge.
+
+## What works on which Android
+
+| | 5.0–6.0 | 7.0–10 | 11+ |
+|---|---|---|---|
+| Element list, typing, clicking elements, back/home | ✅ | ✅ | ✅ |
+| Tap anywhere (grid, pixels), swipes | over USB | ✅ | ✅ |
+| Screenshots | tap "Allow screen capture" once per session, or USB | same | ✅ built in |
+| Enter key | over USB | over USB | ✅ |
+
+"Over USB" means the bridge does it through adb when the phone is plugged in with USB debugging.
+
+Apps that block screen capture (banking, Netflix and similar) show up black in screenshots; their element list usually still works.
+
+## Security
+
+- Only a computer holding the pairing secret from the QR code can connect. `npx android-agent-bridge pair --reset` makes a new secret; every phone then has to scan again.
+- Traffic on your Wi-Fi is not encrypted (plain WebSocket), so use it on networks you trust. Over USB it never leaves the cable.
+- Turn off the accessibility service in the app (or Android settings) to cut access at once.
+- The agent guide tells agents to ask before sending, paying or deleting, and never to type passwords.
+
+## Building the app
+
+```bash
+cd android
+./gradlew assembleRelease
+```
+
+Needs JDK 17 and the Android SDK (`ANDROID_HOME` or `android/local.properties`). The APK lands in `android/app/build/outputs/apk/release/`; copy it to `apk/agent-bridge.apk`.
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,53 @@
-{
-  "name": "android-agent-bridge",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+{
+  "name": "android-agent-bridge",
+  "version": "0.1.0",
+  "description": "Give AI agents (Claude Code, Cursor, Antigravity) your whole Android phone: screenshots with numbered elements and a tap grid, tap, type, scroll, open apps. Pair once by QR over Wi-Fi or plug in USB. Android 5.0+.",
+  "keywords": [
+    "android",
+    "mcp",
+    "model-context-protocol",
+    "ai-agent",
+    "claude-code",
+    "cursor",
+    "antigravity",
+    "phone-control",
+    "accessibility",
+    "automation",
+    "adb",
+    "mobile-testing"
+  ],
+  "license": "MIT",
+  "author": "Rudra Samadhiya",
+  "homepage": "https://github.com/Rudrasamadhiya/android-agent-bridge#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Rudrasamadhiya/android-agent-bridge.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Rudrasamadhiya/android-agent-bridge/issues"
+  },
+  "bin": {
+    "android-agent-bridge": "server/cli.mjs",
+    "phonectl": "server/cli.mjs"
+  },
+  "files": [
+    "server",
+    "skill",
+    "apk",
+    "README.md",
+    "LICENSE",
+    "AI_SETUP.md"
+  ],
+  "scripts": {
+    "test": "node --test test/bridge.test.mjs"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.32.1",
+    "qrcode": "^1.5.4",
+    "ws": "^8.22.0",
+    "zod": "^4.6.7"
+  }
+}

package/server/adb.mjs

@@ -0,0 +1,55 @@
+// adb over USB (or `adb connect`): used for setup (`usb` command) and as a
+// fallback for what the app cannot do on old Android (taps by coordinate
+// before Android 7, Enter key before Android 11, screenshots without capture).
+import { execFile } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+
+export const KEYCODES = {
+  back: 4, home: 3, recents: 187, enter: 66, tab: 61, delete: 67, escape: 111,
+  volume_up: 24, volume_down: 25, mute: 164, power: 26, menu: 82, search: 84,
+};
+
+export function adbPath() {
+  const exe = process.platform === 'win32' ? 'adb.exe' : 'adb';
+  for (const root of [process.env.ANDROID_HOME, process.env.ANDROID_SDK_ROOT,
+    process.env.LOCALAPPDATA && path.join(process.env.LOCALAPPDATA, 'Android', 'Sdk'),
+    process.env.HOME && path.join(process.env.HOME, 'Library', 'Android', 'sdk'),
+    process.env.HOME && path.join(process.env.HOME, 'Android', 'Sdk')]) {
+    if (root && existsSync(path.join(root, 'platform-tools', exe))) return path.join(root, 'platform-tools', exe);
+  }
+  return 'adb';
+}
+
+export function adb(args, { timeout = 15000, binary = false, serial = process.env.ANDROID_SERIAL } = {}) {
+  const full = serial ? ['-s', serial, ...args] : args;
+  return new Promise((resolve, reject) => {
+    execFile(adbPath(), full, { timeout, windowsHide: true, encoding: binary ? 'buffer' : 'utf8', maxBuffer: 64 * 1024 * 1024 }, (err, stdout, stderr) => {
+      if (err) {
+        reject(new Error(err.code === 'ENOENT'
+          ? 'adb not found. Install Android platform-tools (https://developer.android.com/tools/releases/platform-tools) or set ANDROID_HOME.'
+          : String(stderr || err.message).trim()));
+      } else resolve(binary ? stdout : String(stdout).trim());
+    });
+  });
+}
+
+/** Serials of phones attached and authorized. */
+export async function devices() {
+  const out = await adb(['devices', '-l'], { serial: null });
+  return out.split('\n').slice(1).map((l) => l.trim().split(/\s+/)).filter((p) => p[1] === 'device')
+    .map((p) => ({ serial: p[0], model: (p.find((x) => x.startsWith('model:')) || '').slice(6) }));
+}
+
+/** Pick the adb serial for the connected phone (matching model when several are plugged in). */
+export async function pickSerial(model) {
+  if (process.env.ANDROID_SERIAL) return process.env.ANDROID_SERIAL;
+  let list;
+  try { list = await devices(); } catch { return null; }
+  if (!list.length) return null;
+  if (list.length === 1 || !model) return list[0].serial;
+  const norm = (s) => String(s).replace(/[\s_]/g, '').toLowerCase();
+  return (list.find((d) => norm(d.model) === norm(model)) || list[0]).serial;
+}
+
+export const shell = (serial, ...cmd) => adb(['shell', ...cmd], { serial });

package/server/bridge.mjs

@@ -0,0 +1,207 @@
+// Bridge: what the CLI and the MCP server talk to. It either owns the hub
+// (first process to start) or forwards commands to the process that does.
+import { setTimeout as sleep } from 'node:timers/promises';
+import { Hub, pairLink, qrTerminal } from './hub.mjs';
+import { loadConfig, APP_ID } from './config.mjs';
+import { adb, pickSerial, KEYCODES } from './adb.mjs';
+
+// commands that change the screen: report the new screen afterwards
+const ACTIONS = new Set(['tap', 'swipe', 'scroll', 'type', 'key', 'open_app']);
+
+/** Best OCR line for a query: exact, then starts-with, then contains (case-insensitive). */
+export function findText(lines, query) {
+  const q = query.toLowerCase().trim();
+  const t = (l) => l.text.toLowerCase().trim();
+  const strong = lines.find((l) => t(l) === q) || lines.find((l) => t(l).startsWith(q));
+  if (strong) return { ...strong, strong: true };
+  const weak = lines.find((l) => t(l).includes(q));
+  return weak ? { ...weak, strong: false } : null;
+}
+
+async function hubAlive(cfg) {
+  try {
+    const r = await fetch(`http://127.0.0.1:${cfg.port}/status`, { signal: AbortSignal.timeout(800) });
+    return r.ok;
+  } catch { return false; }
+}
+
+async function rpc(cfg, cmd, args, timeout) {
+  let res;
+  try {
+    res = await fetch(`http://127.0.0.1:${cfg.port}/rpc`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json', 'x-aab-token': cfg.token },
+      body: JSON.stringify({ cmd, args, timeout }),
+      signal: AbortSignal.timeout((timeout || 20000) + 15000),
+    });
+  } catch (err) {
+    const e = new Error('hub not reachable: ' + err.message);
+    e.hubGone = true;
+    throw e;
+  }
+  const body = await res.json();
+  if (!body.ok) throw new Error(body.error);
+  return body.result;
+}
+
+export class Bridge {
+  /** host: start the hub here when none is running (MCP server, `start`); false for one-shot CLI commands. */
+  constructor({ log = () => {}, host = true } = {}) {
+    this.cfg = loadConfig();
+    this.log = log;
+    this.host = host;
+    this.hub = null;
+  }
+
+  /** Concurrent callers share one attempt, so only one hub is ever started. */
+  ensure() {
+    if (!this.ensuring) this.ensuring = this.doEnsure().finally(() => { this.ensuring = null; });
+    return this.ensuring;
+  }
+
+  async doEnsure() {
+    if (this.hub) return;
+    if (await hubAlive(this.cfg)) return;
+    if (!this.host) {
+      throw new Error(`No bridge is running. Start one with \`npx android-agent-bridge start\` (or let your AI agent's MCP server start it).`);
+    }
+    const hub = new Hub({ cfg: this.cfg, log: this.log, onRpc: (c, a, t) => this.runLocal(c, a, t) });
+    hub.files.onDrop = (paths) => this.sendFiles(paths);
+    if (await hub.start()) { this.hub = hub; return; }
+    if (!(await hubAlive(this.cfg))) throw new Error(hub.startError + ' Another program is using it; set AAB_PORT to pick another port.');
+  }
+
+  async run(cmd, args = {}, timeout) {
+    await this.ensure();
+    if (this.hub) return this.runLocal(cmd, args, timeout);
+    try {
+      return await rpc(this.cfg, cmd, args, timeout);
+    } catch (err) {
+      if (!err.hubGone || !this.host) throw err;
+      await this.ensure(); // the process that owned the hub exited: take over
+      return this.runLocal(cmd, args, timeout);
+    }
+  }
+
+  async runLocal(cmd, args = {}, timeout) {
+    const hub = this.hub;
+    if (cmd === 'status') return hub.status();
+    if (cmd === 'pair') {
+      const link = pairLink(this.cfg);
+      return { link, page: `http://localhost:${this.cfg.port}/pair`, qr: await qrTerminal(link) };
+    }
+    if (cmd === 'ocr') return this.ocr(args);
+    if (cmd === 'grant_permissions') return this.grantPermissions();
+    if (cmd === 'send_files') return this.sendFiles(args.paths || []);
+    if (cmd === 'received_files') return hub.files.received(args.limit);
+    if (cmd === 'force_stop') return this.forceStop(args.package);
+    let r;
+    try {
+      r = await hub.call(cmd, args, timeout);
+    } catch (err) {
+      // Text the app draws but hides from accessibility (Uber's tab bar, payment row):
+      // find it in the screen pixels and tap there instead.
+      const t = cmd === 'tap' && typeof args.target === 'string' ? args.target.trim() : '';
+      if (!t || !/nothing on screen matches/.test(err.message) || /^#?\d+$|^\d+\s*,\s*\d+$|^[A-Za-z]{1,2}\d{1,3}$/.test(t)) throw err;
+      const lines = (await this.ocr({ idle: 0 })).lines || [];
+      const hit = findText(lines, t);
+      const tapAt = async (h) => ({ ...(await hub.call('tap', { ...args, target: `${h.x},${h.y}` }, timeout)), via: 'ocr', matched: h.text });
+      // exact / starts-with on screen beats a loose "contains" match in the element list
+      if (hit?.strong) r = await tapAt(hit);
+      else if (/closest in the app/.test(err.message)) r = await hub.call('tap', { ...args, loose: true }, timeout);
+      else if (hit) r = await tapAt(hit);
+      // only the system bar has it (e.g. Android's Home button): last resort
+      else if (/only the system bar/.test(err.message)) r = await hub.call('tap', { ...args, system: true }, timeout);
+      else throw new Error(`nothing on screen matches "${t}", not in the element list nor in the screen text (OCR).`);
+    }
+    if (r?.needsAdb) r = { ...r, ...(await this.viaAdb(r.needsAdb)), needsAdb: undefined };
+    if (cmd === 'screen' && !r.image && r.captureError) {
+      const png = await this.screencap();
+      if (png) {
+        try {
+          // the phone draws the numbers/grid on it, same as its own screenshots
+          Object.assign(r, await hub.call('annotate', { image: png, mode: args.mode, maxSide: args.maxSide }, 30000));
+        } catch (err) {
+          Object.assign(r, { image: png, mime: 'image/png', note: `Screenshot taken over USB without labels (${err.message}). Use coordinates "x,y" or element numbers from the list.` });
+        }
+        delete r.captureError;
+      }
+    }
+    if (ACTIONS.has(cmd) && args.after !== false) {
+      // wait for the screen to stop changing (page loads, animations), up to `settle` ms
+      await sleep(250);
+      const settle = args.settle ?? 2500;
+      r.outline = (await hub.call('elements', { idle: settle }, settle + 20000)).outline;
+    }
+    return r;
+  }
+
+  /** Send files from this computer to the phone: staged here, downloaded by the phone into Downloads/Agent Bridge. */
+  async sendFiles(paths) {
+    if (!paths.length) throw new Error('give at least one file');
+    const staged = this.hub.files.stage(paths);
+    const results = [];
+    for (const f of staged) {
+      // a minute, plus about 2 s per 10 MB for slow Wi-Fi
+      const r = await this.hub.call('receive_file', f, 60000 + Math.ceil(f.size / 5e6) * 1000);
+      this.log(`sent ${f.name} to the phone → ${r.saved}`);
+      results.push({ name: f.name, size: f.size, saved: r.saved });
+    }
+    return results;
+  }
+
+  /** Full-resolution screenshot over USB as base64 PNG, or null without adb. */
+  async screencap() {
+    const serial = await pickSerial(this.hub.current?.info?.model);
+    if (!serial) return null;
+    return (await adb(['exec-out', 'screencap', '-p'], { serial, binary: true, timeout: 20000 })).toString('base64');
+  }
+
+  /** Text in the screen pixels, read on the phone (ML Kit). Uses a USB screenshot when the phone can't capture. */
+  async ocr(args = {}) {
+    let r = await this.hub.call('ocr', args, 40000);
+    if (r.captureError) {
+      const png = await this.screencap();
+      if (!png) throw new Error(`Can't read the screen: ${r.captureError}. Connect USB, or allow screen capture in the app.`);
+      r = await this.hub.call('ocr', { ...args, image: png, idle: 0 }, 40000);
+    }
+    return r;
+  }
+
+  /** One-time permissions the user would otherwise switch on in Settings, granted over USB with adb. */
+  async grantPermissions() {
+    const serial = await pickSerial(this.hub.current?.info?.model);
+    if (!serial) throw new Error("Plug the phone in over USB (USB debugging on) to grant permissions, or switch them on in the phone's Settings.");
+    const sh = (...c) => adb(['shell', ...c], { serial });
+    const granted = [];
+    await sh('appops', 'set', APP_ID, 'WRITE_SETTINGS', 'allow').then(() => granted.push('modify system settings')).catch(() => {});
+    await sh('cmd', 'notification', 'allow_dnd', APP_ID).then(() => granted.push('do not disturb access')).catch(() => {});
+    await sh('pm', 'grant', APP_ID, 'android.permission.POST_NOTIFICATIONS').then(() => granted.push('notifications')).catch(() => {});
+    // Android 9 and older: save received files in Downloads/Agent Bridge
+    await sh('pm', 'grant', APP_ID, 'android.permission.WRITE_EXTERNAL_STORAGE').then(() => granted.push('storage')).catch(() => {});
+    return { granted, permissions: await this.hub.call('permissions', {}) };
+  }
+
+  async forceStop(pkg) {
+    if (!pkg || !/^[\w.]+$/.test(pkg)) throw new Error('give the app package, e.g. com.instagram.android (see `apps`)');
+    const serial = await pickSerial(this.hub.current?.info?.model);
+    if (!serial) throw new Error('Force-stopping an app needs the phone on USB.');
+    await adb(['shell', 'am', 'force-stop', pkg], { serial });
+    return { stopped: pkg };
+  }
+
+  /** The phone could not do it itself (old Android): do it through adb. */
+  async viaAdb(op) {
+    const serial = await pickSerial(this.hub.current?.info?.model);
+    if (!serial) throw new Error(`${op.reason} Connect the phone over USB with USB debugging on and it will be done through adb.`);
+    const sh = (...c) => adb(['shell', ...c.map(String)], { serial });
+    if (op.op === 'tap') await (op.long ? sh('input', 'swipe', op.x, op.y, op.x, op.y, 800) : sh('input', 'tap', op.x, op.y));
+    else if (op.op === 'swipe') await sh('input', 'swipe', op.x1, op.y1, op.x2, op.y2, op.ms || 300);
+    else if (op.op === 'key') await sh('input', 'keyevent', KEYCODES[op.key] ?? op.key);
+    else if (op.op === 'text') await sh('input', 'text', `'${String(op.text).replace(/'/g, `'\\''`).replace(/ /g, '%s')}'`);
+    else throw new Error('unknown adb fallback ' + op.op);
+    return { via: 'adb' };
+  }
+
+  close() { this.hub?.close(); }
+}