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
import { browser } from 'wxt/browser';
import { failure, success, type ActionResult } from '@/lib/actions/protocol';
import type { AndroidDevice, 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;
transport?: AndroidDevice['transport'];
mirrorTabId: number;
windowId: number;
openedAt: number;
targets: PhoneTarget[];
/** The tab the mirror follows: the one in front on the phone, found once the mirror starts. */
activeTargetId?: string;
/** The number each phone tab goes by in tool results, counting from 1 and never reused, since a tab id is an integer there. */
tabNumbers?: Record<string, number>;
/** 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;
/** The session with every tab it knows numbered. */
export function numbered(session: PhoneSession, targets: PhoneTarget[] = session.targets): PhoneSession {
const tabNumbers = { ...session.tabNumbers };
let next = Math.max(0, ...Object.values(tabNumbers)) + 1;
for (const { targetId } of targets) tabNumbers[targetId] ??= next++;
return { ...session, targets, tabNumbers };
}
export const currentTarget = (phone: PhoneSession): PhoneTarget | undefined =>
phone.targets.find((target) => target.targetId === phone.activeTargetId) ?? phone.targets[0];
export const targetForNumber = (session: PhoneSession, number: number): string | undefined =>
Object.entries(session.tabNumbers ?? {}).find(([, value]) => value === number)?.[0];
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 resetListeners = new Set<() => void>();
/** Hears the extension end or replace the session itself, which the Bridge never reports back: a new DevTools connection knows none of the old one's sessions. */
export const onPhoneReset = (listener: () => void): void => void resetListeners.add(listener);
function reset(): void {
for (const listener of resetListeners) listener();
}
const writePhone = (session: PhoneSession | null): Promise<void> =>
session ? browser.storage.session.set({ [PHONE_KEY]: session }) : browser.storage.session.remove(PHONE_KEY);
/** A change to the live session, made in turn with every other; nothing happens when there is none. */
export function updatePhone(change: (session: PhoneSession) => PhoneSession): Promise<PhoneSession | null> {
return locked(async () => {
const held = await readPhone();
if (!held || held.ended) return held;
const next = change(held);
await writePhone(next);
return next;
});
}
const opening = (opened: ActionResult<PhoneOpened>) =>
opened.ok
? { targets: opened.data.targets, activeTargetId: undefined, waitingForChrome: false }
: { targets: [], activeTargetId: undefined, waitingForChrome: true };
async function deviceOf(serial: string): Promise<AndroidDevice | 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);
}
/**
* Starts the session and opens its mirror beside the tab the user is on. A second start for the same
* phone shows the mirror already open; one for another phone moves the session, and its tab, to it.
*/
export function startPhone(serial: string, windowId?: number): Promise<ActionResult<PhoneSession>> {
return locked(async () => {
const held = await readPhone();
if (held && !held.ended && held.serial === serial) {
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;
if (held && !held.ended) closePhone(held.serial);
reset();
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);
await writePhone(null);
return failure('BRIDGE_ERROR', 'The phone tab could not be opened.');
}
const session: PhoneSession = numbered({
serial,
mirrorTabId: mirror.id,
windowId: mirror.windowId ?? windowId ?? browser.windows.WINDOW_ID_CURRENT,
openedAt: Date.now(),
tabNumbers: reusable?.serial === serial ? reusable.tabNumbers : undefined,
...opening(opened),
...(await describedPhone(serial, opened)),
});
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') {
await dropPhone(held);
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() } });
});
}
async function dropPhone(held: PhoneSession): Promise<void> {
if (!held.ended) closePhone(held.serial);
reset();
await writePhone(null);
await clearNotification();
}
const mirrorUrl = () => (browser.runtime.getURL as (path: string) => string)(PHONE_PAGE);
/** Any page but the mirror in the mirror's tab: the user took the tab somewhere else. A tab being made reports about:blank on its way in. */
export const leftMirror = (url: string | undefined): boolean => !!url && url !== 'about:blank' && !url.startsWith(mirrorUrl());
/** The mirror tab went to another page: the session ends, and the tab, now the user's, stays. */
function mirrorLeft(tabId: number): Promise<void> {
return locked(async () => {
const held = await readPhone();
if (held?.mirrorTabId === tabId) await dropPhone(held);
});
}
/** 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 = numbered({ ...held, ...opening(opened) });
await writePhone(session);
if (!session.waitingForChrome) await clearNotification();
return success(session);
});
}
export function servePhone(): void {
// A worker that starts has a new link, and the Bridge let go of the phone with the old one.
void endPhone('bridge-gone');
browser.tabs.onRemoved.addListener((tabId) => {
void readPhone().then((held) => {
if (held?.mirrorTabId === tabId) void endPhone('closed');
});
});
browser.tabs.onUpdated.addListener((tabId, change) => {
if (leftMirror(change.url)) void mirrorLeft(tabId);
});
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 describedPhone(serial: string, opened: ActionResult<PhoneOpened>): Promise<Pick<PhoneSession, 'model' | 'transport'>> {
const device = opened.ok ? opened.data.device : await deviceOf(serial);
return { model: device?.model, transport: device?.transport };
}
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: mirrorUrl(),
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] ?? '';
}