From bfb533fc9a829819b9dd425607101d40c676d45c Mon Sep 17 00:00:00 2001 From: Igor Soarez Date: Tue, 28 Jul 2026 21:48:33 +0100 Subject: docs: fork notes — why BU_CDP_HTTP exists, install, upstream merges MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Kept out of README.md so upstream's own README continues to merge cleanly. --- FORK.md | 92 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 92 insertions(+) create mode 100644 FORK.md diff --git a/FORK.md b/FORK.md new file mode 100644 index 0000000..6483188 --- /dev/null +++ b/FORK.md @@ -0,0 +1,92 @@ +# Fork notes + +A fork of [amankumarsingh77/pi-browser-harness](https://github.com/amankumarsingh77/pi-browser-harness), +carrying one patch: `BU_CDP_HTTP`, which lets pi drive a browser on **another +host**. + +Hosted on castle rather than a public forge — deliberately not published to npm +and not proposed upstream. + +``` +origin 10.88.0.25:repos/pi-browser-harness.git (castle, canonical) +upstream https://github.com/amankumarsingh77/pi-browser-harness.git +``` + +## Why the patch exists + +Upstream can only reach a browser on localhost: + +- the pi extension always goes through the daemon (`src/index.ts` uses + `createDaemonTransport`) +- the daemon resolves Chrome with `discoverWsUrl()` (`src/daemon/bridge.ts`) +- that probe is hardcoded to `127.0.0.1` (`src/cdp/discovery.ts`) +- `BU_CDP_WS`, the documented remote escape hatch, is read only by the + in-process client (`src/client.ts`) — which that path never touches, so it has + no effect on the extension + +Without the patch the only option is relaying the remote browser onto localhost +(ssh tunnel or socat), which means a local service on every client machine. + +`BU_CDP_HTTP="host:port"` is resolved inside `discoverEndpoint()`, so daemon and +client both honour it. It names an **HTTP** endpoint, not a WebSocket URL, +because it is re-resolved on every discovery call — the browser UUID is re-read +after the remote browser restarts. Chrome re-mints that UUID on every launch, so +a pinned WebSocket URL breaks as soon as the remote browser is recycled (castle +recycles Chrome hourly; see `cloud-setup/macos/chrome-cdp.sh`). + +## Install + +``` +pi install ssh://sz@10.88.0.25/Users/sz/repos/pi-browser-harness.git +``` + +Clones to `~/.pi/agent/git/10.88.0.25/Users/sz/repos/pi-browser-harness`. The +same identifier works on macOS and Linux, which a local-path install could not +do — pi records those by resolved absolute path, and `settings.json` is shared +across hosts via the dotfiles symlink. + +Then point it at the browser: + +``` +export BU_CDP_HTTP=10.88.0.25:9223 +``` + +`pi update` reconciles the clone to the configured ref rather than pulling stock +from npm, so the patch cannot be silently reverted — which is exactly what the +previous approach (patching `node_modules` in place) suffered from. + +## Taking upstream releases + +The patch is a single commit on top of an upstream tag, so rebasing keeps it +that way: + +``` +git fetch upstream +git rebase upstream/main # or: upstream/main --onto a specific tag +git push --force-with-lease origin master +``` + +Conflicts to expect are confined to `src/cdp/discovery.ts` (the +`discoverEndpoint()` short-circuit and the `host` parameter on +`queryLiveWsUrl`) and `src/setup.ts` (the skipped local-process precondition). +If upstream ever reworks daemon discovery, re-check whether the patch is still +needed at all. + +Note the branch here is `master` (matching the other repos on castle) while +upstream uses `main`. + +## Verifying after a merge + +With a browser exposed at `$BU_CDP_HTTP`: + +``` +pi -p --tools browser_setup,browser_navigate,browser_page_info \ + "Call browser_setup, then browser_navigate to https://example.com/ and browser_page_info." +``` + +Confirm from outside that the remote browser really moved, rather than trusting +the agent's own report: + +``` +curl -s http://10.88.0.25:9223/json/list | grep '"url"' +``` -- cgit v1.2.3