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.

feat(android): the side panel gets an Android toggle whenever the Bridge sees a phone; it opens a phone session and a phone tab beside the current one, offers to open Chrome on the phone when it is closed, and ends when switched off or the tab closes

Shahriar6a110d4e40e8
diff --git a/src/extension/components/phone-toggle.tsx b/src/extension/components/phone-toggle.tsx
new file mode 100644
index 0000000..1e47be3
--- /dev/null
+++ b/src/extension/components/phone-toggle.tsx
@@ -0,0 +1,71 @@
+import { useEffect, useState } from 'react';
+import { Smartphone } from 'lucide-react';
+import { browser } from 'wxt/browser';
+import { ANDROID_PROTOCOL } from '@/lib/actions/protocol';
+import { isLive } from '@/lib/bridge/phone';
+import { askPhone, usePhoneSession } from '@/lib/bridge/phone-client';
+import { useDaemonState } from '@/lib/bridge/use-daemon-state';
+import type { AndroidState } from '@/lib/phone/types';
+import { cn } from '@/lib/utils';
+import { Button } from './ui/button';
+
+const ERROR_SHOWN_MS = 6_000;
+
+/** The first phone adb has a connection to; Chrome closed on it is handled once the session starts. */
+export const drivablePhone = (android: AndroidState | undefined) => android?.devices.find((device) => device.state === 'ready');
+
+export function PhoneToggle() {
+ const daemon = useDaemonState();
+ const session = usePhoneSession();
+ const [busy, setBusy] = useState(false);
+ const [error, setError] = useState<string>();
+
+ useEffect(() => {
+ if (!error) return;
+ const timer = setTimeout(() => setError(undefined), ERROR_SHOWN_MS);
+ return () => clearTimeout(timer);
+ }, [error]);
+
+ if (import.meta.env.FIREFOX) return null;
+ const android = daemon?.connected && (daemon.protocolVersion ?? 0) >= ANDROID_PROTOCOL ? daemon.android : undefined;
+ const on = isLive(session);
+ if (!on && !android?.devices.length) return null;
+
+ const phone = drivablePhone(android);
+ const blocked = !on && !phone;
+ const title = blocked ? (android?.devices[0]?.problem?.message ?? 'The phone is not ready.') : 'Drive Chrome on your Android phone';
+
+ const toggle = async () => {
+ setBusy(true);
+ setError(undefined);
+ const result = on
+ ? await askPhone({ op: 'phoneEnd' })
+ : await askPhone({ op: 'phoneStart', serial: phone!.serial, windowId: (await browser.windows.getCurrent()).id });
+ setBusy(false);
+ if (!result.ok) setError(result.error.message);
+ };
+
+ return (
+ <span className="relative">
+ <Button
+ variant={on ? 'subtle' : 'ghost'}
+ size="icon-sm"
+ title={title}
+ aria-label="Android"
+ aria-pressed={on}
+ disabled={busy || blocked}
+ onClick={() => void toggle()}
+ >
+ <Smartphone className={cn('size-3.5', busy && 'animate-pulse')} />
+ </Button>
+ {error && (
+ <span
+ role="status"
+ className="absolute top-full right-0 z-20 mt-1.5 w-56 rounded-lg border border-destructive/40 bg-surface px-2.5 py-1.5 text-[11.5px] text-ink shadow-lg"
+ >
+ {error}
+ </span>
+ )}
+ </span>
+ );
+}
diff --git a/src/extension/entrypoints/background.ts b/src/extension/entrypoints/background.ts
index b0ec3bb..7dfc0e8 100644
--- a/src/extension/entrypoints/background.ts
+++ b/src/extension/entrypoints/background.ts
@@ -22,6 +22,7 @@ import { serveHandsFree } from '@/lib/bridge/hands-free';
import { endHandsFree } from '@/lib/bridge/panel-view';
import { serveLaunchers } from '@/lib/bridge/launchers';
import { servePreferences } from '@/lib/bridge/preferences';
+import { endPhone, openChromeOnPhone, servePhone, startPhone } from '@/lib/bridge/phone';
import { isAgentKind } from '@/lib/agents/catalog';
import { isPreferenceChange } from '@/lib/settings/preferences';
import {
@@ -140,6 +141,24 @@ export default defineBackground(() => {
.catch((error) => sendResponse(failure('BRIDGE_ERROR', String(error))));
return true;
}
+ if (message.op === 'phoneStart' && typeof message.serial === 'string') {
+ startPhone(message.serial, typeof message.windowId === 'number' ? message.windowId : undefined)
+ .then(sendResponse)
+ .catch((error) => sendResponse(failure('BRIDGE_ERROR', String(error))));
+ return true;
+ }
+ if (message.op === 'phoneEnd') {
+ endPhone('closed')
+ .then(() => sendResponse(success(true)))
+ .catch((error) => sendResponse(failure('BRIDGE_ERROR', String(error))));
+ return true;
+ }
+ if (message.op === 'phoneOpenChrome') {
+ openChromeOnPhone()
+ .then(sendResponse)
+ .catch((error) => sendResponse(failure('BRIDGE_ERROR', String(error))));
+ return true;
+ }
if (message.op === 'tasks' || message.op === 'pauseTasks') {
taskOp(message.op === 'tasks' ? { t: 'tasks' } : { t: 'pauseTasks', paused: message.paused === true })
.then(sendResponse)
@@ -181,7 +200,7 @@ export default defineBackground(() => {
sendResponse(
failure(
'INVALID_REQUEST',
- 'Expected {op:"describe"|"invoke"|"saveSkill"|"removeSkill"|"nameSession"|"recordEvents"|"recordingState"|"analyzeRecording"|"monitorSample"|"monitorState"|"listSkills"|"agentState"|"setAgent"|"setAgentModel"|"grantAgent"|"preferences"|"setPreference"|"tasks"|"saveTask"|"deleteTask"|"runTaskNow"|"pauseTasks"|"pair"|"panelOpened"|"disconnect"}',
+ 'Expected {op:"describe"|"invoke"|"saveSkill"|"removeSkill"|"nameSession"|"recordEvents"|"recordingState"|"analyzeRecording"|"monitorSample"|"monitorState"|"listSkills"|"agentState"|"setAgent"|"setAgentModel"|"grantAgent"|"preferences"|"setPreference"|"tasks"|"saveTask"|"deleteTask"|"runTaskNow"|"pauseTasks"|"pair"|"panelOpened"|"disconnect"|"phoneStart"|"phoneEnd"|"phoneOpenChrome"}',
),
);
return;
@@ -214,6 +233,7 @@ export default defineBackground(() => {
serveToast();
serveHandsFree();
servePreferences();
+ servePhone();
void syncRail();
onWelcome(() => {
diff --git a/src/extension/entrypoints/phone/App.tsx b/src/extension/entrypoints/phone/App.tsx
new file mode 100644
index 0000000..bc4f604
--- /dev/null
+++ b/src/extension/entrypoints/phone/App.tsx
@@ -0,0 +1,85 @@
+import { useEffect, useState } from 'react';
+import { browser } from 'wxt/browser';
+import { Smartphone, Unplug } from 'lucide-react';
+import { Wordmark } from '@/extension/components/brand';
+import { Button } from '@/extension/components/ui/button';
+import { askPhone, usePhoneSession } from '@/lib/bridge/phone-client';
+import type { PhoneEndReason, PhoneSession } from '@/lib/bridge/phone';
+
+const ENDED: Record<PhoneEndReason, string> = {
+ unplugged: 'The phone was disconnected.',
+ 'chrome-exited': 'Chrome closed on the phone.',
+ 'bridge-stopping': 'Browsentic Bridge stopped.',
+ 'bridge-gone': 'The link to Browsentic Bridge went down.',
+ closed: 'Android was switched off.',
+};
+
+async function closeThisTab() {
+ const tab = await browser.tabs.getCurrent();
+ if (tab?.id != null) await browser.tabs.remove(tab.id);
+}
+
+function describe(session: PhoneSession | null): { title: string; body: string } {
+ const phone = session?.model ?? 'your phone';
+ if (!session) return { title: 'Android is off', body: 'Switch on Android in the Browsentic side panel to show your phone here.' };
+ if (session.ended) return { title: `${phone} is not connected`, body: ENDED[session.ended.reason] };
+ if (session.waitingForChrome) return { title: 'Open Chrome on your phone', body: `Browsentic needs Chrome running on ${phone} to show and drive it.` };
+ return { title: `${phone} is connected`, body: `${session.targets.length} tab${session.targets.length === 1 ? '' : 's'} open in Chrome on the phone.` };
+}
+
+export default function App() {
+ const session = usePhoneSession();
+ const [busy, setBusy] = useState(false);
+ const [error, setError] = useState<string>();
+ const { title, body } = describe(session);
+
+ useEffect(() => {
+ document.title = `${session?.model ?? 'Android'} · Browsentic`;
+ }, [session?.model]);
+
+ const act = async (request: Parameters<typeof askPhone>[0]) => {
+ setBusy(true);
+ setError(undefined);
+ const result = await askPhone(request);
+ setBusy(false);
+ if (!result.ok) setError(result.error.message);
+ };
+
+ return (
+ <div className="dot-grid flex min-h-screen items-center justify-center p-6">
+ <main className="panel-card flex w-full max-w-sm flex-col items-center gap-4 p-8 text-center">
+ <Wordmark />
+ <span className="glow-brand flex size-16 items-center justify-center rounded-full border border-brand/50 bg-brand/10 text-brand">
+ {session?.ended ? <Unplug className="size-7" /> : <Smartphone className="size-7" />}
+ </span>
+ <h1 className="text-base font-medium">{title}</h1>
+ <p className="text-xs leading-relaxed text-ink-dim">{body}</p>
+ {session && !session.ended && session.targets.length > 0 && (
+ <ul className="w-full space-y-1 text-left text-xs text-ink-dim">
+ {session.targets.map((target) => (
+ <li key={target.targetId} className="truncate">
+ {target.title || target.url}
+ </li>
+ ))}
+ </ul>
+ )}
+ {session && !session.ended && session.waitingForChrome && (
+ <Button size="sm" disabled={busy} onClick={() => void act({ op: 'phoneOpenChrome' })}>
+ Open Chrome on the phone
+ </Button>
+ )}
+ {session?.ended && (
+ <div className="flex gap-2">
+ <Button size="sm" disabled={busy} onClick={() => void act({ op: 'phoneStart', serial: session.serial, windowId: session.windowId })}>
+ Reconnect
+ </Button>
+ <Button size="sm" variant="outline" onClick={() => void closeThisTab()}>
+ Close tab
+ </Button>
+ </div>
+ )}
+ {error && <p className="text-xs text-destructive">{error}</p>}
+ </main>
+ </div>
+ );
+}
diff --git a/src/extension/entrypoints/phone/index.html b/src/extension/entrypoints/phone/index.html
new file mode 100644
index 0000000..f96f013
--- /dev/null
+++ b/src/extension/entrypoints/phone/index.html
@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en" data-theme="ember" style="background-color: #1a1512">
+ <head>
+ <meta charset="UTF-8" />
+ <meta name="color-scheme" content="dark" />
+ <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+ <title>Android · Browsentic</title>
+ </head>
+ <body>
+ <div id="root"></div>
+ <script type="module" src="./main.tsx"></script>
+ </body>
+</html>
diff --git a/src/extension/entrypoints/phone/main.tsx b/src/extension/entrypoints/phone/main.tsx
new file mode 100644
index 0000000..0026177
--- /dev/null
+++ b/src/extension/entrypoints/phone/main.tsx
@@ -0,0 +1,13 @@
+import React from 'react';
+import ReactDOM from 'react-dom/client';
+import App from './App';
+import { mountTheme } from '@/lib/bridge/theme';
+import '@/extension/assets/globals.css';
+
+mountTheme();
+
+ReactDOM.createRoot(document.getElementById('root')!).render(
+ <React.StrictMode>
+ <App />
+ </React.StrictMode>,
+);
diff --git a/src/extension/entrypoints/sidepanel/App.tsx b/src/extension/entrypoints/sidepanel/App.tsx
index 3a78724..c76a702 100644
--- a/src/extension/entrypoints/sidepanel/App.tsx
+++ b/src/extension/entrypoints/sidepanel/App.tsx
@@ -16,6 +16,7 @@ import { DropMask } from '@/extension/components/drop-mask';
import { Greeting } from '@/extension/components/greeting';
import { MonitorBar } from '@/extension/components/monitor-bar';
import { PanelNav, type PanelTab } from '@/extension/components/panel-nav';
+import { PhoneToggle } from '@/extension/components/phone-toggle';
import { RecordingBar } from '@/extension/components/recording-bar';
import { RecordingPanel } from '@/extension/components/recording-panel';
import { RunTimeline } from '@/extension/components/run-timeline';
@@ -323,6 +324,7 @@ export default function App() {
>
<SquarePen className="size-3.5" />
</Button>
+ <PhoneToggle />
{handsFree && (
<Button
variant="ghost"
diff --git a/src/lib/actions/protocol.ts b/src/lib/actions/protocol.ts
index 3ddf475..44e2117 100644
--- a/src/lib/actions/protocol.ts
+++ b/src/lib/actions/protocol.ts
@@ -64,7 +64,10 @@ export type BridgeRequest =
| { channel: typeof BRIDGE_CHANNEL; op: 'saveTask'; task: unknown }
| { channel: typeof BRIDGE_CHANNEL; op: 'deleteTask'; taskId: string }
| { channel: typeof BRIDGE_CHANNEL; op: 'runTaskNow'; taskId: string }
- | { channel: typeof BRIDGE_CHANNEL; op: 'pauseTasks'; paused: boolean };
+ | { channel: typeof BRIDGE_CHANNEL; op: 'pauseTasks'; paused: boolean }
+ | { channel: typeof BRIDGE_CHANNEL; op: 'phoneStart'; serial: string; windowId?: number }
+ | { channel: typeof BRIDGE_CHANNEL; op: 'phoneEnd' }
+ | { channel: typeof BRIDGE_CHANNEL; op: 'phoneOpenChrome' };
export type ActionResult<T = unknown> =
| { ok: true; data: T }
diff --git a/src/lib/bridge/phone-client.ts b/src/lib/bridge/phone-client.ts
new file mode 100644
index 0000000..417301f
--- /dev/null
+++ b/src/lib/bridge/phone-client.ts
@@ -0,0 +1,32 @@
+import { useEffect, useState } from 'react';
+import { browser } from 'wxt/browser';
+import { BRIDGE_CHANNEL, failure, type ActionResult } from '@/lib/actions/protocol';
+import { PHONE_KEY, readPhone, type PhoneSession } from './phone';
+
+export type PhoneRequest = { op: 'phoneStart'; serial: string; windowId?: number } | { op: 'phoneEnd' } | { op: 'phoneOpenChrome' };
+
+export async function askPhone<T = PhoneSession>(request: PhoneRequest): Promise<ActionResult<T>> {
+ const result = (await browser.runtime
+ .sendMessage({ channel: BRIDGE_CHANNEL, ...request })
+ .catch(() => null)) as ActionResult<T> | null;
+ return result ?? failure('BRIDGE_ERROR', 'The extension did not answer — reload it and try again.');
+}
+
+export function usePhoneSession(): PhoneSession | null {
+ const [session, setSession] = useState<PhoneSession | null>(null);
+
+ useEffect(() => {
+ let current = true;
+ void readPhone().then((stored) => current && setSession(stored));
+ const listener = (changes: Record<string, { newValue?: unknown }>) => {
+ if (PHONE_KEY in changes) setSession((changes[PHONE_KEY].newValue as PhoneSession | undefined) ?? null);
+ };
+ browser.storage.session.onChanged.addListener(listener);
+ return () => {
+ current = false;
+ browser.storage.session.onChanged.removeListener(listener);
+ };
+ }, []);
+
+ return session;
+}
diff --git a/src/lib/bridge/phone.test.ts b/src/lib/bridge/phone.test.ts
new file mode 100644
index 0000000..41f35cd
--- /dev/null
+++ b/src/lib/bridge/phone.test.ts
@@ -0,0 +1,139 @@
+import { beforeEach, describe, expect, test, vi } from 'vitest';
+import { fakeBrowser } from 'wxt/testing';
+import { failure, success } from '@/lib/actions/protocol';
+import type { PhoneClosedReason, PhoneOpened } from '@/lib/phone/types';
+
+const socket = vi.hoisted(() => ({
+ openPhone: vi.fn(),
+ closePhone: vi.fn(),
+ launchPhoneChrome: vi.fn(),
+ daemonClosed: [] as (() => void)[],
+ phoneClosed: [] as ((serial: string, reason: PhoneClosedReason) => void)[],
+}));
+
+vi.mock('./socket', () => ({
+ DAEMON_STATE_KEY: 'browsentic/daemon',
+ openPhone: socket.openPhone,
+ closePhone: socket.closePhone,
+ launchPhoneChrome: socket.launchPhoneChrome,
+ onDaemonClosed: (listener: () => void) => socket.daemonClosed.push(listener),
+ onPhoneClosed: (listener: (serial: string, reason: PhoneClosedReason) => void) => socket.phoneClosed.push(listener),
+}));
+
+const { endPhone, openChromeOnPhone, readPhone, servePhone, startPhone } = await import('./phone');
+
+const SERIAL = 'emulator-5554';
+const OPENED: PhoneOpened = {
+ device: { serial: SERIAL, transport: 'usb', state: 'ready', model: 'Pixel 8', chrome: { installed: true, running: true, debuggable: true } },
+ targets: [{ targetId: 'A'.repeat(32), url: 'https://example.com/', title: 'Example' }],
+ browserVersion: 'Chrome/150.0.7871.186',
+};
+
+let notify: ReturnType<typeof vi.spyOn>;
+
+beforeEach(async () => {
+ fakeBrowser.reset();
+ socket.daemonClosed.length = 0;
+ socket.phoneClosed.length = 0;
+ socket.openPhone.mockReset().mockResolvedValue(success(OPENED));
+ socket.closePhone.mockReset();
+ socket.launchPhoneChrome.mockReset().mockResolvedValue(success({}));
+ notify = vi.spyOn(fakeBrowser.notifications, 'create').mockResolvedValue('');
+ vi.spyOn(fakeBrowser.notifications, 'clear').mockResolvedValue(true);
+ vi.spyOn(fakeBrowser.runtime, 'getManifest').mockReturnValue({ icons: { 128: 'icon/128.png' } } as never);
+ await fakeBrowser.tabs.create({ url: 'https://news.example/', active: true });
+ servePhone();
+});
+
+const tabs = () => fakeBrowser.tabs.query({});
+const settle = () => new Promise((resolve) => setTimeout(resolve, 10));
+
+describe('the phone session', () => {
+ test('starts with a mirror tab beside the one the user is on, holding the phone’s tabs', async () => {
+ const started = await startPhone(SERIAL);
+ expect(started.ok).toBe(true);
+ const session = await readPhone();
+ expect(session).toMatchObject({ serial: SERIAL, model: 'Pixel 8', targets: OPENED.targets, activeTargetId: OPENED.targets[0].targetId, waitingForChrome: false });
+ const mirror = await fakeBrowser.tabs.get(session!.mirrorTabId);
+ expect(mirror.url).toMatch(/phone\.html$/);
+ expect(notify).not.toHaveBeenCalled();
+ });
+
+ test('a second start shows the mirror already open, and asks the Bridge nothing', async () => {
+ await startPhone(SERIAL);
+ const first = await readPhone();
+ await startPhone(SERIAL);
+ expect(socket.openPhone).toHaveBeenCalledTimes(1);
+ expect((await readPhone())?.mirrorTabId).toBe(first?.mirrorTabId);
+ expect((await tabs()).filter((tab) => tab.url?.endsWith('phone.html'))).toHaveLength(1);
+ });
+
+ test('turning it off closes the session and its mirror', async () => {
+ await startPhone(SERIAL);
+ const { mirrorTabId } = (await readPhone())!;
+ await endPhone('closed');
+ expect(socket.closePhone).toHaveBeenCalledWith(SERIAL);
+ expect(await readPhone()).toBeNull();
+ expect((await tabs()).some((tab) => tab.id === mirrorTabId)).toBe(false);
+ });
+
+ test('closing the mirror tab turns it off', async () => {
+ await startPhone(SERIAL);
+ const { mirrorTabId, windowId } = (await readPhone())!;
+ await fakeBrowser.tabs.onRemoved.trigger(mirrorTabId, { windowId, isWindowClosing: false });
+ await settle();
+ expect(await readPhone()).toBeNull();
+ expect(socket.closePhone).toHaveBeenCalledWith(SERIAL);
+ });
+
+ test('the phone going away ends it but keeps the mirror, to say why; Reconnect reuses that tab', async () => {
+ await startPhone(SERIAL);
+ const { mirrorTabId } = (await readPhone())!;
+ socket.phoneClosed.forEach((listener) => listener(SERIAL, 'unplugged'));
+ await settle();
+ expect((await readPhone())?.ended?.reason).toBe('unplugged');
+ expect((await fakeBrowser.tabs.get(mirrorTabId)).id).toBe(mirrorTabId);
+ expect(socket.closePhone).not.toHaveBeenCalled();
+
+ await startPhone(SERIAL);
+ const reopened = await readPhone();
+ expect([reopened?.mirrorTabId, reopened?.ended]).toEqual([mirrorTabId, undefined]);
+ });
+
+ test('the Bridge going away ends it the same way', async () => {
+ await startPhone(SERIAL);
+ socket.daemonClosed.forEach((listener) => listener());
+ await settle();
+ expect((await readPhone())?.ended?.reason).toBe('bridge-gone');
+ });
+
+ test('another phone’s close leaves this session alone', async () => {
+ await startPhone(SERIAL);
+ socket.phoneClosed.forEach((listener) => listener('R5CT1234567', 'unplugged'));
+ await settle();
+ expect((await readPhone())?.ended).toBeUndefined();
+ });
+
+ test('Chrome closed on the phone opens the mirror anyway, once, with a notification that can open it', async () => {
+ socket.openPhone.mockResolvedValueOnce(failure('CHROME_NOT_RUNNING', 'Chrome is not open on the phone.'));
+ await fakeBrowser.storage.session.set({ 'browsentic/daemon': { android: { devices: [{ serial: SERIAL, model: 'Pixel 8' }] } } });
+ expect((await startPhone(SERIAL)).ok).toBe(true);
+ expect(await readPhone()).toMatchObject({ waitingForChrome: true, targets: [] });
+ expect(notify).toHaveBeenCalledWith(
+ 'browsentic/phone-chrome',
+ expect.objectContaining({ title: 'Open Chrome on your phone', message: 'Browsentic needs Chrome running on Pixel 8 to show and drive it.', buttons: [{ title: 'Open Chrome' }] }),
+ );
+
+ expect((await openChromeOnPhone()).ok).toBe(true);
+ expect(socket.launchPhoneChrome).toHaveBeenCalledWith(SERIAL);
+ expect(await readPhone()).toMatchObject({ waitingForChrome: false, targets: OPENED.targets });
+ expect(notify).toHaveBeenCalledTimes(1);
+ });
+
+ test('any other refusal opens nothing and says why', async () => {
+ socket.openPhone.mockResolvedValueOnce(failure('NOT_OWNER', 'Another browser is driving this phone.'));
+ expect(await startPhone(SERIAL)).toMatchObject({ ok: false, error: { code: 'NOT_OWNER' } });
+ expect(await readPhone()).toBeNull();
+ expect((await tabs()).some((tab) => tab.url?.endsWith('phone.html'))).toBe(false);
+ });
+});
diff --git a/src/lib/bridge/phone.ts b/src/lib/bridge/phone.ts
new file mode 100644
index 0000000..9858229
--- /dev/null
+++ b/src/lib/bridge/phone.ts
@@ -0,0 +1,186 @@
+import { browser } from 'wxt/browser';
+import { failure, success, type ActionResult } from '@/lib/actions/protocol';
+import type { PhoneClosedReason, PhoneOpened, PhoneTarget } from '@/lib/phone/types';
+import { DAEMON_STATE_KEY, closePhone, launchPhoneChrome, onDaemonClosed, onPhoneClosed, openPhone, type DaemonState } from './socket';
+
+export const PHONE_KEY = 'browsentic/phone';
+export const PHONE_PAGE = '/phone.html';
+const NOTIFICATION_ID = 'browsentic/phone-chrome';
+
+export type PhoneEndReason = PhoneClosedReason | 'bridge-gone';
+
+/**
+ * The one phone session, while it is on. Session storage on purpose: a browser that restarts comes
+ * back without a phone session, as it does without hands-free mode.
+ */
+export interface PhoneSession {
+ serial: string;
+ model?: string;
+ mirrorTabId: number;
+ windowId: number;
+ openedAt: number;
+ targets: PhoneTarget[];
+ activeTargetId?: string;
+ /** Chrome was not open on the phone; the mirror waits, and the notification offers to open it. */
+ waitingForChrome?: boolean;
+ /** The session is over but its mirror tab is still open, to say why and offer to reconnect. */
+ ended?: { reason: PhoneEndReason; at: number };
+}
+
+export const isLive = (session: PhoneSession | null | undefined): boolean => !!session && !session.ended;
+
+let queue: Promise<unknown> = Promise.resolve();
+
+function locked<T>(work: () => Promise<T>): Promise<T> {
+ const run = queue.then(work, work);
+ queue = run.catch(() => undefined);
+ return run;
+}
+
+export async function readPhone(): Promise<PhoneSession | null> {
+ const stored = await browser.storage.session.get(PHONE_KEY);
+ return (stored[PHONE_KEY] as PhoneSession | undefined) ?? null;
+}
+
+const writePhone = (session: PhoneSession | null): Promise<void> =>
+ session ? browser.storage.session.set({ [PHONE_KEY]: session }) : browser.storage.session.remove(PHONE_KEY);
+
+const opening = (opened: ActionResult<PhoneOpened>) =>
+ opened.ok
+ ? { targets: opened.data.targets, activeTargetId: opened.data.targets[0]?.targetId, waitingForChrome: false }
+ : { targets: [], activeTargetId: undefined, waitingForChrome: true };
+
+async function modelOf(serial: string): Promise<string | undefined> {
+ const stored = await browser.storage.session.get(DAEMON_STATE_KEY);
+ return (stored[DAEMON_STATE_KEY] as DaemonState | undefined)?.android?.devices.find((device) => device.serial === serial)?.model;
+}
+
+/** Starts the session and opens its mirror beside the tab the user is on. A second start shows the mirror already open. */
+export function startPhone(serial: string, windowId?: number): Promise<ActionResult<PhoneSession>> {
+ return locked(async () => {
+ const held = await readPhone();
+ if (held && !held.ended) {
+ await showTab(held.mirrorTabId, held.windowId);
+ return success(held);
+ }
+
+ const opened = await openPhone(serial);
+ if (!opened.ok && opened.error.code !== 'CHROME_NOT_RUNNING') return opened;
+
+ const reusable = held && (await tabExists(held.mirrorTabId)) ? held : null;
+ const mirror = reusable ? await showTab(reusable.mirrorTabId, reusable.windowId) : await openMirror(windowId);
+ if (!mirror?.id) {
+ if (opened.ok) closePhone(serial);
+ return failure('BRIDGE_ERROR', 'The phone tab could not be opened.');
+ }
+ const session: PhoneSession = {
+ serial,
+ mirrorTabId: mirror.id,
+ windowId: mirror.windowId ?? windowId ?? browser.windows.WINDOW_ID_CURRENT,
+ openedAt: Date.now(),
+ ...opening(opened),
+ model: (opened.ok ? opened.data.device.model : undefined) ?? (await modelOf(serial)),
+ };
+ await writePhone(session);
+ if (session.waitingForChrome) await askToOpenChrome(session);
+ return success(session);
+ });
+}
+
+/** Ends the session. Turned off or closed by the user, its mirror goes too; ended by the phone or the Bridge, the mirror stays to say why. */
+export function endPhone(reason: PhoneEndReason): Promise<void> {
+ return locked(async () => {
+ const held = await readPhone();
+ if (!held) return;
+ if (reason === 'closed') {
+ if (!held.ended) closePhone(held.serial);
+ await writePhone(null);
+ await clearNotification();
+ if (await tabExists(held.mirrorTabId)) await browser.tabs.remove(held.mirrorTabId).catch(() => undefined);
+ return;
+ }
+ if (held.ended) return;
+ await writePhone({ ...held, ended: { reason, at: Date.now() } });
+ });
+}
+
+/** Asks Chrome on the phone to open, then tries the session again: what the notification's button and the mirror's button do. */
+export function openChromeOnPhone(): Promise<ActionResult<PhoneSession>> {
+ return locked(async () => {
+ const held = await readPhone();
+ if (!held || held.ended) return failure('PHONE_GONE', 'Android is off. Switch it on in the side panel.');
+ const launched = await launchPhoneChrome(held.serial);
+ if (!launched.ok) return launched;
+ const opened = await openPhone(held.serial);
+ const session = { ...held, ...opening(opened) };
+ await writePhone(session);
+ if (!session.waitingForChrome) await clearNotification();
+ return success(session);
+ });
+}
+
+export function servePhone(): void {
+ browser.tabs.onRemoved.addListener((tabId) => {
+ void readPhone().then((held) => {
+ if (held?.mirrorTabId === tabId) void endPhone('closed');
+ });
+ });
+ onPhoneClosed((serial, reason) => {
+ void readPhone().then((held) => {
+ if (held?.serial === serial) void endPhone(reason);
+ });
+ });
+ onDaemonClosed(() => void endPhone('bridge-gone'));
+ browser.notifications?.onClicked.addListener((notificationId) => {
+ if (notificationId !== NOTIFICATION_ID) return;
+ void readPhone().then((held) => held && showTab(held.mirrorTabId, held.windowId));
+ });
+ browser.notifications?.onButtonClicked?.addListener((notificationId) => {
+ if (notificationId === NOTIFICATION_ID) void openChromeOnPhone();
+ });
+}
+
+async function openMirror(windowId?: number) {
+ const [current] = await browser.tabs.query(windowId === undefined ? { active: true, lastFocusedWindow: true } : { active: true, windowId });
+ return browser.tabs.create({
+ url: (browser.runtime.getURL as (path: string) => string)(PHONE_PAGE),
+ windowId: current?.windowId ?? windowId,
+ index: current ? current.index + 1 : undefined,
+ openerTabId: current?.id,
+ active: true,
+ });
+}
+
+async function showTab(tabId: number, windowId: number) {
+ const tab = await browser.tabs.update(tabId, { active: true }).catch(() => undefined);
+ await browser.windows.update(tab?.windowId ?? windowId, { focused: true }).catch(() => undefined);
+ return tab;
+}
+
+const tabExists = (tabId: number): Promise<boolean> =>
+ browser.tabs.get(tabId).then(
+ (tab) => !!tab,
+ () => false,
+ );
+
+async function askToOpenChrome(session: PhoneSession): Promise<void> {
+ await browser.notifications
+ ?.create(NOTIFICATION_ID, {
+ type: 'basic',
+ iconUrl: largestIcon(),
+ title: 'Open Chrome on your phone',
+ message: `Browsentic needs Chrome running on ${session.model ?? 'your phone'} to show and drive it.`,
+ buttons: [{ title: 'Open Chrome' }],
+ })
+ .catch(() => undefined);
+}
+
+const clearNotification = () => browser.notifications?.clear(NOTIFICATION_ID).catch(() => undefined);
+
+function largestIcon(): string {
+ const icons = browser.runtime.getManifest().icons ?? {};
+ const [largest] = Object.keys(icons)
+ .map(Number)
+ .sort((a, b) => b - a);
+ return icons[largest] ?? '';
+}
diff --git a/src/lib/bridge/socket-window.test.ts b/src/lib/bridge/socket-window.test.ts
index a9fbedf..9d4f999 100644
--- a/src/lib/bridge/socket-window.test.ts
+++ b/src/lib/bridge/socket-window.test.ts
@@ -80,5 +80,11 @@ describe('an extension against a Bridge from before Android', () => {
expect(worker.daemonSpeaks(RELEASED_BRIDGE.protocolVersion)).toBe(true);
expect(worker.daemonSpeaks(ANDROID_PROTOCOL)).toBe(false);
expect(heard.find((frame) => frame.t === 'hello')).toMatchObject({ protocolVersion: ANDROID_PROTOCOL });
+
+ expect(await worker.openPhone('emulator-5554')).toMatchObject({ ok: false, error: { code: 'UNSUPPORTED' } });
+ expect(await worker.sendCdp('emulator-5554', 'Runtime.evaluate')).toMatchObject({ ok: false, error: { code: 'UNSUPPORTED' } });
+ worker.closePhone('emulator-5554');
+ expect(heard.map(({ t }) => t).filter((t) => t.startsWith('phone') || t === 'cdp')).toEqual([]);
+ expect((await daemonState())?.android).toBeUndefined();
}, TEST_TIMEOUT_MS);
});
diff --git a/src/lib/bridge/socket.test.ts b/src/lib/bridge/socket.test.ts
index dc74f8d..0e748d7 100644
--- a/src/lib/bridge/socket.test.ts
+++ b/src/lib/bridge/socket.test.ts
@@ -98,7 +98,14 @@ describe('keeping one link to the daemon', () => {
await online();
expect((await daemonState())?.protocolVersion).toBe(SOCKET_PROTOCOL_VERSION);
expect(socket.daemonSpeaks(ANDROID_PROTOCOL)).toBe(true);
+ for (let tries = 0; !(await daemonState())?.android; tries++) {
+ if (tries > 100) throw new Error('the Bridge never said what it knows about phones');
+ await wait(20);
+ }
+ expect((await daemonState())?.android).toMatchObject({ enabled: false, problem: { code: 'ANDROID_OFF' } });
+ expect(await socket.openPhone('emulator-5554')).toMatchObject({ ok: false, error: { code: 'ANDROID_OFF' } });
await socket.disconnectDaemon();
expect(socket.daemonSpeaks(ANDROID_PROTOCOL)).toBe(false);
+ expect((await daemonState())?.android).toBeUndefined();
}, TEST_TIMEOUT_MS);
});
diff --git a/src/lib/bridge/socket.ts b/src/lib/bridge/socket.ts
index 24e7dfc..18816b3 100644
--- a/src/lib/bridge/socket.ts
+++ b/src/lib/bridge/socket.ts
@@ -12,6 +12,7 @@ import {
type Transcript,
} from '@/lib/actions/handshake';
import {
+ ANDROID_PROTOCOL,
DAEMON_PORTS,
SOCKET_PROTOCOL_VERSION,
failure,
@@ -26,6 +27,7 @@ import {
type SocketFrame,
} from '@/lib/actions/protocol';
import type { AgentKind, AgentState } from '@/lib/agents/catalog';
+import type { AndroidState, PhoneClosedReason, PhoneOpened } from '@/lib/phone/types';
import type { FileReport } from '@/lib/files/report';
import type { PreferenceChange, Preferences } from '@/lib/settings/preferences';
import type { SkillDraft } from '@/lib/skills/format';
@@ -83,6 +85,8 @@ export interface DaemonState {
skillCatalog?: SkillCatalog;
/** The settings config.json holds for every surface. Pushed on connect and whenever the file changes. */
preferences?: Preferences;
+ /** The phones the Bridge sees. Pushed only by a Bridge that speaks Android, on connect and on every change. */
+ android?: AndroidState;
error?: string;
lastChangeAt: number;
}
@@ -100,6 +104,22 @@ let draftListener: ((runId: string, draft: SiteMapDraft) => void) | null = null;
let taskRunner: ((order: TaskOrder) => Promise<ActionResult>) | null = null;
let preferencesListener: ((preferences: Preferences) => void) | null = null;
+export type CdpEvent = Extract<SocketFrame, { t: 'cdpEvent' }>;
+
+const cdpListeners = new Set<(event: CdpEvent) => void>();
+const phoneClosedListeners = new Set<(serial: string, reason: PhoneClosedReason) => void>();
+const closedListeners = new Set<() => void>();
+
+const listen = <T>(listeners: Set<T>, listener: T): (() => void) => {
+ listeners.add(listener);
+ return () => listeners.delete(listener);
+};
+
+export const onCdpEvent = (listener: (event: CdpEvent) => void) => listen(cdpListeners, listener);
+export const onPhoneClosed = (listener: (serial: string, reason: PhoneClosedReason) => void) => listen(phoneClosedListeners, listener);
+/** The link to a Bridge that had welcomed us went down. */
+export const onDaemonClosed = (listener: () => void) => listen(closedListeners, listener);
+
export function onPreferences(listener: (preferences: Preferences) => void): void {
preferencesListener = listener;
}
@@ -351,6 +371,56 @@ export function reportTaskDone(taskId: string, result: TaskResult): boolean {
return post({ t: 'taskDone', id: crypto.randomUUID(), taskId, result });
}
+const PHONE_OPEN_TIMEOUT_MS = 20_000;
+const PHONE_COMMAND_TIMEOUT_MS = 40_000;
+
+const pendingPhoneOps = new Map<string, (result: ActionResult<never>) => void>();
+
+type PhoneFrame = Extract<SocketFrame, { t: 'phoneOpen' | 'phoneLaunch' | 'cdp' }>;
+
+function phoneOp<T>(frame: PhoneFrame, timeoutMs: number): Promise<ActionResult<T>> {
+ if (!daemonSpeaks(ANDROID_PROTOCOL)) {
+ return Promise.resolve(failure('UNSUPPORTED', 'This Browsentic Bridge predates Android. Update it with “browsentic update”.'));
+ }
+ if (!post(frame)) return Promise.resolve(failure('EXTENSION_OFFLINE', 'No Browsentic daemon is attached — pair the browser first.'));
+ return new Promise((resolve) => {
+ const timer = setTimeout(() => {
+ pendingPhoneOps.delete(frame.id);
+ resolve(failure('TIMEOUT', 'Browsentic Bridge did not answer about the phone in time.'));
+ }, timeoutMs);
+ pendingPhoneOps.set(frame.id, (result) => {
+ clearTimeout(timer);
+ resolve(result as ActionResult<T>);
+ });
+ });
+}
+
+function settlePhoneOp(id: string, result: ActionResult<unknown>): void {
+ pendingPhoneOps.get(id)?.(result as ActionResult<never>);
+ pendingPhoneOps.delete(id);
+}
+
+export function openPhone(serial: string): Promise<ActionResult<PhoneOpened>> {
+ return phoneOp({ t: 'phoneOpen', id: crypto.randomUUID(), serial }, PHONE_OPEN_TIMEOUT_MS);
+}
+
+export function launchPhoneChrome(serial: string, url?: string): Promise<ActionResult<AndroidState>> {
+ return phoneOp({ t: 'phoneLaunch', id: crypto.randomUUID(), serial, url }, PHONE_COMMAND_TIMEOUT_MS);
+}
+
+export function sendCdp(
+ serial: string,
+ method: string,
+ params?: Record<string, unknown>,
+ sessionId?: string,
+): Promise<ActionResult<Record<string, unknown>>> {
+ return phoneOp({ t: 'cdp', id: crypto.randomUUID(), serial, method, params, sessionId }, PHONE_COMMAND_TIMEOUT_MS);
+}
+
+export function closePhone(serial: string): void {
+ if (daemonSpeaks(ANDROID_PROTOCOL)) post({ t: 'phoneClose', id: crypto.randomUUID(), serial });
+}
+
export function cancelRun(id: string): boolean {
return post({ t: 'cancel', id });
}
@@ -413,7 +483,7 @@ export async function disconnectDaemon(): Promise<void> {
clearTimeout(reconnectTimer);
disconnectSocket();
await browser.storage.local.remove(SESSION_KEY_STORE);
- await setState({ connected: false, paired: false, error: undefined, agent: undefined, lastChangeAt: Date.now() });
+ await setState({ connected: false, paired: false, error: undefined, agent: undefined, android: undefined, lastChangeAt: Date.now() });
}
let pairingResult: ((result: { ok: boolean; error?: string }) => void) | null = null;
@@ -511,7 +581,9 @@ function dial(credential: Credential, portIndex: number, carried?: Refusal): voi
// Nothing on this port ever proved itself — a squatter, a stale daemon, an empty port — so the
// walk continues instead of pinning the extension to whoever answered first.
if (!welcomed) return dial(credential, portIndex + 1, refusal);
- void setState({ connected: false, paired: true, error: undefined, lastChangeAt: Date.now() });
+ void setState({ connected: false, paired: true, error: undefined, android: undefined, lastChangeAt: Date.now() });
+ for (const [id] of pendingPhoneOps) settlePhoneOp(id, failure('PHONE_GONE', 'The link to Browsentic Bridge went down.'));
+ for (const listener of closedListeners) listener();
if (credential.kind === 'session') scheduleRetry();
};
}
@@ -674,6 +746,24 @@ async function handle(ws: WebSocket, raw: string, attempt: Attempt): Promise<voi
case 'siteMapDraft':
return draftListener?.(frame.id, frame.draft);
+ case 'androidInfo': {
+ if (frame.id) settlePhoneOp(frame.id, frame.result);
+ if (frame.result.ok) await setState({ android: frame.result.data, lastChangeAt: Date.now() });
+ return;
+ }
+
+ case 'phoneOpened':
+ case 'cdpResult':
+ return settlePhoneOp(frame.id, frame.result);
+
+ case 'cdpEvent':
+ for (const listener of cdpListeners) listener(frame);
+ return;
+
+ case 'phoneClosed':
+ for (const listener of phoneClosedListeners) listener(frame.serial, frame.reason);
+ return;
+
case 'taskList': {
pendingTaskOps.get(frame.id)?.(frame.result);
pendingTaskOps.delete(frame.id);