rea/docs/javascript-runtime-observation.md

Passive Node and Electron runtime observation

REA can attach to an already-running Node.js or Electron V8 Inspector target and retain script-load and execution-context metadata. The list_javascript_runtime_targets and observe_javascript_runtime MCP tools have equivalent rea list-javascript-runtime-targets and rea observe-javascript-runtime commands. Successful calls return deterministic Evidence.

Each request supplies the loopback Inspector endpoint and, for observation, the target ID. This surface is separate from browser CDP, Electron file-page inspection, and Process Capture:

rea list-javascript-runtime-targets http://127.0.0.1:9229 \
  --json
rea observe-javascript-runtime http://127.0.0.1:9229 TARGET_ID \
  --runtime-kind node --json

Start a caller-owned Node target

Run your selected application with Inspector bound to loopback:

node --inspect=127.0.0.1:9229 ./app.mjs

Keep it running while listing targets and observing the selected ID. Use a free port and the same literal endpoint in both REA calls. Stop the application through its normal lifecycle when finished; REA disconnects but does not own or terminate it. Node.js must already be installed.

Use --inspect for this passive workflow. --inspect-brk pauses before the application starts, and REA never resumes it or sends Runtime.runIfWaitingForDebugger. Resume a paused target with a separate caller-owned debugger before requesting application runtime observations.

For a packaged Electron app, read inspect_electron_fuses before starting an electron-main target. When EnableNodeCliInspectArguments is disabled or removed, Electron ignores --inspect and --inspect-brk. A missing main-process target after launch does not, by itself, show that fuse.

The caller supplies the literal-loopback HTTP endpoint directly. Selecting an endpoint exposes all targets it serves and their local script locations or renderer origins. A target must match the exact requested target ID and expose a same-port WebSocket reported by that endpoint. Targets explicitly marked attached are rejected rather than displacing another debugger. Node's /json/list omits attachment state, so REA preserves it as null (unknown), reports that limitation, and permits observation unless the endpoint explicitly reports attached: true. Local paths are canonicalized after symlink resolution.

The attached field in JavaScript runtime and browser target results is nullable: true and false are reported only when discovery supplied a boolean; null means the endpoint omitted or could not report the state. CDP TargetInfo worker records require an attached boolean; REA excludes a worker record with a missing or malformed value as an invalid protocol value.

list_javascript_runtime_targets returns every available target in one inline array.

For the MCP follow-up call, pass the same literal-loopback endpoint and the selected target ID to observe_javascript_runtime. REA rediscovers targets and validates the ID against the live endpoint before observation.

Discovery file locations

Node's /json/list reports a best-effort pathname prefixed with file://, without URI encoding. On POSIX, REA interprets unambiguous paths literally, including # and % in filenames. Node also replaces backslashes and double quotes with underscores. That transformation cannot be reversed reliably: an underscore may already be part of the original filename.

Windows paths, ambiguous underscore paths, and local discovery paths that cannot be verified remain eligible by their endpoint and exact target ID. Their target location preserves the reported value: