# 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.

Nothing else to configure: castle is the built-in default
(`DEFAULT_REMOTE_CDP` in `src/cdp/endpoint.ts`).

## Choosing a browser

From inside a pi session:

```
/browser-target                 show the current target
/browser-target local           this machine's own browser
/browser-target default         back to castle
/browser-target host:port       somewhere else
```

The choice persists in `~/.pi/agent/browser-target.json` and applies to every
session on the machine, because the browser daemon is machine-wide. Switching
replaces that daemon process — it resolves its target once at startup and holds
the WebSocket to the old browser, so nothing short of a restart actually moves
you.

Or set it per-process:

| `BU_CDP_HTTP` | behaviour |
|---|---|
| unset | the stored choice, else castle, falling back to this machine's browser if unreachable |
| `host:port` | that endpoint; **unreachable is a hard error** |
| `local` (also `localhost`, `off`, `none`, `0`, `no`) | upstream behaviour — this machine's own browser |

Precedence is `BU_CDP_HTTP` > `/browser-target` > built-in default, so a one-off
`BU_CDP_HTTP=… pi` is never silently overridden by a choice made days ago. When
the variable is set, `/browser-target` says so instead of pretending to obey.

The asymmetry is deliberate. An explicit endpoint is an instruction, so failing
to reach it must not quietly automate a different browser — that would drive
your own signed-in Chrome instead of the shared one. The default is only a
preference, so a laptop away from the wire network still gets the local browser.

`/browser-status` names the resolved target and whether it is reachable. Note
the connection is **lazy**: nothing dials the browser until the first `browser_*`
tool runs, so a fresh session reports "not connected yet" rather than an error.

`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"'
```