rea-agents 1.2.0 → 1.3.0

package/dist/server/toolResult.js

@@ -1,4 +1,4 @@
-import { projectAnalysisError } from "../domain/errors.js";
+import { AnalysisOutputError, projectAnalysisError, } from "../domain/errors.js";
 /**
  * Translate an application result into MCP text content.
  * Error tags and safe messages remain visible while underlying causes, process
@@ -11,9 +11,10 @@ const errorResult = (error) => {
         content: [
             {
                 type: "text",
-                text: `${projected.tag}: ${projected.message}`,
+                text: projected.message,
             },
         ],
+        structuredContent: { error: projected },
         isError: true,
     };
 };
@@ -25,9 +26,12 @@ const successResult = (value, contract) => {
             content: [
                 {
                     type: "text",
-                    text: "AnalysisOutputError: Analysis output does not match the tool contract",
+                    text: "Analysis returned an unreadable result. Retry once; if it continues, run `rea doctor`.",
                 },
             ],
+            structuredContent: {
+                error: projectAnalysisError(new AnalysisOutputError(contract.name, "output does not match the tool contract")),
+            },
             isError: true,
         };
     }

package/install.sh

@@ -17,7 +17,7 @@ usage() {
   cat <<'EOF'
 Usage: install.sh [--version VERSION] [--dry-run] [--no-setup] [--no-prompt] [--verbose]
 
-Installs only the REA CLI. Run `rea setup` separately to configure Hopper and coding agents.
+Installs only the REA CLI. Run `rea setup` separately to configure Hopper and agents.
 EOF
 }
 
@@ -54,13 +54,13 @@ fi
 
 platform="$(uname -s)"
 [[ "$platform" == "Darwin" || "$platform" == "Linux" ]] || fail "REA supports macOS and selected 64-bit Linux distributions."
-command -v curl >/dev/null 2>&1 || fail "curl is required."
+command -v curl >/dev/null 2>&1 || fail "curl is required. Install curl, then rerun this installer."
 command -v node >/dev/null 2>&1 || fail "Node.js 22.19+ or 24.11+ is required; install it from https://nodejs.org and retry."
 command -v npm >/dev/null 2>&1 || fail "npm is required; install it with Node.js and retry."
 
 node_version="$(node -p 'process.versions.node' 2>/dev/null || true)"
 IFS=. read -r node_major node_minor _node_patch <<<"$node_version"
-[[ "$node_major" =~ ^[0-9]+$ && "$node_minor" =~ ^[0-9]+$ ]] || fail "could not determine the active Node.js version."
+[[ "$node_major" =~ ^[0-9]+$ && "$node_minor" =~ ^[0-9]+$ ]] || fail "the active Node.js version could not be read. Check that node works and is on PATH, then retry."
 if ! ((node_major == 22 && node_minor >= 19 || node_major >= 24)); then
   fail "Node.js $node_version is unsupported; use Node.js 22.19+ or 24.11+."
 fi
@@ -71,9 +71,9 @@ fi
 if [[ -n "$version" ]]; then
   [[ "$version" =~ ^[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.-]+)?$ ]] || fail "version must be an exact semantic version."
 else
-  release_json="$(curl -fsSL --proto '=https' --tlsv1.2 --retry 3 -H 'Accept: application/vnd.github+json' "https://api.github.com/repos/$REPOSITORY/releases/latest")" || fail "could not resolve the latest GitHub release."
-  tag="$(printf '%s' "$release_json" | node -e 'let s="";process.stdin.on("data",c=>s+=c).on("end",()=>{const v=JSON.parse(s).tag_name;if(typeof v!=="string")process.exit(1);process.stdout.write(v)})')" || fail "GitHub returned malformed release metadata."
-  [[ "$tag" =~ ^rea-agents-([0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.-]+)?)$ ]] || fail "latest release tag is not a valid rea-agents release."
+  release_json="$(curl -fsSL --proto '=https' --tlsv1.2 --retry 3 -H 'Accept: application/vnd.github+json' "https://api.github.com/repos/$REPOSITORY/releases/latest")" || fail "the latest REA release could not be resolved. Check network access or pass --version VERSION, then retry."
+  tag="$(printf '%s' "$release_json" | node -e 'let s="";process.stdin.on("data",c=>s+=c).on("end",()=>{const v=JSON.parse(s).tag_name;if(typeof v!=="string")process.exit(1);process.stdout.write(v)})' 2>/dev/null)" || fail "the release response was invalid. Retry later or pass --version VERSION."
+  [[ "$tag" =~ ^rea-agents-([0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.-]+)?)$ ]] || fail "the latest release tag was invalid. Retry later or pass --version VERSION."
   version="${BASH_REMATCH[1]}"
 fi
 
@@ -82,7 +82,7 @@ if [[ "$platform" == "Linux" ]]; then
   prefix_args=(--prefix "$HOME/.local")
   install_bin="$HOME/.local/bin/rea"
 else
-  npm_prefix="$(npm prefix --global)" || fail "could not determine the npm global prefix."
+  npm_prefix="$(npm prefix --global)" || fail "the npm global prefix could not be read. Repair the npm configuration, then retry."
   install_bin="$npm_prefix/bin/rea"
 fi
 
@@ -99,9 +99,9 @@ if [[ "$dry_run" == true ]]; then
 fi
 
 printf 'Installing %s@%s...\n' "$PACKAGE" "$version"
-npm install --global "${prefix_args[@]}" "$PACKAGE@$version" || fail "npm package installation failed."
-[[ -x "$install_bin" ]] || fail "the rea command was not installed at $install_bin."
-installed_version="$("$install_bin" --version 2>/dev/null | tr -d '[:space:]')" || fail "could not read the installed REA version."
+npm install --global "${prefix_args[@]}" "$PACKAGE@$version" || fail "npm could not install REA. Check registry access and npm permissions, then retry."
+[[ -x "$install_bin" ]] || fail "npm completed without installing the rea command. Check the npm global bin directory and PATH, then retry."
+installed_version="$("$install_bin" --version 2>/dev/null | tr -d '[:space:]')" || fail "the installed REA version could not be read. Reinstall the requested version, then retry."
 [[ "$installed_version" == "$version" ]] || fail "installed version $installed_version does not match $version."
 
 printf 'REA %s is installed.\n' "$version"
@@ -109,5 +109,5 @@ if [[ "$start_setup" == true && -r /dev/tty && -w /dev/tty && -t 1 ]]; then
   printf 'Starting REA setup...\n'
   "$install_bin" setup </dev/tty >/dev/tty
 else
-  printf 'Run %s setup to configure Hopper and coding agents.\n' "$install_bin"
+  printf 'Run %s setup to configure Hopper and agents.\n' "$install_bin"
 fi

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "rea-agents",
-  "version": "1.2.0",
-  "description": "Reverse engineer anything from your terminal or coding agent with one CLI and MCP server.",
+  "version": "1.3.0",
+  "description": "Reverse engineer anything from your terminal or agent with one CLI and MCP server.",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -14,7 +14,7 @@
   "keywords": [
     "reverse-engineering",
     "binary-analysis",
-    "coding-agents",
+    "agents",
     "agent-skills",
     "cli",
     "mcp-server",
@@ -43,6 +43,7 @@
     "scripts/rea.mjs",
     "scripts/prepare-node-pty.mjs",
     "scripts/rebuild-native.mjs",
+    "scripts/hopper-demo-x11.py",
     "skills",
     "README.md",
     "LICENSE"
@@ -69,6 +70,7 @@
     "typecheck": "tsc --noEmit",
     "verify:hopper": "npm run build && node scripts/verify-real-hopper.mjs",
     "verify:hopper:linux": "npm run build && node scripts/verify-real-hopper-linux.mjs",
+    "verify:setup:linux": "npm run build && node scripts/verify-linux-setup-e2e.mjs",
     "build:fixtures": "node scripts/build-conformance-fixtures.mjs",
     "verify:fixtures": "npm run build:fixtures && node scripts/verify-conformance-fixtures.mjs",
     "verify:package": "npm run build && node scripts/verify-package.mjs",

package/scripts/hopper-demo-x11.py

@@ -0,0 +1,349 @@
+#!/usr/bin/env python3
+"""Inspect or activate Hopper's version-pinned demo dialog on a private X display."""
+
+from __future__ import annotations
+
+import argparse
+import ctypes
+import hashlib
+import os
+from pathlib import Path
+import secrets
+import subprocess
+import time
+
+
+# Keep this digest aligned with LinuxHopper.ts and rerun real-Hopper verification
+# before accepting another vendor build.
+SUPPORTED_HOPPER_SHA256 = {
+    "0294ced141cc373468ee22d8343e7dac41980cb05a937994ca81c9f09afe7ded"
+}
+EXPECTED_SCREEN = (1280, 1024)
+EXPECTED_DIALOG = (189, 370, 901, 284)
+DEMO_CLICK = (305, 632)
+PRIVATE_DISPLAY_UNAVAILABLE = 70
+X11_AUTHORIZATION_FAILED = 71
+UNSUPPORTED_HOPPER_BUILD = 72
+INVALID_LAUNCH_COMMAND = 73
+PROCESS_OWNERSHIP_MISMATCH = 74
+HOPPER_EXITED_DURING_STARTUP = 75
+UNSUPPORTED_DEMO_DIALOG = 76
+UNEXPECTED_DISPLAY_GEOMETRY = 77
+X11_INPUT_FAILED = 78
+RUNTIME_DEPENDENCY_UNAVAILABLE = 79
+
+
+class AdapterFailure(Exception):
+    def __init__(self, code: int, message: str) -> None:
+        super().__init__(message)
+        self.code = code
+
+
+class XWindowAttributes(ctypes.Structure):
+    _fields_ = [
+        ("x", ctypes.c_int),
+        ("y", ctypes.c_int),
+        ("width", ctypes.c_int),
+        ("height", ctypes.c_int),
+        ("border_width", ctypes.c_int),
+        ("depth", ctypes.c_int),
+        ("visual", ctypes.c_void_p),
+        ("root", ctypes.c_ulong),
+        ("class_", ctypes.c_int),
+        ("bit_gravity", ctypes.c_int),
+        ("win_gravity", ctypes.c_int),
+        ("backing_store", ctypes.c_int),
+        ("backing_planes", ctypes.c_ulong),
+        ("backing_pixel", ctypes.c_ulong),
+        ("save_under", ctypes.c_int),
+        ("colormap", ctypes.c_ulong),
+        ("map_installed", ctypes.c_int),
+        ("map_state", ctypes.c_int),
+        ("all_event_masks", ctypes.c_long),
+        ("your_event_mask", ctypes.c_long),
+        ("do_not_propagate_mask", ctypes.c_long),
+        ("override_redirect", ctypes.c_int),
+        ("screen", ctypes.c_void_p),
+    ]
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--hopper", required=True)
+    parser.add_argument("--socket", required=True)
+    parser.add_argument("command", nargs=argparse.REMAINDER)
+    return parser.parse_args()
+
+
+def digest(path: Path) -> str:
+    value = hashlib.sha256()
+    with path.open("rb") as file:
+        for chunk in iter(lambda: file.read(1024 * 1024), b""):
+            value.update(chunk)
+    return value.hexdigest()
+
+
+def descendants(pid: int) -> set[int]:
+    found = {pid}
+    changed = True
+    while changed:
+        changed = False
+        for stat in Path("/proc").glob("[0-9]*/stat"):
+            try:
+                fields = stat.read_text().split()
+                child = int(fields[0])
+                parent = int(fields[3])
+            except (OSError, ValueError, IndexError):
+                continue
+            if parent in found and child not in found:
+                found.add(child)
+                changed = True
+    return found
+
+
+def hopper_is_owned(leader: int, hopper: Path) -> bool:
+    expected = hopper.resolve()
+    for pid in descendants(leader):
+        try:
+            if Path(f"/proc/{pid}/exe").resolve() == expected:
+                return True
+        except OSError:
+            continue
+    return False
+
+
+def windows(x11: ctypes.CDLL, display: int, root: int) -> list[tuple[int, int, int, int, int]]:
+    found: list[tuple[int, int, int, int, int]] = []
+    pending = [root]
+    while pending:
+        window = pending.pop()
+        attributes = XWindowAttributes()
+        if x11.XGetWindowAttributes(display, window, ctypes.byref(attributes)):
+            if attributes.map_state == 2:
+                found.append(
+                    (window, attributes.x, attributes.y, attributes.width, attributes.height)
+                )
+        root_return = ctypes.c_ulong()
+        parent_return = ctypes.c_ulong()
+        children = ctypes.POINTER(ctypes.c_ulong)()
+        count = ctypes.c_uint()
+        if x11.XQueryTree(
+            display,
+            window,
+            ctypes.byref(root_return),
+            ctypes.byref(parent_return),
+            ctypes.byref(children),
+            ctypes.byref(count),
+        ):
+            pending.extend(children[index] for index in range(count.value))
+            if children:
+                x11.XFree(children)
+    return found
+
+
+def configure_x11(x11: ctypes.CDLL, xtst: ctypes.CDLL) -> None:
+    window_pointer = ctypes.POINTER(ctypes.c_ulong)
+    x11.XOpenDisplay.argtypes = [ctypes.c_char_p]
+    x11.XOpenDisplay.restype = ctypes.c_void_p
+    x11.XDefaultRootWindow.argtypes = [ctypes.c_void_p]
+    x11.XDefaultRootWindow.restype = ctypes.c_ulong
+    x11.XDisplayWidth.argtypes = [ctypes.c_void_p, ctypes.c_int]
+    x11.XDisplayWidth.restype = ctypes.c_int
+    x11.XDisplayHeight.argtypes = [ctypes.c_void_p, ctypes.c_int]
+    x11.XDisplayHeight.restype = ctypes.c_int
+    x11.XGetWindowAttributes.argtypes = [
+        ctypes.c_void_p,
+        ctypes.c_ulong,
+        ctypes.POINTER(XWindowAttributes),
+    ]
+    x11.XGetWindowAttributes.restype = ctypes.c_int
+    x11.XQueryTree.argtypes = [
+        ctypes.c_void_p,
+        ctypes.c_ulong,
+        window_pointer,
+        window_pointer,
+        ctypes.POINTER(window_pointer),
+        ctypes.POINTER(ctypes.c_uint),
+    ]
+    x11.XQueryTree.restype = ctypes.c_int
+    x11.XFree.argtypes = [ctypes.c_void_p]
+    x11.XFree.restype = ctypes.c_int
+    x11.XFlush.argtypes = [ctypes.c_void_p]
+    x11.XFlush.restype = ctypes.c_int
+    x11.XCloseDisplay.argtypes = [ctypes.c_void_p]
+    x11.XCloseDisplay.restype = ctypes.c_int
+    xtst.XTestFakeMotionEvent.argtypes = [
+        ctypes.c_void_p,
+        ctypes.c_int,
+        ctypes.c_int,
+        ctypes.c_int,
+        ctypes.c_ulong,
+    ]
+    xtst.XTestFakeMotionEvent.restype = ctypes.c_int
+    xtst.XTestFakeButtonEvent.argtypes = [
+        ctypes.c_void_p,
+        ctypes.c_uint,
+        ctypes.c_int,
+        ctypes.c_ulong,
+    ]
+    xtst.XTestFakeButtonEvent.restype = ctypes.c_int
+
+
+def start_xvfb(session: Path) -> tuple[subprocess.Popen[bytes], str, Path]:
+    authority = session / "Xauthority"
+    for _ in range(20):
+        display_number = 100 + secrets.randbelow(900)
+        display_name = f":{display_number}"
+        if Path(f"/tmp/.X11-unix/X{display_number}").exists():
+            continue
+        cookie = secrets.token_hex(16)
+        try:
+            subprocess.run(
+                [
+                    "/usr/bin/xauth", "-f", str(authority), "add",
+                    display_name, ".", cookie,
+                ],
+                check=True,
+                stdout=subprocess.DEVNULL,
+                stderr=subprocess.DEVNULL,
+            )
+        except (OSError, subprocess.CalledProcessError) as error:
+            raise AdapterFailure(
+                X11_AUTHORIZATION_FAILED, "private X authorization failed"
+            ) from error
+        authority.chmod(0o600)
+        process = subprocess.Popen(
+            [
+                "/usr/bin/Xvfb",
+                display_name,
+                "-screen",
+                "0",
+                "1280x1024x24",
+                "-nolisten",
+                "tcp",
+                "-auth",
+                str(authority),
+            ],
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+        )
+        deadline = time.monotonic() + 2
+        socket = Path(f"/tmp/.X11-unix/X{display_number}")
+        while time.monotonic() < deadline and process.poll() is None:
+            if socket.exists():
+                return process, display_name, authority
+            time.sleep(0.05)
+        if process.poll() is None:
+            process.terminate()
+        process.wait()
+    raise AdapterFailure(PRIVATE_DISPLAY_UNAVAILABLE, "private X display unavailable")
+
+
+def main() -> int:
+    args = parse_args()
+    hopper = Path(args.hopper)
+    socket = Path(args.socket)
+    if digest(hopper) not in SUPPORTED_HOPPER_SHA256:
+        raise AdapterFailure(UNSUPPORTED_HOPPER_BUILD, "unsupported Hopper binary")
+    command = args.command[1:] if args.command[:1] == ["--"] else args.command
+    if not command or Path(command[0]).resolve() != hopper.resolve():
+        raise AdapterFailure(INVALID_LAUNCH_COMMAND, "invalid Hopper launch command")
+    xvfb, display_name, authority = start_xvfb(socket.parent)
+    child: subprocess.Popen[bytes] | None = None
+    display: int | None = None
+    try:
+        hopper_environment = dict(os.environ)
+        for name in ("WAYLAND_DISPLAY", "WAYLAND_SOCKET"):
+            hopper_environment.pop(name, None)
+        hopper_environment.update(
+            {
+                "DISPLAY": display_name,
+                "XAUTHORITY": str(authority),
+                "GDK_BACKEND": "x11",
+                "QT_QPA_PLATFORM": "xcb",
+                "XDG_SESSION_TYPE": "x11",
+            }
+        )
+        child = subprocess.Popen(command, env=hopper_environment)
+        leader = os.getpid()
+        os.environ["XAUTHORITY"] = str(authority)
+
+        try:
+            x11 = ctypes.CDLL("libX11.so.6")
+            xtst = ctypes.CDLL("libXtst.so.6")
+        except OSError as error:
+            raise AdapterFailure(
+                RUNTIME_DEPENDENCY_UNAVAILABLE, "X11 runtime unavailable"
+            ) from error
+        configure_x11(x11, xtst)
+        display = x11.XOpenDisplay(display_name.encode())
+        if not display:
+            raise AdapterFailure(PRIVATE_DISPLAY_UNAVAILABLE, "private X display unavailable")
+        root = x11.XDefaultRootWindow(display)
+        if (
+            x11.XDisplayWidth(display, 0),
+            x11.XDisplayHeight(display, 0),
+        ) != EXPECTED_SCREEN:
+            raise AdapterFailure(
+                UNEXPECTED_DISPLAY_GEOMETRY, "unexpected private display geometry"
+            )
+
+        deadline = time.monotonic() + 10
+        observed: list[tuple[int, int, int, int, int]] = []
+        while time.monotonic() < deadline:
+            if socket.exists():
+                x11.XCloseDisplay(display)
+                display = None
+                return child.wait()
+            if not hopper_is_owned(leader, hopper):
+                if child.poll() is None:
+                    time.sleep(0.1)
+                    continue
+                raise AdapterFailure(
+                    HOPPER_EXITED_DURING_STARTUP, "owned Hopper process exited"
+                )
+            observed = windows(x11, display, root)
+            if any(window[1:] == EXPECTED_DIALOG for window in observed):
+                break
+            time.sleep(0.1)
+        else:
+            if not hopper_is_owned(leader, hopper):
+                raise AdapterFailure(
+                    PROCESS_OWNERSHIP_MISMATCH, "Hopper process ownership mismatch"
+                )
+            raise AdapterFailure(
+                UNSUPPORTED_DEMO_DIALOG, "expected Hopper demo dialog not found"
+            )
+
+        input_results = (
+            xtst.XTestFakeMotionEvent(display, -1, DEMO_CLICK[0], DEMO_CLICK[1], 0),
+            xtst.XTestFakeButtonEvent(display, 1, True, 0),
+            xtst.XTestFakeButtonEvent(display, 1, False, 0),
+        )
+        if not all(input_results):
+            raise AdapterFailure(X11_INPUT_FAILED, "private X input failed")
+        x11.XFlush(display)
+        x11.XCloseDisplay(display)
+        display = None
+        return child.wait()
+    finally:
+        if display is not None:
+            x11.XCloseDisplay(display)
+        if child is not None and child.poll() is None:
+            child.terminate()
+            child.wait()
+        if xvfb.poll() is None:
+            xvfb.terminate()
+            try:
+                xvfb.wait(timeout=2)
+            except subprocess.TimeoutExpired:
+                xvfb.kill()
+                xvfb.wait()
+
+
+if __name__ == "__main__":
+    try:
+        raise SystemExit(main())
+    except AdapterFailure as error:
+        print(str(error), file=os.sys.stderr)
+        raise SystemExit(error.code) from None

package/scripts/rea.mjs

@@ -11,9 +11,12 @@ const isMcpMode =
   args[0] === "--mcp" || (args.length === 1 && args[0] === "mcp");
 
 if (isMcpMode) {
-  const { run } = await import("../dist/main.js");
-  process.exitCode = await run();
+  const { runEntrypoint } = await import("../dist/main.js");
+  await runEntrypoint();
 } else {
   const { createCli } = await import("../dist/cli.js");
-  await createCli().serve(args);
+  const { sanitizeCliOutput } = await import("../dist/cliOutput.js");
+  await createCli().serve(args, {
+    stdout: (output) => process.stdout.write(sanitizeCliOutput(output)),
+  });
 }

package/skills/rea-analysis/SKILL.md

@@ -2,7 +2,7 @@
 name: rea-analysis
 description: Reverse engineer apps with REA. Explore how features work, then build a version tailored to your project.
 metadata:
-  version: "11"
+  version: "12"
   tool_count: 68
 ---
 
@@ -24,7 +24,7 @@ Notes is only a documentation example. Never select an app unless the user names
 2. If setup is needed, tell the user REA needs to install its local binary-analysis tools. Do not lead with implementation details or assume the user knows reverse-engineering products.
 3. Before installing external software, obtain approval and identify what will be installed. If deeper analysis needs Hopper, describe it as REA's local analysis engine and note that it is a separate Mac app with its own license. Then run `npx -y rea-agents setup --yes`.
 4. If macOS or an installer requests human input, tell the user exactly what needs attention. After they finish, rerun setup and doctor.
-5. If setup registers a new MCP server, tell the user to restart their coding agent to load all REA tools. Direct CLI commands remain available before restart.
+5. If setup registers a new MCP server, tell the user to restart their agent to load all REA tools. Direct CLI commands remain available before restart.
 
 ## Locate the app
 
@@ -109,6 +109,13 @@ bundle digests to anchor paginated reports.
 Use `find_changed_behavior` to combine existing comparison Evidence. Runtime
 process differences are observed changes; artifact and function differences
 remain static candidates, not causal proof. Supply complete comparison pages.
+For an automatic two-version artifact investigation, use its
+`investigation_run` mode with explicit write approval and a workspace beneath
+`REA_EVIDENCE_ROOTS_JSON`. It checkpoints inventory, comparison, and report
+Evidence in monotonic CAS-linked revisions. Repeating the same content and
+budgets resumes or reuses the run. This automatic mode does not execute either
+version or perform fuzzy function matching, so its behavior status remains
+unknown without separate controlled runtime Evidence.
 
 Use `build_call_path` with explicit `analyze_function` Evidence groups from one
 artifact and provider. Select endpoints by exact address. Missing dossiers,