Repository navigation
docs(setup): acquire packages outside a REA source checkout - #9695
2SinceJuly wants to merge 5 commits into
Conversation
npm exec resolves a package request against a local project of the same name, so `npx rea-agents@X` run inside a REA source checkout selects the unbuilt workspace package instead of the published one. The launcher then fails with "'rea' is not recognized" before REA starts, and a client registration that runs it reports a closed connection with no REA diagnostic. The onboarding docs and the bundled skill already said to acquire from a trusted directory outside the target project. Name the source checkout as a second exclusion so the guidance covers the failure DerekMaki reported (morluto#9685), and say what the failure looks like.
Codex Review Summary: ✅ CompletedThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
|
CI status on this head:
The checks this change is responsible for pass locally on the same head: |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 1443610af8
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
| with absolute target paths. Inside a checkout npm resolves `rea-agents` to the | ||
| local unbuilt package, so the launcher fails and the client reports a closed |
There was a problem hiding this comment.
When this authored skill is used directly, the fallback immediately above is npx -y rea-agents@latest, and npm does not shadow that tag with the checkout: with npm 11.4 an offline run from this repository queried npmjs.org and returned ENOTCACHED, whereas the matching exact @6.8.0 request selected the checkout and failed with rea: not found. npm's exec documentation likewise says that a package with a specifier is considered a local match only for the exact same name and version. The package-skill generator may pin @latest, but the repository/source skill retains the tag, so this explanation sends agents diagnosing a valid @latest launch down the wrong recovery path; scope it to unversioned or matching exact-version requests.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Fixed in 6a60523: the paragraph now says npm treats rea-agents as a local match only for an unversioned request or one naming the checkout's exact version, and that an @latest request keeps resolving the registry entry, so the shadowing does not explain a failure of the documented @latest fallback.
Not run: no test covers this prose; node scripts/verify/architecture-guards.mjs still reports the pre-existing DesktopBuildSecrets.ts violation that main carries, untouched here.
|
Full run finished; adding the two jobs that landed after my last comment. Both trace to the same two base defects:
This PR changes four Markdown files and nothing else ( |
The guidance says a checkout makes the `npx -y rea-agents@latest` fallback fail, but npm treats a specifier as a local match only for the same name and exact version: `@latest` keeps resolving the registry entry (npm 11.4 returned its own `ENOTCACHED`, not a checkout hit). Saying otherwise sends agents diagnosing a valid `@latest` launch down the wrong recovery path.
|
Re-checked on head The This PR changes four Markdown files and nothing else, so it cannot affect any of these. |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: ef9bc15005
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
| child launcher. Run that acquisition from a trusted directory outside any REA | ||
| source checkout; prefer managed |
There was a problem hiding this comment.
When a contributor opens this installation guide directly from a REA checkout, the first Start setup command at line 19 is still the unversioned npx rea-agents setup and is shown without this exclusion; npm 11's exec documentation says that a package name without a specifier is matched to whatever version exists in the local project. The only warning added to this guide is over 1,200 lines later in the Ghidra/rea mcp add aside, so the primary onboarding path can hit the checkout shadowing before seeing the advice; put the exclusion beside Start setup or in the linked package-runner section.
AGENTS.md reference: AGENTS.md:L31-L33
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Fair — the only warning was 1,200 lines below the command it protects. Fixed in 32b99523a: the Start setup section now says to run it from a trusted directory outside any REA source checkout and gives the unversioned-match reason, and the mcp add aside at line 1245 points back to it instead of restating the rule.
| Inside a checkout, npm resolves `rea-agents` to the local unbuilt package, so the | ||
| launcher fails before REA starts and a registration that runs from there reports a | ||
| closed connection rather than a REA diagnostic. |
There was a problem hiding this comment.
When a registration uses @latest or an exact version different from the checkout, this sentence still falsely attributes the launch to the local package: npm 11's exec documentation says a package with a specifier is a local match only for the exact same name and version, and the corrected SKILL.md lines 74–79 now records that qualifier. Fresh evidence after the earlier fix is that this linked sibling reference retained the unconditional wording, so an agent consulting it can still misdiagnose the same closed connection; apply the same unversioned/matching-version qualification here.
AGENTS.md reference: AGENTS.md:L35-L35
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Fixed in 32b99523a. The reference now scopes the shadowing the same way SKILL.md does: an unversioned rea-agents request, or one naming the checkout's exact version, matches the local unbuilt package; @latest or another version still resolves the registry entry and is unaffected.
The warning was placed only beside the mcp add aside, over 1,200 lines below the first setup command, so the primary onboarding path could hit the shadowing before ever seeing it. State the exclusion next to the Start setup command as well. The recovery reference still described the checkout as unconditionally shadowing the launch. npm only treats a package as a local match for an unversioned request or one naming the checkout's exact version; an @latest request resolves the registry entry, which is the form SKILL.md recommends.
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 32b99523a7
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
| available. Run package acquisition from a trusted directory outside the target | ||
| project. Installation and recovery details are in the setup guide below. | ||
| project and outside a REA source checkout: inside that checkout npm resolves | ||
| `rea-agents` to the local (unbuilt) package instead of the published one, so the | ||
| launcher fails before REA starts. Installation and recovery details are in the setup guide below. |
There was a problem hiding this comment.
When a contributor starts from the prominent README command at line 27 or the website command at docs/index.md:31, they can run npx rea-agents setup from a checkout before ever seeing this warning; the guide's linked package-runner section at docs/getting-started/installation.md:1957-1960 also retains only the older “outside the target project” advice. npm 11's exec documentation says an unversioned package name is matched to whatever version exists in the local project, so all of these public entry paths still reproduce the launcher failure this patch is meant to prevent. Put the exclusion beside those commands or use the unaffected @latest form there.
AGENTS.md reference: AGENTS.md:L31-L33
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Fixed in 4b53aa25: README.md:27 and docs/index.md:31 now run npx rea-agents@latest setup, which resolves the registry entry even when the cwd sits inside a checkout. The README hero also states the exclusion next to the command, and docs/getting-started/installation.md "Package runners and global installation" now names the source checkout alongside the target project.
Leaving the in-checkout shadowing pinned by request version (not an unconditional failure) is intentional — it is what 32b99523 established and npm 11 matches a local package only for an unversioned or exact-version request.
Verified locally: tests/boundary/filesystem/documentationFacts.test.ts and tests/conformance/readmeConsistency.test.ts pass (10 tests); npx oxfmt --check clean on the three touched files. Translations under docs/readme/ are synced in their own batch and were not touched here.
The warning next to Start setup only helps a reader who got that far. The README hero and the website quick start still ran an unversioned npx rea-agents, which inside a source checkout matches the local unbuilt package and fails before REA starts. Pin those commands to @latest so they resolve the published release from any directory, and say why in the hero note.
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 4b53aa25f1
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
| [Quick start](#quick-start) · [How REA works](#how-rea-works) · [What you can analyze](#what-you-can-analyze) · [Showcases](#showcases) · [Build RL environments](#build-rl-environments) · [FAQ](#faq) · [Documentation](#documentation) | ||
|
|
||
| <code>npx rea-agents setup</code> | ||
| <code>npx rea-agents@latest setup</code> |
There was a problem hiding this comment.
When a reader chooses any non-English edition linked at README.md:3-4, both its hero and quick-start setup commands remain unversioned (for example docs/readme/README_fr.md:27 and :78), so running them from a REA checkout still selects the unbuilt local package. A repo-wide search at this revision found the command in all 23 docs/readme/README_*.md editions, none of which receives this commit's new checkout guidance; npm 11's exec documentation says an unversioned name “will be matched with whatever version exists in the local project.” Fresh evidence after the earlier public-entry-point fix is this untouched set of linked editions; pin their executable literals to @latest or carry the warning there as well.
AGENTS.md reference: AGENTS.md:L31-L33
Useful? React with 👍 / 👎.
| trusted directory outside the target project, with absolute target paths. Managed | ||
| trusted directory outside the target project and outside any REA source checkout, | ||
| with absolute target paths. Inside a checkout npm treats `rea-agents` as a local | ||
| match only for an unversioned request or one naming the checkout's exact version, |
There was a problem hiding this comment.
When an MCP registration uses a semver range satisfied by the checkout's 6.8.0 version (for example rea-agents@^6.8.0), npm still selects the local checkout, but this new only qualifier tells the agent to rule that cause out. npm 11.4.2's implementation explicitly handles a “package requested by version range” by returning the local node when semver.satisfies(...); with the installed npm 11.4.2, an offline run here likewise ended in rea: not found for @^6.8.0 while @latest attempted the registry. This range branch/runtime result is fresh evidence beyond the earlier exact-version thread; include satisfying ranges here and in the matching recovery reference so these closed connections are not misdiagnosed.
AGENTS.md reference: AGENTS.md:L31-L33
Useful? React with 👍 / 👎.
Summary
Fixes #9685.
npx rea-agents@Xrun inside a REA source checkout selects the checkout's ownrea-agentsworkspace package instead of the published one, because npm resolves package requests against the local project. Nothing is built into that checkout'snode_modules/.bin, so the launcher fails with'rea' is not recognizedbefore REA starts. A client registration the agent runs from that directory then reports a closed connection, and nothing in the recovery path points at the working directory.The onboarding docs and the bundled skill already said to acquire from a trusted directory outside the target project. A target project and a REA source checkout are different exclusions: contributors hit this while working inside the checkout itself, which the existing wording does not cover.
Problem and expected behavior
Observed on Windows 11 with a Claude Code user-scope registration
cmd.exe /d /c npx -y rea-agents@6.8.0 mcp, started with cwd in a REA source checkout:CONNECTION_CLOSED.npx -y rea-agents@6.8.0 --versionfrom that checkout prints'rea' is not recognized as an internal or external command; from%TEMP%the same command prints6.8.0.npx -y -p rea-agents@6.8.0 -c "echo %PATH%"shows the childPATHwith<checkout>\node_modules\.binand no_npx\<hash>\node_modules\.binentry.Expected: the acquisition guidance names the source checkout as an environment to avoid, so a contributor can recognize the closed connection as a launcher-resolution failure rather than a REA transport failure.
Change and scope
Documentation and skill guidance only:
README.md— the setup section's acquisition sentence.docs/getting-started/installation.md— the package-runner sentence in therea mcp addparagraph..agents/skills/reverse-engineer-anything/SKILL.mdandreferences/connection-and-recovery.md— the same exclusion plus what the failure looks like.Not included, and deliberately so:
registrationAlignedinsrc/application/ClientRegistrationStatus.ts. The 6.8.0 behavior the report describes ("an exactnpx/bunxreference is aligned with no further checks") is already gone on currentmain:legacy package runners remain owned, but setup migrates them(src/application/ClientRegistrationStatus.ts:493) makes any package-runner registrationstale. Changing that classification on a source-derived claim would need a runtime reproduction of the 6.8.0 dist, which this environment cannot run.npm_config_local_prefix-style detection would be a new behavioral rule, and the issue does not establish what setup should do when it detects a checkout cwd.Contract and boundary impact
skills/reverse-engineer-anything/SKILL.mdis generated from.agents/skills/; regenerated locally withnode scripts/generate-skill-metadata.mjsand verified with--check. Nothing generated is committed.Expected effects:
Evidence and regression coverage
rea-agentsis selected over the registry). Not reproduced on this machine, which has no checkout-levelrea-agentspackage to select.bunxcases are untested, as the report itself notes.Validation performed
npm run test:focused -- tests/conformance/readmeConsistency.test.ts— 9/9 passed, including the translated-README shell-example equality check.node scripts/generate-skill-metadata.mjs --check— passed.node scripts/check-doc-facts.mjs— passed.npx oxfmt --check README.md docs/getting-started/installation.md .agents/skills/reverse-engineer-anything/SKILL.md .agents/skills/reverse-engineer-anything/references/connection-and-recovery.md— all files formatted.npm run check:fast/npm run typecheckwere not run: currentmain(e9b6c87c1) does not compile —src/cli/adbCommands.ts:48redeclarespackageName(TS2451) — and open PRs #9677 and #9678 already fix it. To runcheck-doc-facts.mjsand the skill generator, the duplicate was removed locally, the docs and skill checks were run, and the file was restored; this PR's diff does not include that file.Compatibility, safety, and release
Author readiness
Human owner: @2SinceJuly
Before merge
type(scope): outcome.