[PR #6173] [MERGED] fix(process): capture MCP process scenarios with the server environment #7183

Closed
opened 2026-11-01 21:45:58 +00:00 by bsakaguchi · 0 comments
Owner

📋 Pull Request Information

Original PR: https://github.com/morluto/rea/pull/6173
Author: @Adolanium
Created: 10/21/2026
Status: ✅ Merged
Merged: 10/22/2026
Merged by: @morluto

Base: main ← Head: fix/process-capture-server-environment


📝 Commits (1)

  • c3d8892 fix(process): capture MCP process scenarios with the server environment

📊 Changes

3 files changed (+120 additions, -2 deletions)

View changed files

📝 src/server/registerSessionTools.ts (+6 -1)
📝 tests/boundary/process/processSessionMcp.test.ts (+53 -1)
➕ tests/process-global/processCaptureServerEnvironment.test.ts (+61 -0)

📄 Description

Summary

Fixes #6174.

The MCP capture_process_scenario handler ran captures with the ambient process.env instead of the environment the server was created with. createServer snapshots options.environment and uses it for every other environment-dependent decision, and rea capture-process-scenario passes its selected environment, so the same request could resolve a different executable or give the child different variables over MCP than over the CLI. The handler now uses the server's environment snapshot.

Problem and expected behavior

registerProcessTools in src/server/registerSessionTools.ts called captureProcessScenario(input, signal, process.platform, process.env, ...). The fourth argument is the environment the capture owner uses to resolve a bare executable name through PATH and to build the child's inherited environment. Any embedder or test that passes createServer(..., { environment }), for example to select a PATH or provider variables, got that environment for capability probes but not for process capture.

Expected: an MCP capture resolves and inherits the same environment the server selected, with caller-supplied environment entries still overriding it, as the CLI already does.

Change and scope

  • SessionToolOptions gains a required environment (the server's snapshot), which createServer already passes through its selected options. registerProcessTools passes it to captureProcessScenario instead of process.env.
  • No change to the capture owner, the tool contract, or the CLI.

Contribution scope: not applicable. This is a fix inside the existing process-capture boundary.

Contract and boundary impact

  • Semantic owner and earliest changed stage: MCP session tool registration; the environment the MCP adapter hands to the capture owner.
  • Contribution scope fit and linked maintainer decision: not applicable.
  • CLI and MCP/tool-catalog contract: no schema change. MCP captures now use the server's selected environment, matching the CLI.
  • Provider, bridge, target-format, or platform compatibility: none.
  • Evidence, artifact, provenance, or reconstruction contract: none. The captured environment follows the same selection as the CLI.
  • Target selection, authority, upstream behavior, and cleanup details (if applicable): executable PATH resolution and the inherited environment now come from the server's snapshot. When createServer is called without environment, the snapshot is taken from process.env, so the stdio server's behavior is unchanged.
  • Generated metadata (docs/public/product-catalog.json), package, or installation impact: none.

Expected effects (check known effects; use documentation-only on its own).
Unchecked items do not establish absence; leave uncertainties visible.

  • 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:
    • tests/boundary/process/processSessionMcp.test.ts, "resolves and inherits the server's selected environment through MCP": a real capture through an in-memory MCP client. The server's environment puts a probe script on PATH and sets two variables; the scenario overrides one. The captured output must read injected-value|scenario-value. Runs where process capture is available.
    • tests/process-global/processCaptureServerEnvironment.test.ts, "captures MCP process scenarios with the server's selected environment": mocks the capture owner and asserts the MCP adapter hands it exactly the server's environment, not ambient variables stubbed into process.env. Runs on every host, including Windows, where capture is rejected before the environment is read.
  • Base reproduction or other evidence: with process.env restored in registerProcessTools, both tests fail.
  • User-visible CLI/MCP output (if applicable): none changed.
  • Remaining proof gaps: no run through a real MCP client with a custom server environment; the stdio entry point uses the process environment, so it is unaffected either way.

For evidence-bearing changes:

  • Observed, derived, and inferred claims remain distinguishable.
  • Artifact identity, source provenance, and failed attempts remain preserved.
  • Unsupported, incomplete, unavailable, or uncertain outcomes remain visible.

Validation performed

On Linux (WSL Ubuntu, Node 24.18.0) at upstream/main 76dbc32f3 plus this commit, after npm ci and npm run build:cached:

  • npx tsc -p . --noEmit — passed.
  • npx oxfmt --check on the three changed files — clean.
  • npx oxlint on the three changed files — 1 warning (max-lines-per-function on registerSessionTools), also present on the parent commit.
  • npm run docs:check — passed.
  • npx vitest run tests/boundary/process/processSessionMcp.test.ts tests/process-global/processCaptureServerEnvironment.test.ts src/server — 14 files, 153 tests passed, in two runs.
  • The same two test files with process.env restored in registerProcessTools — the two new tests failed.

Compatibility, safety, and release

  • Breaking changes or migration steps: none. SessionToolOptions.environment is internal and supplied by createServer.
  • Real Hopper/Ghidra, browser, or OS coverage: Linux only for the real capture test; the adapter test also covers hosts without capture.
  • Package or release metadata impact: none.
  • Security, privacy, process, or containment review: captures now inherit the environment the server selected instead of the ambient one. No new variables are exposed, and caller environment overrides still apply.

Author readiness

Human owner: @Adolanium

  • I reviewed the final diff and relevant existing code, understand the change and its edge cases, and take responsibility for the complete PR, including AI-assisted work.
  • I checked the evidence above, confirmed it supports the current change, and recorded meaningful validation gaps.
  • I declare this PR ready for initial maintainer review.

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.
  • Owning docs, contracts, and generated metadata are updated where needed.
  • User-visible CLI/MCP changes include representative output.
  • 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/6173 **Author:** [@Adolanium](https://github.com/Adolanium) **Created:** 10/21/2026 **Status:** ✅ Merged **Merged:** 10/22/2026 **Merged by:** [@morluto](https://github.com/morluto) **Base:** `main` ← **Head:** `fix/process-capture-server-environment` --- ### 📝 Commits (1) - [`c3d8892`](https://github.com/morluto/rea/commit/c3d889210806bd0acd47d24b5c38eda9e5988d94) fix(process): capture MCP process scenarios with the server environment ### 📊 Changes **3 files changed** (+120 additions, -2 deletions) <details> <summary>View changed files</summary> 📝 `src/server/registerSessionTools.ts` (+6 -1) 📝 `tests/boundary/process/processSessionMcp.test.ts` (+53 -1) ➕ `tests/process-global/processCaptureServerEnvironment.test.ts` (+61 -0) </details> ### 📄 Description ## Summary Fixes #6174. The MCP `capture_process_scenario` handler ran captures with the ambient `process.env` instead of the environment the server was created with. `createServer` snapshots `options.environment` and uses it for every other environment-dependent decision, and `rea capture-process-scenario` passes its selected environment, so the same request could resolve a different executable or give the child different variables over MCP than over the CLI. The handler now uses the server's environment snapshot. ## Problem and expected behavior `registerProcessTools` in `src/server/registerSessionTools.ts` called `captureProcessScenario(input, signal, process.platform, process.env, ...)`. The fourth argument is the environment the capture owner uses to resolve a bare executable name through `PATH` and to build the child's inherited environment. Any embedder or test that passes `createServer(..., { environment })`, for example to select a `PATH` or provider variables, got that environment for capability probes but not for process capture. Expected: an MCP capture resolves and inherits the same environment the server selected, with caller-supplied `environment` entries still overriding it, as the CLI already does. ## Change and scope - `SessionToolOptions` gains a required `environment` (the server's snapshot), which `createServer` already passes through its selected options. `registerProcessTools` passes it to `captureProcessScenario` instead of `process.env`. - No change to the capture owner, the tool contract, or the CLI. Contribution scope: not applicable. This is a fix inside the existing process-capture boundary. ## Contract and boundary impact - Semantic owner and earliest changed stage: MCP session tool registration; the environment the MCP adapter hands to the capture owner. - Contribution scope fit and linked maintainer decision: not applicable. - CLI and MCP/tool-catalog contract: no schema change. MCP captures now use the server's selected environment, matching the CLI. - Provider, bridge, target-format, or platform compatibility: none. - Evidence, artifact, provenance, or reconstruction contract: none. The captured environment follows the same selection as the CLI. - Target selection, authority, upstream behavior, and cleanup details (if applicable): executable `PATH` resolution and the inherited environment now come from the server's snapshot. When `createServer` is called without `environment`, the snapshot is taken from `process.env`, so the stdio server's behavior is unchanged. - Generated metadata (`docs/public/product-catalog.json`), package, or installation impact: none. Expected effects (check known effects; use documentation-only on its own). Unchecked items do not establish absence; leave uncertainties visible. - [ ] Read existing files or captured data. - [x] 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: - `tests/boundary/process/processSessionMcp.test.ts`, "resolves and inherits the server's selected environment through MCP": a real capture through an in-memory MCP client. The server's environment puts a probe script on `PATH` and sets two variables; the scenario overrides one. The captured output must read `injected-value|scenario-value`. Runs where process capture is available. - `tests/process-global/processCaptureServerEnvironment.test.ts`, "captures MCP process scenarios with the server's selected environment": mocks the capture owner and asserts the MCP adapter hands it exactly the server's environment, not ambient variables stubbed into `process.env`. Runs on every host, including Windows, where capture is rejected before the environment is read. - Base reproduction or other evidence: with `process.env` restored in `registerProcessTools`, both tests fail. - User-visible CLI/MCP output (if applicable): none changed. - Remaining proof gaps: no run through a real MCP client with a custom server environment; the stdio entry point uses the process environment, so it is unaffected either way. For evidence-bearing changes: - [x] Observed, derived, and inferred claims remain distinguishable. - [x] Artifact identity, source provenance, and failed attempts remain preserved. - [x] Unsupported, incomplete, unavailable, or uncertain outcomes remain visible. ## Validation performed On Linux (WSL Ubuntu, Node 24.18.0) at upstream/main 76dbc32f3 plus this commit, after `npm ci` and `npm run build:cached`: - `npx tsc -p . --noEmit` — passed. - `npx oxfmt --check` on the three changed files — clean. - `npx oxlint` on the three changed files — 1 warning (`max-lines-per-function` on `registerSessionTools`), also present on the parent commit. - `npm run docs:check` — passed. - `npx vitest run tests/boundary/process/processSessionMcp.test.ts tests/process-global/processCaptureServerEnvironment.test.ts src/server` — 14 files, 153 tests passed, in two runs. - The same two test files with `process.env` restored in `registerProcessTools` — the two new tests failed. ## Compatibility, safety, and release - Breaking changes or migration steps: none. `SessionToolOptions.environment` is internal and supplied by `createServer`. - Real Hopper/Ghidra, browser, or OS coverage: Linux only for the real capture test; the adapter test also covers hosts without capture. - Package or release metadata impact: none. - Security, privacy, process, or containment review: captures now inherit the environment the server selected instead of the ambient one. No new variables are exposed, and caller `environment` overrides still apply. ## Author readiness <!-- The human owner completes these declarations before requesting review. The PR author is the owner by default. A different owner must explicitly accept ownership on this PR. AI agents must leave these declarations to a human to dictate to them or there could be catastrophic consequences for many users of REA. Draft PRs may leave them unchecked. These declarations record initial readiness when opening the PR for review; later pushes do not require a new human sign-off. Keep the description and validation evidence current as the work changes. See CONTRIBUTING.md#pull-request-ownership-and-readiness. --> Human owner: @Adolanium - [x] I reviewed the final diff and relevant existing code, understand the change and its edge cases, and take responsibility for the complete PR, including AI-assisted work. - [x] I checked the evidence above, confirmed it supports the current change, and recorded meaningful validation gaps. - [x] I declare this PR ready for initial maintainer review. ## Before merge <!-- Draft PRs may leave pending items unchecked. Resolve material scope and authority questions before integration. --> - [ ] 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. - [ ] Owning docs, contracts, and generated metadata are updated where needed. - [ ] User-visible CLI/MCP changes include representative output. - [ ] 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-11-01 21:45:58 +00:00
Sign in to join this conversation.
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#7183
No description provided.