rea-agents 3.0.0 → 3.2.0

package/scripts/electron-active-hook.cjs

@@ -0,0 +1,469 @@
+"use strict";
+
+const {
+  createElectronActiveBoundaryPatches,
+} = require("./electron-active-hook-boundaries.cjs");
+
+const ipcEventKinds = new Set([
+  "main-handler-invocation",
+  "main-event-invocation",
+  "utility-process-fork",
+  "utility-process-message",
+  "ipc-main-to-renderer",
+  "ipc-utility-to-main",
+  "ipc-renderer-send",
+  "ipc-renderer-invoke",
+  "ipc-renderer-post-message",
+]);
+const events = [];
+let observed = 0;
+let observedIpc = 0;
+let observedRuntime = 0;
+let sequence = 0;
+let correlationSequence = 0;
+
+const shape = (value, depth = 0) => {
+  if (depth > 2 || value === null) return value === null ? "null" : "nested";
+  if (Array.isArray(value)) return "array";
+  switch (typeof value) {
+    case "string":
+      return "string";
+    case "number":
+      return "number";
+    case "boolean":
+      return "boolean";
+    case "undefined":
+      return "undefined";
+    case "function":
+      return "function";
+    case "object":
+      return "object";
+    default:
+      return "unknown";
+  }
+};
+
+const isAllowedNavigation = (value) => {
+  if (typeof value !== "string") return true;
+  try {
+    const parsed = new URL(value);
+    if (["file:", "data:", "about:"].includes(parsed.protocol)) return true;
+    return (
+      ["http:", "https:"].includes(parsed.protocol) &&
+      ["127.0.0.1", "localhost", "[::1]", "::1"].includes(parsed.hostname)
+    );
+  } catch {
+    return false;
+  }
+};
+
+const processType = () =>
+  typeof process.type === "string" && process.type.length > 0
+    ? process.type
+    : "main";
+
+const identity = (value, prefix) => {
+  if (value === null || value === undefined) return null;
+  const id = value.id;
+  const processId = value.pid;
+  return typeof id === "string" || typeof id === "number"
+    ? `${prefix}:${String(id)}`
+    : typeof processId === "number"
+      ? `${prefix}:pid:${String(processId)}`
+      : null;
+};
+
+const frameIdentity = (event) => {
+  const frame = event?.senderFrame ?? event?.frame;
+  const id = frame?.frameTreeNodeId ?? frame?.routingId ?? frame?.id;
+  return typeof id === "string" || typeof id === "number"
+    ? `frame:${String(id)}`
+    : null;
+};
+
+const record = (event) => {
+  observed += 1;
+  if (ipcEventKinds.has(event.kind)) observedIpc += 1;
+  else observedRuntime += 1;
+  const raw = {
+    sequence: ++sequence,
+    correlation_id:
+      typeof event.correlation_id === "string"
+        ? event.correlation_id
+        : `capture:${process.pid}:${++correlationSequence}`,
+    event: null,
+    phase: "observed",
+    channel: null,
+    direction: null,
+    sender: null,
+    receiver: null,
+    frame: null,
+    target: null,
+    argument_shapes: [],
+    result_shape: null,
+    process_type: processType(),
+    source: "electron-active-hook",
+    capture_method: "api-wrapper",
+    artifact_path: null,
+    artifact_sha256: null,
+    error: false,
+    ...event,
+  };
+  const argumentShapes = Array.isArray(raw.argument_shapes)
+    ? raw.argument_shapes
+    : [];
+  events.push({
+    ...raw,
+    correlation_id: raw.correlation_id,
+    event: typeof raw.event === "string" ? raw.event : null,
+    channel: typeof raw.channel === "string" ? raw.channel : null,
+    sender: typeof raw.sender === "string" ? raw.sender : null,
+    receiver: typeof raw.receiver === "string" ? raw.receiver : null,
+    frame: typeof raw.frame === "string" ? raw.frame : null,
+    target: typeof raw.target === "string" ? raw.target : null,
+    argument_shapes: argumentShapes.map((value) =>
+      typeof value === "string" ? value : "unknown",
+    ),
+    result_shape:
+      typeof raw.result_shape === "string" ? raw.result_shape : null,
+    process_type:
+      typeof raw.process_type === "string" ? raw.process_type : null,
+    artifact_path:
+      typeof raw.artifact_path === "string" ? raw.artifact_path : null,
+    artifact_sha256:
+      typeof raw.artifact_sha256 === "string" ? raw.artifact_sha256 : null,
+  });
+  return events.at(-1);
+};
+
+const recordRuntime = (kind, event, phase, details = {}) =>
+  record({ kind, event, phase, ...details });
+
+const recordIpc = (kind, channel, args, details = {}) =>
+  (() => {
+    const values = Array.isArray(args) ? args : [];
+    return record({
+      kind,
+      channel: typeof channel === "string" ? channel : null,
+      argument_shapes: values.map((value) => shape(value)),
+      ...details,
+    });
+  })();
+
+const patchEmitter = (emitter, observeEvent) => {
+  if (emitter === null || emitter === undefined) return;
+  const original = emitter.emit;
+  if (typeof original !== "function") return;
+  if (emitter.__reaElectronActiveEmitPatched === true) return;
+  try {
+    emitter.__reaElectronActiveEmitPatched = true;
+    emitter.emit = function patchedEmit(event, ...args) {
+      if (typeof event === "string") observeEvent.call(this, event, args);
+      return original.call(this, event, ...args);
+    };
+  } catch {
+    globalThis.__reaElectronActiveHookError = true;
+  }
+};
+
+const recordInvocation = (kind, channel, event, args) =>
+  recordIpc(kind, channel, args, {
+    direction: "renderer-to-main",
+    sender: identity(event?.sender, "webContents"),
+    receiver: "main",
+    frame: frameIdentity(event),
+    process_type: "main",
+    error: false,
+  });
+
+const patchIpcMain = (ipcMain) => {
+  if (ipcMain === null || ipcMain === undefined) return;
+  for (const [method, kind] of [
+    ["handle", "main-handler-invocation"],
+    ["on", "main-event-invocation"],
+    ["once", "main-event-invocation"],
+  ]) {
+    const original = ipcMain[method];
+    if (typeof original !== "function") continue;
+    ipcMain[method] = function patchedIpcMain(channel, listener) {
+      if (typeof listener !== "function")
+        return original.call(this, channel, listener);
+      const wrapped =
+        kind === "main-handler-invocation"
+          ? async function wrappedHandler(event, ...args) {
+              const recorded = recordInvocation(kind, channel, event, args);
+              try {
+                const result = await listener.call(this, event, ...args);
+                if (recorded !== null) recorded.result_shape = shape(result);
+                return result;
+              } catch (cause) {
+                if (recorded !== null) recorded.error = true;
+                throw cause;
+              }
+            }
+          : function wrappedEventListener(event, ...args) {
+              const recorded = recordInvocation(kind, channel, event, args);
+              try {
+                return listener.call(this, event, ...args);
+              } catch (cause) {
+                if (recorded !== null) recorded.error = true;
+                throw cause;
+              }
+            };
+      return original.call(this, channel, wrapped);
+    };
+  }
+};
+
+const patchNavigationMethods = (webContents, contentsId) => {
+  for (const method of ["loadURL", "loadFile", "loadDataURL"]) {
+    const original = webContents[method];
+    if (typeof original !== "function") continue;
+    webContents[method] = function patchedNavigation(...args) {
+      recordRuntime("navigation", method, "attempted", {
+        target: contentsId,
+        argument_shapes: args.map((value) => shape(value)),
+      });
+      if (method === "loadURL" && !isAllowedNavigation(args[0])) {
+        recordRuntime("navigation", method, "blocked", {
+          target: contentsId,
+          error: true,
+        });
+        return Promise.reject(new Error("External navigation is blocked"));
+      }
+      try {
+        const result = original.apply(this, args);
+        if (result !== null && typeof result?.then === "function")
+          return result.then(
+            (value) => {
+              recordRuntime("navigation", method, "completed", {
+                target: contentsId,
+              });
+              return value;
+            },
+            (cause) => {
+              recordRuntime("navigation", method, "failed", {
+                target: contentsId,
+                error: true,
+              });
+              throw cause;
+            },
+          );
+        recordRuntime("navigation", method, "completed", {
+          target: contentsId,
+        });
+        return result;
+      } catch (cause) {
+        recordRuntime("navigation", method, "failed", {
+          target: contentsId,
+          error: true,
+        });
+        throw cause;
+      }
+    };
+  }
+};
+
+const patchWebContentsIpc = (webContents, contentsId) => {
+  const originalSend = webContents.send;
+  if (typeof originalSend === "function")
+    webContents.send = function patchedSend(channel, ...args) {
+      const recorded = recordIpc("ipc-main-to-renderer", channel, args, {
+        direction: "main-to-renderer",
+        sender: "main",
+        receiver: contentsId,
+        target: contentsId,
+        process_type: "main",
+        error: false,
+      });
+      try {
+        const result = originalSend.call(this, channel, ...args);
+        if (recorded !== null) recorded.result_shape = shape(result);
+        return result;
+      } catch (cause) {
+        if (recorded !== null) recorded.error = true;
+        throw cause;
+      }
+    };
+  const originalPostMessage = webContents.postMessage;
+  if (typeof originalPostMessage === "function")
+    webContents.postMessage = function patchedPostMessage(
+      channel,
+      message,
+      transfer,
+    ) {
+      const recorded = recordIpc(
+        "ipc-main-to-renderer",
+        channel,
+        [message, transfer],
+        {
+          direction: "main-to-renderer",
+          sender: "main",
+          receiver: contentsId,
+          target: contentsId,
+          process_type: "main",
+          error: false,
+        },
+      );
+      try {
+        const result = originalPostMessage.call(
+          this,
+          channel,
+          message,
+          transfer,
+        );
+        if (recorded !== null) recorded.result_shape = shape(result);
+        return result;
+      } catch (cause) {
+        if (recorded !== null) recorded.error = true;
+        throw cause;
+      }
+    };
+};
+
+const patchWebContents = (webContents, windowId) => {
+  if (webContents === null || webContents === undefined) return;
+  const contentsId = identity(webContents, "webContents");
+  patchEmitter(webContents, (event, args) => {
+    const navigation = [
+      "did-start-loading",
+      "did-stop-loading",
+      "did-finish-load",
+      "did-fail-load",
+      "did-frame-finish-load",
+      "will-navigate",
+      "will-redirect",
+    ].includes(event);
+    const kind = navigation
+      ? "navigation"
+      : [
+            "console-message",
+            "render-process-gone",
+            "crashed",
+            "unresponsive",
+            "responsive",
+          ].includes(event)
+        ? "error"
+        : event === "did-create-window"
+          ? "popup-attempt"
+          : "web-contents-lifecycle";
+    if (event === "will-navigate" || event === "will-redirect") {
+      if (!isAllowedNavigation(args[1])) {
+        const preventDefault = args[0]?.preventDefault;
+        if (typeof preventDefault === "function") preventDefault.call(args[0]);
+        recordRuntime("navigation", event, "blocked", {
+          target: contentsId,
+          sender: windowId,
+          argument_shapes: args.map((value) => shape(value)),
+          error: true,
+        });
+        return;
+      }
+    }
+    recordRuntime(kind, event, "observed", {
+      target: contentsId,
+      sender: windowId,
+      argument_shapes: args.map((value) => shape(value)),
+      error: kind === "error",
+    });
+    if (event === "did-create-window") {
+      const childWindow = args[0];
+      patchWebContents(
+        childWindow?.webContents,
+        identity(childWindow, "window"),
+      );
+    }
+  });
+  patchNavigationMethods(webContents, contentsId);
+  patchWebContentsIpc(webContents, contentsId);
+  boundaries.patchWindowOpenHandler(webContents, contentsId);
+};
+
+const patchBrowserWindow = (electron) => {
+  const original = electron.BrowserWindow;
+  if (typeof original !== "function") return;
+  electron.BrowserWindow = new Proxy(original, {
+    construct(target, args, newTarget) {
+      const window = Reflect.construct(target, args, newTarget);
+      const targetId = identity(window, "window");
+      recordRuntime("window-lifecycle", "created", "completed", {
+        target: targetId,
+        argument_shapes: args.map((value) => shape(value)),
+      });
+      const preload = args[0]?.webPreferences?.preload;
+      if (typeof preload === "string")
+        recordRuntime("preload", "configured", "completed", {
+          target: targetId,
+          artifact_path: preload,
+        });
+      patchEmitter(window, (event) =>
+        recordRuntime("window-lifecycle", event, "observed", {
+          target: targetId,
+        }),
+      );
+      patchWebContents(window.webContents, targetId);
+      return window;
+    },
+  });
+};
+
+const boundaries = createElectronActiveBoundaryPatches({
+  identity,
+  patchEmitter,
+  processType,
+  recordIpc,
+  recordRuntime,
+  shape,
+});
+
+try {
+  const electron = require("electron");
+  patchEmitter(electron.app, (event, args) =>
+    recordRuntime(
+      event === "open-url" || event === "second-instance"
+        ? "protocol"
+        : "app-lifecycle",
+      event,
+      "observed",
+      {
+        target: "app",
+        argument_shapes: args.map((value) => shape(value)),
+        process_type: "main",
+      },
+    ),
+  );
+  patchIpcMain(electron.ipcMain);
+  boundaries.patchIpcRenderer(electron.ipcRenderer);
+  boundaries.patchContextBridge(electron.contextBridge);
+  patchBrowserWindow(electron);
+  boundaries.patchUtilityProcess(electron.utilityProcess);
+  boundaries.patchShell(electron.shell);
+  boundaries.patchSessionManager(electron.session);
+  boundaries.patchApplicationEffects(electron.app);
+  boundaries.patchNativeAddonLoading();
+  boundaries.patchChildProcess();
+  process.once("uncaughtException", (cause, origin) => {
+    recordRuntime("process-lifecycle", "uncaught-exception", "observed", {
+      argument_shapes: [shape(cause), shape(origin)],
+      error: true,
+    });
+    throw cause;
+  });
+  process.once("unhandledRejection", (reason, promise) => {
+    recordRuntime("process-lifecycle", "unhandled-rejection", "observed", {
+      argument_shapes: [shape(reason), shape(promise)],
+      error: true,
+    });
+    throw reason;
+  });
+} catch {
+  globalThis.__reaElectronActiveHookError = true;
+}
+
+globalThis.__reaElectronActiveSnapshot = () => ({
+  events: events.slice(),
+  observed,
+  observed_ipc: observedIpc,
+  observed_runtime: observedRuntime,
+  hook_error: globalThis.__reaElectronActiveHookError === true,
+});

package/scripts/hopper-demo-x11.py

@@ -36,11 +36,8 @@ UNEXPECTED_DISPLAY_GEOMETRY = 77
 X11_INPUT_FAILED = 78
 RUNTIME_DEPENDENCY_UNAVAILABLE = 79
 X11_SOCKET_DIRECTORY_UNUSABLE = 80
-DIAGNOSTIC_PREFIX = "REA_X11_DIAGNOSTIC_V1="
+DIAGNOSTIC_PREFIX = "REA_X11_DIAGNOSTIC="
 X11_SOCKET_DIRECTORY = Path("/tmp/.X11-unix")
-XVFB_STDERR_LIMIT = 16 * 1024
-
-
 class AdapterFailure(Exception):
     def __init__(
         self,
@@ -48,20 +45,18 @@ class AdapterFailure(Exception):
         reason: str,
         message: str,
         stderr_bytes: int = 0,
-        stderr_truncated: bool = False,
     ) -> None:
         super().__init__(message)
         self.code = code
         self.reason = reason
         self.stderr_bytes = stderr_bytes
-        self.stderr_truncated = stderr_truncated
 
-    def with_stderr(self, capture: BoundedStderr) -> AdapterFailure:
-        self.stderr_bytes, self.stderr_truncated, _ = capture.snapshot()
+    def with_stderr(self, capture: CapturedStderr) -> AdapterFailure:
+        self.stderr_bytes, _ = capture.snapshot()
         return self
 
 
-class BoundedStderr:
+class CapturedStderr:
     def __init__(self, stream: object) -> None:
         self._stream = stream
         self._retained = bytearray()
@@ -77,15 +72,13 @@ class BoundedStderr:
                 return
             with self._lock:
                 self._bytes += len(chunk)
-                remaining = XVFB_STDERR_LIMIT - len(self._retained)
-                if remaining > 0:
-                    self._retained.extend(chunk[:remaining])
+                self._retained.extend(chunk)
 
-    def snapshot(self) -> tuple[int, bool, str]:
+    def snapshot(self) -> tuple[int, str]:
         with self._lock:
             retained = bytes(self._retained)
             total = self._bytes
-        return total, total > len(retained), retained.decode("utf-8", "replace")
+        return total, retained.decode("utf-8", "replace")
 
     def close(self) -> None:
         self._thread.join(timeout=0.5)
@@ -284,14 +277,11 @@ def diagnostic(
     operation: str,
     status: str,
     failure: AdapterFailure | None = None,
-    capture: BoundedStderr | None = None,
+    capture: CapturedStderr | None = None,
 ) -> dict[str, object]:
     mode, read_only, _ = socket_directory_state()
-    captured_bytes, captured_truncated, _ = (
-        (0, False, "") if capture is None else capture.snapshot()
-    )
+    captured_bytes, _ = (0, "") if capture is None else capture.snapshot()
     return {
-        "schema_version": 1,
         "component": "hopper_private_display",
         "operation": operation,
         "status": status,
@@ -308,9 +298,6 @@ def diagnostic(
         "xvfb_stderr_bytes": captured_bytes
         if failure is None
         else failure.stderr_bytes,
-        "xvfb_stderr_truncated": captured_truncated
-        if failure is None
-        else failure.stderr_truncated,
     }
 
 
@@ -441,8 +428,8 @@ def authorize_display(
         ) from error
 
 
-def classify_xvfb_failure(capture: BoundedStderr) -> AdapterFailure:
-    stderr_bytes, stderr_truncated, text = capture.snapshot()
+def classify_xvfb_failure(capture: CapturedStderr) -> AdapterFailure:
+    stderr_bytes, text = capture.snapshot()
     mode, read_only, directory = socket_directory_state()
     if read_only is True:
         return AdapterFailure(
@@ -450,7 +437,6 @@ def classify_xvfb_failure(capture: BoundedStderr) -> AdapterFailure:
             "socket_directory_read_only",
             "X11 socket directory is read-only",
             stderr_bytes,
-            stderr_truncated,
         )
     if directory and mode != "1777":
         return AdapterFailure(
@@ -458,7 +444,6 @@ def classify_xvfb_failure(capture: BoundedStderr) -> AdapterFailure:
             "socket_directory_mode",
             "X11 socket directory mode is not 1777",
             stderr_bytes,
-            stderr_truncated,
         )
     if mode is not None and not directory:
         return AdapterFailure(
@@ -466,7 +451,6 @@ def classify_xvfb_failure(capture: BoundedStderr) -> AdapterFailure:
             "socket_directory_type",
             "X11 socket path is not a directory",
             stderr_bytes,
-            stderr_truncated,
         )
     lowered = text.lower()
     if "error while loading shared libraries" in lowered:
@@ -475,7 +459,6 @@ def classify_xvfb_failure(capture: BoundedStderr) -> AdapterFailure:
             "missing_library",
             "Xvfb shared library unavailable",
             stderr_bytes,
-            stderr_truncated,
         )
     if any(
         marker in lowered
@@ -490,21 +473,19 @@ def classify_xvfb_failure(capture: BoundedStderr) -> AdapterFailure:
             "address_collision",
             "private display address collision",
             stderr_bytes,
-            stderr_truncated,
         )
     return AdapterFailure(
         PRIVATE_DISPLAY_UNAVAILABLE,
         "xvfb_startup_failed",
         "private X display unavailable",
         stderr_bytes,
-        stderr_truncated,
     )
 
 
 def start_xvfb(
     session: Path,
     args: argparse.Namespace,
-) -> tuple[subprocess.Popen[bytes], str, Path, BoundedStderr]:
+) -> tuple[subprocess.Popen[bytes], str, Path, CapturedStderr]:
     authority = session / "Xauthority"
     collision: AdapterFailure | None = None
     for _ in range(3):
@@ -551,7 +532,7 @@ def start_xvfb(
                 "xvfb_startup_failed",
                 "Xvfb stderr unavailable",
             )
-        capture = BoundedStderr(process.stderr)
+        capture = CapturedStderr(process.stderr)
         deadline = time.monotonic() + 2
         socket = Path(f"/tmp/.X11-unix/X{display_number}")
         while time.monotonic() < deadline and process.poll() is None:

package/scripts/rea.mjs

@@ -4,8 +4,6 @@ import { access } from "node:fs/promises";
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
-import { runPackageRunnerSetupBootstrap } from "./package-runner-bootstrap.mjs";
-
 // Route production MCP before importing Incur. Incur owns registration helpers
 // such as `mcp add`, while only dist/main.js may serve the stdio tool catalog.
 const args = process.argv.slice(2);
@@ -17,21 +15,13 @@ const isMcpMode =
   args.length === 1 && (args[0] === "--mcp" || args[0] === "mcp");
 const isMcpDoctorMode = args[0] === "mcp" && args[1] === "doctor";
 const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
-const bootstrapExitCode = await runPackageRunnerSetupBootstrap({
-  args,
-  environment: process.env,
-  packageRoot,
-  packageName: packageJson.name,
-});
 const runtimeFiles = isMcpMode
   ? ["dist/main.js"]
   : isMcpDoctorMode
     ? ["dist/main.js", "dist/mcpDoctor.js"]
     : ["dist/cli.js", "dist/cliOutput.js"];
 
-if (bootstrapExitCode !== undefined) {
-  process.exitCode = bootstrapExitCode;
-} else if (!(await compiledRuntimeExists(runtimeFiles))) {
+if (!(await compiledRuntimeExists(runtimeFiles))) {
   process.stderr.write(
     `REA's compiled runtime is missing. Run \`npm ci\` in ${packageRoot} to install dependencies and build REA, then restart it. If this is an installed package, reinstall rea-agents.\n`,
   );