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): docs: setting up a phone, what works on it and what stays on the desktop, its limits, troubleshooting and error codes, the config keys, and an internals page that follows one tap from the agent to the phone
Shahriar6427533a4e73
diff --git a/README.md b/README.mdindex 3ca0dc0..450d176 100644--- a/README.md+++ b/README.md@@ -112,6 +112,9 @@ Full guide, Firefox and unpacked installs included: **[browsentic.com/docs/guide<td>🛡️ <a href="docs/guide/approvals.md"><b>Guardrails & approvals</b></a></td><td>🔌 <a href="docs/guide/mcp-clients.md"><b>Optional MCP server</b></a></td></tr>+ <tr>+ <td colspan="3">📱 <a href="docs/guide/features/android.md"><b>Drives Chrome on your Android phone</b></a>, live in a desktop tab, with real taps</td>+ </tr></table>## How It Worksdiff --git a/docs/guide/configuration.md b/docs/guide/configuration.mdindex fec1073..a33083a 100644--- a/docs/guide/configuration.md+++ b/docs/guide/configuration.md@@ -42,7 +42,8 @@ None of these keys is required."maxPages": 15,"maxScreenshots": 10,"timeoutMs": 600000- }+ },+ "android": { "enabled": true }}```@@ -101,6 +102,13 @@ settings page shows but will not change.| `skillsDir` | `~/browsentic/skills` | Where panel uploads and generated site maps live || `extensionDir` | `~/browsentic/extension/chrome-mv3` | Where `browsentic setup --unpacked` writes the unpacked extension. `--dir` writes it for you, and `update` reads it back so it refreshes the copy the browser actually loaded. If you change it by hand, load the new folder in the browser again, because the extension ID follows the path |+## Android++| Key | Default | Notes |+| --- | --- | --- |+| `android.enabled` | `true` | `false` stops the Bridge using adb at all: it never looks for phones, and the side panel shows no Android switch. See [Android phone](features/android.md) |+| `android.adb` | found | Absolute path to the adb to use. Without it the Bridge looks on `PATH`, under `ANDROID_HOME` and `ANDROID_SDK_ROOT`, in Android Studio's SDK, where Homebrew puts it, and on Windows where winget unpacks it. Name one when you have several, since two adb versions stop each other's server |+## Site mapping| Key | Default | Ceiling | Notes |diff --git a/docs/guide/features/README.md b/docs/guide/features/README.mdindex 0e1911f..bde2326 100644--- a/docs/guide/features/README.md+++ b/docs/guide/features/README.md@@ -28,6 +28,7 @@ If you have not set Browsentic up yet, start with [Install](../install.md), [Pai| [Captchas](captcha.md) | What it will and will not do at a "verify you are human" block || [Diagnostics](diagnostics.md) | Recording console errors and failed requests to find why a page broke || [Files](files.md) | Uploading a file to a page, and capturing a file a page downloads |+| [Android phone](android.md) | Driving Chrome on your Android phone from the side panel, in a tab that shows the phone live |## Doing things over timediff --git a/docs/guide/features/android.md b/docs/guide/features/android.mdnew file mode 100644index 0000000..518e892--- /dev/null+++ b/docs/guide/features/android.md@@ -0,0 +1,128 @@+# Android phone++Browsentic can drive Chrome on your Android phone from your desktop browser. Plug the phone in,+switch on **Android** in the side panel, and a tab opens showing the phone's Chrome live inside a+phone frame. A conversation in that tab works on the phone: the same requests, with real taps and+swipes on the phone instead of mouse clicks. Nothing is installed on the phone.++---++## What you need++- A Chromium browser (Chrome, Edge, Brave, Arc and the like) with the Browsentic extension, paired+ to Browsentic Bridge. Firefox has no Android switch.+- **adb**, Android's debugging tool, from Google's+ [platform-tools](https://developer.android.com/tools/releases/platform-tools). The Bridge looks+ for it on your `PATH`, under `ANDROID_HOME` or `ANDROID_SDK_ROOT`, in Android Studio's SDK, where+ Homebrew puts it, and on Windows where winget unpacks it. If it is somewhere else, name it in+ [`config.json`](../configuration.md#android).+- An Android phone with Google Chrome, connected by USB, or over Wi-Fi once it has been paired with+ adb.++`browsentic android`, or the **Android** tab in the [Mac](../mac-app.md) and+[Windows](../windows-app.md) apps, checks each of these and says what is missing.++## Setting up a phone++Once per phone:++1. **Turn on Developer options.** On the phone, open Settings, then About phone, and tap Build+ number seven times.+2. **Turn on USB debugging.** Open Settings, then System, then Developer options, and turn on USB+ debugging.+3. **Connect the phone** to the computer with a USB cable. When the phone asks, tick "Always allow+ from this computer" and tap Allow.+4. **Or connect over Wi-Fi** (Android 11 or later). In Developer options, turn on Wireless+ debugging and tap Pair device with pairing code. On the computer, run `adb pair <ip:port> <code>`,+ then `adb connect <ip:port>`.+5. **Open Chrome on the phone.** Browsentic drives the Chrome app, so it has to be open.+ `browsentic android open` opens it for you.++After that, plug the phone in and open Chrome.++On Windows, many phones also need a USB driver from their maker, or Google's, before adb can see+them. Android's [OEM USB drivers](https://developer.android.com/studio/run/oem-usb) page lists them.++## Using it++The **Android** switch (a phone icon) appears in the side panel's header once the Bridge sees a+phone. Switch it on and a **phone tab** opens beside the tab you were on. It shows the page in+front on the phone, kept up to date as it changes.++- **Talk to it** in the side panel while the phone tab is in front, exactly as you would for a+ desktop tab. The conversation belongs to the phone tab, and the agent's actions land on the phone.+- **Use it yourself.** Click the picture to tap the phone, scroll on it to scroll, and type while it+ has focus to type on the phone. The bar above has back, forward, reload, the page's address (type+ an address or a search to go there) and the phone's tabs.+- **It follows the phone.** Switch tabs on the phone itself and the picture follows.+- **Switch it off**, or close the phone tab, to stop. Unplugging the phone or closing Chrome on it+ ends the session too, and the phone tab says why, with a button to reconnect.++The picture pauses while the phone tab is hidden, and while the phone's screen is off, because+Chrome stops drawing then. The phone tab asks you to wake the phone.++An [MCP client](../mcp-clients.md) drives the phone too while the phone tab is the active tab, with+the same limits as below.++## What works on the phone++Reading and acting on a page work the same way: page info and text, waiting for an element,+clicking, filling and typing, keys, choosing an option, selecting text, submitting forms,+scrolling, dragging, screenshots, frames, searching a site, theming and the contrast audit, the+phone's tabs, and timers. The differences:++| On a desktop tab | On the phone |+| --- | --- |+| A click is a script event, or a mouse click through Chrome's debugger | Every click is a real tap |+| Hover opens menus | There is no hover; menus open on a tap |+| Scrolling jumps | Scrolling is a real scroll, so content that loads as you scroll does load |+| Typing is set or simulated in the page | Typing is real keyboard input to the phone |+| A screenshot is of the desktop tab | A screenshot is of the phone's screen, at the page's size |+| Tabs are your browser window's tabs | Tabs are the phone's Chrome tabs |++[Blocked sites](blocked-sites.md) are checked against the phone's own address, and+[approvals](../approvals.md) work as they do on a desktop tab.++## What is off on the phone++While the phone tab is in front, the side panel hides what only works in a desktop tab:+[recordings](recordings.md), [scheduling](scheduling.md), live tools and saved tools,+[A-Eye](a-eye.md), [action cues](action-cues.md) and [hands-free](hands-free.md). Voice in the+panel, attaching a file and attaching the page's context still work. They all come back when you+switch to a desktop tab.++The agent is offered only the tools that work on the phone. Hovering, captchas, downloads,+uploading a file to a page, page code, a site's own tools, monitors and diagnostics stay on the+desktop. If you ask for one of those, the agent says it is not available on the phone.++## Privacy and safety++adb is a powerful connection: a computer that the phone allows over USB debugging can install+apps, read files and control the phone. Browsentic uses it narrowly:++- it reads the phone's model, Android and Chrome versions, screen size and whether the screen is+ on;+- it opens Chrome when you ask it to;+- it forwards one local port to Chrome's own debugging socket, and drives Chrome through that.++It installs nothing on the phone and touches no other app. The connection stays on your computer,+between the Bridge and the phone. Switching Android off, closing the phone tab or unplugging the+phone stops it.++Chrome on the phone holds your real sessions and logins, just like your desktop browser. The same+[approvals](../approvals.md) and [blocked sites](blocked-sites.md) protect it.++If you never want the Bridge to use adb at all, set `"android": { "enabled": false }` in+[`config.json`](../configuration.md#android).++## Limits++- One phone at a time.+- Google Chrome on the phone: not Chrome Beta, Dev or Canary, and not other browsers.+- The phone's screen has to be on and unlocked while the agent works.+- A `<select>` opens the phone's own picker, which Browsentic cannot see. The agent sets the+ value instead.+- New tabs always open in front on the phone, because Chrome on Android does that.++More in [Limits](../limits.md#android-phones). If a phone will not connect, see+[Troubleshooting](../troubleshooting.md#android-phones).diff --git a/docs/guide/limits.md b/docs/guide/limits.mdindex 43bae62..e560e8f 100644--- a/docs/guide/limits.md+++ b/docs/guide/limits.md@@ -184,6 +184,27 @@ and it does nothing but start the Bridge. The trust boundary is unchanged: yourand Vivaldi and Arc on Windows, are not registered yet, so there the Bridge starts with the app, acommand or an MCP client instead.+## Android phones++[Driving a phone](features/android.md) has limits of its own:++- **One phone at a time**, driven by one browser at a time.+- **Google Chrome only**, the stable app from the Play Store. Chrome Beta, Dev and Canary and other+ Android browsers are not found.+- **Chromium desktop browsers only.** Firefox has no Android switch.+- **The screen has to stay on.** With the screen off Chrome stops drawing, the picture stops, and+ the agent's actions can stall or fail. Keep the phone unlocked while it works.+- **USB, or Wi-Fi already paired with adb.** Browsentic does not pair a phone over Wi-Fi for you.+- **Desktop-only tools stay on the desktop**: hover, captchas, downloads, uploading a file to a+ page, page code, a site's own tools, monitors, diagnostics, recordings, scheduling and A-Eye.+- **Native pickers are out of reach.** A `<select>` opens the phone's own picker, which is not part+ of the page; the agent sets its value instead. The same goes for permission prompts and anything+ else Android draws over Chrome.+- **New tabs open in front.** Chrome on Android always brings a new tab forward, so a tab the agent+ opens "in the background" shows briefly before it switches back.+- **Out-of-process iframes** have not been tested on a real phone; the emulator keeps every frame in+ one process.+## Unpacked extensionAn unpacked copy (`setup --unpacked`, or a source build) is not updated by any store, and thediff --git a/docs/guide/troubleshooting.md b/docs/guide/troubleshooting.mdindex 32340b6..a51b03f 100644--- a/docs/guide/troubleshooting.md+++ b/docs/guide/troubleshooting.md@@ -105,6 +105,32 @@ Those three answer most questions. The Bridge's log is at `~/.browsentic/daemon.| A tool set to run on every visit never runs | Chrome keeps user scripts off until you allow them for the extension | Open `chrome://extensions` → Browsentic → **Details** and turn on **Allow User Scripts**. See [Running one on every visit](features/page-actions.md#running-one-on-every-visit) || A tool set to run on every visit ran but changed nothing | It ran before the site had drawn what it changes, or the site changed its markup | Check the page's console for a `Browsentic:` line, which appears if it threw. Run the tool with `/` to check it still works; if it does not, make a new one with the Live tool switch |+## Android phones++`browsentic android`, or the **Android** tab in the Mac and Windows apps, runs every check below and+names the one that fails. See [Android phone](features/android.md) for setting a phone up.++| Symptom | Cause | Fix |+| --- | --- | --- |+| No Android switch in the side panel | The Bridge sees no phone, the Bridge predates Android, or the browser is Firefox | Run `browsentic android`. Update the Bridge if it does not know the command. Firefox has no Android switch |+| `ANDROID_OFF` | `"android": { "enabled": false }` is set in `config.json` | Set it to `true`, or remove it |+| `ADB_MISSING` | adb, from Android's platform-tools, is not installed, or not where the Bridge looks | Install platform-tools (the check prints the command for your system), or name your adb with `"android": { "adb": "/path/to/adb" }` |+| `ADB_BROKEN` | The adb the Bridge found does not run | Reinstall platform-tools, or name a working adb in `config.json` |+| `NO_DEVICE` | No phone is connected, USB debugging is off, or the cable only charges | Turn on USB debugging and connect with a data cable. On Windows, see the next row |+| adb sees nothing on Windows | Many phones need their maker's USB driver, or Google's, before Windows lets adb see them | Install the driver from Android's [OEM USB drivers](https://developer.android.com/studio/run/oem-usb) page, then plug the phone in again |+| `DEVICE_UNAUTHORIZED` | The phone has not allowed this computer | Unlock the phone and tap **Allow** on the USB debugging prompt. If no prompt shows, unplug it and plug it in again |+| `DEVICE_OFFLINE` | The phone is connected but not answering adb, or it is in recovery or bootloader mode | Unplug it and plug it in again; over Wi-Fi, run `adb connect <ip:port>` again. A phone in another mode needs a normal restart |+| `DEVICE_BOOTING` | The phone is still starting up | Wait for it to finish |+| `NO_PERMISSIONS` (Linux) | The system does not let your user open the phone's USB connection | Install udev rules for Android phones (`sudo apt install android-sdk-platform-tools-common` on Debian and Ubuntu), then plug the phone in again |+| `CHROME_MISSING` | Google Chrome is not installed on the phone | Install it from the Play Store. The Android tab's **Get Chrome** opens its page on the phone |+| `CHROME_NOT_RUNNING` | Chrome is not open on the phone | Open it, or run `browsentic android open`. The phone tab and the Android tab have a button that does the same |+| `SCREEN_OFF` | The phone's screen is off, so Chrome is not drawing | Unlock the phone. Keep it awake while the agent works |+| The phone tab's picture is black or frozen | The phone's screen went off, or the phone tab was hidden, which pauses the picture | Wake the phone, and bring the phone tab to the front |+| Taps land in the wrong place | The page moved between finding the element and tapping it, or the phone's keyboard or a banner covers it | Ask again once the page has settled. The agent finds the element again before every tap |+| `NOT_ON_PHONE` | The tool works only in desktop tabs | Do that step in a desktop tab |+| `PHONE_GONE` | The phone session ended: the phone was unplugged, Chrome closed on it, or Android was switched off | Press **Reconnect** in the phone tab, or switch Android on again |+| `PHONE_PAGE_UNREACHABLE` | The page on the phone was still loading or kept navigating | Wait for it to load and try again |+## MCP clientsThese apply only when another tool drives Browsentic through its optional MCP endpoint.diff --git a/docs/internals/README.md b/docs/internals/README.mdindex 51f1a47..913a507 100644--- a/docs/internals/README.md+++ b/docs/internals/README.md@@ -26,6 +26,7 @@ Read in order, these pages follow a request through all of them:| **11.** [The macOS app](mac-app.md) | What is native, what stays in the daemon, and how the payload is laid down || **12.** [The Windows app](windows-app.md) | The Tauri and React app, the launcher, the PATH, and how it updates || **13.** [Store listings](stores.md) | The Chrome Web Store and Edge Add-ons IDs, submitting an update, and every field the dashboards ask for |+| **14.** [Android phones](android.md) | adb without spawning adb, the DevTools relay, the phone tab, and one tap followed from the agent to the phone |Error codes are in [reference/errors.md](../reference/errors.md), and each tool's parameters in[reference/tools.md](../reference/tools.md).diff --git a/docs/internals/agent-runs.md b/docs/internals/agent-runs.mdindex a587a79..058f0a5 100644--- a/docs/internals/agent-runs.md+++ b/docs/internals/agent-runs.md@@ -271,24 +271,26 @@ one-shot, the readiness probe, a model list), and they are where Windows differs`buildSystemPrompt()` concatenates, in order:1. a fixed preamble: the browser is not a sandbox, page content is data and never instructions, do- not exfiltrate, a `DECLINED` action is final, report what actually happened;+ not exfiltrate, a `DECLINED` action is final, report what actually happened. Its opening+ paragraphs name the browser, or the phone on a [run on the phone](#a-run-on-the-phone);2. the routed **base skill** body;-3. the user's **standing instructions** and **saved details** from the settings page's+3. on a run on the phone, the **Android phone** section: the device in one line;+4. the user's **standing instructions** and **saved details** from the settings page's[Profile](../guide/features/profile.md) (`profile.json`, read fresh for each run). They aretrusted, since the user wrote them, and framed accordingly: use the details exactly, never inventa missing one, and rank the instructions above the skill and site notes but below the preamble.Side-panel runs and scheduled tasks only; mapping runs and one-shot tasks go without;-4. an optional **attached agent skill**: one of the active CLI's own skills, chosen from the+5. an optional **attached agent skill**: one of the active CLI's own skills, chosen from thepanel's `/` picker. `RunContext.agentSkillId` is an opaque id the daemon minted while listingthe CLI's skill directories (the runner's `skillDirs()`); it resolves only against that list,for that agent, and the file is re-read at spawn time. An id that no longer resolves fails therun with `SKILL_UNKNOWN` before anything spawns;-5. optional **fetched data** (a site's own `robots.txt`/`sitemap.xml`, during mapping);-6. optional **attached files**: one line for each file whose report this conversation's agent+6. optional **fetched data** (a site's own `robots.txt`/`sitemap.xml`, during mapping);+7. optional **attached files**: one line for each file whose report this conversation's agentalready holds, with the id `page_attachFile` takes. The reports themselves travel in themessage ([below](#the-file-analyst));-7. optional **recordings** index, capped at 4 KB;-8. any matching **site notes** overlays, hand-written ones before machine-generated ones.+8. optional **recordings** index, capped at 4 KB;+9. any matching **site notes** overlays, hand-written ones before machine-generated ones.The whole prompt is capped at **64 KB**. Overlays that would push it over are dropped by name, andthe side panel is told which ones: a silently truncated prompt is worse than a visibly incomplete@@ -469,7 +471,7 @@ directory shadows an earlier one by name:| Directory | Source | Contents || --- | --- | --- |-| `src/daemon/skills/` (bundled) | `bundled` | `browser-control` (default), `page-research`, `page-theming`, `browse-navigation`, `monitor-progress`, `site-mapper`, `captcha`, `a-eye` |+| `src/daemon/skills/` (bundled) | `bundled` | `browser-control` (default), `page-research`, `page-theming`, `browse-navigation`, `monitor-progress`, `site-mapper`, `captcha`, `a-eye`, and `phone`, the base of every [run on the phone](#a-run-on-the-phone) || `~/.browsentic/skills/` | `user` | Hand-written overrides || `~/browsentic/skills/` (or `skillsDir`) | `uploaded` | Panel uploads and generated site maps |@@ -482,6 +484,39 @@ the `default: true` skill as the fallback. A `@name` prefix pins one explicitly.Skills with `category: site-exploration` are **overlays** instead: they stack on top of the basewhenever the active tab's host matches their `domains`, longest match first.+## A run on the phone++A conversation on the [phone tab](android.md) sends `RunContext.phone`: the model, the Android and+Chrome versions, and the viewport, read when the message is sent. The run changes in four ways:++- **Its base skill is always `phone`** (`PHONE_SKILL` in `skills.ts`), whatever the words would+ have routed to, even when a `@name` names another general skill. `browser-control.md` teaches+ desktop tools a phone run is not offered (hover, captchas, downloads, a site's own tools, page+ code), and naming a withheld tool invites the agent to try it. `phone.md` names only+ `PHONE_TOOLS`, and a test holds it to that. Site notes for the phone page's host still ride+ along; the page-scripting overlay never does, even with `liveTools` set. Like `page-scripting`,+ `phone` is a `general` skill kept out of desktop routing by name.+- **Its prompt opens on the phone** (`PHONE_OPENING` in `prompt.ts`): every tool call lands on the+ tab in front on the phone, not on "whichever tab is frontmost". The numbered rules are the same.+- **An `# Android phone` section** carries `phoneBlock(context.phone)`, such as+ `Pixel 8 · Android 16 · Chrome 150 · viewport 411×915 CSS px at 2.625x`, so the agent needs no+ tool call to learn the device. It holds no address, so it does not change with every message.+- **Its tool list is smaller.** `offerFor` withholds every tool off `PHONE_TOOLS`, and+ `invokeForRun` refuses a call to one with `NOT_ON_PHONE`. The tool list the browser describes+ is never varied, because it feeds the manifest hash.++Together these make a phone run's fixed overhead about 40 % smaller than a desktop run's: measured+as sent on 9 Oct 2026, the repository's part of the system prompt was 7.9 KB against 19.6 KB, and+the tool list 31 tools in 39.6 KB of JSON against 52 in 60.7 KB.++A conversation can move between the phone and a desktop tab when it is restored onto the other. A+CLI that keeps its first prompt then hears the change in its next message: the `phone` and `skill`+sections going one way, and "No longer in force: the Android phone" with the desktop skill going+the other. Its tool list shrinks or grows at that point, which re-bills the cached prefix once.+Codex fixes its tool list when a thread starts and lists withheld tools out of sight, so on a Codex+thread that began on the phone the desktop tools stay out of sight; a call to an off-list tool on+the phone is refused either way.+---## Nextdiff --git a/docs/internals/android.md b/docs/internals/android.mdnew file mode 100644index 0000000..3eddf3c--- /dev/null+++ b/docs/internals/android.md@@ -0,0 +1,206 @@+# Android phones++How Browsentic drives Chrome on an Android phone: the Bridge reaches the phone through adb and+relays the Chrome DevTools Protocol, and the extension keeps every bit of tool logic. For what the+user sees, read [guide/features/android.md](../guide/features/android.md) first.++---++## The shape of it++```+Phone Chrome ── debugging socket (localabstract:chrome_devtools_remote)+ │ adb forward tcp:<free port>+Desktop Browsentic Bridge ── ws, no Origin header ──► CDP browser target (flattened sessions)+ │ relay frames on the existing paired socket (protocol 23)+ Extension background: phone session + phone backend (a branch in invokeForHarness)+ │ runtime Port "browsentic/phone"+ Phone tab (phone.html): phone frame, screencast canvas, the user's taps and typing+ Side panel on the phone tab: the conversation that drives the phone+```++Nothing is installed on the phone. Chrome on Android always listens on an abstract Unix socket for+DevTools once USB debugging is on; adb forwards a local port to it, and from there it is the same+protocol as desktop Chrome's remote debugging.++## Who owns what++| Part | Owns | Where |+| --- | --- | --- |+| Bridge | adb (finding it, its server, the phone list), readiness, opening Chrome, the forward and the one WebSocket per phone | `src/daemon/android/` |+| Extension | The phone session, the phone tab, every tool's logic, blocked sites, secrets, the tab-session registry | `src/lib/bridge/phone*.ts`, `src/extension/entrypoints/phone/`, `phone-page.ts` |+| Shared | Types, the setup guide, the checklist, the tool list, the page bundle, touch input | `src/lib/phone/` |++**Why the extension keeps the tool logic.** The [blocked-sites list](../guide/features/blocked-sites.md)+lives only in the browser and is never sent to the Bridge, so a Bridge that drove the phone on its+own would drive it past that list. Secrets, frame focus and tab sessions live there too. The Bridge+is a relay, not a second implementation: the control socket's `android` op can open Chrome, but it+has no way to send a DevTools command.++**Why the Bridge holds the socket, not the extension.** Chrome refuses a DevTools WebSocket that+carries an `Origin` header unless it was started with `--remote-allow-origins`, and every+WebSocket an extension page opens carries one. Node's `ws` sends none.++## adb, without spawning adb++`src/daemon/android/adb.ts` finds one adb binary (the configured `android.adb`, then `PATH`,+`ANDROID_HOME`, `ANDROID_SDK_ROOT`, Android Studio's SDK, Homebrew and winget) and runs it only for+`adb version` and, when nothing listens on 5037, `adb start-server`. Everything else goes to adb's+own server over its socket on 127.0.0.1:5037 (`adb-server.ts`): `host:track-devices-l` for the+phone list, `shell:` for the facts, `forward` and `killforward`.++A socket client never kills a server of another version, which running a second adb binary does,+taking Android Studio's connection with it. For the same reason the Bridge never runs+`adb kill-server` or removes forwards it did not make.++`phone-facts.ts` asks for everything in one `shell:` call, each answer under its own marker:+`getprop` for the model and Android version, `wm size` and `wm density`, `dumpsys power` for the+screen, `pm path` and `dumpsys package` for Chrome, `pidof`, and `/proc/net/unix` for the+DevTools socket. Only that socket means Chrome is ready; Android pre-starts the process.++## Readiness++`readiness.ts` turns adb's state and the facts into one `AndroidState`: `enabled`, `ready`, the adb+it found, a device list, and a `problem` with a code, a message, and a `fix` that is only ever+something to copy. `src/lib/phone/checks.ts` (`phoneReport`) turns that into the checklist that+`browsentic android`, the Mac app and the Windows app all show, and `guide.ts` holds the one copy of+the setup steps. The Mac app repeats both by hand and must match.++The Bridge looks for phones only while someone watches: an extension that speaks protocol 23, or an+app showing its Android tab. It pushes every change as `androidInfo`.++## The relay++`relay.ts` holds at most one session per phone. `phoneOpen` makes a fresh forward to+`localabstract:chrome_devtools_remote`, reads `/json/version` for the browser target (never+`/json/protocol`, which crashes Chrome on Android), opens the WebSocket, and lists tabs with+`Target.getTargets`, dropping the phantom target `"1"` that the phone reports beside the real ones.++- **Ownership.** The extension link that opened a session owns it. Another browser asking gets+ `NOT_OWNER`, and events go only to the owner.+- **Commands.** `cdp` frames carry one method each, with a flattened `sessionId`. The answer comes+ back as `cdpResult`. A command that waits inside the page passes `timeoutMs`, at most 180 s.+- **Events.** Everything Chrome sends goes back as `cdpEvent`. Screencast frames are large JPEGs, so+ one that finds the extension's socket more than 4 MB behind is dropped and acknowledged to the+ phone, which keeps the stream going rather than stalling it.+- **Ending.** The phone leaving adb's list, Chrome's socket closing, the Bridge stopping or a+ `phoneClose` ends the session with a `phoneClosed` reason. The forward is removed with it; a+ transport reset drops forwards anyway, so each open makes its own.++The frames are listed in [transport.md § Protocol 23](transport.md#protocol-23-android).++## The phone session and the phone tab++`src/lib/bridge/phone.ts` keeps the session in `storage.session` under `browsentic/phone`: the+serial, the phone tab's id and window, the phone's targets and which one is in front, each target's+tab number, and why it ended. The **Android** toggle (`components/phone-toggle.tsx`) starts and ends+it through the `phoneStart` and `phoneEnd` bridge ops.++The phone tab is `phone.html` (`src/extension/entrypoints/phone/`), an unlisted page. It talks to+the background over the `browsentic/phone` Port, served by `phone-mirror.ts`:++- **The picture** is `Page.startScreencast` on the tab in front, drawn on a canvas inside a phone+ frame the page draws itself. Every frame is acknowledged. It stops while the tab is hidden, and an+ idle page sends no frames, so silence is not a disconnect.+- **Following the phone.** A tab switch on the phone fires no `Target.*` event, so the mirror+ watches page visibility and `Page.screencastVisibilityChanged`, and finds the front tab again.+- **The user's input** goes the same way as the agent's (below): a click becomes a tap, the wheel+ becomes wheel steps, keys become key events, and the bar's back, forward, reload, address and tab+ list become commands.++A conversation started on the phone tab is anchored on the phone's page, never on `phone.html`+(`phone-conversation.ts`), and its `TabSession` carries `phone: { serial }`. Each run's+`RunContext.phone` carries the model, the Android and Chrome versions and the viewport, read when+the message is sent.++## One tap, end to end++The agent calls `page_clickElement { target: { text: "Sign in" } }` in a conversation on the phone+tab.++1. **Agent CLI → MCP server → Bridge.** `browsentic-mcp` (`src/daemon/server.ts`, `tool-host.ts`)+ sends the call over the control socket. `daemon.ts` hands it to `AgentSession.invokeForRun`+ (`agent/service.ts`), where guardrails and approvals run as usual, and a tool off the phone's+ list is refused with `NOT_ON_PHONE` before the browser hears of it.+2. **Bridge → extension.** `link.invoke` (`extension-link.ts`) sends an `invoke` frame;+ `socket.ts` receives it and calls `invokeForHarness` (`src/lib/bridge/invoke.ts`).+3. **The phone branch.** Before any desktop check, `phoneRoute` (`phone-invoke.ts`) sees that the+ run's tab is the phone tab, and `invokeOnPhone` takes over. Host-side tools (the timers) skip the+ branch. `invokeOnPhone` checks `PHONE_TOOLS`, checks the blocked-sites list against the **phone+ page's** address, releases sealed secrets, and calls the backend. Tab tools (`navigate`,+ `openTab`, `switchTab`, `closeTab`) have their own handlers there, over `Target.*` and `Page.*`.+4. **Finding the element.** `pageSideOnPhone` (`phone-backend.ts`) asks the page where the element+ is. The page side runs in an isolated world named `browsentic`, made with+ `Page.createIsolatedWorld` on first use and cached per tab and frame; the bundle `phone-page.js`+ (built from `entrypoints/phone-page.ts` and `src/lib/phone/page-api.ts`) is evaluated in it once.+ It holds the same action code desktop tabs run, under `__browsenticPhone.dispatch`, with no+ extension API in it. A call that finds its world gone, because the page navigated, makes it again+ and retries once. The trusted-click plan scrolls the element into view and returns its centre.+5. **The tap.** `tapOn` subtracts the visual viewport's offset (`Page.getLayoutMetrics`+ `cssVisualViewport`) and refuses a point off screen with `TAP_MISSED`. `src/lib/phone/touch.ts`+ builds `Input.dispatchTouchEvent` `touchStart` and `touchEnd`, and `sendCdp` (`socket.ts`) sends+ each as a `cdp` frame.+6. **Bridge → phone.** `daemon.ts` passes the frame to the relay's `command`, which sends it on the+ phone's WebSocket, through the adb forward, to Chrome. The result comes back the same way as+ `cdpResult`.+7. **The result.** `invokeOnPhone` checks the landing address against blocked sites again for+ tools that navigate, seals any secret in what came back, and the result returns to the agent.+ The phone tab shows the tap as the next screencast frame.++## Touch, keys and scrolling++All of it is in `src/lib/phone/touch.ts`, used by both the backend and the phone tab:++- **Points** are CSS pixels from the visual viewport's corner, never scaled by the pinch zoom: the+ element's client centre minus `visualViewport.offsetLeft/Top`. Chrome accepts points off screen,+ so the backend checks the point is visible first.+- **A click** is a tap; **a drag** is a touch drag that holds before it moves.+- **Scrolling** by an amount is trusted `mouseWheel` steps of 120 px at the middle of the screen,+ adding to 85 % of it. Never `Input.synthesizeScrollGesture`: once a page is pinch-zoomed it strips+ pointer events from every later tap.+- **Typing** focuses the field in the page, then `Input.insertText` in chunks; a newline is Enter.+- **Keys**: Enter is a `keyDown` with `text: '\r'`; others are `rawKeyDown` with a Windows virtual+ key code, without which Backspace and the arrows do nothing.+- **Screenshots** clip in CSS pixels and scale by `1 / dpr`, so one image pixel is one CSS pixel.+- **A `<select>`** opens a native picker CDP cannot see, so its value is set in the page.++## What a phone run is offered++`src/lib/phone/features.ts` holds `PHONE_TOOLS`, an allowlist: a new tool stays off the phone until+someone makes it work there and adds it, with a test. `HOST_SIDE` lists the tools that touch no page+(the timers), which skip the phone branch.++The tool list a browser describes, and so its manifest hash, never changes for the phone. Instead+`AgentSession.offerFor` withholds every tool `phoneOffers` rejects for a run whose context carries+`phone`, and `invokeForRun` refuses a call to one. On the phone tab the side panel hides recordings,+schedules, live tools and saved tools, A-Eye, action cues and hands-free, by the phone tab's id+(`useMirroredPhone` in `phone-client.ts`), because without the `tabs` permission an extension+page's URL is hidden from the panel.++## The prompt++A phone run's prompt opens on the phone rather than "whichever tab is frontmost", and its base skill+is always `src/daemon/skills/phone.md`, whatever the instruction's words would have routed to:+`browser-control.md` teaches desktop tools a phone run is not offered. `phone.md` names only+`PHONE_TOOLS`, and a test holds it to that. A `# Android phone` section carries the device in one+line, so the agent needs no tool call to learn it. See+[agent-runs.md § A run on the phone](agent-runs.md#a-run-on-the-phone).++## Traps++- **A warm VIEW intent opens a new tab every time.** `am start` is only used to cold-start Chrome;+ addresses open over CDP.+- **`Target.createTarget` always opens in front** on Android; `background: true` is ignored.+- **A sleeping phone** stops drawing and throttles the tab. Readiness reports `SCREEN_OFF` from+ `dumpsys power`, and the phone tab asks the user to wake the phone.+- **`MAX_ACTIVE_SESSIONS`** counts the phone tab's conversation like any other.+- **Out-of-process iframes** are untested: the emulator keeps every frame in one process.++## Testing it++The Android emulator is the test phone: an AVD with the Play Store image has Chrome. Fold a+foldable AVD (`adb emu fold`) for the phone layout. `adb reverse tcp:<port> tcp:<port>` lets the+phone load a test server on the computer. Unit tests use recorded adb output under+`src/daemon/android/fixtures/` (the `.handwritten` ones stand in until a real phone records them)+and `src/daemon/test/fake-android.ts`; extension checks run in Chrome for Testing paired+to a scratch Bridge (`BROWSENTIC_HOME` and `BROWSENTIC_PORTS` set, so it never touches a real one).diff --git a/docs/internals/extension.md b/docs/internals/extension.mdindex b9c9474..b5269f5 100644--- a/docs/internals/extension.md+++ b/docs/internals/extension.md@@ -421,6 +421,21 @@ remembers which frames are lit until a few seconds after the cue settles, longertab's throttled timers take to fade it. The host answers after two frames, once the page hasrepainted without it, or at once in a hidden tab. A tab with nothing lit is not messaged at all.+## The phone tab++Driving a phone (see [Android phones](android.md)) adds two unlisted entrypoints and a Port:++| Piece | What it is |+| --- | --- |+| `entrypoints/phone/` → `phone.html` | The phone tab: a phone frame the page draws itself, the screencast on a canvas, and a bar with back, forward, reload, the address and the phone's tabs. It holds no state of its own beyond what is on screen |+| `entrypoints/phone-page.ts` → `phone-page.js` | The page bundle evaluated in an isolated world on the phone: the same action code desktop tabs run, under `__browsenticPhone`, with no extension API in it (`page-api.test.ts` fails the build on any). It is never injected into a desktop page |+| `browsentic/phone` Port | Between the phone tab and the background (`phone-mirror.ts`): screencast frames and page state down, the user's taps, scrolls, keys and the bar's commands up |++The phone session itself is `browsentic/phone` in `storage.session`, written only through+`phone.ts`, and the side panel and popup read it with `usePhoneSession`. The panel recognises the+phone tab by its id, not its URL: without the `tabs` permission an extension page's URL is hidden+from `tabs.query`. The **Android** toggle is hidden on Firefox, and no new permission was needed.+## Tab scopingA panel conversation is **bound to the tab it started in**.@@ -448,6 +463,11 @@ elsewhere, and two sessions in two tabs act independently.Calls with no run behind them (an external MCP client, the local fast path) still target the**active tab of the current window**.+A session on the [phone tab](android.md) carries `phone: { serial }` and is anchored on the+phone's page, never on `phone.html`. Its runs take the phone branch in `invokeForHarness`, before+`guardTarget` and every other desktop check, because the tab they resolve to is an extension page+that must never be navigated, reloaded or injected into.+A site-mapping run keeps its own older pin, threading a literal `tabId` and failing with`MAPPING_TAB_CHANGED` if that tab goes away.diff --git a/docs/internals/state.md b/docs/internals/state.mdindex 15f11a6..966373c 100644--- a/docs/internals/state.md+++ b/docs/internals/state.md@@ -81,6 +81,13 @@ never comes back with a microphone on. Only where the orb was dragged to (`browsbrowser shows (`browsentic/contextMenu`, both on when absent) and whether agent actions are ringed onthe page (`browsentic/actionCues`, off when absent).+**The phone session** is `browsentic/phone` in `storage.session`: the phone's serial, the phone+tab's id and window, the phone's tabs and which one is in front, and why it ended. A conversation on+the phone tab is a tab session like any other, marked `phone: { serial }`. Both go when the browser+closes. Nothing about the phone reaches the Bridge's disk beyond `daemon.log` lines naming its serial,+its Chrome version and each DevTools method sent, never its parameters; screencast frames are+never logged or stored. See [Android phones](android.md).+**Blocked sites** are `browsentic/blockedSites` in `storage.local`: a list of up to 500 patterns thatthe daemon never receives. Removing the extension removes it; each browser keeps its own.diff --git a/docs/internals/transport.md b/docs/internals/transport.mdindex 1be4264..01bc31f 100644--- a/docs/internals/transport.md+++ b/docs/internals/transport.md@@ -148,15 +148,18 @@ request from it is answered `UNSUPPORTED`. The shapes are in `src/lib/phone/type| `phoneOpened` | Bridge | The device, its open tabs and Chrome's version, or an error || `phoneClose` | extension | `serial`: end the session. Not answered || `phoneLaunch` | extension | `serial` and an optional `url`: open Chrome on the phone |-| `cdp` | extension | One DevTools command for the phone's Chrome: `method`, `params` and `sessionId`. Answered by `cdpResult` |+| `cdp` | extension | One DevTools command for the phone's Chrome: `method`, `params`, `sessionId`, and `timeoutMs` (at most 180 s) when the command waits inside the page. Answered by `cdpResult` || `cdpResult` | Bridge | Chrome's result, or `CDP_ERROR`, `TIMEOUT`, `PHONE_GONE` or `NOT_OWNER` |-| `cdpEvent` | Bridge | Every DevTools event from the phone, screencast frames included, sent only to the extension that opened the session |+| `cdpEvent` | Bridge | Every DevTools event from the phone, screencast frames included, sent only to the extension that opened the session. A screencast frame that finds the socket more than 4 MB behind is dropped and acknowledged to the phone, so the stream keeps going || `phoneClosed` | Bridge | `serial` and why the session ended: `unplugged`, `chrome-exited`, `bridge-stopping` or `closed` |-The control socket has an `android` op that reads the same state, subscribes to `android-changed`-with `watch`, and opens Chrome on a phone with `launch` (refused to an agent run's connection). It-has no way to send a DevTools command. Every action on the phone goes through the extension, which-is where the blocked-sites list is checked.+The Bridge looks for phones only while someone is watching: an extension that speaks 23, or an app+showing its Android tab. The control socket has an `android` op that reads the same state,+subscribes to `android-changed` with `watch` (and lets go with `watch: false`), answers only what is+already known with `peek` (`NOT_CHECKED` while nobody watches), and opens Chrome on a phone with+`launch` and an optional `url` (refused to an agent run's connection). It has no way to send a+DevTools command. Every action on the phone goes through the extension, which+is where the blocked-sites list is checked. [Android phones](android.md) follows a tap through all of it.---diff --git a/docs/reference/errors.md b/docs/reference/errors.mdindex c087001..f4e56b4 100644--- a/docs/reference/errors.md+++ b/docs/reference/errors.md@@ -130,6 +130,25 @@ and handed to the agent with the file so it can say why it cannot answer from it| `FILE_NOT_FOUND` | failed | The browser no longer holds the file's bytes. Attach it again || `AGENT_FAILED` | failed | The agent could not start, or returned something that was not a report. The message says which |++## Android phones++These come from a conversation on the [phone tab](../guide/features/android.md). The readiness codes+(`ADB_MISSING`, `NO_DEVICE`, `DEVICE_UNAUTHORIZED` and the rest) are what `browsentic android` and+the apps report; each has a row in [troubleshooting](../guide/troubleshooting.md#android-phones).++| Code | Origin | Meaning and next move |+| --- | --- | --- |+| `NOT_ON_PHONE` | Daemon or extension | The tool works only in desktop tabs. A phone run is not offered it, so only an MCP client or a stale skill reaches this. Do that step in a desktop tab |+| `PHONE_GONE` | Extension | The phone session ended: the phone was unplugged, Chrome closed on it, Android was switched off, or the Bridge went away. **Retrying will not help**; reconnect from the phone tab |+| `PHONE_PAGE_UNREACHABLE` | Extension | The page on the phone was loading, or kept navigating, so its script world could not be made. Try again once it has loaded |+| `TAP_MISSED` | Extension | The point was outside the visible part of the phone's screen, so nothing was touched. Scroll it into view first |+| `NAVIGATION_FAILED` | Extension | Chrome on the phone could not open the address; the message carries Chrome's reason |+| `CHROME_NOT_RUNNING` | Daemon | Chrome is not open on the phone, so the session could not start. Open it, or run `browsentic android open` |+| `NOT_OWNER` | Daemon | Another paired browser is already driving this phone. One browser drives a phone at a time |+| `NOT_CHECKED` | Daemon | `browsentic android` asked before any browser or app was watching for phones, so the Bridge has not looked yet |+| `CDP_ERROR` | Daemon | Chrome on the phone refused a command. The message carries Chrome's reason |+---## See also