[PR #917] [MERGED] feat(browser): attribute native execution and listener sources #2345

New issue

Closed

opened 2026-10-16 21:17:37 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-16 21:17:37 +00:00

Owner

📋 Pull Request Information

Original PR: https://github.com/morluto/rea/pull/917
Author: @N0zoM1z0
Created: 10/7/2026
Status: ✅ Merged
Merged: 10/7/2026
Merged by: @N0zoM1z0

Base: main ← Head: feat/web-runtime-attribution

📝 Commits (10+)

b963cc7 feat(browser): attribute native execution and listener sources
0ab68aa fix(browser): preserve runtime identity and settle fixture cleanup
14d18d8 chore: merge main and regenerate combined catalog metadata
f54536b fix(browser): settle invalid events and preserve document evidence
8ad19f8 chore: sync main and preserve combined website runtime metadata
d1da92a chore: sync latest main before runtime verification
e8b37b2 fix(browser): end detached target windows and sanitize coverage identities
955a65f fix(browser): retain final sample metadata and settle fatal protocol failures
3cbc438 chore: sync current main before runtime review
907f922 fix(browser): require default execution worlds for website attribution

📊 Changes

82 files changed (+5392 additions, -85 deletions)

View changed files

➕ .github/workflows/real-web-runtime.yml (+54 -0)
📝 README.md (+5 -1)
📝 README_ar.md (+1 -1)
📝 README_ja.md (+1 -1)
📝 README_ko.md (+1 -1)
📝 README_zh.md (+1 -1)
📝 docs/architecture.mermaid (+1 -1)
📝 docs/product-catalog.json (+14 -8)
📝 docs/testing.md (+16 -0)
📝 docs/verification/managed-conformance-manifest.json (+2 -2)
➕ docs/web-runtime.md (+61 -0)
📝 package.json (+2 -1)
➕ scripts/fixtures/browser-runtime-site.mjs (+51 -0)
➕ scripts/lib/browser-runtime-e2e.mjs (+445 -0)
➕ scripts/lib/browser-runtime-fixture-lifecycle.mjs (+153 -0)
➕ scripts/lib/browser-runtime-selector-e2e.mjs (+49 -0)
➕ scripts/lib/browser-runtime-termination-e2e.mjs (+104 -0)
➕ scripts/lib/browser-runtime-world-e2e.mjs (+34 -0)
📝 scripts/lib/catalog-builders.mjs (+5 -1)
📝 scripts/lib/catalog-core.mjs (+1 -0)

...and 62 more files

📄 Description

Summary

Closes #881. Refs #774.

Add observe_web_execution / observe-web-execution: one finite externally driven window using native V8 precise coverage, actual armed progress, resetting counter effects, exact session script IDs, retained UTF-16 ranges/counts, complete source text/digests, and request initiator stacks.
Add inspect_web_event_listeners / inspect-web-event-listeners: inspect direct native listeners on the first selected main-document CSS match, without invoking handlers or evaluating page JavaScript.
Compose both CLI/MCP surfaces through a narrow WebRuntimePort; keep CDP schemas, source/context identity, requests, windows, coverage, listeners and cleanup in separate provider modules.
Register cleanup before instrumentation commands. Cancellation awaits stopping coverage, releasing only owned remote objects, disabling owned domains and detachment. Unknown cleanup is a meaningful error with the target, failed commands and previous reason.
Add a conditional real Chrome CI lane; ordinary static/unit gates do not install or acquire Chrome. Update source inventories and regenerate canonical catalogs/skill metadata.

Evidence semantics and bounds

Repeated or synthetic URLs never establish source identity. Loaded scripts missing from a sample remain execution-unknown. Native Chrome can return function-only coverage during subsequent windows even with detailed: true; preserve is_block_coverage and never invent zero branches. Embedded async stacks and unresolved parent IDs are retained; initiator association does not prove UI causality. Navigation ends the document-scoped window with unavailable final coverage.

Per-message 64 MiB, metadata 8 MiB per collection, complete source text 32 MiB, individual commands and completion phase 20 s, independent cleanup 5 s. Oversize or malformed captures do not return partial success. The existing page/browser remain externally owned; REA does not control their resource usage. Child frames, workers/service workers and WebAssembly remain outside these tools.

Public MCP examples

{"name":"observe_web_execution","arguments":{"cdp_endpoint":"http://127.0.0.1:9222","target_id":"selected-page","observation_ms":10000}}

Perform the external action after negotiated browser_execution armed progress. No extra approval flag is required.

{"name":"inspect_web_event_listeners","arguments":{"cdp_endpoint":"http://127.0.0.1:9222","target_id":"selected-page","selector":"#submit"}}

Both return inline Evidence with normalized results and the provided MCP session writer.

Verification of current head

Current head 80ca3d942d319b3150080609045934d98baf0bdc, including main a6575572; generated contract conflicts resolved by regenerating from the combined source inventory (133 tools).

After the final main merge: 12 tests / 3 files passed, covering the canonical inventory, all advertised SDK schemas and inline runtime Evidence; docs:check and pre-push check:fast passed. Browser implementation is unchanged from the installed package tested below.
Latest review regression lane: 27 tests / 8 files passed; latest main affected source tests: 102 tests / 4 files passed. Earlier related focused lane: 48 tests / 9 files passed. After the latest main merge, 18 tests / 4 files passed for the world ownership regressions, all advertised SDK JSON schemas, session-owned Evidence and canonical catalog. These overlapping lanes are not summed.
npm run check:fast, npm run docs:check, npm run knip: passed. Static lint includes provider module boundaries.
Real Chrome 153 / Linux x64 / Node 24: eight public CLI/MCP cases passed, both working build and isolated installed tarball. Checks exact UTF-8 digests/UTF-16 ranges, Unicode/CRLF, distinct same-URL script IDs, block/function-only semantics, native listener locations, request initiators, same-document navigation, inert sourceURL declarations, actually executed isolated-world functions excluded, actual armed progress and prompt selected-target termination, and native invalid-selector classification through both CLI and MCP. Caller page remains open; verifier descendants are empty.
Final tarball: 1,411,507 bytes / 900 entries; _reference, .codex and node_modules absent. Isolated installation; no host defaults changed.
No new Hopper/Ghidra or non-Linux browser claim; corresponding real verification not performed. All runtime fixture data are synthetic. One CPU and bounded Node heaps used.

Review fixes

Revalidate known source identities after asynchronous reads and final assertions; downgrade cached source/frame associations and final coverage/initiator/inventory joins when ownership becomes ambiguous. Six source-read/completion regressions pass.
Translate only Chromium's exact native DOM selector syntax rejection into an input error; other command/transport failures preserve their cause. Three producer regressions and both native public adapters pass.
Require positive default-world metadata plus main-frame identity; preserve reported context/world metadata for referenced sources, exclude isolated/worker/unknown/conflicting worlds. Four before-fix producer failures and real Chrome old-installed-package contamination reproduced; six new negative world cases pass.
Loader availability transitions cannot establish document identity; stable loader permits same-document history changes within allowed origins.
Preserve unowned producer metadata without claiming source/frame ownership. Invalid events terminate without returning partial evidence.
Native flat-session root detachment matches params.sessionId; foreign sessions are ignored, and prearming termination never reports armed. Cleanup failures retain target identity, failed commands and original reason.
Known initiator/resource URLs remove transport userinfo; inert sourceURL declarations and unknown names are preserved. Source, coverage and initiator joins use session script identity rather than URL guesses.
Keep source metadata open through the final resetting sample and freeze at that cutoff. Reject fatal raw protocol errors even with no outstanding commands. Recheck source collector failures after final listener assertions.
New final-collection regressions failed before the fix; existing observer compatibility and actual SDK/schema boundaries pass.

Full latest-head CI is required before merge.

_{🔄 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/917 **Author:** [@N0zoM1z0](https://github.com/N0zoM1z0) **Created:** 10/7/2026 **Status:** ✅ Merged **Merged:** 10/7/2026 **Merged by:** [@N0zoM1z0](https://github.com/N0zoM1z0) **Base:** `main` ← **Head:** `feat/web-runtime-attribution` --- ### 📝 Commits (10+) - [`b963cc7`](https://github.com/morluto/rea/commit/b963cc738ded135c272e3da91880542980e360f5) feat(browser): attribute native execution and listener sources - [`0ab68aa`](https://github.com/morluto/rea/commit/0ab68aa5545c876145ea10c5053b716bb96df972) fix(browser): preserve runtime identity and settle fixture cleanup - [`14d18d8`](https://github.com/morluto/rea/commit/14d18d83605ffa59700fab952194b823902de24a) chore: merge main and regenerate combined catalog metadata - [`f54536b`](https://github.com/morluto/rea/commit/f54536b0cb63730d5f5845486aa4fb7e4f124a25) fix(browser): settle invalid events and preserve document evidence - [`8ad19f8`](https://github.com/morluto/rea/commit/8ad19f8ca2adf81a2c1351b5e62cbc6ce6ae7c95) chore: sync main and preserve combined website runtime metadata - [`d1da92a`](https://github.com/morluto/rea/commit/d1da92a59cc74da30425b7193d07994ada2bd2b3) chore: sync latest main before runtime verification - [`e8b37b2`](https://github.com/morluto/rea/commit/e8b37b2de568c9d7cc77025879b1f4f094c2e897) fix(browser): end detached target windows and sanitize coverage identities - [`955a65f`](https://github.com/morluto/rea/commit/955a65fbbe63582bb11a0c156e81e30632e33a48) fix(browser): retain final sample metadata and settle fatal protocol failures - [`3cbc438`](https://github.com/morluto/rea/commit/3cbc4389889ae613c5277adcb17f6f8e3f9c3709) chore: sync current main before runtime review - [`907f922`](https://github.com/morluto/rea/commit/907f922d4124d67c096693e047e9fab6d7f5f250) fix(browser): require default execution worlds for website attribution ### 📊 Changes **82 files changed** (+5392 additions, -85 deletions) <details> <summary>View changed files</summary> ➕ `.github/workflows/real-web-runtime.yml` (+54 -0) 📝 `README.md` (+5 -1) 📝 `README_ar.md` (+1 -1) 📝 `README_ja.md` (+1 -1) 📝 `README_ko.md` (+1 -1) 📝 `README_zh.md` (+1 -1) 📝 `docs/architecture.mermaid` (+1 -1) 📝 `docs/product-catalog.json` (+14 -8) 📝 `docs/testing.md` (+16 -0) 📝 `docs/verification/managed-conformance-manifest.json` (+2 -2) ➕ `docs/web-runtime.md` (+61 -0) 📝 `package.json` (+2 -1) ➕ `scripts/fixtures/browser-runtime-site.mjs` (+51 -0) ➕ `scripts/lib/browser-runtime-e2e.mjs` (+445 -0) ➕ `scripts/lib/browser-runtime-fixture-lifecycle.mjs` (+153 -0) ➕ `scripts/lib/browser-runtime-selector-e2e.mjs` (+49 -0) ➕ `scripts/lib/browser-runtime-termination-e2e.mjs` (+104 -0) ➕ `scripts/lib/browser-runtime-world-e2e.mjs` (+34 -0) 📝 `scripts/lib/catalog-builders.mjs` (+5 -1) 📝 `scripts/lib/catalog-core.mjs` (+1 -0) _...and 62 more files_ </details> ### 📄 Description ## Summary Closes #881. Refs #774. - Add `observe_web_execution` / `observe-web-execution`: one finite externally driven window using native V8 precise coverage, actual armed progress, resetting counter effects, exact session script IDs, retained UTF-16 ranges/counts, complete source text/digests, and request initiator stacks. - Add `inspect_web_event_listeners` / `inspect-web-event-listeners`: inspect direct native listeners on the first selected main-document CSS match, without invoking handlers or evaluating page JavaScript. - Compose both CLI/MCP surfaces through a narrow `WebRuntimePort`; keep CDP schemas, source/context identity, requests, windows, coverage, listeners and cleanup in separate provider modules. - Register cleanup before instrumentation commands. Cancellation awaits stopping coverage, releasing only owned remote objects, disabling owned domains and detachment. Unknown cleanup is a meaningful error with the target, failed commands and previous reason. - Add a conditional real Chrome CI lane; ordinary static/unit gates do not install or acquire Chrome. Update source inventories and regenerate canonical catalogs/skill metadata. ## Evidence semantics and bounds Repeated or synthetic URLs never establish source identity. Loaded scripts missing from a sample remain execution-unknown. Native Chrome can return function-only coverage during subsequent windows even with `detailed: true`; preserve `is_block_coverage` and never invent zero branches. Embedded async stacks and unresolved parent IDs are retained; initiator association does not prove UI causality. Navigation ends the document-scoped window with unavailable final coverage. Per-message 64 MiB, metadata 8 MiB per collection, complete source text 32 MiB, individual commands and completion phase 20 s, independent cleanup 5 s. Oversize or malformed captures do not return partial success. The existing page/browser remain externally owned; REA does not control their resource usage. Child frames, workers/service workers and WebAssembly remain outside these tools. ## Public MCP examples ```json {"name":"observe_web_execution","arguments":{"cdp_endpoint":"http://127.0.0.1:9222","target_id":"selected-page","observation_ms":10000}} ``` Perform the external action after negotiated `browser_execution` armed progress. No extra approval flag is required. ```json {"name":"inspect_web_event_listeners","arguments":{"cdp_endpoint":"http://127.0.0.1:9222","target_id":"selected-page","selector":"#submit"}} ``` Both return inline Evidence with normalized results and the provided MCP session writer. ## Verification of current head Current head `80ca3d942d319b3150080609045934d98baf0bdc`, including main `a6575572`; generated contract conflicts resolved by regenerating from the combined source inventory (133 tools). - After the final main merge: **12 tests / 3 files passed**, covering the canonical inventory, all advertised SDK schemas and inline runtime Evidence; `docs:check` and pre-push `check:fast` passed. Browser implementation is unchanged from the installed package tested below. - Latest review regression lane: **27 tests / 8 files passed**; latest main affected source tests: **102 tests / 4 files passed**. Earlier related focused lane: **48 tests / 9 files passed**. After the latest main merge, **18 tests / 4 files passed** for the world ownership regressions, all advertised SDK JSON schemas, session-owned Evidence and canonical catalog. These overlapping lanes are not summed. - `npm run check:fast`, `npm run docs:check`, `npm run knip`: passed. Static lint includes provider module boundaries. - Real Chrome 153 / Linux x64 / Node 24: **eight public CLI/MCP cases passed**, both working build and isolated installed tarball. Checks exact UTF-8 digests/UTF-16 ranges, Unicode/CRLF, distinct same-URL script IDs, block/function-only semantics, native listener locations, request initiators, same-document navigation, inert sourceURL declarations, actually executed isolated-world functions excluded, actual armed progress and prompt selected-target termination, and native invalid-selector classification through both CLI and MCP. Caller page remains open; verifier descendants are empty. - Final tarball: **1,411,507 bytes / 900 entries**; `_reference`, `.codex` and `node_modules` absent. Isolated installation; no host defaults changed. - No new Hopper/Ghidra or non-Linux browser claim; corresponding real verification not performed. All runtime fixture data are synthetic. One CPU and bounded Node heaps used. ## Review fixes - Revalidate known source identities after asynchronous reads and final assertions; downgrade cached source/frame associations and final coverage/initiator/inventory joins when ownership becomes ambiguous. Six source-read/completion regressions pass. - Translate only Chromium's exact native DOM selector syntax rejection into an input error; other command/transport failures preserve their cause. Three producer regressions and both native public adapters pass. - Require positive default-world metadata plus main-frame identity; preserve reported context/world metadata for referenced sources, exclude isolated/worker/unknown/conflicting worlds. Four before-fix producer failures and real Chrome old-installed-package contamination reproduced; six new negative world cases pass. - Loader availability transitions cannot establish document identity; stable loader permits same-document history changes within allowed origins. - Preserve unowned producer metadata without claiming source/frame ownership. Invalid events terminate without returning partial evidence. - Native flat-session root detachment matches `params.sessionId`; foreign sessions are ignored, and prearming termination never reports armed. Cleanup failures retain target identity, failed commands and original reason. - Known initiator/resource URLs remove transport userinfo; inert sourceURL declarations and unknown names are preserved. Source, coverage and initiator joins use session script identity rather than URL guesses. - Keep source metadata open through the final resetting sample and freeze at that cutoff. Reject fatal raw protocol errors even with no outstanding commands. Recheck source collector failures after final listener assertions. - New final-collection regressions failed before the fix; existing observer compatibility and actual SDK/schema boundaries pass. Full latest-head CI is required before merge. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

bsakaguchi

2026-10-16 21:17:37 +00:00