android-agent-bridge 0.0.0-stage → 0.1.1

package/server/cli.mjs

@@ -0,0 +1,361 @@
+#!/usr/bin/env node
+// android-agent-bridge (alias: phonectl)
+//   (no command)      MCP server, launched by AI agents
+//   start             run the bridge and show the pairing QR code
+//   usb               set up a USB-connected phone (install, permissions, pair)
+//   init              add the MCP server + agent guide to the current project
+//   status | screen | elements | tap | type | scroll | swipe | key | open | apps | wait
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { Bridge } from './bridge.mjs';
+import { loadConfig, resetToken, APP_ID } from './config.mjs';
+import { lanAddresses, pairLink, qrTerminal } from './hub.mjs';
+import { adb, devices, pickSerial } from './adb.mjs';
+import { fmtSize } from './files.mjs';
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const [cmd, ...rest] = process.argv.slice(2);
+
+function parseArgs(list) {
+  const pos = [], flags = {};
+  for (let i = 0; i < list.length; i++) {
+    const a = list[i];
+    if (!a.startsWith('--')) { pos.push(a); continue; }
+    const key = a.slice(2);
+    if (list[i + 1] != null && !list[i + 1].startsWith('--')) flags[key] = list[++i];
+    else flags[key] = true;
+  }
+  return { pos, flags };
+}
+
+const num = (v) => (v == null || v === true ? undefined : Number(v));
+const die = (msg) => { console.error(msg); process.exit(1); };
+
+const HELP = `android-agent-bridge — let AI agents use your Android phone
+
+Setup
+  start                      run the bridge and show the QR code to pair over Wi-Fi
+  usb                        set up a phone plugged in over USB (install app, permissions, pair)
+  init                       add the MCP server and agent guide to this project
+  pair [--reset]             show the QR code again (--reset: new secret, phones must re-scan)
+  (no command)               MCP server (what Claude Code / Cursor / Antigravity launch)
+
+Control (needs a running bridge: \`start\`, \`usb\` or an agent session)
+  status                     connected phone and what it can do
+  screen [--mode marks|grid|both|plain] [--cols 12] [--out file]
+                             screenshot with numbered elements (saved to a file) + element list
+  elements [--all] [--ocr]   element list only (text); --all also lists elements hidden under sheets,
+                             --ocr adds text read from the screen pixels
+  ocr                        text read from the screen pixels, with positions (finds what apps hide)
+  tap <target> [--long]      target: element "12", grid cell "C7", "x,y" or visible text
+                             (text not in the element list is found by OCR automatically)
+  type <text> [--into target] [--append] [--submit]
+  scroll <up|down|left|right> [--in target] [--amount 0.6]
+  swipe <from> <to> [--ms 300]
+  key <back|home|recents|notifications|quick_settings|enter|lock|power_dialog>
+  open <app> [--store]       open an app by name or package; --store: if not installed, show it in the Play Store
+  launch <app> [--store]     same as open
+  apps [filter]
+  current                    which app is in front
+  wait <text> [--timeout 10000]
+
+Device (direct commands, no navigating Settings)
+  volume [media|ring|notification|alarm|call|system] [get|up|down|mute|unmute|max|<level>|<n>%] [--show]
+  ringer [normal|vibrate|silent]
+  brightness [get|0-100|auto|manual]       needs "Modify system settings" once (permissions grant)
+  rotation [get|auto|portrait|landscape]   needs "Modify system settings" once
+  flashlight <on|off>
+  dnd [get|on|alarms|total|off]            Do Not Disturb; needs DND access once (permissions grant)
+  settings [page] [--app <package>]        open a settings page: wifi, bluetooth, display, sound, battery, apps, ...
+  url <link> [--package <app>]             open a web page or deep link (myapp://..., geo:, mailto:)
+  dial <number>                            open the dialer with the number filled in (never calls)
+  search <query>                           web search on the phone
+  store <app name> | --package <id>        Play Store page / search
+  battery                                  level, charging, temperature, power saver
+  wake                                     turn the screen on (a PIN lock stays locked)
+  clipboard [set <text>]                   read / set the phone clipboard
+  notifications [--limit 20] [--clear]     notifications seen since the service started
+  permissions [grant]                      what the app may do; grant: allow the one-time permissions over USB
+  stop <package>                           force-stop an app (USB)
+
+Transfer (Wi-Fi or USB)
+  send <file> [file...]                    send files to the phone (they land in Downloads/Agent Bridge)
+  received                                 files the phone sent to this computer, and where they are
+  drop                                     drag-and-drop page for sending files: http://localhost:8350/drop
+`;
+
+async function control() {
+  const { pos, flags } = parseArgs(rest);
+  const bridge = new Bridge({ host: false });
+  const run = (c, a, t) => bridge.run(c, a, t);
+  const outline = (r) => r.outline && console.log(r.outline);
+  const via = (r) => (r.via === 'adb' ? ' (through adb)' : '');
+  const chooser = async () => {
+    const c = await run('current_app');
+    if (c.package === 'android') console.log('Android is asking which app to use ("Complete action using"): tap one, e.g. `tap Phone`.');
+  };
+  switch (cmd) {
+    case 'status': {
+      const s = await run('status');
+      if (!s.phones.length) return console.log(`No phone connected. Pair at http://localhost:${s.port}/pair`);
+      for (const p of s.phones) console.log(`${p.manufacturer} ${p.model} — Android ${p.release} (API ${p.sdk}), ${p.screenW}x${p.screenH}, via ${p.via}, gestures: ${p.gestures}, screenshots: ${p.screenshot}`);
+      return;
+    }
+    case 'screen': {
+      const r = await run('screen', { mode: flags.mode, cols: num(flags.cols), maxSide: num(flags['max-side']) }, 30000);
+      if (r.image) {
+        const out = path.resolve(typeof flags.out === 'string' ? flags.out : 'phone-screen.' + (r.mime === 'image/png' ? 'png' : 'jpg'));
+        fs.writeFileSync(out, Buffer.from(r.image, 'base64'));
+        console.log('Screenshot: ' + out);
+      }
+      if (r.note || r.captureError) console.log(r.note || 'No screenshot: ' + r.captureError);
+      return outline(r);
+    }
+    case 'elements': {
+      outline(await run('elements', { all: !!flags.all }));
+      if (flags.ocr) console.log('\n' + (await run('ocr')).outline);
+      return;
+    }
+    case 'ocr': return console.log((await run('ocr', {}, 45000)).outline);
+    case 'tap': {
+      if (!pos[0]) die('usage: tap <target> [--long]');
+      const r = await run('tap', { target: pos.join(' '), long: !!flags.long });
+      console.log(`Tapped at ${r.x},${r.y}${r.via === 'ocr' ? ` (found "${r.matched}" by reading the screen)` : via(r)}`);
+      return outline(r);
+    }
+    case 'type': {
+      if (!pos.length) die('usage: type <text> [--into target] [--append] [--submit]');
+      const r = await run('type', { text: pos.join(' '), target: flags.into, append: !!flags.append, submit: !!flags.submit });
+      console.log('Typed' + via(r));
+      return outline(r);
+    }
+    case 'scroll': {
+      if (!pos[0]) die('usage: scroll <up|down|left|right> [--in target]');
+      const r = await run('scroll', { direction: pos[0], target: flags.in, amount: num(flags.amount) });
+      console.log('Scrolled ' + pos[0] + via(r));
+      return outline(r);
+    }
+    case 'swipe': {
+      if (pos.length < 2) die('usage: swipe <from> <to> [--ms 300]');
+      const r = await run('swipe', { from: pos[0], to: pos[1], ms: num(flags.ms) });
+      console.log('Swiped' + via(r));
+      return outline(r);
+    }
+    case 'key': {
+      if (!pos[0]) die('usage: key <name>');
+      const r = await run('key', { key: pos[0] });
+      console.log('Pressed ' + pos[0] + via(r));
+      return outline(r);
+    }
+    case 'open':
+    case 'launch': {
+      if (!pos.length) die('usage: open <app> [--store]');
+      const r = await run('open_app', { name: pos.join(' '), settle: 5000, store: !!flags.store });
+      console.log(r.installed === false ? `${pos.join(' ')} is not installed; opened the Play Store so you can install it` : `Opened ${r.label} (${r.package})`);
+      return outline(r);
+    }
+    case 'current': {
+      const r = await run('current_app');
+      return console.log(r.package ? `${r.label} (${r.package})` : 'No app in front');
+    }
+    case 'volume': {
+      const streams = ['media', 'ring', 'notification', 'alarm', 'call', 'system'];
+      const stream = streams.includes(pos[0]) ? pos.shift() : 'media';
+      const r = await run('volume', { stream, action: pos[0] || 'get', show: !!flags.show });
+      console.log(`${r.stream} volume ${r.level}/${r.max} · ringer ${r.ringer}`);
+      return console.log(Object.entries(r.all).map(([k, v]) => `  ${k.padEnd(13)}${v.level}/${v.max}`).join('\n'));
+    }
+    case 'ringer': { const r = await run('ringer', { mode: pos[0] || '' }); return console.log('Ringer: ' + r.ringer); }
+    case 'brightness': { const r = await run('brightness', { value: pos[0] || 'get' }); return console.log(`Brightness ${r.percent}%${r.auto ? ' (auto)' : ''}`); }
+    case 'rotation': { const r = await run('rotation', { value: pos[0] || 'get' }); return console.log(r.auto ? 'Rotation: auto' : `Rotation: locked ${r.locked}`); }
+    case 'flashlight':
+    case 'torch': { if (!pos[0]) die('usage: flashlight <on|off>'); const r = await run('torch', { state: pos[0] }); return console.log('Flashlight ' + r.flashlight); }
+    case 'dnd': { const r = await run('dnd', { state: pos[0] || 'get' }); return console.log('Do Not Disturb: ' + r.dnd); }
+    case 'settings': {
+      const app = typeof flags.app === 'string' ? flags.app : '';
+      const r = await run('settings_page', { page: pos[0] || (app ? '' : 'settings'), app });
+      return console.log('Opened ' + r.opened);
+    }
+    case 'url': { if (!pos[0]) die('usage: url <link>'); const r = await run('view_url', { url: pos[0], package: typeof flags.package === 'string' ? flags.package : '' }); console.log('Opened ' + r.opened); return chooser(); }
+    case 'dial': { if (!pos[0]) die('usage: dial <number>'); const r = await run('dial', { number: pos.join('') }); console.log(`Dialer open with ${r.dialer} (not calling)`); return chooser(); }
+    case 'search': { if (!pos.length) die('usage: search <query>'); const r = await run('web_search', { query: pos.join(' ') }); console.log('Searching for ' + r.searched); return chooser(); }
+    case 'store': { const r = await run('store', { query: pos.join(' '), package: typeof flags.package === 'string' ? flags.package : '' }); return console.log('Opened ' + r.opened); }
+    case 'battery': {
+      const r = await run('battery');
+      return console.log(`Battery ${r.percent}% · ${r.charging ? 'charging' : 'not charging'} (plugged: ${r.plugged}) · ${r.temperature_c}°C · power saver ${r.power_saver ? 'on' : 'off'} · screen ${r.screen_on ? 'on' : 'off'}`);
+    }
+    case 'wake': { await run('wake'); return console.log('Screen on (a PIN or pattern lock stays locked)'); }
+    case 'clipboard': {
+      const r = await run('clipboard', pos[0] === 'set' ? { set: pos.slice(1).join(' ') } : {});
+      return console.log(pos[0] === 'set' ? 'Clipboard set' : r.clipboard == null ? '(clipboard empty or not readable: Android 10+ hides it from background apps)' : r.clipboard);
+    }
+    case 'notifications': {
+      const r = await run('notifications', { limit: num(flags.limit) ?? 20, clear: !!flags.clear });
+      if (!r.notifications.length) return console.log('No notifications seen since the service started.');
+      return console.log(r.notifications.map((n) => `${new Date(n.time).toLocaleTimeString()}  ${n.app}  ${n.text}`).join('\n'));
+    }
+    case 'permissions': {
+      const r = await run(pos[0] === 'grant' ? 'grant_permissions' : 'permissions', {}, 30000);
+      if (r.granted) console.log('Granted over USB: ' + (r.granted.join(', ') || 'nothing'));
+      const p = r.permissions || r;
+      return console.log(Object.entries(p).map(([k, v]) => `  ${k.replace(/_/g, ' ').padEnd(24)}${v === true ? 'yes' : v === false ? 'NO' : v}`).join('\n'));
+    }
+    case 'send': {
+      if (!pos.length) die('usage: send <file> [file...]');
+      const files = pos.map((p) => path.resolve(p));
+      for (const f of files) if (!fs.existsSync(f) || !fs.statSync(f).isFile()) die(`not a file: ${f}`);
+      const r = await run('send_files', { paths: files }, 30 * 60 * 1000);
+      return console.log(r.map((x) => `Sent ${x.name} (${fmtSize(x.size)}) → phone: ${x.saved}`).join('\n'));
+    }
+    case 'received': {
+      const r = await run('received_files', { limit: num(flags.limit) ?? 20 });
+      console.log('Folder: ' + r.folder);
+      return console.log(r.files.length ? r.files.map((f) => `  ${new Date(f.time).toLocaleString()}  ${fmtSize(f.size).padStart(9)}  ${f.name}`).join('\n') : '  (nothing yet)');
+    }
+    case 'drop': return console.log(`Open http://localhost:${loadConfig().port}/drop in your browser to drag files to the phone.`);
+    case 'stop': { if (!pos[0]) die('usage: stop <package>'); const r = await run('force_stop', { package: pos[0] }); return console.log('Stopped ' + r.stopped); }
+    case 'apps': {
+      const r = await run('apps', { filter: pos.join(' ') || undefined });
+      return console.log(r.apps.map((x) => `${x.label} — ${x.package}`).join('\n'));
+    }
+    case 'wait': {
+      const timeout = num(flags.timeout) ?? 10000;
+      const r = await run('wait_text', { text: pos.join(' '), timeout }, timeout + 5000);
+      console.log(r.found ? 'Found' : 'Not found');
+      return outline(r);
+    }
+  }
+}
+
+async function start({ quiet = false } = {}) {
+  const bridge = new Bridge({ host: true, log: (m) => console.log(`[${new Date().toLocaleTimeString()}] ${m}`) });
+  await bridge.ensure();
+  const cfg = bridge.cfg;
+  const link = pairLink(cfg);
+  if (!bridge.hub) {
+    console.log(`A bridge is already running on port ${cfg.port}. Pairing page: http://localhost:${cfg.port}/pair`);
+    if (!quiet) process.exit(0);
+    return bridge;
+  }
+  if (quiet) return bridge;
+  console.log('\nScan with the Agent Bridge app (phone on the same Wi-Fi):\n');
+  console.log(await qrTerminal(link));
+  console.log(`Bigger QR code: http://localhost:${cfg.port}/pair`);
+  if (!lanAddresses().length) console.log('No Wi-Fi/LAN address found on this computer; use `usb` instead.');
+  console.log('Agents (MCP or CLI) on this computer now share this bridge. Ctrl+C to stop.\n');
+  return bridge;
+}
+
+function findApk() {
+  return [
+    path.join(here, '..', 'apk', 'agent-bridge.apk'),
+    path.join(here, '..', 'android', 'app', 'build', 'outputs', 'apk', 'release', 'app-release.apk'),
+    path.join(here, '..', 'android', 'app', 'build', 'outputs', 'apk', 'debug', 'app-debug.apk'),
+  ].find((f) => fs.existsSync(f));
+}
+
+async function usb() {
+  const { flags } = parseArgs(rest);
+  const list = await devices().catch((e) => die(e.message));
+  if (!list.length) {
+    die('No phone found over USB.\n1. Settings → About phone → tap "Build number" 7 times (developer mode).\n2. Settings → Developer options → turn on USB debugging.\n3. Plug the phone in and accept the "Allow USB debugging?" prompt.');
+  }
+  const serial = await pickSerial();
+  const sh = (...c) => adb(['shell', ...c], { serial });
+  const cfg = loadConfig();
+  const sdk = Number(await sh('getprop', 'ro.build.version.sdk'));
+  const model = await sh('getprop', 'ro.product.model');
+  console.log(`Phone: ${model} (API ${sdk}), serial ${serial}`);
+  if (sdk < 21) die('Android 5.0 (API 21) or newer is required.');
+
+  const installed = (await sh('pm', 'path', APP_ID).catch(() => '')).includes('package:');
+  if (!installed || flags.reinstall) {
+    const apk = typeof flags.apk === 'string' ? flags.apk : findApk();
+    if (!apk) die('The Agent Bridge app is not installed and no APK was found. Install it on the phone first (see README), or pass --apk <file>.');
+    console.log('Installing ' + path.basename(apk) + ' …');
+    await adb(['install', '-r', apk], { serial, timeout: 120000 });
+  }
+
+  // bridge first, so the phone connects the moment it is paired
+  const bridge = await start({ quiet: true });
+  await adb(['reverse', `tcp:${cfg.port}`, `tcp:${cfg.port}`], { serial });
+  console.log(`✔ USB tunnel on port ${cfg.port}`);
+
+  const comp = `${APP_ID}/${APP_ID}.AgentService`;
+  const cur = (await sh('settings', 'get', 'secure', 'enabled_accessibility_services')).trim();
+  if (!cur.includes(comp)) {
+    const next = cur && cur !== 'null' ? `${cur}:${comp}` : comp;
+    await sh('settings', 'put', 'secure', 'enabled_accessibility_services', next);
+    await sh('settings', 'put', 'secure', 'accessibility_enabled', '1');
+  }
+  console.log('✔ Accessibility service on');
+
+  const link = pairLink(cfg, ['127.0.0.1', ...lanAddresses()]);
+  await sh('am', 'start', '-a', 'android.intent.action.VIEW', '-d', `'${link}'`, APP_ID);
+  console.log('✔ Paired (USB first, Wi-Fi when unplugged)');
+  if (sdk < 24) console.log('• Android ' + sdk + ': taps by coordinate and grid go through adb, so keep USB plugged in for those.');
+  if (sdk < 30) console.log('• For screenshots over Wi-Fi tap "Allow screen capture" in the app (over USB they work anyway).');
+  if (!bridge.hub) process.exit(0);
+  console.log('\nBridge running. Agents (MCP or CLI) on this computer use it. Ctrl+C to stop.\n');
+}
+
+function writeMcpConfig(file) {
+  let cfg = {};
+  try { cfg = JSON.parse(fs.readFileSync(file, 'utf8')); } catch {}
+  cfg.mcpServers ||= {};
+  // run from a source checkout (not installed from npm): point at this copy
+  const local = !/node_modules|[\\/]_npx[\\/]/.test(here);
+  cfg.mcpServers.phone = local
+    ? { command: 'node', args: [path.join(here, 'cli.mjs')] }
+    : process.platform === 'win32'
+      ? { command: 'cmd', args: ['/c', 'npx', '-y', 'android-agent-bridge'] }
+      : { command: 'npx', args: ['-y', 'android-agent-bridge'] };
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, JSON.stringify(cfg, null, 2) + '\n');
+}
+
+function init() {
+  const root = process.cwd();
+  const done = [];
+  writeMcpConfig(path.join(root, '.mcp.json'));
+  done.push('.mcp.json                                 (Claude Code)');
+  if (fs.existsSync(path.join(root, '.cursor')) || rest.includes('--cursor')) {
+    writeMcpConfig(path.join(root, '.cursor', 'mcp.json'));
+    done.push('.cursor/mcp.json                          (Cursor)');
+  }
+  const skillSrc = path.join(here, '..', 'skill', 'SKILL.md');
+  const skillDst = path.join(root, '.claude', 'skills', 'phone-control', 'SKILL.md');
+  fs.mkdirSync(path.dirname(skillDst), { recursive: true });
+  fs.copyFileSync(skillSrc, skillDst);
+  done.push('.claude/skills/phone-control/SKILL.md     (how the agent uses the phone)');
+  const agents = path.join(root, 'AGENTS.md');
+  const guide = fs.readFileSync(skillSrc, 'utf8').replace(/^---[\s\S]*?---\n/, '');
+  const section = `<!-- phone-control:start -->\n${guide.trim()}\n<!-- phone-control:end -->\n`;
+  const existing = fs.existsSync(agents) ? fs.readFileSync(agents, 'utf8') : '';
+  fs.writeFileSync(agents, existing.includes('<!-- phone-control:start -->')
+    ? existing.replace(/<!-- phone-control:start -->[\s\S]*?<!-- phone-control:end -->\n?/, section)
+    : (existing ? existing.trimEnd() + '\n\n' : '') + section);
+  done.push('AGENTS.md (phone-control section)         (Antigravity, Cursor, others)');
+  console.log('\n✔ android-agent-bridge set up:\n  ' + done.join('\n  '));
+  console.log('\nNext: restart your agent, then pair the phone (`npx android-agent-bridge start` or `usb`).\n');
+}
+
+try {
+  if (!cmd || cmd === 'mcp') {
+    const { startServer } = await import('./mcp.mjs');
+    await startServer();
+  } else if (cmd === 'help' || cmd === '--help' || cmd === '-h') console.log(HELP);
+  else if (cmd === 'start') await start();
+  else if (cmd === 'usb') await usb();
+  else if (cmd === 'init') init();
+  else if (cmd === 'pair') {
+    const cfg = parseArgs(rest).flags.reset ? resetToken() : loadConfig();
+    const link = pairLink(cfg);
+    console.log(await qrTerminal(link));
+    console.log(link + `\n\nThe bridge must be running (\`start\`) for the phone to connect. Page: http://localhost:${cfg.port}/pair`);
+  } else if (['status', 'screen', 'elements', 'ocr', 'tap', 'type', 'scroll', 'swipe', 'key', 'open', 'launch', 'apps', 'current', 'wait', 'volume', 'ringer', 'brightness', 'rotation', 'flashlight', 'torch', 'dnd', 'settings', 'url', 'dial', 'search', 'store', 'battery', 'wake', 'clipboard', 'notifications', 'permissions', 'stop', 'send', 'received', 'drop'].includes(cmd)) await control();
+  else die(`Unknown command "${cmd}".\n\n` + HELP);
+} catch (err) {
+  die('Error: ' + err.message);
+}

package/server/config.mjs

@@ -0,0 +1,36 @@
+// Pairing secret and port, kept in ~/.android-agent-bridge/config.json so a
+// paired phone reconnects on its own after the computer restarts.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import crypto from 'node:crypto';
+
+export const CONFIG_DIR = process.env.AAB_HOME || path.join(os.homedir(), '.android-agent-bridge');
+const FILE = path.join(CONFIG_DIR, 'config.json');
+export const DEFAULT_PORT = Number(process.env.AAB_PORT) || 8350;
+export const APP_ID = 'io.github.rudrasamadhiya.agentbridge';
+
+function save(cfg) {
+  fs.mkdirSync(CONFIG_DIR, { recursive: true });
+  fs.writeFileSync(FILE, JSON.stringify(cfg, null, 2) + '\n', { mode: 0o600 });
+}
+
+export function loadConfig() {
+  let cfg = null;
+  try { cfg = JSON.parse(fs.readFileSync(FILE, 'utf8')); } catch {}
+  if (!cfg?.token) {
+    cfg = { token: crypto.randomBytes(16).toString('hex'), port: DEFAULT_PORT };
+    save(cfg);
+  }
+  if (process.env.AAB_PORT) cfg.port = DEFAULT_PORT;
+  cfg.port ||= DEFAULT_PORT;
+  return cfg;
+}
+
+/** New secret: every paired phone has to scan again. */
+export function resetToken() {
+  const cfg = loadConfig();
+  cfg.token = crypto.randomBytes(16).toString('hex');
+  save(cfg);
+  return cfg;
+}

package/server/droppage.mjs

@@ -0,0 +1,76 @@
+// The drag-and-drop page at http://localhost:<port>/drop: send files to the phone,
+// see what the phone has sent to this computer.
+export function dropPage() {
+  return `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
+<title>Agent Bridge Transfer</title>
+<style>
+:root{--bg:#0a0b0d;--card:#15171c;--card2:#1c1f25;--line:#262a31;--fg:#f2f4f7;--muted:#9aa3af;--faint:#6b7380;--acc:#3ddc97;--on:#06140e;--err:#f87171}
+@media (prefers-color-scheme:light){:root{--bg:#f6f7f9;--card:#fff;--card2:#f0f2f5;--line:#e3e6eb;--fg:#111418;--muted:#5b6370;--faint:#8a919c;--acc:#0f9d63;--on:#fff;--err:#c0392b}}
+*{box-sizing:border-box}
+body{margin:0;background:var(--bg);color:var(--fg);font:15px/1.5 ui-sans-serif,system-ui,-apple-system,"Segoe UI",sans-serif}
+main{max-width:720px;margin:0 auto;padding:32px 16px 64px}
+header{display:flex;align-items:center;gap:12px}
+.mark{width:36px;height:36px;border-radius:10px;background:var(--card);border:1px solid var(--line);display:grid;place-items:center;font:600 15px ui-monospace,Consolas,monospace;color:var(--acc)}
+h1{font-size:20px;margin:0}
+.sub{color:var(--muted);font-size:13px}
+#phone{margin-left:auto;font-size:13px;color:var(--muted);display:flex;align-items:center;gap:8px}
+#phone i{width:8px;height:8px;border-radius:50%;background:var(--faint)}
+#phone.on i{background:var(--acc);box-shadow:0 0 0 4px color-mix(in srgb,var(--acc) 25%,transparent)}
+.zone{display:block;margin-top:24px;border:1.5px dashed var(--line);border-radius:16px;background:var(--card);padding:48px 16px;text-align:center;cursor:pointer;transition:.15s}
+.zone.over{border-color:var(--acc);background:color-mix(in srgb,var(--acc) 8%,var(--card))}
+.zone b{display:block;font-size:17px}
+.zone span{color:var(--muted);font-size:13px}
+.btn{display:inline-block;margin-top:14px;background:var(--acc);color:var(--on);border:0;border-radius:10px;padding:9px 16px;font-weight:600;font-size:14px;cursor:pointer}
+h2{font-size:12px;letter-spacing:.08em;text-transform:uppercase;color:var(--faint);margin:32px 4px 10px}
+.list{background:var(--card);border:1px solid var(--line);border-radius:14px;overflow:hidden}
+.row{display:flex;align-items:center;gap:12px;padding:12px 14px;border-top:1px solid var(--line)}
+.row:first-child{border-top:0}
+.row .n{flex:1;min-width:0;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
+.row .m{color:var(--muted);font-size:13px;white-space:nowrap}
+.bar{height:3px;background:var(--card2);border-radius:2px;overflow:hidden;margin-top:6px}
+.bar i{display:block;height:100%;width:0;background:var(--acc);transition:width .2s}
+.empty{padding:16px;color:var(--muted);font-size:14px}
+.ok{color:var(--acc)}.bad{color:var(--err)}
+code{font:13px ui-monospace,Consolas,monospace;color:var(--muted);word-break:break-all}
+</style></head><body><main>
+<header><div class="mark">&gt;_</div><div><h1>Transfer</h1><div class="sub">Between this computer and your phone</div></div>
+<div id="phone"><i></i><span>Checking…</span></div></header>
+
+<label class="zone" id="zone"><input type="file" id="pick" multiple hidden>
+<b>Drop files to send to your phone</b><span>They land in Downloads / Agent Bridge on the phone</span><br><span class="btn">Choose files</span></label>
+
+<h2>Sending</h2><div class="list" id="out"><div class="empty">Nothing sent yet.</div></div>
+<h2>Received from the phone</h2><div class="list" id="in"><div class="empty">Loading…</div></div>
+<p class="sub" style="margin:10px 4px">Saved in <code id="folder"></code>. On the phone: Agent Bridge → Transfer → Send to computer, or Share → Agent Bridge from any app.</p>
+</main><script>
+const fmt=n=>n<1024?n+' B':n<1048576?(n/1024).toFixed(1)+' KB':n<1073741824?(n/1048576).toFixed(1)+' MB':(n/1073741824).toFixed(2)+' GB';
+const esc=s=>String(s).replace(/[&<>"]/g,c=>({'&':'&amp;','<':'&lt;','>':'&gt;','"':'&quot;'}[c]));
+const out=document.getElementById('out'),zone=document.getElementById('zone');
+function send(file){
+  if(out.querySelector('.empty'))out.innerHTML='';
+  const row=document.createElement('div');row.className='row';
+  row.innerHTML='<div class="n">'+esc(file.name)+'<div class="bar"><i></i></div></div><div class="m">'+fmt(file.size)+'</div>';
+  out.prepend(row);
+  const bar=row.querySelector('.bar i'),m=row.querySelector('.m');
+  const x=new XMLHttpRequest();x.open('POST','/files/drop?name='+encodeURIComponent(file.name));
+  x.upload.onprogress=e=>{if(e.lengthComputable)bar.style.width=(e.loaded/e.total*90)+'%'};
+  x.onload=()=>{let r={};try{r=JSON.parse(x.responseText)}catch{}
+    if(r.ok){bar.style.width='100%';m.innerHTML='<span class="ok">On phone</span>';m.title=r.result&&r.result.saved||''}
+    else{m.innerHTML='<span class="bad">'+esc(r.error||'Failed')+'</span>'}};
+  x.onerror=()=>{m.innerHTML='<span class="bad">Failed</span>'};
+  x.send(file);
+}
+const many=fs=>[...fs].forEach(send);
+document.getElementById('pick').onchange=e=>many(e.target.files);
+['dragenter','dragover'].forEach(t=>zone.addEventListener(t,e=>{e.preventDefault();zone.classList.add('over')}));
+['dragleave','drop'].forEach(t=>zone.addEventListener(t,e=>{e.preventDefault();zone.classList.remove('over')}));
+zone.addEventListener('drop',e=>many(e.dataTransfer.files));
+async function poll(){
+  try{const s=(await (await fetch('/status')).json()).result,p=s.phones[0],el=document.getElementById('phone');
+    el.className=p?'on':'';el.querySelector('span').textContent=p?(p.deviceName||p.model)+' · '+p.via:'No phone connected';}catch{}
+  try{const r=(await (await fetch('/files/received')).json()).result;document.getElementById('folder').textContent=r.folder;
+    document.getElementById('in').innerHTML=r.files.length?r.files.map(f=>'<div class="row"><div class="n">'+esc(f.name)+'</div><div class="m">'+fmt(f.size)+' · '+new Date(f.time).toLocaleTimeString()+'</div></div>').join(''):'<div class="empty">Nothing yet.</div>';}catch{}
+  setTimeout(poll,2000)}
+poll();
+</script></body></html>`;
+}

package/server/files.mjs

@@ -0,0 +1,119 @@
+// File transfer between this computer and the paired phone, over the bridge's own port.
+//   POST /files/in?name=…     phone → computer (token header). Saved in the received folder.
+//   GET  /files/out/<id>      computer → phone (token header). The phone downloads a staged file.
+//   POST /files/drop?name=…   drop page on this computer → staged and sent to the phone.
+//   GET  /files/received      what has arrived from the phone (this computer only).
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { pipeline } from 'node:stream/promises';
+
+export const RECEIVED_DIR = process.env.AAB_RECEIVED || path.join(os.homedir(), 'Downloads', 'Agent Bridge');
+const DROP_DIR = path.join(os.tmpdir(), 'agent-bridge-outbox');
+
+/** A name that is safe on every OS and does not overwrite an existing file. */
+export function uniquePath(dir, name) {
+  const clean = (path.basename(String(name || 'file')).replace(/[<>:"/\\|?*\x00-\x1f]/g, '_').trim() || 'file').slice(0, 180);
+  const ext = path.extname(clean);
+  const stem = clean.slice(0, clean.length - ext.length);
+  let p = path.join(dir, clean);
+  for (let i = 2; fs.existsSync(p); i++) p = path.join(dir, `${stem} (${i})${ext}`);
+  return p;
+}
+
+export class Files {
+  constructor({ log = () => {} } = {}) {
+    this.log = log;
+    this.staged = new Map(); // id -> { path, name, size, expires }
+    this.onDrop = null; // set by the bridge: (paths) => send them to the phone
+  }
+
+  /** Make files downloadable by the phone for a while; returns what to tell the phone. */
+  stage(paths) {
+    const now = Date.now();
+    for (const [id, f] of this.staged) if (f.expires < now) this.staged.delete(id);
+    return paths.map((p) => {
+      const st = fs.statSync(p);
+      if (!st.isFile()) throw new Error(`${p} is not a file`);
+      const id = crypto.randomBytes(9).toString('hex');
+      const f = { path: p, name: path.basename(p), size: st.size, expires: now + 30 * 60 * 1000 };
+      this.staged.set(id, f);
+      return { id, name: f.name, size: f.size };
+    });
+  }
+
+  received(limit = 30) {
+    if (!fs.existsSync(RECEIVED_DIR)) return { folder: RECEIVED_DIR, files: [] };
+    const files = fs.readdirSync(RECEIVED_DIR)
+      .map((name) => { const st = fs.statSync(path.join(RECEIVED_DIR, name)); return { name, size: st.size, time: st.mtimeMs, file: st.isFile() }; })
+      .filter((f) => f.file)
+      .sort((a, b) => b.time - a.time)
+      .slice(0, limit)
+      .map(({ file, ...f }) => f);
+    return { folder: RECEIVED_DIR, files };
+  }
+
+  /** Handles /files/* requests. authed: token header matched; local: request came from this computer. */
+  async handle(req, res, url, { authed, local }) {
+    const json = (code, body) => res.writeHead(code, { 'content-type': 'application/json' }).end(JSON.stringify(body));
+    const name = url.searchParams.get('name') || 'file';
+
+    if (req.method === 'POST' && url.pathname === '/files/in') {
+      if (!authed) return json(401, { ok: false, error: 'bad token' });
+      fs.mkdirSync(RECEIVED_DIR, { recursive: true });
+      const dest = uniquePath(RECEIVED_DIR, name);
+      const part = dest + '.part';
+      try {
+        await pipeline(req, fs.createWriteStream(part));
+        fs.renameSync(part, dest);
+      } catch (err) {
+        fs.rmSync(part, { force: true });
+        return json(500, { ok: false, error: err.message });
+      }
+      const size = fs.statSync(dest).size;
+      this.log(`received ${path.basename(dest)} (${fmtSize(size)}) from the phone → ${dest}`);
+      return json(200, { ok: true, path: dest, name: path.basename(dest), size });
+    }
+
+    const out = url.pathname.match(/^\/files\/out\/([0-9a-f]+)$/);
+    if (req.method === 'GET' && out) {
+      if (!authed) return json(401, { ok: false, error: 'bad token' });
+      const f = this.staged.get(out[1]);
+      if (!f || !fs.existsSync(f.path)) return json(404, { ok: false, error: 'not staged' });
+      res.writeHead(200, {
+        'content-type': 'application/octet-stream',
+        'content-length': f.size,
+        'content-disposition': `attachment; filename*=UTF-8''${encodeURIComponent(f.name)}`,
+      });
+      await pipeline(fs.createReadStream(f.path), res);
+      return;
+    }
+
+    if (req.method === 'POST' && url.pathname === '/files/drop') {
+      if (!local) return json(403, { ok: false, error: 'only reachable from this computer' });
+      fs.mkdirSync(DROP_DIR, { recursive: true });
+      const dest = uniquePath(DROP_DIR, name);
+      await pipeline(req, fs.createWriteStream(dest));
+      try {
+        const [result] = await this.onDrop([dest]);
+        return json(200, { ok: true, result });
+      } catch (err) {
+        return json(200, { ok: false, error: err.message });
+      }
+    }
+
+    if (req.method === 'GET' && url.pathname === '/files/received') {
+      if (!local) return json(403, { ok: false, error: 'only reachable from this computer' });
+      return json(200, { ok: true, result: this.received() });
+    }
+    json(404, { ok: false, error: 'not found' });
+  }
+}
+
+export function fmtSize(n) {
+  if (n < 1024) return `${n} B`;
+  if (n < 1024 ** 2) return `${(n / 1024).toFixed(1)} KB`;
+  if (n < 1024 ** 3) return `${(n / 1024 ** 2).toFixed(1)} MB`;
+  return `${(n / 1024 ** 3).toFixed(2)} GB`;
+}