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.
TypeScript agentic-browseragentic-browsingagy-cliaiai-agentai-browser-extensionai-toolsbrave-extensionbrowser-agentbrowser-automationbrowser-extensionbrowser-usebrowserskillchrome-extensionclaude-codecodexfirefox-addonmcp-servernanobrowserweb-automation
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.tsxnew file mode 100644index 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.tsindex 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.tsxnew file mode 100644index 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.htmlnew file mode 100644index 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.tsxnew file mode 100644index 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.tsxindex 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 && (<Buttonvariant="ghost"diff --git a/src/lib/actions/protocol.ts b/src/lib/actions/protocol.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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<voicase '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);