Skip to content

An agentic browser harness: an AI side panel & orb in your own logged-in Chrome, Edge, Arc, Brave or even Firefox run by the agent/subscription you already use (Claude Code, Codex, Antigravity). Free, open source, no API key. Also an MCP server.

10.3 KB
Raw Blame
import { failure, success, type ActionResult } from '@/lib/actions/protocol';
import type { AndroidProblemCode, AndroidState, PhoneOpened } from '@/lib/phone/types';
import { androidSettings, readAgentConfig, type AndroidSettings } from '../agent/config';
import { log } from '../log';
import { locateAdb, startServer, type AdbFound } from './adb';
import { AdbServerError, adbServer, type AdbServer } from './adb-server';
import { parseDeviceList, type TrackedDevice } from './devices';
import { launchChrome, openChromeListing } from './launch';
import { FACTS_COMMAND, parseFacts, type PhoneFacts } from './phone-facts';
import { judge } from './readiness';
import { startRelay, type CdpRequest, type PhoneOwner } from './relay';

export interface Android {
  state(): Promise<AndroidState>;
  /** What is already known, without looking: null while nobody watches, so a status line never starts adb. */
  peek(): AndroidState | null;
  /**
   * A watcher hears the state as soon as it is known, then every change. The Bridge looks for phones
   * only while someone holds a watch, and the returned function lets go of it.
   */
  watch(listener: (state: AndroidState) => void): () => void;
  launch(serial: string, url?: string): Promise<ActionResult<AndroidState>>;
  /** A session with Chrome on the phone, owned by the browser that opened it; only that browser's commands reach it. */
  open(owner: PhoneOwner, serial: string): Promise<ActionResult<PhoneOpened>>;
  /** Answers the owner with a `cdpResult` itself, in the order Chrome sent it among the events. */
  command(owner: PhoneOwner, request: CdpRequest): Promise<void>;
  close(owner: PhoneOwner, serial: string): Promise<void>;
  /** The owner went away: its sessions end without telling it. */
  release(owner: PhoneOwner): Promise<void>;
  stop(): Promise<void>;
}

export interface AndroidDeps {
  settings(): AndroidSettings;
  locate(configured?: string): Promise<AdbFound | null>;
  startServer(path: string): Promise<boolean>;
  server: AdbServer;
  platform: NodeJS.Platform;
}

const REFRESH_MS = 5_000;
const FACTS_TIMEOUT_MS = 5_000;
const BROKEN_RECHECK_MS = 60_000;
const RETRACK_MS = 2_000;
/** A phone that did not answer, or is still starting, reads as one without Chrome, so `launch` acts only past these problems. */
const LAUNCHABLE: ReadonlySet<AndroidProblemCode> = new Set(['CHROME_MISSING', 'CHROME_NOT_RUNNING', 'SCREEN_OFF']);

export const ANDROID_OFF_STATE: AndroidState = judge({ enabled: false, platform: process.platform, devices: [] });

export function androidOff(): Android {
  return {
    state: async () => ANDROID_OFF_STATE,
    peek: () => ANDROID_OFF_STATE,
    watch: (listener) => {
      queueMicrotask(() => listener(ANDROID_OFF_STATE));
      return () => {};
    },
    launch: async () => switchedOff(),
    open: async () => switchedOff(),
    command: async (owner, request) => owner.send({ t: 'cdpResult', id: request.id, result: switchedOff() }),
    close: async () => {},
    release: async () => {},
    stop: async () => {},
  };
}

const switchedOff = () => failure('ANDROID_OFF', ANDROID_OFF_STATE.problem?.message ?? 'Android is switched off.');

export function liveAndroidDeps(): AndroidDeps {
  return {
    settings: () => androidSettings(readAgentConfig()),
    locate: (configured) => locateAdb({ configured }),
    startServer,
    server: adbServer(),
    platform: process.platform,
  };
}

interface Tracker {
  devices: TrackedDevice[] | null;
  stop(): void;
}

export function startAndroid(deps: AndroidDeps = liveAndroidDeps()): Android {
  const heard = new Map<(state: AndroidState) => void, string>();
  let latest: AndroidState | null = null;
  let located: { adb: AdbFound | null; configured?: string; at: number } | undefined;
  let tracker: Tracker | null = null;
  let ticker: ReturnType<typeof setInterval> | undefined;
  let retrack: ReturnType<typeof setTimeout> | undefined;
  let refreshing: Promise<AndroidState> | null = null;
  let again = false;
  let session: AndroidState['session'];
  const current = (): Promise<AndroidState> => (latest && tracker ? Promise.resolve(latest) : refresh());
  const relay = startRelay({
    server: deps.server,
    state: current,
    onSession: (next) => {
      session = next;
      if (latest) publish({ ...latest, session });
      void refresh();
    },
  });

  const watched = () => heard.size > 0;

  async function adbFor(settings: AndroidSettings): Promise<AdbFound | null> {
    const recheck =
      !located?.adb || located.configured !== settings.adb || (!!located.adb.broken && Date.now() - located.at > BROKEN_RECHECK_MS);
    if (recheck) {
      const adb = await deps.locate(settings.adb);
      if (adb && adb.path !== located?.adb?.path) log(`android: adb at ${adb.path} (${adb.broken ? `broken: ${adb.broken}` : adb.version})`);
      located = { adb, configured: settings.adb, at: Date.now() };
    }
    return located?.adb ?? null;
  }

  async function withServer<T>(path: string, call: () => Promise<T>): Promise<T> {
    try {
      return await call();
    } catch (error) {
      if (!(error instanceof AdbServerError) || error.code !== 'NO_SERVER') throw error;
      log(`android: no adb server is running; starting one with ${path}`);
      if (!(await deps.startServer(path))) throw new AdbServerError('NO_SERVER', `"${path} start-server" did not start adb's server`);
      return call();
    }
  }

  async function startTracking(path: string): Promise<void> {
    await withServer(path, () => deps.server.version());
    if (!watched()) return;
    const current: Tracker = { devices: null, stop: () => {} };
    tracker = current;
    current.stop = deps.server.track(
      (list) => {
        current.devices = parseDeviceList(list);
        if (tracker === current) void refresh();
      },
      (error) => {
        if (tracker !== current) return;
        log(`android: lost adb's device list (${error.message}); watching again in ${RETRACK_MS} ms`);
        tracker = null;
        retrack = setTimeout(() => void refresh(), RETRACK_MS);
      },
    );
  }

  function stopTracking(): void {
    clearTimeout(retrack);
    tracker?.stop();
    tracker = null;
  }

  const factsOf = (serial: string): Promise<PhoneFacts | null> =>
    deps.server
      .shell(serial, FACTS_COMMAND, FACTS_TIMEOUT_MS)
      .then(parseFacts)
      .catch(() => null);

  async function observe(): Promise<AndroidState> {
    const settings = deps.settings();
    const seen = { enabled: settings.enabled, platform: deps.platform, devices: [], session };
    if (!settings.enabled) {
      stopTracking();
      return judge(seen);
    }
    const adb = await adbFor(settings);
    if (!adb || adb.broken) {
      stopTracking();
      return judge({ ...seen, adb });
    }
    try {
      if (watched() && !tracker) await startTracking(adb.path);
      const listed = tracker?.devices ?? parseDeviceList(await withServer(adb.path, () => deps.server.devices()));
      const devices = await Promise.all(
        listed.map(async (device) => ({ device, facts: device.state === 'ready' ? await factsOf(device.serial) : null })),
      );
      return judge({ ...seen, adb, devices });
    } catch (error) {
      return judge({ ...seen, adb, serverError: error instanceof Error ? error.message : String(error) });
    }
  }

  function refresh(): Promise<AndroidState> {
    if (refreshing) {
      again = true;
      return refreshing;
    }
    const run = async (): Promise<AndroidState> => {
      try {
        let state: AndroidState;
        do {
          again = false;
          state = await observe();
          publish(state);
        } while (again);
        return state;
      } finally {
        refreshing = null;
      }
    };
    return (refreshing = run());
  }

  function publish(state: AndroidState): void {
    if (watched() && headline(state) !== (latest && headline(latest))) log(`android: ${headline(state)}`);
    latest = state;
    for (const listener of heard.keys()) deliver(listener, state);
  }

  function deliver(listener: (state: AndroidState) => void, state: AndroidState): void {
    const json = JSON.stringify(state);
    if (heard.get(listener) === json) return;
    heard.set(listener, json);
    listener(state);
  }

  return {
    state: current,
    peek: () => (watched() ? latest : null),

    watch(listener) {
      heard.set(listener, '');
      if (heard.size === 1) {
        ticker = setInterval(() => void refresh(), REFRESH_MS);
        ticker.unref();
      }
      if (latest && tracker) {
        const known = latest;
        queueMicrotask(() => heard.has(listener) && deliver(listener, known));
      } else void refresh();
      return () => {
        if (!heard.delete(listener) || watched()) return;
        clearInterval(ticker);
        stopTracking();
      };
    },

    async launch(serial, url) {
      const before = await refresh();
      const device = before.devices.find((each) => each.serial === serial);
      if (!device) {
        const problem = before.devices.length ? undefined : before.problem;
        return failure(problem?.code ?? 'NO_DEVICE', problem?.message ?? `No phone "${serial}" is connected.`);
      }
      if (device.state !== 'ready' || (device.problem && !LAUNCHABLE.has(device.problem.code))) {
        return failure(device.problem?.code ?? 'DEVICE_OFFLINE', device.problem?.message ?? 'The phone is not ready.');
      }
      try {
        if (!device.chrome.installed) await openChromeListing(deps.server, serial);
        else if (!device.chrome.debuggable || url) await launchChrome(deps.server, serial, url);
      } catch (error) {
        return failure('DEVICE_OFFLINE', `The phone did not open Chrome: ${error instanceof Error ? error.message : String(error)}`);
      }
      return success(await refresh());
    },

    open: (owner, serial) => relay.open(owner, serial),
    command: (owner, request) => relay.command(owner, request),
    close: (owner, serial) => relay.close(owner, serial),
    release: (owner) => relay.release(owner),

    async stop() {
      await relay.stop();
      heard.clear();
      clearInterval(ticker);
      stopTracking();
    },
  };
}

function headline(state: AndroidState): string {
  const ready = state.devices.find((device) => device.state === 'ready' && device.chrome.debuggable);
  return state.ready ? `ready (${ready?.serial})${state.problem ? `, ${state.problem.code}` : ''}` : (state.problem?.code ?? 'not ready');
}