Skip to content

feat: CDP attach mode — observe any DevTools-protocol browser #6

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Steel-tech merged 7 commits into from
Aug 6, 2026
Merged

feat: CDP attach mode — observe any DevTools-protocol browser #6

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
69c461f
docs: plan CDP attach mode
Steel-tech Aug 5, 2026
6e5ea40
feat(cdp): zero-dep DevTools protocol client with discovery and flat …
Steel-tech Aug 5, 2026
f4ccd01
feat(cdp): Renderer-facing attach backend with pinned-target policy
Steel-tech Aug 5, 2026
6d60a9d
feat(attach): CDP backend arbitration, frame pipeline, and ownership …
Steel-tech Aug 5, 2026
0f74cd2
feat(attach): event-driven console feed with OOPIF coverage and repla…
Steel-tech Aug 5, 2026
7064757
feat(attach): entry affordances, link handoff, and endpoint hygiene
Steel-tech Aug 5, 2026
06931ec
docs: document CDP attach mode, guarantees, and the a key
Steel-tech Aug 5, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
56 changes: 55 additions & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,8 @@ Conductor).
## Highlights

- **Shared agent sessions** — one isolated browser session per Herdr workspace.
- **Attach to any CDP browser** — observe a Playwright, Puppeteer, or Browser Use
run (or any Chrome started with `--remote-debugging-port`) without owning it.
- **Live push streaming** — frames, URL/title changes, console messages, and
page errors arrive over WebSocket, with transparent polling fallback.
- **Failed network requests** — 4xx/5xx and no-response xhr/fetch/document
Expand All @@ -37,7 +39,7 @@ Conductor).
| Component | Requirement | Notes |
| --- | --- | --- |
| Herdr | `>= 0.7.0` | Tested with Herdr 0.7.4 |
| Node.js | `>= 20` | Node 22+ enables live WebSocket streaming |
| Node.js | `>= 20` | Node 22+ enables live WebSocket streaming and CDP attach mode |
| agent-browser | Required | Tested with agent-browser 0.33.x; failed-request reporting needs the `network requests` command |
| chafa | Optional | ANSI rendering and streamed JPEGs in Kitty mode |
| carbonyl | Optional | Only required for the separate interactive Browse action |
Expand Down Expand Up @@ -137,6 +139,7 @@ Use these controls to drive the shared session directly:
| Input | Action |
| --- | --- |
| `u` | Open the address prompt; `https://` is assumed when omitted |
| `a` | Attach to a CDP endpoint (`http://host:port` or `ws://…`) |
| Click the screenshot | Send real Chrome mouse move/down/up events at that page coordinate |
| `i` | Type into the currently focused page element |
| `b` / `f` | Navigate backward / forward |
Expand Down Expand Up @@ -213,6 +216,57 @@ identical failure paints once and stays collapsed until it has been quiet for
sessions the feed turns itself off with a one-time note once the daemon's
request log outgrows the pane's read buffer.

## Attach to any CDP browser

The pane can observe a browser it does not own. Point it at a Chrome DevTools
Protocol endpoint and it renders that browser's page, streams its console and
network failures, and forwards your clicks and keystrokes — while your
automation client keeps driving.

```sh
# the browser your automation already runs, with a debugging port
chrome --remote-debugging-port=9222

# tell the pane where to look (either source works)
export HERDR_BROWSER_CDP_URL=http://127.0.0.1:9222
printf 'http://127.0.0.1:9222\n' > "$(herdr plugin config-dir structupath.browser)/cdp-url"
```

Press `a` in the pane to attach at runtime. `u` still means "navigate" — the
keys are separate because `localhost:9222` is a valid destination as well as a
valid endpoint.

Launcher recipes: Playwright `chromium.launch({args:['--remote-debugging-port=9222']})`,
Puppeteer the same `args`, Browser Use its `chrome_remote_debugging_port` option.
A default launch often uses a pipe transport with no TCP port — the port has to
be requested explicitly.

### What attach mode guarantees

- **It never owns anything.** No target is created or closed, no viewport or
device emulation is set (your automation client owns those — a pane that
overrode them would fight the client it is meant to observe), and quitting
the pane closes only its own screencast and socket.
- **It opens no port.** The pane dials out to the endpoint you name. There is
no gateway, proxy, or listening socket to secure.
- **Endpoint tokens stay secret.** A DevTools URL's path is a capability token;
the pane displays and logs `host:port` only.
- **One honest footprint:** the console feed calls `Runtime.enable`, which is
observable by the page and is avoided by stealth automation stacks. Set
`consoleTier` to `log-only` to skip it — network failures and violations
still surface through the Log domain.
Comment on lines +254 to +257

@coderabbitai coderabbitai Bot Aug 5, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

consoleTier is not user-settable.

The text tells the reader to set consoleTier to log-only. consoleTier is only an option of makeCdpBrowser, and the renderer calls makeCdpBrowser(endpoint) with no options at bin/renderer.mjs lines 568 and 778. No environment variable or config file reaches it. Either expose it (for example HERDR_BROWSER_CDP_CONSOLE_TIER plus a cdp-console-tier config file) or describe the current behavior without an instruction the reader cannot perform.

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@README.md` around lines 254 - 257, Update the README section describing the
console feed so it no longer instructs users to set the inaccessible consoleTier
option. Describe the current behavior as implemented by
makeCdpBrowser(endpoint), or expose a supported configuration path before
documenting user configuration; keep the guidance consistent with the renderer’s
existing invocation.


### What it shows

Failed requests appear with Chrome's own error text — `net::ERR_CONNECTION_REFUSED`
rather than a bare status — alongside console output, uncaught exceptions, and
failures from embedded iframes and workers. One blind spot by design: a request
that hangs without ever failing produces no CDP event, so attach mode cannot
report it the way the agent-browser polling feed's timeout heuristic does.

Attach mode needs Node 22 or newer (for the built-in WebSocket client); the pane
says so plainly on older Node and keeps working in agent-browser mode.

## Session model

By default, each Herdr workspace uses:
Expand Down
Loading