rea-agents 5.0.0 → 6.1.0

package/scripts/electron-active-hook.cjs

@@ -16,9 +16,19 @@ const ipcEventKinds = new Set([
   "ipc-renderer-post-message",
 ]);
 const events = [];
+// Budget serialized data and estimated retained object/array storage together.
+const retentionBudgetBytes = 16 * 1024 * 1024;
+const snapshotEnvelopeReserveBytes = 1024;
+let estimatedRetainedBytes = 0;
+let serializedBytes = 0;
 let observed = 0;
 let observedIpc = 0;
 let observedRuntime = 0;
+let dropped = 0;
+let droppedIpc = 0;
+let droppedRuntime = 0;
+const droppedFamilies = new Map();
+const droppedRoles = new Map();
 let sequence = 0;
 let correlationSequence = 0;
 
@@ -43,6 +53,73 @@ const shape = (value, depth = 0) => {
   }
 };
 
+// Measure JSON strings without allocating an encoded copy of a caller value.
+const jsonStringBytes = (value) => {
+  let bytes = 2;
+  for (let index = 0; index < value.length; index += 1) {
+    const code = value.charCodeAt(index);
+    if (code === 0x22 || code === 0x5c) bytes += 2;
+    else if (
+      code === 0x08 ||
+      code === 0x09 ||
+      code === 0x0a ||
+      code === 0x0c ||
+      code === 0x0d
+    )
+      bytes += 2;
+    else if (code <= 0x1f) bytes += 6;
+    else if (code >= 0xd800 && code <= 0xdbff) {
+      const next = value.charCodeAt(index + 1);
+      if (next >= 0xdc00 && next <= 0xdfff) {
+        bytes += 4;
+        index += 1;
+      } else bytes += 6;
+    } else if (code >= 0xdc00 && code <= 0xdfff) bytes += 6;
+    else if (code <= 0x7f) bytes += 1;
+    else if (code <= 0x7ff) bytes += 2;
+    else bytes += 3;
+    if (bytes > retentionBudgetBytes) return bytes;
+  }
+  return bytes;
+};
+
+const jsonScalarBytes = (value) => {
+  if (value === null) return 4;
+  if (typeof value === "string") return jsonStringBytes(value);
+  if (typeof value === "boolean") return value ? 4 : 5;
+  return String(value).length;
+};
+
+const eventFamily = (kind, processTypeValue) => {
+  if (kind === "preload" && processTypeValue === "main")
+    return "preload-configuration";
+  if (kind.startsWith("ipc-renderer"))
+    return processTypeValue === "renderer" ? "renderer-ipc" : "ipc";
+  return ipcEventKinds.has(kind) ? "ipc" : kind;
+};
+
+const noteDropped = (kind, processTypeValue, isIpc) => {
+  dropped += 1;
+  if (isIpc) droppedIpc += 1;
+  else droppedRuntime += 1;
+  const family = eventFamily(kind, processTypeValue);
+  droppedFamilies.set(family, (droppedFamilies.get(family) ?? 0) + 1);
+  if (typeof processTypeValue === "string")
+    droppedRoles.set(
+      processTypeValue,
+      (droppedRoles.get(processTypeValue) ?? 0) + 1,
+    );
+  if (kind === "window-lifecycle")
+    droppedRoles.set("window", (droppedRoles.get("window") ?? 0) + 1);
+  if (kind === "web-contents-lifecycle" || kind === "navigation")
+    droppedRoles.set(
+      "web_contents",
+      (droppedRoles.get("web_contents") ?? 0) + 1,
+    );
+  if (kind === "preload" && processTypeValue === "preload")
+    droppedRoles.set("preload", (droppedRoles.get("preload") ?? 0) + 1);
+};
+
 const isAllowedNavigation = (value) => {
   if (typeof value !== "string") return true;
   try {
@@ -83,7 +160,8 @@ const frameIdentity = (event) => {
 
 const record = (event) => {
   observed += 1;
-  if (ipcEventKinds.has(event.kind)) observedIpc += 1;
+  const isIpc = ipcEventKinds.has(event.kind);
+  if (isIpc) observedIpc += 1;
   else observedRuntime += 1;
   const raw = {
     sequence: ++sequence,
@@ -109,10 +187,15 @@ const record = (event) => {
     error: false,
     ...event,
   };
-  const argumentShapes = Array.isArray(raw.argument_shapes)
+  const shapeGroups = Array.isArray(raw.argument_shape_value_groups)
+    ? raw.argument_shape_value_groups.filter(Array.isArray)
+    : Array.isArray(raw.argument_shape_values)
+      ? [raw.argument_shape_values]
+      : [];
+  const existingShapes = Array.isArray(raw.argument_shapes)
     ? raw.argument_shapes
     : [];
-  events.push({
+  const retainedEvent = {
     ...raw,
     correlation_id: raw.correlation_id,
     event: typeof raw.event === "string" ? raw.event : null,
@@ -121,9 +204,7 @@ const record = (event) => {
     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",
-    ),
+    argument_shapes: [],
     result_shape:
       typeof raw.result_shape === "string" ? raw.result_shape : null,
     process_type:
@@ -132,8 +213,91 @@ const record = (event) => {
       typeof raw.artifact_path === "string" ? raw.artifact_path : null,
     artifact_sha256:
       typeof raw.artifact_sha256 === "string" ? raw.artifact_sha256 : null,
-  });
-  return events.at(-1);
+  };
+  delete retainedEvent.argument_shape_values;
+  delete retainedEvent.argument_shape_value_groups;
+
+  // All event values are JSON scalars except argument_shapes. Measure them
+  // incrementally so large channels, paths, or shape lists never require a
+  // full JSON.stringify temporary allocation before the budget decision.
+  let eventBytes = 2;
+  let argumentShapeCount = 0;
+  const eventKeys = Object.keys(retainedEvent);
+  for (let index = 0; index < eventKeys.length; index += 1) {
+    const key = eventKeys[index];
+    const value = retainedEvent[key];
+    if (index > 0) eventBytes += 1;
+    eventBytes += jsonStringBytes(key) + 1;
+    if (key === "argument_shapes") {
+      eventBytes += 2;
+      let shapeOverflow = false;
+      const countShape = (argument) => {
+        const encodedShapeBytes = jsonStringBytes(shape(argument));
+        eventBytes += encodedShapeBytes + (argumentShapeCount === 0 ? 0 : 1);
+        argumentShapeCount += 1;
+        shapeOverflow =
+          eventBytes + estimatedRetainedBytes + snapshotEnvelopeReserveBytes >
+          retentionBudgetBytes;
+      };
+      for (const group of shapeGroups)
+        for (const argument of group) {
+          countShape(argument);
+          if (shapeOverflow) break;
+        }
+      if (shapeOverflow) {
+        noteDropped(raw.kind, retainedEvent.process_type, isIpc);
+        return null;
+      }
+      for (const valueShape of existingShapes)
+        if (!shapeOverflow) {
+          eventBytes +=
+            jsonStringBytes(
+              typeof valueShape === "string" ? valueShape : "unknown",
+            ) + (argumentShapeCount++ === 0 ? 0 : 1);
+          shapeOverflow =
+            eventBytes + estimatedRetainedBytes + snapshotEnvelopeReserveBytes >
+            retentionBudgetBytes;
+        }
+      if (shapeOverflow) {
+        noteDropped(raw.kind, retainedEvent.process_type, isIpc);
+        return null;
+      }
+    } else eventBytes += jsonScalarBytes(value);
+    if (
+      eventBytes + estimatedRetainedBytes + snapshotEnvelopeReserveBytes >
+      retentionBudgetBytes
+    ) {
+      noteDropped(raw.kind, retainedEvent.process_type, isIpc);
+      return null;
+    }
+  }
+  // Reserve room for the only fields mutated after recording: result_shape and
+  // error. The shape vocabulary's longest value is "undefined".
+  const reservedMutationBytes = retainedEvent.result_shape === null ? 7 : 0;
+  // Include one byte for the event-array separator and reserve space for the
+  // snapshot's counters and JSON delimiters.
+  // One retained event, one defensive snapshot copy, and up to two serialized
+  // result views (timeline plus IPC), with per-object and per-array-slot costs.
+  const eventEstimateBytes = eventBytes * 3 + 512 + argumentShapeCount * 16;
+  const retainedEventBytes = eventEstimateBytes + reservedMutationBytes + 1;
+  if (
+    estimatedRetainedBytes + retainedEventBytes + snapshotEnvelopeReserveBytes >
+    retentionBudgetBytes
+  ) {
+    noteDropped(raw.kind, retainedEvent.process_type, isIpc);
+    return null;
+  }
+  for (const group of shapeGroups)
+    for (const argument of group)
+      retainedEvent.argument_shapes.push(shape(argument));
+  for (const valueShape of existingShapes)
+    retainedEvent.argument_shapes.push(
+      typeof valueShape === "string" ? valueShape : "unknown",
+    );
+  events.push(retainedEvent);
+  estimatedRetainedBytes += retainedEventBytes;
+  serializedBytes += eventBytes + reservedMutationBytes + 1;
+  return retainedEvent;
 };
 
 const recordRuntime = (kind, event, phase, details = {}) =>
@@ -145,7 +309,7 @@ const recordIpc = (kind, channel, args, details = {}) =>
     return record({
       kind,
       channel: typeof channel === "string" ? channel : null,
-      argument_shapes: values.map((value) => shape(value)),
+      argument_shape_values: values,
       ...details,
     });
   })();
@@ -222,7 +386,7 @@ const patchNavigationMethods = (webContents, contentsId) => {
     webContents[method] = function patchedNavigation(...args) {
       recordRuntime("navigation", method, "attempted", {
         target: contentsId,
-        argument_shapes: args.map((value) => shape(value)),
+        argument_shape_values: args,
       });
       if (method === "loadURL" && !isAllowedNavigation(args[0])) {
         recordRuntime("navigation", method, "blocked", {
@@ -354,7 +518,7 @@ const patchWebContents = (webContents, windowId) => {
         recordRuntime("navigation", event, "blocked", {
           target: contentsId,
           sender: windowId,
-          argument_shapes: args.map((value) => shape(value)),
+          argument_shape_values: args,
           error: true,
         });
         return;
@@ -363,7 +527,7 @@ const patchWebContents = (webContents, windowId) => {
     recordRuntime(kind, event, "observed", {
       target: contentsId,
       sender: windowId,
-      argument_shapes: args.map((value) => shape(value)),
+      argument_shape_values: args,
       error: kind === "error",
     });
     if (event === "did-create-window") {
@@ -379,31 +543,44 @@ const patchWebContents = (webContents, windowId) => {
   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;
+const patchWindows = (app) => {
+  if (app === null || app === undefined) return;
+  app.on("browser-window-created", (_event, window) => {
+    const targetId = identity(window, "window");
+    recordRuntime("window-lifecycle", "created", "completed", {
+      target: targetId,
+      capture_method: "event-emitter",
+    });
+    try {
+      // Electron 44 separates the preload descriptor from WebPreferences.
+      // Read the engine's descriptor, never infer a path from application code.
+      const preferences = window.webContents.getLastWebPreferences?.();
+      const preload =
+        typeof preferences?.preload === "string"
+          ? preferences.preload
+          : window.webContents._getPreloadScript?.()?.filePath;
       if (typeof preload === "string")
         recordRuntime("preload", "configured", "completed", {
           target: targetId,
           artifact_path: preload,
         });
-      patchEmitter(window, (event) =>
-        recordRuntime("window-lifecycle", event, "observed", {
+    } catch (cause) {
+      recordRuntime(
+        "error",
+        cause instanceof Error ? cause.message : String(cause),
+        "failed",
+        {
           target: targetId,
-        }),
+          error: true,
+        },
       );
-      patchWebContents(window.webContents, targetId);
-      return window;
-    },
+    }
+    patchEmitter(window, (event) =>
+      recordRuntime("window-lifecycle", event, "observed", {
+        target: targetId,
+      }),
+    );
+    patchWebContents(window.webContents, targetId);
   });
 };
 
@@ -427,7 +604,7 @@ try {
       "observed",
       {
         target: "app",
-        argument_shapes: args.map((value) => shape(value)),
+        argument_shape_values: args,
         process_type: "main",
       },
     ),
@@ -435,33 +612,60 @@ try {
   patchIpcMain(electron.ipcMain);
   boundaries.patchIpcRenderer(electron.ipcRenderer);
   boundaries.patchContextBridge(electron.contextBridge);
-  patchBrowserWindow(electron);
+  patchWindows(electron.app);
   boundaries.patchUtilityProcess(electron.utilityProcess);
   boundaries.patchShell(electron.shell);
-  boundaries.patchSessionManager(electron.session);
+  boundaries.patchSessionManager(electron.session, electron.app);
   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)],
+      argument_shape_values: [cause, origin],
       error: true,
     });
     throw cause;
   });
   process.once("unhandledRejection", (reason, promise) => {
     recordRuntime("process-lifecycle", "unhandled-rejection", "observed", {
-      argument_shapes: [shape(reason), shape(promise)],
+      argument_shape_values: [reason, promise],
       error: true,
     });
     throw reason;
   });
-} catch {
+} catch (cause) {
   globalThis.__reaElectronActiveHookError = true;
+  recordRuntime(
+    "error",
+    cause instanceof Error ? cause.message : String(cause),
+    "failed",
+    {
+      target: "active-hook-installation",
+      error: true,
+    },
+  );
 }
 
 globalThis.__reaElectronActiveSnapshot = () => ({
-  events: events.slice(),
+  events: events.map((event) => ({
+    ...event,
+    argument_shapes: [...event.argument_shapes],
+  })),
+  retention_budget_bytes: retentionBudgetBytes,
+  estimated_retained_bytes: estimatedRetainedBytes,
+  event_serialized_byte_upper_bound: serializedBytes,
+  retained: events.length,
+  dropped,
+  dropped_ipc: droppedIpc,
+  dropped_runtime: droppedRuntime,
+  dropped_event_families: [...droppedFamilies].map(([family, count]) => ({
+    family,
+    count,
+  })),
+  dropped_event_roles: [...droppedRoles].map(([role, count]) => ({
+    role,
+    count,
+  })),
   observed,
   observed_ipc: observedIpc,
   observed_runtime: observedRuntime,

package/scripts/rea.mjs

@@ -19,7 +19,7 @@ const runtimeFiles = isMcpMode
   ? ["dist/main.js"]
   : isMcpDoctorMode
     ? ["dist/main.js", "dist/mcpDoctor.js"]
-    : ["dist/cli.js", "dist/cliOutput.js"];
+    : ["dist/cli.js", "dist/cliOutput.js", "dist/cli/streamedJsonOutput.js"];
 
 if (!(await compiledRuntimeExists(runtimeFiles))) {
   process.stderr.write(
@@ -39,6 +39,8 @@ if (!(await compiledRuntimeExists(runtimeFiles))) {
   process.exitCode = result.exitCode;
 } else {
   const { createCli } = await import("../dist/cli.js");
+  const { createStreamedCliJsonOutput } =
+    await import("../dist/cli/streamedJsonOutput.js");
   const {
     renderCliOutputArgumentError,
     renderEmptyFilteredCliOutput,
@@ -51,14 +53,20 @@ if (!(await compiledRuntimeExists(runtimeFiles))) {
     process.exitCode = 1;
   } else {
     let wroteOutput = false;
-    await createCli().serve(args, {
+    const resultOutput = createStreamedCliJsonOutput(args, process.stdout);
+    await createCli(process.env, resultOutput).serve(args, {
       stdout: (output) => {
+        if (resultOutput?.handled) {
+          if (resultOutput.failed)
+            process.stderr.write(sanitizeCliOutput(output));
+          return;
+        }
         const sanitized = sanitizeCliOutput(output);
         if (sanitized.length > 0) wroteOutput = true;
         process.stdout.write(sanitized);
       },
     });
-    if (!wroteOutput)
+    if (!wroteOutput && !resultOutput?.handled)
       process.stdout.write(renderEmptyFilteredCliOutput(args) ?? "");
   }
 }

package/skills/reverse-engineer-anything/SKILL.md

@@ -2,9 +2,8 @@
 name: reverse-engineer-anything
 description: Reverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.
 metadata:
-  version: "27"
-  tool_count: 133
-  catalog_digest: "83b4c3445ed0ec003c0aeefa3188f123d9ae319484f8b1e2b611d2fe278c9c72"
+  version: "33"
+  tool_count: 138
 ---
 
 # REA
@@ -33,7 +32,9 @@ When tools are absent or registration is stale:
    `npx -y rea-agents@latest doctor --client codex --json`. Substitute the current
    supported client: `claude_code`, `claude_desktop`, `codex`, `cursor`,
    `gemini_cli`, `windsurf`, `devin`, `opencode`, `antigravity`, `copilot_cli`,
-   `commandcode`, or `vscode`. If the client is unknown, use `doctor --json` and
+   `commandcode`, `vscode`, `grok_build`, or `grok_bot`. `grok_bot` has no local
+   file registration: doctor reports the Grok Bot chat step, and setup does not
+   write `mcp.json`. If the client is unknown, use `doctor --json` and
    inspect its registration results before choosing a setup scope.
 2. Distinguish the reason. Missing, malformed, or stale registration needs a
    scoped configuration repair. An aligned registration with no tools in the
@@ -93,7 +94,27 @@ explicit path or endpoint and do not need it.
   consult the NativeAOT workflow in `references/native-and-artifacts.md` for
   optional metadata recovery and its supported host/layout boundary.
 - User-owned browser page already open: `list_browser_targets`.
+- Retained HAR/native mitmproxy capture: `inspect_web_network_capture`. Select
+  original record ordinals when useful; inspect producer fields and byte/number
+  sidecars without fetching recorded URLs or claiming live attribution. See
+  [historical captures](https://github.com/morluto/rea/blob/main/docs/web-network-captures.md) for the exact upstream
+  profile and credential exclusions.
 - User-owned Electron runtime already open: `list_electron_targets`.
+- Explicit local EVM bytecode carrier: `inspect_evm_interface` with caller-selected
+  `raw` or `hex` encoding. Preserve carrier/decoded digests and treat selectors,
+  argument strings and mutability as inferred candidates; this performs no chain
+  lookup or target execution. See the
+  [EVM bytecode guide](https://github.com/morluto/rea/blob/main/docs/evm-bytecode.md).
+- Explicit Linux ELF file for offline layout, symbols, relocations or static
+  mitigation evidence: `inspect_binary_layout`. This target-free operation uses
+  caller-supplied pwntools without opening a disassembler database. Preserve its
+  raw locations and inference/coverage limits; see the
+  [offline binary guide](https://github.com/morluto/rea/blob/main/docs/binary-diagnostics.md).
+- Supplied Linux x86-64 ELF core: `inspect_recorded_crash`. Read every recorded
+  thread, raw note and source-bound register without opening a live target.
+  Historical PIDs do not select live processes. Request `include_debugger_context`
+  only when core-only mapping candidates help; see the
+  [recorded crash guide](https://github.com/morluto/rea/blob/main/docs/recorded-crashes.md).
 - Native executable, library, or analysis database: `open_binary`, then
   use focused analysis tools directly; call `binary_overview` when metadata or
   inventory context is useful and available from the selected provider.
@@ -126,6 +147,13 @@ Start with the default result and use its inline Evidence and graph context.
 Do not repeat an identical tool call. Make a focused follow-up only when the
 returned result leaves a specific question unanswered.
 
+If MCP reports `resource_constraint` with `details.resource: "transport"`, use
+its reported same-session Evidence reference with a focused application tool,
+or call `export_evidence_bundle` to write the complete session to a selected
+path. The analysis remains complete in the ledger; avoid repeating it merely
+to request the same oversized response. Complete CLI JSON output also streams
+without a single MCP frame.
+
 Every conclusion must distinguish observations, inferences, and unknowns. Cite
 Evidence IDs, preserve limitations and incomplete coverage, and never imply
 that static analysis observed execution. Runtime requests execute the declared

package/skills/reverse-engineer-anything/references/javascript-applications.md

@@ -2,10 +2,17 @@
 
 Use `analyze_javascript_application` directly on the operator-supplied ASAR or
 extracted tree. The complete result, graph, and Evidence context are returned
-inline. Source-map contents are part of the static analysis. Start from its
+inline when they fit the MCP frame. Source-map contents are part of the static analysis. Start from its
 findings, coverage, unknowns, and graph context, then make a focused follow-up
 only when a specific question remains unanswered.
 
+An oversized response reports `resource_constraint` and
+`details.resource: "transport"`. Reuse
+`details.reported_limits.evidence_reference` with `trace_application_feature`
+for the module or feature under investigation. `export_evidence_bundle` writes
+the complete canonical session to a caller-selected file. Both workflows keep
+the original Evidence and coverage; a broad follow-up can also exceed framing.
+
 BrowserWindow preferences, preload and contextBridge surfaces, IPC
 registrations, utility processes, and native binding requests are static syntax
 observations. Only a unique exact literal IPC channel match supports an inferred

package/skills/reverse-engineer-anything/references/native-and-artifacts.md

@@ -1,5 +1,21 @@
 # Native, managed, and packaged artifacts
 
+## Recorded Linux crashes
+
+Use `inspect_recorded_crash` with an explicit Linux x86-64 ELF core path to
+inspect historical thread registers, signals, raw notes and original file
+ranges. It is independent of the active disassembler target. Source-bound
+register values and note bytes are observations; missing notes, signal-thread
+association and current executable/library identity remain unknown. PIDs are
+historical metadata and never authorize live attach or control.
+
+The optional `include_debugger_context` facet adds mapping candidates through
+caller-supplied GDB/pwndbg in an owned core-only session. Display names do not
+establish current file identity; zero reported flags leave permissions unknown.
+Requested unavailable context fails with setup guidance. See
+[recorded crashes](https://github.com/morluto/rea/blob/main/docs/recorded-crashes.md)
+for exact upstream profiles, bounds and verification coverage.
+
 ## Native targets
 
 After `open_binary`, use focused search, procedure, or function tools directly.
@@ -9,6 +25,12 @@ cross-references. Addresses and recovered pseudocode are analysis observations,
 not original source. Provider unavailability and unsupported metadata remain
 unknown rather than false.
 
+To see which functions or Objective-C methods a Mach-O actually calls in one
+run, use `observe_native_calls` with explicit breakpoints and a bounded
+`duration_ms`/`max_events`. It launches a new process under LLDB, so the target
+runs and may change files or use the network. Hardened-runtime targets need the
+`get-task-allow` entitlement.
+
 Use `binary_session` with no arguments to check the open target, selected
 provider, and alignment. Its default `result.tool_availability` includes the
 complete tool inventory with availability reasons and remediation. When choosing
@@ -77,6 +99,13 @@ helpers, launchd plists, symlinks, and each bundle's `info_plist_path` and
 executable candidates. Roles are path conventions, not parsed plists; read the
 listed plists with `inspect_plist`.
 
+After `open_binary` on a `.app` or Mach-O, use `trace_dylib_resolution` to see
+which file each `@rpath`, `@loader_path` and `@executable_path` load reaches for
+every executable in the bundle. It also lists missing or weak loads and earlier
+`@rpath` candidates that are absent. Narrow large bundles with `roots` or
+`architecture`. System paths stay undetermined because the dyld shared cache
+provides them.
+
 Use `extract_artifact` when materialized files are needed. It takes no arguments
 and materializes all regular files into a fresh temporary directory chosen by
 REA. Symlinks and encrypted entries are inventory facts, not extractable files.

package/third_party/README.md

@@ -0,0 +1,60 @@
+# Upstream analysis engines
+
+REA integrates existing tools through provider adapters. Upstream source remains
+unmodified and retains its own license; it is not copied into REA's domain or
+application code.
+
+## jadx-headless-mcp
+
+- Source: <https://github.com/1013503897/jadx-headless-mcp>
+- Submodule: `third_party/jadx-headless-mcp`
+- Release: `v0.7.1`
+- Commit: `5844800a486d2248fa949b74c9896285f5b54de2`
+- License: Apache-2.0; see the submodule's `LICENSE`.
+- Release identity: `src/android/JadxRelease.ts`.
+- REA integration: `src/android/`; no upstream patches in this version.
+
+Fetch source for inspection with:
+
+```sh
+git submodule update --init third_party/jadx-headless-mcp
+```
+
+Normal REA builds and installed npm packages do not require this submodule or a
+Gradle build. Supply a separately obtained JAR with `REA_JADX_MCP_JAR`; REA never
+downloads engines during an analysis operation. The audited release JAR is
+identified by SHA-256. A caller-supplied build reporting the supported protocol
+version retains its actual digest and an unknown source revision unless its
+bytes match the audited release.
+
+When updating: review upstream protocol and license changes, update the gitlink
+and release identity together, exercise the adapter's producer regressions, and
+run the real APK CLI/MCP lane. Never attribute modified engine bytes to the
+audited source revision.
+
+## Public APK fixture
+
+`scripts/fetch-android-fixtures.mjs` explicitly downloads the audited engine and
+Appium ApiDemos v6.0.18 into ignored `_reference/apk-integration/`. Both downloads
+are checked against fixed SHA-256 values. Fixture provenance is recorded in
+`scripts/fixtures/android-apidemos.json`; the source uses Apache-2.0. This is a
+static analysis fixture: no emulator, device, SDK installation or app execution
+is needed. APKs and JARs are neither tracked nor included in npm packages.
+
+## Firmware engines
+
+| Engine | Source | Release | Pinned commit | License |
+| --- | --- | --- | --- | --- |
+| Binwalk | <https://github.com/ReFirmLabs/binwalk> | v3.1.0 | `4fdab3d464d97b68e0af9088df3f9e2e1545b21c` | MIT, upstream `LICENSE` |
+| Unblob | <https://github.com/onekey-sec/unblob> | 26.6.4 | `1fcc7a0a584a70a96c31f5a276c20944d199a089` | MIT, upstream `LICENSE` |
+
+Source remains unmodified in `third_party/binwalk` and `third_party/unblob`.
+Release records live in `src/firmware/FirmwareRelease.ts`; REA adapters own the
+CLI/report interpretation and lifecycle in `src/firmware/`. Caller-supplied
+executables retain their actual launcher digest and unknown source revision;
+version output alone does not establish source identity. REA does not bundle
+extractors or download/install firmware engines during analysis.
+
+On updates: inspect actual pinned CLI and report producers, preserve licenses,
+update gitlinks/release records, run report regressions and the real firmware
+lane. See [firmware setup and coverage](../docs/firmware-analysis.md).

package/third_party/evmole/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Maxim Andreev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.