rea-agents 4.1.0 → 5.0.0

package/bridge/android/ReaJadxBridge.java

@@ -0,0 +1,247 @@
+import com.atxx.jhmcp.*;
+import com.google.gson.*;
+import io.modelcontextprotocol.kotlin.sdk.server.*;
+import io.modelcontextprotocol.kotlin.sdk.types.*;
+import jadx.api.*;
+import jadx.core.dex.nodes.*;
+import java.io.PrintStream;
+import java.util.*;
+import java.util.concurrent.CountDownLatch;
+import java.util.stream.Collectors;
+import kotlin.Unit;
+import kotlin.coroutines.EmptyCoroutineContext;
+import kotlinx.coroutines.BuildersKt;
+import kotlinx.io.CoreKt;
+import kotlinx.io.JvmCoreKt;
+import kotlinx.serialization.json.JsonObject;
+
+/** REA-owned metadata boundary for the unmodified jadx-headless-mcp 0.7.1 JAR. */
+class ReaJadxBridge {
+  private static final Gson JSON = new Gson();
+  private final SessionHolder holder;
+  private JadxSession indexedSession;
+  private Map<String, List<ClassSnapshot>> classes = Map.of();
+
+  private record MethodSnapshot(String name, String shortId, Map<String, Object> summary) {}
+  private record ClassSnapshot(JavaClass node, List<MethodSnapshot> methods, Map<String, Object> summary) {}
+
+  private ReaJadxBridge(SessionHolder holder) { this.holder = holder; }
+
+  private static CallToolResult text(String value, boolean failed) {
+    return new CallToolResult(List.of(new TextContent(value, null, null)), failed, null, null);
+  }
+
+  private static CallToolResult json(Object value) { return text(JSON.toJson(value), false); }
+
+  private static String string(JsonObject args, String name) {
+    JsonElement value = JsonParser.parseString(args.toString()).getAsJsonObject().get(name);
+    if (value == null || !value.isJsonPrimitive() || !value.getAsJsonPrimitive().isString())
+      throw new IllegalArgumentException(name + " must be a string");
+    return value.getAsString();
+  }
+
+  private static int integer(JsonObject args, String name, int fallback) {
+    JsonElement value = JsonParser.parseString(args.toString()).getAsJsonObject().get(name);
+    if (value == null) return fallback;
+    if (!value.isJsonPrimitive() || !value.getAsJsonPrimitive().isNumber())
+      throw new IllegalArgumentException(name + " must be a nonnegative integer");
+    try {
+      int result = value.getAsBigDecimal().intValueExact();
+      if (result < 0) throw new ArithmeticException();
+      return result;
+    } catch (ArithmeticException error) {
+      throw new IllegalArgumentException(name + " must be a nonnegative integer", error);
+    }
+  }
+
+  private JadxSession session() {
+    JadxSession current = holder.current();
+    if (current == null) throw new IllegalArgumentException("No APK loaded");
+    return current;
+  }
+
+  private ClassSnapshot selected(JsonObject args) {
+    JadxSession current = session();
+    if (indexedSession != current) {
+      Map<String, List<ClassSnapshot>> index = new LinkedHashMap<>();
+      if (!current.getClasses().isEmpty()) {
+        JadxDecompiler decompiler = current.getClasses().get(0).getClassNode().root().getDecompiler();
+        // JavaClass.getMethods/getFields/getInnerClasses all load code. Raw nodes do not.
+        // Snapshot every identity before code generation can rewrite aliases or members.
+        for (JavaClass cls : decompiler.getClassesWithInners()) {
+          ClassNode node = cls.getClassNode();
+          List<MethodNode> ordered = new ArrayList<>(node.getMethods());
+          ordered.sort(Comparator.comparing(MethodNode::getAlias));
+          List<MethodSnapshot> methods = ordered.stream().map(method -> {
+            String name = method.getAlias();
+            String signature = name + "(" + method.getArgTypes().stream()
+                .map(Object::toString).collect(Collectors.joining(", "))
+                + "): " + method.getReturnType().toString();
+            return new MethodSnapshot(name, method.getMethodInfo().getShortId(), Map.of(
+                "name", name, "signature", signature,
+                "is_constructor", method.isConstructor(), "def_pos", 0));
+          }).toList();
+          List<Map<String, Object>> fields = node.getFields().stream()
+              .sorted(Comparator.comparing(FieldNode::getAlias))
+              .map(field -> Map.<String, Object>of("name", field.getAlias(),
+                  "type", field.getType().toString(), "def_pos", 0)).toList();
+          List<String> inner = node.getInnerClasses().stream().map(ClassNode::getFullName).toList();
+          Map<String, Object> summary = Map.of(
+              "full_name", cls.getFullName(), "name", cls.getName(),
+              "method_count", methods.size(), "field_count", fields.size(),
+              "inner_class_count", inner.size(), "inner_classes", inner,
+              "methods", methods.stream().map(MethodSnapshot::summary).toList(), "fields", fields);
+          index.computeIfAbsent(cls.getFullName(), ignored -> new ArrayList<>())
+              .add(new ClassSnapshot(cls, methods, summary));
+        }
+      }
+      classes = Collections.unmodifiableMap(index);
+      indexedSession = current;
+    }
+    String name = string(args, "class_name");
+    List<ClassSnapshot> candidates = classes.get(name);
+    if (candidates == null) throw new IllegalArgumentException("Exact class not found: " + name);
+    if (candidates.size() != 1) throw new IllegalArgumentException("Ambiguous metadata class identity: " + name
+        + "; raw identities: " + candidates.stream().map(candidate -> candidate.node().getRawName()).toList());
+    return candidates.get(0);
+  }
+
+  private List<MethodSnapshot> methods(ClassSnapshot cls, JsonObject args) {
+    String name = string(args, "method_name");
+    List<MethodSnapshot> result = cls.methods().stream().filter(method -> method.name().equals(name)).toList();
+    if (result.isEmpty()) throw new IllegalArgumentException("Method not found: " + name);
+    return result;
+  }
+
+  private JavaMethod method(ClassSnapshot cls, MethodSnapshot selected) {
+    JavaMethod result = cls.node().searchMethodByShortId(selected.shortId());
+    if (result == null) throw new IllegalArgumentException("Method identity no longer available: " + selected.shortId());
+    return result;
+  }
+
+  private CallToolResult handle(String name, JsonObject args) {
+    if (name.equals("rea_jvm_status")) return json(Map.of(
+        "engine_reported_version", BuildInfo.VERSION,
+        "max_heap_bytes", Runtime.getRuntime().maxMemory(),
+        "available_processors", Runtime.getRuntime().availableProcessors(),
+        "java_version", System.getProperty("java.version"),
+        "metadata_scope", "parsed_members"));
+    JadxSession current = session();
+    if (name.equals("list_classes")) {
+      List<String> names = current.getClassFqns();
+      int offset = integer(args, "offset", 0);
+      int limit = integer(args, "limit", 200);
+      int start = Math.min(offset, names.size());
+      int end = (int) Math.min((long) start + limit, names.size());
+      return json(Map.of("total", names.size(), "offset", offset, "limit", limit,
+          "items", names.subList(start, end)));
+    }
+    ClassSnapshot cls = selected(args);
+    if (name.equals("get_class_summary")) return json(cls.summary());
+    if (name.equals("get_method_body")) {
+      List<MethodSnapshot> overloads = methods(cls, args);
+      int index = integer(args, "overload_index", 0);
+      if (index >= overloads.size()) throw new IllegalArgumentException("overload_index out of range: " + index);
+      JavaMethod method = method(cls, overloads.get(index));
+      JadxSession.SmartCode code = current.getMethodBodySmart(method, current.getMaxSourceBytes(), true);
+      return json(Map.of("class_name", cls.summary().get("full_name"),
+          "method_name", overloads.get(index).name(), "full_name", method.getFullName(),
+          "overload_index", index, "overload_count", overloads.size(),
+          "mode", code.getKind(), "fell_back", code.getFellBack(),
+          "markers", code.getMarkers(), "body", code.getText()));
+    }
+    List<JavaNode> uses;
+    String target = string(args, "class_name");
+    if (name.equals("get_xrefs_to_class")) uses = cls.node().getUseIn();
+    else {
+      List<MethodSnapshot> overloads = methods(cls, args);
+      if (overloads.size() != 1) throw new IllegalArgumentException("Method references require a unique overload");
+      target += "." + overloads.get(0).name();
+      uses = method(cls, overloads.get(0)).getUseIn();
+    }
+    // REA consumes all references without materializing source line information.
+    List<Map<String, Object>> items = uses.stream().map(node -> current.describeUsage(node, false)).toList();
+    return json(Map.of("target", target, "total", uses.size(), "count", items.size(),
+        "resolve_line", false, "items", items));
+  }
+
+  public static void main(String[] args) throws Exception {
+    PrintStream protocolOut = System.out;
+    System.setOut(System.err);
+    SessionHolder holder = new SessionHolder(new SessionConfig(
+        1048576, 0, 90000L, 1, List.of(), List.of(), 64, ResourceMode.FULL));
+    ServerCapabilities capabilities = new ServerCapabilities(
+        new ServerCapabilities.Tools(null), null, null, null, null, null, null, Map.of());
+    Server server = new Server(new Implementation("rea-jadx-bridge", "1", null, null, null),
+        new ServerOptions(capabilities), "", ignored -> Unit.INSTANCE);
+    SessionToolsKt.registerSessionTools(server, holder);
+    ManifestToolsKt.registerManifestTools(server, holder);
+    ClassToolsKt.registerClassTools(server, holder);
+    MethodToolsKt.registerMethodTools(server, holder);
+    XrefToolsKt.registerXrefTools(server, holder);
+    ReaJadxBridge bridge = new ReaJadxBridge(holder);
+    Set<String> consumed = Set.of("load_apk", "get_app_info", "get_android_manifest",
+        "list_classes", "get_class_summary", "get_method_body",
+        "get_xrefs_to_class", "get_xrefs_to_method");
+    for (String name : new ArrayList<>(server.getTools().keySet()))
+      if (!consumed.contains(name)) server.removeTool(name);
+    Tool diagnostics = new Tool("rea_jvm_status",
+        new ToolSchema(null, new JsonObject(Map.of()), List.of(), null),
+        "Observed worker JVM and metadata scope", null, null, null, null, null, null);
+    server.addTool(diagnostics, (connection, request, continuation) -> bridge.handle("rea_jvm_status", request.getArguments()));
+    for (String name : List.of("list_classes", "get_class_summary",
+        "get_method_body", "get_xrefs_to_class", "get_xrefs_to_method")) {
+      Tool tool = server.getTools().get(name).getTool();
+      server.removeTool(name);
+      List<String> fields = switch (name) {
+        case "list_classes" -> List.of("offset", "limit");
+        case "get_method_body" -> List.of("class_name", "method_name", "overload_index");
+        case "get_xrefs_to_method" -> List.of("class_name", "method_name");
+        default -> List.of("class_name");
+      };
+      Map<String, kotlinx.serialization.json.JsonElement> properties = new LinkedHashMap<>();
+      for (String field : fields) properties.put(field, tool.getInputSchema().getProperties().get(field));
+      String description = switch (name) {
+        case "list_classes" -> "Indexed pages of all top-level class names, with offset and limit.";
+        case "get_class_summary" -> "Parsed member metadata for one exact class name; no source generation.";
+        case "get_method_body" -> "Source for an exact class and stable same-name overload index, with smali fallback.";
+        default -> "Complete static references to an exact class or unique method; source lines are unresolved.";
+      };
+      Tool narrowed = new Tool(name, new ToolSchema(null, new JsonObject(properties),
+          tool.getInputSchema().getRequired(), null), description, null, null, null, null, null, null);
+      server.addTool(narrowed, (connection, request, continuation) -> {
+        try { return bridge.handle(name, request.getArguments()); }
+        catch (IllegalArgumentException error) { return text(error.getMessage(), true); }
+      });
+    }
+    CountDownLatch done = new CountDownLatch(1);
+    server.onClose(() -> { done.countDown(); return Unit.INSTANCE; });
+    StdioServerTransport transport = new StdioServerTransport(
+        CoreKt.buffered(JvmCoreKt.asSource(System.in)),
+        CoreKt.buffered(JvmCoreKt.asSink(protocolOut)));
+    transport.onClose(() -> { done.countDown(); return Unit.INSTANCE; });
+    ServerSession connection = null;
+    try {
+      connection = BuildersKt.runBlocking(EmptyCoroutineContext.INSTANCE,
+          (scope, continuation) -> server.createSession(transport, continuation));
+      done.await();
+    } finally {
+      try {
+        if (connection != null) {
+          ServerSession connected = connection;
+          // Unsubscribe the connection before the SDK joins its notification service.
+          BuildersKt.runBlocking(EmptyCoroutineContext.INSTANCE,
+              (scope, continuation) -> connected.close(continuation));
+        }
+      } finally {
+        try {
+          BuildersKt.runBlocking(EmptyCoroutineContext.INSTANCE,
+              (scope, continuation) -> server.close(continuation));
+        } finally {
+          BuildersKt.runBlocking(EmptyCoroutineContext.INSTANCE,
+              (scope, continuation) -> holder.unload(continuation));
+        }
+      }
+    }
+  }
+}

package/bridge/native/NativeUIChildren.swift

@@ -0,0 +1,27 @@
+import Foundation
+
+struct ChildBatch<Element> {
+  let values: [Element]
+  let complete: Bool
+}
+
+struct ChildCount {
+  let value: Int?
+  let error: Int32?
+}
+
+func serializeHelperOutput(_ value: Any) throws -> Data {
+  try JSONSerialization.data(withJSONObject: value, options: [.sortedKeys, .withoutEscapingSlashes])
+}
+
+func captureChildCount(status: Int32, success: Int32, value: Int) -> ChildCount {
+  guard status == success else { return ChildCount(value: nil, error: status) }
+  return ChildCount(value: value, error: nil)
+}
+
+func captureChildValues<Element>(requestedCount: Int, copy: () -> [Element]?) -> ChildBatch<Element> {
+  guard requestedCount > 0 else { return ChildBatch(values: [], complete: true) }
+  let returned = copy() ?? []
+  let values = Array(returned.prefix(requestedCount))
+  return ChildBatch(values: values, complete: values.count == requestedCount)
+}

package/bridge/native/ReaNativeUI.swift

@@ -22,15 +22,17 @@ func attribute(_ element: AXUIElement, _ key: String) -> CFTypeRef? {
   var value: CFTypeRef?
   return AXUIElementCopyAttributeValue(element, key as CFString, &value) == .success ? value : nil
 }
-func childCount(_ element: AXUIElement) -> Int {
+func childCount(_ element: AXUIElement) -> ChildCount {
   var count = 0
-  return AXUIElementGetAttributeValueCount(element, kAXChildrenAttribute as CFString, &count) == .success ? count : 0
+  let status = AXUIElementGetAttributeValueCount(element, kAXChildrenAttribute as CFString, &count)
+  return captureChildCount(status: status.rawValue, success: AXError.success.rawValue, value: count)
 }
-func children(_ element: AXUIElement, limit: Int) -> [AXUIElement] {
-  var value: CFArray?
-  let count = min(limit, childCount(element))
-  if count == 0 { return [] }
-  return AXUIElementCopyAttributeValues(element, kAXChildrenAttribute as CFString, 0, count, &value) == .success ? value as? [AXUIElement] ?? [] : []
+func children(_ element: AXUIElement, count: Int) -> ChildBatch<AXUIElement> {
+  captureChildValues(requestedCount: count) {
+    var value: CFArray?
+    guard AXUIElementCopyAttributeValues(element, kAXChildrenAttribute as CFString, 0, count, &value) == .success else { return nil }
+    return value as? [AXUIElement]
+  }
 }
 func text(_ element: AXUIElement, _ key: String) -> Any { (attribute(element, key) as? String) ?? NSNull() as Any }
 func windowBounds(_ element: AXUIElement) -> CGRect? {
@@ -87,7 +89,11 @@ func observe(_ request: Request) async throws -> [String: Any] {
     var element = root
     for index in action.path ?? [] {
       var selectedChild: CFArray?
-      guard index >= 0 && index < childCount(element),
+      let count = childCount(element)
+      guard let available = count.value else {
+        try fail("element-count-unavailable", "Cannot validate selected accessibility path because child count failed with AXError \(count.error ?? -1)")
+      }
+      guard index >= 0 && index < available,
         AXUIElementCopyAttributeValues(element, kAXChildrenAttribute as CFString, index, 1, &selectedChild) == .success,
         let item = (selectedChild as? [AXUIElement])?.first else { try fail("element-missing", "Selected accessibility path no longer exists") }
       element = item
@@ -103,21 +109,29 @@ func observe(_ request: Request) async throws -> [String: Any] {
     }
     guard outcome == .success else { try fail("action-failed", "Accessibility action failed with AXError \(outcome.rawValue)") }
   }
-  var nodes: [[String: Any]] = []; var truncated = false
+  var nodes: [[String: Any]] = []; var truncated = false; var gaps: [String] = []
   if request.accessibility, let root = selected {
     var pending: [(AXUIElement, [Int])] = [(root, [])]
     while let (element, path) = pending.popLast() {
       if nodes.count >= request.max_nodes { truncated = true; break }
-      let totalChildren = childCount(element)
+      let childCountResult = childCount(element)
       var actions: CFArray?
       AXUIElementCopyActionNames(element, &actions)
-      nodes.append(["path": path, "role": text(element, kAXRoleAttribute), "title": text(element, kAXTitleAttribute), "value": text(element, kAXValueAttribute), "actions": actions as? [String] ?? [], "children_count": totalChildren])
+      nodes.append(["path": path, "role": text(element, kAXRoleAttribute), "title": text(element, kAXTitleAttribute), "value": text(element, kAXValueAttribute), "actions": actions as? [String] ?? [], "children_count": childCountResult.value.map { $0 as Any } ?? NSNull()])
+      guard let totalChildren = childCountResult.value else {
+        truncated = true
+        gaps.append("AX child count unavailable at path \(path): AXError \(childCountResult.error ?? -1)")
+        continue
+      }
       if path.count >= 32 { if totalChildren > 0 { truncated = true }; continue }
       let available = max(0, request.max_nodes - nodes.count - pending.count)
       let count = min(available, totalChildren)
-      let items = children(element, limit: count)
+      let batch = children(element, count: count)
+      if !batch.complete { truncated = true }
       if totalChildren > count { truncated = true }
-      for index in (0..<count).reversed() { pending.append((items[index], path + [index])) }
+      for (index, item) in batch.values.enumerated().reversed() {
+        pending.append((item, path + [index]))
+      }
     }
   }
   var screenshot: Any = NSNull()
@@ -139,18 +153,18 @@ func observe(_ request: Request) async throws -> [String: Any] {
     }
     screenshot = ["mime_type": "image/png", "base64": png.base64EncodedString(), "sha256": SHA256.hash(data: png).map({ String(format: "%02x", $0) }).joined(), "width": image.width, "height": image.height]
   }
-  return ["window": ["pid": request.pid, "window_id": request.window_id, "executable": request.executable, "launch_time": launch, "title": window[kCGWindowName as String] as? String ?? ""], "nodes": nodes, "truncated": truncated, "screenshot": screenshot, "gaps": request.accessibility ? [] : ["Accessibility capture was disabled"]]
+  return ["window": ["pid": request.pid, "window_id": request.window_id, "executable": request.executable, "launch_time": launch, "title": window[kCGWindowName as String] as? String ?? ""], "nodes": nodes, "truncated": truncated, "screenshot": screenshot, "gaps": request.accessibility ? gaps : ["Accessibility capture was disabled"]]
 }
 Task { @MainActor in
   do {
     let request = try JSONDecoder().decode(Request.self, from: Data(CommandLine.arguments[1].utf8))
     let result = try await observe(request)
-    let output = try JSONSerialization.data(withJSONObject: ["ok": true, "result": result], options: [.sortedKeys])
+    let output = try serializeHelperOutput(["ok": true, "result": result])
     FileHandle.standardOutput.write(output)
   } catch {
     let failure = error as? BoundaryFailure
     let output: [String: Any] = ["ok": false, "code": failure?.code ?? "capture-failed", "message": failure?.message ?? error.localizedDescription]
-    if let data = try? JSONSerialization.data(withJSONObject: output, options: [.sortedKeys]) { FileHandle.standardOutput.write(data) }
+    if let data = try? serializeHelperOutput(output) { FileHandle.standardOutput.write(data) }
   }
   exit(0)
 }

package/dist/android/AndroidTargetSnapshot.js

@@ -2,7 +2,7 @@ import { constants, createReadStream } from "node:fs";
 import { chmod, copyFile } from "node:fs/promises";
 import { createHash } from "node:crypto";
 import { join } from "node:path";
-import { AnalysisInputError } from "../domain/analysisErrorCore.js";
+import { AnalysisInputError, AnalysisCapabilityUnavailableError, } from "../domain/analysisErrorCore.js";
 /** Stream a local file digest without retaining the APK or JAR in memory. */
 export const hashAndroidFile = async (path) => {
     const hash = createHash("sha256");
@@ -26,9 +26,11 @@ export const snapshotAndroidTarget = async (path, sha256, root, operation) => {
     return snapshot;
 };
 /** Fingerprint the actual immutable engine bytes executed for this observation. */
-export const snapshotAndroidEngine = async (source, root) => {
+export const snapshotAndroidEngine = async (source, sha256, root, operation) => {
     const path = join(root, "engine.jar");
     await copyFile(source, path, constants.COPYFILE_EXCL);
     await chmod(path, 0o400);
-    return { path, sha256: await hashAndroidFile(path) };
+    if ((await hashAndroidFile(path)) !== sha256)
+        throw new AnalysisCapabilityUnavailableError("jadx", operation, "REA_JADX_MCP_JAR bytes changed during admission; retry with a stable engine file.");
+    return { path, sha256 };
 };

package/dist/android/JadxAnalysis.js

@@ -1,6 +1,7 @@
-import { androidResultSchemas } from "../domain/androidAnalysis.js";
+import { androidResultSchemas } from "../domain/android/androidAnalysis.js";
 import { AnalysisCapabilityUnavailableError, AnalysisInputError, AnalysisOutputError, } from "../domain/analysisErrorCore.js";
 import { jadxAppSchema, jadxClassPageSchema, jadxClassSchema, jadxLoadSchema, jadxMethodSchema, jadxXrefsSchema, normalizeJadxText, } from "./JadxProtocol.js";
+import { JADX_RELEASE } from "./JadxRelease.js";
 const methodsOf = (summary) => {
     const seen = new Map();
     return summary.methods.map((method) => {
@@ -60,16 +61,17 @@ const inspectPackage = async (tools, loaded, engine) => {
 };
 const searchClasses = async (tools, request, loaded, engine) => {
     const classes = [];
+    const pageSize = 4096;
     let total;
     do {
         const page = jadxClassPageSchema.parse(await tools.json("list_classes", {
             offset: classes.length,
-            limit: 200,
+            limit: pageSize,
         }));
         if ((total !== undefined && total !== page.total) ||
             page.offset !== classes.length ||
-            page.limit !== 200 ||
-            page.items.length > 200)
+            page.limit !== pageSize ||
+            page.items.length > pageSize)
             throw new AnalysisOutputError(request.operation, "JADX class pagination changed identity or counts");
         total = page.total;
         classes.push(...page.items);
@@ -115,7 +117,7 @@ const inspectMethod = async (tools, request, summary, engine) => {
     if (body.body.startsWith("// ERROR:"))
         throw new AnalysisOutputError(request.operation, `JADX did not produce method source: ${body.body}`);
     if (body.mode === "smali" && candidates.length > 1)
-        throw new AnalysisCapabilityUnavailableError("jadx", request.operation, `JADX 0.7.1 smali fallback joins all same-name overloads for ${summary.full_name}.${request.input.method_name}; it cannot establish source for only overload ${index}.`);
+        throw new AnalysisCapabilityUnavailableError("jadx", request.operation, `JADX ${JADX_RELEASE.version} smali fallback joins all same-name overloads for ${summary.full_name}.${request.input.method_name}; it cannot establish source for only overload ${index}.`);
     return androidResultSchemas.inspect_android_method.parse({
         engine,
         class_name: summary.full_name,
@@ -158,7 +160,7 @@ const traceReferences = async (tools, request, summary, engine) => {
     const methodName = request.input.method_name;
     const candidates = matchingMethods(summary, request);
     if (candidates.length > 1)
-        throw new AnalysisCapabilityUnavailableError("jadx", request.operation, `JADX 0.7.1 references select the first same-name method; ${summary.full_name}.${methodName} has ${candidates.length} overloads. No unambiguous reference result is available.`);
+        throw new AnalysisCapabilityUnavailableError("jadx", request.operation, `References require a unique method name; ${summary.full_name}.${methodName} has ${candidates.length} overloads. No unambiguous reference result is available.`);
     const expectedTarget = methodName === undefined
         ? summary.full_name
         : `${summary.full_name}.${methodName}`;

package/dist/android/JadxConfiguration.js

@@ -2,16 +2,17 @@ import { access, realpath, stat } from "node:fs/promises";
 import { constants } from "node:fs";
 import { isAbsolute, join } from "node:path";
 import { AnalysisCapabilityUnavailableError } from "../domain/analysisErrorCore.js";
+import { JADX_JAR_CONFIGURATION_REMEDIATION } from "./JadxRelease.js";
 /** Admit explicit local tooling without installing or changing host configuration. */
 export const resolveJadxConfiguration = async (environment, operation) => {
     const unavailable = (reason) => new AnalysisCapabilityUnavailableError("jadx", operation, reason);
     if (process.platform !== "linux" && process.platform !== "darwin")
-        throw unavailable(`Android JADX subprocess ownership is unsupported on ${process.platform}; use Linux or macOS. Only Linux has real-provider verification.`);
+        throw unavailable(`Android JADX subprocess ownership is unsupported on ${process.platform}; use Linux or macOS. The metadata bridge has real-provider verification on macOS arm64.`);
     const jar = environment.REA_JADX_MCP_JAR;
     if (environment.JAVA_HOME !== undefined && !isAbsolute(environment.JAVA_HOME))
         throw unavailable("JAVA_HOME must select an existing JDK by absolute path; omit it to use java on PATH.");
     if (jar === undefined || !isAbsolute(jar))
-        throw unavailable("Set REA_JADX_MCP_JAR to the absolute path of a caller-supplied jadx-headless-mcp 0.7.1 JAR. REA does not download or install it.");
+        throw unavailable(JADX_JAR_CONFIGURATION_REMEDIATION);
     const java = environment.JAVA_HOME === undefined
         ? "java"
         : join(environment.JAVA_HOME, "bin", "java");
@@ -37,5 +38,20 @@ export const resolveJadxConfiguration = async (environment, operation) => {
             throw unavailable(`Cannot execute JAVA_HOME java ${java}: ${cause instanceof Error ? cause.message : String(cause)}`);
         }
     }
-    return { jar: await realpath(jar), java };
+    const jvmArguments = [];
+    for (const [name, prefix, suffix] of [
+        ["REA_JADX_HEAP_MIB", "-Xmx", "m"],
+        ["REA_JADX_ACTIVE_PROCESSOR_COUNT", "-XX:ActiveProcessorCount=", ""],
+    ]) {
+        const value = environment[name];
+        if (value === undefined)
+            continue;
+        if (!/^[1-9]\d*$/u.test(value) || !Number.isSafeInteger(Number(value)))
+            throw unavailable(`${name} must be a positive safe integer; received ${value}.`);
+        if (name === "REA_JADX_ACTIVE_PROCESSOR_COUNT" &&
+            Number(value) > 2_147_483_647)
+            throw unavailable(`${name} exceeds the JVM's signed 32-bit processor-count range.`);
+        jvmArguments.push(`${prefix}${value}${suffix}`);
+    }
+    return { jar: await realpath(jar), java, jvmArguments };
 };

package/dist/android/JadxMcpTransport.js

@@ -4,7 +4,7 @@ import { ProviderProcessSupervisor, spawnOwnedProviderProcess, } from "../proces
 import { cleanupOwnedProcessGroup } from "../process/ProcessOwnership.js";
 import { ProviderCleanupError } from "../domain/providerCleanupError.js";
 const MAX_FRAME_BYTES = 8 * 1024 * 1024;
-const MAX_SESSION_BYTES = 32 * 1024 * 1024;
+const MAX_OPERATION_BYTES = 32 * 1024 * 1024;
 /** SDK-framed stdio with REA-owned process cleanup rather than an unowned child. */
 export class JadxMcpTransport {
     options;
@@ -15,7 +15,8 @@ export class JadxMcpTransport {
     runId = randomUUID();
     #spawned;
     #supervisor;
-    #buffer = Buffer.alloc(0);
+    #frameBuffer = Buffer.alloc(0);
+    #frameLength = 0;
     #bytes = 0;
     #started = false;
     #closed = false;
@@ -44,8 +45,9 @@ export class JadxMcpTransport {
         this.#supervisor = new ProviderProcessSupervisor({
             ...spawned,
             ownsProcessLifetime: true,
-            cleanup: spawned.cleanup ?? (() => cleanupOwnedProcessGroup(spawned.ownership)),
-        });
+            cleanup: spawned.cleanup ??
+                (() => cleanupOwnedProcessGroup(spawned.ownership)),
+        }, { captureStdout: false });
         if (spawned.process.stdin === undefined ||
             spawned.process.stdin === null ||
             spawned.process.stdout === null)
@@ -80,8 +82,15 @@ export class JadxMcpTransport {
     failureReason() {
         return this.#failure;
     }
+    /** Scope both the byte budget and diagnostic retention to the next serialized request. */
+    beginOperation() {
+        this.#bytes = 0;
+        this.#supervisor?.resetOutput();
+    }
     async #stop() {
         this.#closed = true;
+        this.#frameBuffer = Buffer.alloc(0);
+        this.#frameLength = 0;
         // A cancellation may race acquisition. Join it before inspecting ownership.
         await this.#starting?.catch(() => undefined);
         const process = this.#spawned?.process;
@@ -106,35 +115,53 @@ export class JadxMcpTransport {
     };
     #countStderr = (chunk) => {
         this.#bytes += Buffer.byteLength(chunk);
-        if (this.#bytes > MAX_SESSION_BYTES)
-            this.#fail(new Error(`JADX session output exceeds ${MAX_SESSION_BYTES} bytes; no complete result is available`));
+        if (this.#bytes > MAX_OPERATION_BYTES)
+            this.#fail(new Error(`JADX operation output exceeds ${MAX_OPERATION_BYTES} bytes; no complete result is available`));
     };
     #read = (chunk) => {
         if (this.#closed)
             return;
         const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
         this.#bytes += bytes.length;
-        if (this.#bytes > MAX_SESSION_BYTES) {
-            this.#fail(new Error(`JADX session output exceeds ${MAX_SESSION_BYTES} bytes; no complete result is available`));
+        if (this.#bytes > MAX_OPERATION_BYTES) {
+            this.#fail(new Error(`JADX operation output exceeds ${MAX_OPERATION_BYTES} bytes; no complete result is available`));
             return;
         }
-        this.#buffer = Buffer.concat([this.#buffer, bytes]);
         try {
-            let newline;
-            while ((newline = this.#buffer.indexOf(10)) !== -1) {
-                if (newline > MAX_FRAME_BYTES)
+            let offset = 0;
+            while (offset < bytes.length) {
+                const newline = bytes.indexOf(10, offset);
+                const end = newline === -1 ? bytes.length : newline;
+                const fragment = bytes.subarray(offset, end);
+                const frameBytes = this.#frameLength + fragment.length;
+                if (frameBytes > MAX_FRAME_BYTES)
                     throw new Error(`JADX MCP frame exceeds ${MAX_FRAME_BYTES} bytes`);
-                const line = this.#buffer.subarray(0, newline).toString("utf8");
-                this.#buffer = this.#buffer.subarray(newline + 1);
+                this.#appendFrame(fragment, frameBytes);
+                if (newline === -1)
+                    return;
+                const line = this.#frameBuffer
+                    .subarray(0, this.#frameLength)
+                    .toString("utf8");
+                this.#frameBuffer = Buffer.alloc(0);
+                this.#frameLength = 0;
                 this.onmessage?.(deserializeMessage(line));
+                offset = newline + 1;
             }
-            if (this.#buffer.length > MAX_FRAME_BYTES)
-                throw new Error(`JADX MCP frame exceeds ${MAX_FRAME_BYTES} bytes`);
         }
         catch (cause) {
             this.#fail(cause instanceof Error ? cause : new Error(String(cause)));
         }
     };
+    #appendFrame(fragment, frameBytes) {
+        if (frameBytes > this.#frameBuffer.length) {
+            const capacity = Math.min(MAX_FRAME_BYTES, Math.max(frameBytes, this.#frameBuffer.length * 2, 1));
+            const grown = Buffer.allocUnsafe(capacity);
+            this.#frameBuffer.copy(grown, 0, 0, this.#frameLength);
+            this.#frameBuffer = grown;
+        }
+        fragment.copy(this.#frameBuffer, this.#frameLength);
+        this.#frameLength = frameBytes;
+    }
     #fail(error) {
         this.#failure ??= error.message;
         this.onerror?.(error);

package/dist/android/JadxProtocol.js

@@ -2,6 +2,14 @@ import { z } from "zod";
 import { AnalysisOutputError } from "../domain/analysisErrorCore.js";
 import { jsonValueSchema } from "../domain/jsonValue.js";
 const count = z.number().int().nonnegative();
+/** Values observed inside the exact JVM producing the analysis. */
+export const jadxRuntimeSchema = z.object({
+    engine_reported_version: z.string().min(1),
+    max_heap_bytes: z.number().int().positive().safe(),
+    available_processors: z.number().int().positive(),
+    java_version: z.string().min(1),
+    metadata_scope: z.literal("parsed_members"),
+});
 export const jadxLoadSchema = z.object({
     state: z.literal("LOADED"),
     apk_path: z.string(),