companion: drive your real Chrome via an extension, not Playwright

[Anton-Horn]

Why

The companion drove the user's live Chrome by launching it with Playwright against their real profile. That's fundamentally unstable — Chrome wants to own its profile exclusively, so every recent fix fought the same root problem: profile locks (must Cmd-Q Chrome first), the mock-keychain making every site look logged-out, and stripping disruptive launch flags one at a time.

What

Run an MV3 extension inside the user's already-open Chrome and drive the active tab via chrome.debugger (CDP). Nothing is launched or locked, so that whole class of bugs disappears — and the user can keep browsing while the agent works.

Extension (chrome.debugger/CDP) ──localhost WS── zero CLI BridgeEngine ──/ws/companion── Server
       drives the active tab            (unchanged token/device/backoff)        (unchanged)

Only the laptop end of the link changes; the server is untouched. zero browser connect runs a loopback WebSocket bridge and forwards each BrowserAction to the extension, which executes it and returns a byte-identical BrowserResult.

The CDP action logic — a11y-tree snapshot with stable [ref=eN] ids, stale-ref recovery, incremental diff, replMode evaluate with console capture — is ported from server/lib/browser/host-pool.ts, plus the CDP-trivial actions (hover/scroll/back/forward/reload/select).

Changes

• extension/ — MV3 package: manifest.json, src/worker.ts, build.ts (bundles the worker → embedded asset module the CLI ships).
• bridge-engine.ts — loopback WS server, one-time-secret handshake, id-correlated command/response (90s timeout), 20s keepalive for the MV3 worker, hardened teardown.
• chrome-launch.ts — one-time quit + relaunch with --load-extension --restore-last-session (macOS full; Windows/Linux best-effort).
• runner.ts / companion.ts — use BridgeEngine; new connect UX and --no-launch.
• Deleted engine.ts + playwright-setup.ts; dropped Playwright from the CLI bundle.

Verified

• ✅ Both packages build and tsc --noEmit clean.
• ✅ Bridge wire protocol end-to-end via a simulated extension: secret handshake, command/response correlation, bad-secret rejection, keepalive, clean teardown (caught + fixed a wss.close() hang under bun).

Not covered by automated checks (needs a live browser)

The chrome.debugger actions against a real page, the one-time relaunch UX, >5-min service-worker survival, and the full round-trip through the server. The CDP logic is a line-for-line port of the already-working host-pool path.

Caveat

--load-extension isn't persistent across a full Chrome quit, so connect re-triggers the one-time relaunch whenever Chrome was fully closed since last time (it skips when the extension is already live). A Web Store / Load-unpacked install is the natural follow-up to remove even that.

🤖 Generated with Claude Code