morluto/rea

Fork 0

mirror of https://github.com/morluto/rea.git synced 2026-11-05 06:45:22 +00:00

[PR #2287] [MERGED] docs(browser): clarify attach coverage and Chromium setup #5141

New issue

Closed

opened 2026-10-31 01:04:18 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-31 01:04:18 +00:00

Owner

📋 Pull Request Information

Original PR: https://github.com/morluto/rea/pull/2287
Author: @0xRafie
Created: 10/12/2026
Status: ✅ Merged
Merged: 10/13/2026
Merged by: @morluto

Base: main ← Head: docs/browser-observation-practicalities

📝 Commits (2)

98bb7f1 docs(browser): clarify attach coverage and Chromium setup
d9868e7 docs(browser): distinguish discovery transport and response failures

📊 Changes

1 file changed (+22 additions, -1 deletions)

View changed files

📝 docs/browser-observation.md (+22 -1)

📄 Description

Summary

Three practical gaps in docs/browser-observation.md that an agent or user runs into the first time they attach to a page:

Attach coverage. The doc already says network and console coverage starts at attach. It does not say that scripts the page parsed before attach are still reported. Because of that, a capture can list export.js under scripts while network.requests has no request that fetched it, which looks contradictory until you know why.
Starting a browser that is not google-chrome. It was not clear that any Chromium-family browser works, or where the executable lives on macOS (inside the .app bundle). Fedora's binary name is chromium-browser. There is also a container pitfall: headed Chromium under Xvfb keeps running, but its DevTools port never opens when GL libraries are missing.
Browsers without an HTTP discovery endpoint. An agent browser that drives CDP internally (over --remote-debugging-pipe or a private channel) gives list_browser_targets nothing to attach to. The doc now says to reproduce the flow in a Chromium-family browser started with --remote-debugging-port.

No linked issue. This only corrects and clarifies documentation within existing boundaries. Related design discussion about attaching without an HTTP discovery endpoint: #2288.

Problem and expected behavior

Without click: inspect-web-page --include-script-sources on the notes-web demo returns export.js in scripts, network.requests: [], and prior_activity_available: false. The current text explains the empty network array but not why the script is there. Expected: the doc explains both.
Pointing REA at a loopback port with no discovery endpoint reports endpoint_unreachable. A browser driven over a pipe or a private channel has no such endpoint at all. Expected: the doc says REA needs the HTTP discovery endpoint and what to do instead.

Change and scope

The change is documentation only, with 20 added lines in docs/browser-observation.md:

"Start a browser": a Chromium-family note with macOS .app executable paths, Fedora's chromium-browser, the HTTP discovery endpoint requirement with the workaround, and the minimal-container GL libraries note.
"Completeness and limits": two sentences next to the prior_activity_available paragraph saying that pre-attach scripts are still reported under scripts, unlike network and console.

Intentionally not included: any runtime change, and any attach path that does not use HTTP discovery (that would be a separate feature discussion).

Contribution scope: documentation correction within existing boundaries; maintainer scope decision not applicable.

Contract and boundary impact

Semantic owner and earliest changed stage: browser observation docs (docs/browser-observation.md); no code stage changed.
Contribution scope fit and linked maintainer decision: not applicable (documentation correction within existing boundaries).
CLI and MCP/tool-catalog contract: none.
Provider, bridge, target-format, or platform compatibility: none. Documents existing Chromium-family behavior.
Evidence, artifact, provenance, or reconstruction contract: none. Describes existing scripts / network / prior_activity_available output.
Target selection, authority, upstream behavior, and cleanup details (if applicable): not applicable.
Generated metadata (docs/public/product-catalog.json), package, or installation impact: none. Skill metadata.version untouched (no skill change).

Expected effects:

Read existing files or captured data.
Launch or attach to a process.
Inject instrumentation or run scripts/code.
Change process memory, registers, files, or configuration.
Contact network services.
Recover protected code or work around protections.
Documentation or usability only; no target interaction.
Not sure yet; investigation or maintainer guidance needed.

Evidence and regression coverage

Tests added or updated: none (documentation only).
Base reproduction or other evidence (executed with the CLI built from main at d96550f, REA 6.4.0, macOS 26). The demo was website/public/examples/notes-web/, served on 127.0.0.1. Browsers ran headless with a fresh profile each:
- Chrome 154.0.8037.99, --remote-debugging-port=9242. With the page fully loaded and no click, I ran rea inspect-web-page http://127.0.0.1:9242 <target> --include-script-sources --observation-ms 1000 --json:
  - scripts.items[0].url = .../notes-web/export.js, source included (length 925).
  - network.requests = [], so there is no notes.json request and no request for export.js itself.
  - network.prior_activity_available and console.prior_activity_available are both false.
  - completeness.attach_limited_sections includes network_requests and console_events.
- Brave 155.1.97.56 (product Chrome/155.0.8059.40), --remote-debugging-port=9244: rea list-browser-targets http://127.0.0.1:9244 --json listed the notes-web page target, the same as Chrome.
- Nothing listening on 127.0.0.1:9246 (checked with lsof). rea list-browser-targets http://127.0.0.1:9246 --json exited 1 with:
```
{"error":"Browser observation failed","code":"provider_unavailable","category":"unavailable","message":"list_browser_targets could not reach the selected loopback debugging endpoint. Verify that the target process is running with debugging enabled and that the endpoint's port matches it, then retry.","retryable":true,"remediation":{"action":"list_browser_targets could not reach the selected loopback debugging endpoint. Verify that the target process is running with debugging enabled and that the endpoint's port matches it, then retry."},"details":{"operation":"list_browser_targets","reason":"endpoint_unreachable"}}
```
- Minimal-container note: verified earlier on Fedora 44 (Docker) + Xvfb + headed Chromium 154. The browser process stayed up but the DevTools port never listened until libglvnd-gles, mesa-libEGL and mesa-dri-drivers were installed. That check used plain CDP scripts against the port, not REA itself. The chromium-browser binary name comes from the same Fedora setup.
User-visible CLI/MCP output (if applicable): the error above, quoted for reference. No output changes.
Remaining proof gaps:
- I did not launch a browser with --remote-debugging-pipe. The pipe statement relies on that flag providing no TCP discovery endpoint. The endpoint_unreachable result was observed for a port with nothing listening.
- I did not run REA itself on Fedora or inside a container.
- On macOS, Brave was only checked with list-browser-targets, not a full inspection.

For evidence-bearing changes: not applicable (documentation only).

Validation performed

npm run check: passed (6/6 turbo tasks; module boundaries and architecture guards passed).
npm run docs:check: passed.
npm run docs:build: passed (only the existing chunk-size warning).
The REA CLI runs listed under Evidence were all executed as described.
Base: rebased onto main ec2d251 before opening. npm run check and npm run docs:check re-ran there and passed. docs:build and the CLI runs ran on the previous base d96550f; the four commits in between do not touch this page or the browser provider.

Compatibility, safety, and release

Breaking changes or migration steps: none.
Real Hopper/Ghidra, browser, or OS coverage: macOS 26 headless Chrome 154 and Brave 155 with REA. The Fedora 44 container finding was checked without REA (see above).
Package or release metadata impact: none. Skill metadata.version left at its current value, because no skill file changed and no check required a bump.
Security, privacy, process, or containment review: none. The added text keeps the existing advice to use a dedicated profile and loopback-only debugging.

Before merge

This PR addresses a concrete problem or an agreed enhancement.
Material scope and authority questions are resolved, and any required maintainer scope decision covers the final diff.
The PR has one focused outcome and the title follows type(scope): outcome.
Related issue is linked, or the reason for not linking one is stated above.
Tests cover changed observable behavior and meaningful failure paths. (Not applicable: documentation only.)
Owning docs, contracts, and generated metadata are updated where needed.
User-visible CLI/MCP changes include representative output. (Not applicable: no CLI/MCP change; the existing error output is quoted above.)
I checked the final diff for secrets, unrelated cleanup, and unsupported claims.

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/morluto/rea/pull/2287 **Author:** [@0xRafie](https://github.com/0xRafie) **Created:** 10/12/2026 **Status:** ✅ Merged **Merged:** 10/13/2026 **Merged by:** [@morluto](https://github.com/morluto) **Base:** `main` ← **Head:** `docs/browser-observation-practicalities` --- ### 📝 Commits (2) - [`98bb7f1`](https://github.com/morluto/rea/commit/98bb7f183e30aacaa3044f4181f7df7528e9ac0e) docs(browser): clarify attach coverage and Chromium setup - [`d9868e7`](https://github.com/morluto/rea/commit/d9868e770910b9fd4a939c33f489eed16710dc43) docs(browser): distinguish discovery transport and response failures ### 📊 Changes **1 file changed** (+22 additions, -1 deletions) <details> <summary>View changed files</summary> 📝 `docs/browser-observation.md` (+22 -1) </details> ### 📄 Description ## Summary Three practical gaps in `docs/browser-observation.md` that an agent or user runs into the first time they attach to a page: 1. **Attach coverage.** The doc already says network and console coverage starts at attach. It does not say that scripts the page parsed *before* attach are still reported. Because of that, a capture can list `export.js` under `scripts` while `network.requests` has no request that fetched it, which looks contradictory until you know why. 2. **Starting a browser that is not `google-chrome`.** It was not clear that any Chromium-family browser works, or where the executable lives on macOS (inside the `.app` bundle). Fedora's binary name is `chromium-browser`. There is also a container pitfall: headed Chromium under Xvfb keeps running, but its DevTools port never opens when GL libraries are missing. 3. **Browsers without an HTTP discovery endpoint.** An agent browser that drives CDP internally (over `--remote-debugging-pipe` or a private channel) gives `list_browser_targets` nothing to attach to. The doc now says to reproduce the flow in a Chromium-family browser started with `--remote-debugging-port`. No linked issue. This only corrects and clarifies documentation within existing boundaries. Related design discussion about attaching without an HTTP discovery endpoint: #2288. ## Problem and expected behavior - Without click: `inspect-web-page --include-script-sources` on the notes-web demo returns `export.js` in `scripts`, `network.requests: []`, and `prior_activity_available: false`. The current text explains the empty network array but not why the script is there. Expected: the doc explains both. - Pointing REA at a loopback port with no discovery endpoint reports `endpoint_unreachable`. A browser driven over a pipe or a private channel has no such endpoint at all. Expected: the doc says REA needs the HTTP discovery endpoint and what to do instead. ## Change and scope The change is documentation only, with 20 added lines in `docs/browser-observation.md`: - "Start a browser": a Chromium-family note with macOS `.app` executable paths, Fedora's `chromium-browser`, the HTTP discovery endpoint requirement with the workaround, and the minimal-container GL libraries note. - "Completeness and limits": two sentences next to the `prior_activity_available` paragraph saying that pre-attach scripts are still reported under `scripts`, unlike network and console. Intentionally not included: any runtime change, and any attach path that does not use HTTP discovery (that would be a separate feature discussion). Contribution scope: documentation correction within existing boundaries; maintainer scope decision not applicable. ## Contract and boundary impact - Semantic owner and earliest changed stage: browser observation docs (`docs/browser-observation.md`); no code stage changed. - Contribution scope fit and linked maintainer decision: not applicable (documentation correction within existing boundaries). - CLI and MCP/tool-catalog contract: none. - Provider, bridge, target-format, or platform compatibility: none. Documents existing Chromium-family behavior. - Evidence, artifact, provenance, or reconstruction contract: none. Describes existing `scripts` / `network` / `prior_activity_available` output. - Target selection, authority, upstream behavior, and cleanup details (if applicable): not applicable. - Generated metadata (`docs/public/product-catalog.json`), package, or installation impact: none. Skill `metadata.version` untouched (no skill change). Expected effects: - [ ] Read existing files or captured data. - [ ] Launch or attach to a process. - [ ] Inject instrumentation or run scripts/code. - [ ] Change process memory, registers, files, or configuration. - [ ] Contact network services. - [ ] Recover protected code or work around protections. - [x] Documentation or usability only; no target interaction. - [ ] Not sure yet; investigation or maintainer guidance needed. ## Evidence and regression coverage - Tests added or updated: none (documentation only). - Base reproduction or other evidence (executed with the CLI built from `main` at `d96550f`, REA 6.4.0, macOS 26). The demo was `website/public/examples/notes-web/`, served on `127.0.0.1`. Browsers ran headless with a fresh profile each: - Chrome 154.0.8037.99, `--remote-debugging-port=9242`. With the page fully loaded and no click, I ran `rea inspect-web-page http://127.0.0.1:9242 <target> --include-script-sources --observation-ms 1000 --json`: - `scripts.items[0].url` = `.../notes-web/export.js`, source included (length 925). - `network.requests` = `[]`, so there is no `notes.json` request and no request for `export.js` itself. - `network.prior_activity_available` and `console.prior_activity_available` are both `false`. - `completeness.attach_limited_sections` includes `network_requests` and `console_events`. - Brave 155.1.97.56 (product `Chrome/155.0.8059.40`), `--remote-debugging-port=9244`: `rea list-browser-targets http://127.0.0.1:9244 --json` listed the notes-web page target, the same as Chrome. - Nothing listening on `127.0.0.1:9246` (checked with `lsof`). `rea list-browser-targets http://127.0.0.1:9246 --json` exited 1 with: ```json {"error":"Browser observation failed","code":"provider_unavailable","category":"unavailable","message":"list_browser_targets could not reach the selected loopback debugging endpoint. Verify that the target process is running with debugging enabled and that the endpoint's port matches it, then retry.","retryable":true,"remediation":{"action":"list_browser_targets could not reach the selected loopback debugging endpoint. Verify that the target process is running with debugging enabled and that the endpoint's port matches it, then retry."},"details":{"operation":"list_browser_targets","reason":"endpoint_unreachable"}} ``` - Minimal-container note: verified earlier on Fedora 44 (Docker) + Xvfb + headed Chromium 154. The browser process stayed up but the DevTools port never listened until `libglvnd-gles`, `mesa-libEGL` and `mesa-dri-drivers` were installed. That check used plain CDP scripts against the port, not REA itself. The `chromium-browser` binary name comes from the same Fedora setup. - User-visible CLI/MCP output (if applicable): the error above, quoted for reference. No output changes. - Remaining proof gaps: - I did not launch a browser with `--remote-debugging-pipe`. The pipe statement relies on that flag providing no TCP discovery endpoint. The `endpoint_unreachable` result was observed for a port with nothing listening. - I did not run REA itself on Fedora or inside a container. - On macOS, Brave was only checked with `list-browser-targets`, not a full inspection. For evidence-bearing changes: not applicable (documentation only). ## Validation performed - `npm run check`: passed (6/6 turbo tasks; module boundaries and architecture guards passed). - `npm run docs:check`: passed. - `npm run docs:build`: passed (only the existing chunk-size warning). - The REA CLI runs listed under Evidence were all executed as described. - Base: rebased onto main `ec2d251` before opening. `npm run check` and `npm run docs:check` re-ran there and passed. `docs:build` and the CLI runs ran on the previous base `d96550f`; the four commits in between do not touch this page or the browser provider. ## Compatibility, safety, and release - Breaking changes or migration steps: none. - Real Hopper/Ghidra, browser, or OS coverage: macOS 26 headless Chrome 154 and Brave 155 with REA. The Fedora 44 container finding was checked without REA (see above). - Package or release metadata impact: none. Skill `metadata.version` left at its current value, because no skill file changed and no check required a bump. - Security, privacy, process, or containment review: none. The added text keeps the existing advice to use a dedicated profile and loopback-only debugging. ## Before merge - [x] This PR addresses a concrete problem or an agreed enhancement. - [x] Material scope and authority questions are resolved, and any required maintainer scope decision covers the final diff. - [x] The PR has one focused outcome and the title follows `type(scope): outcome`. - [x] Related issue is linked, or the reason for not linking one is stated above. - [ ] Tests cover changed observable behavior and meaningful failure paths. (Not applicable: documentation only.) - [x] Owning docs, contracts, and generated metadata are updated where needed. - [ ] User-visible CLI/MCP changes include representative output. (Not applicable: no CLI/MCP change; the existing error output is quoted above.) - [x] I checked the final diff for secrets, unrelated cleanup, and unsupported claims. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

bsakaguchi

2026-10-31 01:04:18 +00:00

closed this issue
added the
pull-request
label

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

morluto/rea#5141

No description provided.

Rows
Columns