[GH-ISSUE #3423] [Docs] Pin install commands and align passive-observation and scenario timeout wording with code #1277

New issue

Open

opened 2026-10-16 21:03:40 +00:00 by bsakaguchi · 1 comment

bsakaguchi commented

2026-10-16 21:03:40 +00:00

Owner

Originally created by @dadbob on GitHub (Oct 14, 2026).
Original GitHub issue: https://github.com/morluto/rea/issues/3423

Before submitting

I searched the existing issues for a related documentation report.
I removed credentials, tokens, private paths, and sensitive target data.

Documentation location

website/public/get-started/index.html (install section, around line 1671) and its links from website/public/index.html
npx -y rea-agents@latest … examples in README.md, website/public/get-started/index.html, website/public/faq/index.html and the guides
docs/javascript-runtime-observation.md and docs/browser-observation.md (passive-observation wording)
docs/browser-scenario-contract.md (timeout and event-cap wording)

Problem

This is a source-only reading; I did not run anything.

Unpinned install instructions.
- The get-started page recommends curl -fsSL https://raw.githubusercontent.com/morluto/rea/main/install.sh | bash, which runs whatever is on main at that moment.
- Many examples use npx -y rea-agents@latest, which skips npm's confirmation and follows every new publish.
- The FAQ says setup later pins a version, but users who copy these commands, including agents following the copyable prompt, run unpinned code first.
"Passive" observation can pause targets.
- V8 Inspector and CDP observation enable the Debugger domain without skipping pauses (src/inspector/V8InspectorProvider.ts:192, src/browser/CdpPageCapture.ts:392).
- A debugger; statement in the target can therefore pause it for the observation window.
- The Evidence limitation text and the docs describe this observation as never pausing.
Scenario timeouts.
- docs/browser-scenario-contract.md says duration, action and navigation timeouts "remain fixed provider-owned liveness limits".
- The code sets Playwright's default and navigation timeouts to 0 (src/browser/PlaywrightScenarioSession.ts:59-60).
Event caps. The same document says there are no event caps, but the code caps events (PlaywrightScenarioEvents.ts:51-53, PlaywrightScenarioNetwork.ts:243).
Cache body fingerprints. docs/browser-observation.md says cache bodies above 64 KiB make fingerprint coverage incomplete, but CdpCaptureStorageFingerprints.ts:381-425 hashes any size and marks the result complete.

Expected content

Show version-pinned install commands by default, for example npx rea-agents@<version> setup and a tagged install.sh URL, and explain @latest as an opt-in.
Either skip pauses during passive observation, or document that the target can pause.
3–5. Align the scenario and cache wording with the code, or change the code to match the docs.

Supporting evidence

The file and line references above come from a source review of main at 322506d0c. This is a source-only finding with no runtime reproduction.

Additional context

Security-relevant findings from the same review were sent through private vulnerability reporting, as SECURITY.md requires.

Originally created by @dadbob on GitHub (Oct 14, 2026). Original GitHub issue: https://github.com/morluto/rea/issues/3423 ### Before submitting - [x] I searched the existing issues for a related documentation report. - [x] I removed credentials, tokens, private paths, and sensitive target data. ### Documentation location - `website/public/get-started/index.html` (install section, around line 1671) and its links from `website/public/index.html` - `npx -y rea-agents@latest …` examples in `README.md`, `website/public/get-started/index.html`, `website/public/faq/index.html` and the guides - `docs/javascript-runtime-observation.md` and `docs/browser-observation.md` (passive-observation wording) - `docs/browser-scenario-contract.md` (timeout and event-cap wording) ### Problem This is a source-only reading; I did not run anything. 1. **Unpinned install instructions.** - The get-started page recommends `curl -fsSL https://raw.githubusercontent.com/morluto/rea/main/install.sh | bash`, which runs whatever is on `main` at that moment. - Many examples use `npx -y rea-agents@latest`, which skips npm's confirmation and follows every new publish. - The FAQ says setup later pins a version, but users who copy these commands, including agents following the copyable prompt, run unpinned code first. 2. **"Passive" observation can pause targets.** - V8 Inspector and CDP observation enable the `Debugger` domain without skipping pauses (`src/inspector/V8InspectorProvider.ts:192`, `src/browser/CdpPageCapture.ts:392`). - A `debugger;` statement in the target can therefore pause it for the observation window. - The Evidence limitation text and the docs describe this observation as never pausing. 3. **Scenario timeouts.** - `docs/browser-scenario-contract.md` says duration, action and navigation timeouts "remain fixed provider-owned liveness limits". - The code sets Playwright's default and navigation timeouts to 0 (`src/browser/PlaywrightScenarioSession.ts:59-60`). 4. **Event caps.** The same document says there are no event caps, but the code caps events (`PlaywrightScenarioEvents.ts:51-53`, `PlaywrightScenarioNetwork.ts:243`). 5. **Cache body fingerprints.** `docs/browser-observation.md` says cache bodies above 64 KiB make fingerprint coverage incomplete, but `CdpCaptureStorageFingerprints.ts:381-425` hashes any size and marks the result complete. ### Expected content 1. Show version-pinned install commands by default, for example `npx rea-agents@<version> setup` and a tagged `install.sh` URL, and explain `@latest` as an opt-in. 2. Either skip pauses during passive observation, or document that the target can pause. 3–5. Align the scenario and cache wording with the code, or change the code to match the docs. ### Supporting evidence The file and line references above come from a source review of `main` at `322506d0c`. This is a source-only finding with no runtime reproduction. ### Additional context Security-relevant findings from the same review were sent through private vulnerability reporting, as `SECURITY.md` requires.

bsakaguchi commented

2026-10-16 21:03:42 +00:00

Author

Owner

@Xinglan233 commented on GitHub (Oct 14, 2026):

Opened draft PR #3546 to address item 5 by correcting the cache fingerprint documentation. Item 4 overlaps with #2961, so I’ve left it out of this change.

@Xinglan233 commented on GitHub (Oct 14, 2026): Opened draft PR #3546 to address item 5 by correcting the cache fingerprint documentation. Item 4 overlaps with #2961, so I’ve left it out of this change.

bsakaguchi referenced this issue

2026-10-17 21:09:57 +00:00

[PR #1277] [MERGED] fix(mcp): deliver tool errors within advertised schema contracts #2762

bsakaguchi referenced this issue

2026-10-17 21:10:01 +00:00

[PR #1288] [MERGED] fix(mcp): measure tool errors against their text-only delivery #2768

bsakaguchi referenced this issue

2026-10-17 21:10:03 +00:00

[PR #1289] [MERGED] fix(ghidra): stop dereferencing the removed error payload in address verification #2770