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. HTTP /json/list discovery parses target rows independently. Malformed optional attachment metadata becomes null with a row and field diagnostic in limitations; usable siblings remain available. Rows with malformed target identity are excluded with diagnostics, and socket authority is still validated before connection. 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.

Attachment refusals identify attached: true and ask the caller to disconnect the other debugger or select another target. A declared-role mismatch names runtime_kind and the target protocol type; correct the role or omit it to retain an unknown role. A role-only disagreement in supplied runtime Evidence is attributed to parameters.runtime_kind, separately from a target-ID disa