rea-agents 5.0.0 → 6.1.0

package/bridge/android/ReaJadxBridge.java

@@ -25,6 +25,11 @@ class ReaJadxBridge {
   private record MethodSnapshot(String name, String shortId, Map<String, Object> summary) {}
   private record ClassSnapshot(JavaClass node, List<MethodSnapshot> methods, Map<String, Object> summary) {}
 
+  private static final class InputFailure extends IllegalArgumentException {
+    final String field;
+    InputFailure(String field, String message) { super(message); this.field = field; }
+  }
+
   private ReaJadxBridge(SessionHolder holder) { this.holder = holder; }
 
   private static CallToolResult text(String value, boolean failed) {
@@ -100,8 +105,9 @@ class ReaJadxBridge {
     }
     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
+    if (candidates == null) throw new InputFailure("class_name", "Exact class not found: " + name
+        + "; use search_android_classes to discover fully qualified names.");
+    if (candidates.size() != 1) throw new InputFailure("class_name", "Ambiguous metadata class identity: " + name
         + "; raw identities: " + candidates.stream().map(candidate -> candidate.node().getRawName()).toList());
     return candidates.get(0);
   }
@@ -109,7 +115,8 @@ class ReaJadxBridge {
   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);
+    if (result.isEmpty()) throw new InputFailure("method_name", "Method not found: " + name
+        + "; use inspect_android_class to discover available methods.");
     return result;
   }
 
@@ -141,7 +148,7 @@ class ReaJadxBridge {
     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);
+      if (index >= overloads.size()) throw new InputFailure("overload_index", "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"),
@@ -155,7 +162,7 @@ class ReaJadxBridge {
     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");
+      if (overloads.size() != 1) throw new InputFailure("method_name", "Method references require a unique overload");
       target += "." + overloads.get(0).name();
       uses = method(cls, overloads.get(0)).getUseIn();
     }
@@ -211,6 +218,8 @@ class ReaJadxBridge {
           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 (InputFailure error) { return text(JSON.toJson(Map.of(
+            "kind", "invalid-input", "field", error.field, "message", error.getMessage())), true); }
         catch (IllegalArgumentException error) { return text(error.getMessage(), true); }
       });
     }

package/bridge/ghidra/ReaGhidraBridge.java

@@ -52,6 +52,8 @@ import ghidra.app.decompiler.ClangCaseToken;
 import ghidra.app.decompiler.ClangNode;
 import ghidra.framework.Application;
 import ghidra.program.model.address.Address;
+import ghidra.program.model.address.AddressIterator;
+import ghidra.program.model.address.AddressSet;
 import ghidra.program.model.address.AddressSpace;
 import ghidra.program.model.address.AddressRange;
 import ghidra.program.model.address.AddressRangeIterator;
@@ -723,8 +725,7 @@ public final class ReaGhidraBridge extends HeadlessScript {
         if (!direction.equals("incoming") && !direction.equals("outgoing")) {
             throw new RequestFailure("invalid_request", "direction must be incoming or outgoing");
         }
-        InstructionScan scan = scanInstructions(function, Integer.MAX_VALUE);
-        List<Reference> references = collectReferences(scan.instructions, direction);
+        List<Reference> references = collectReferences(function, direction);
         JsonArray edges = new JsonArray();
         for (Reference reference : references) {
             edges.add(referenceEdge(reference));
@@ -735,7 +736,7 @@ public final class ReaGhidraBridge extends HeadlessScript {
         result.add("references", edges);
         result.addProperty("reference_kinds_available", true);
         JsonArray unresolvedCalls = new JsonArray();
-        if (direction.equals("outgoing")) for (Instruction instruction : scan.instructions) {
+        if (direction.equals("outgoing")) for (Instruction instruction : scanInstructions(function, Integer.MAX_VALUE).instructions) {
             if (!instruction.getFlowType().isCall()) continue;
             boolean resolved = false;
             for (Reference reference : instruction.getReferencesFrom()) if (reference.getReferenceType().isCall()) resolved = true;
@@ -1007,6 +1008,11 @@ public final class ReaGhidraBridge extends HeadlessScript {
         Address entry = function.getEntryPoint();
         if (function.isExternal() || !currentProgram.getMemory().contains(entry))
             throw new RequestFailure("invalid_request", "Annotations require a local function entry: " + canonicalAddress(entry));
+        for (String field : List.of("name", "comment", "inline_comment")) {
+            if (params.has(field)) validateAnnotationText(requireText(params, field), field);
+        }
+        String leafName = params.has("name")
+            ? annotationLeafName(function, requireString(params, "name")) : null;
         int transaction = currentProgram.startTransaction("REA function annotations");
         boolean commit = false;
         try {
@@ -1020,7 +1026,7 @@ public final class ReaGhidraBridge extends HeadlessScript {
                 }
             }
             if (params.has("name"))
-                function.setName(requireString(params, "name"), SourceType.USER_DEFINED);
+                function.setName(leafName, SourceType.USER_DEFINED);
             monitor.checkCancelled();
             invalidateAnalysisCaches();
             JsonObject readback = annotationReadback(function);
@@ -1028,7 +1034,7 @@ public final class ReaGhidraBridge extends HeadlessScript {
                 if (!params.has(field)) continue;
                 String requested = requireText(params, field);
                 JsonElement measured = readback.get(field);
-                String expected = !field.equals("name") && requested.isEmpty() ? null : requested;
+                String expected = field.equals("name") ? leafName : requested.isEmpty() ? null : requested;
                 String observed = field.equals("name") ? function.getName() :
                     (measured.isJsonNull() ? null : measured.getAsString());
                 if (!java.util.Objects.equals(expected, observed))
@@ -1058,6 +1064,22 @@ public final class ReaGhidraBridge extends HeadlessScript {
         }
     }
 
+    private String annotationLeafName(Function function, String requested) {
+        // Fully qualified readback must be usable as an idempotent rename input.
+        if (requested.equals(procedureName(function))) return function.getName();
+        String namespace = function.getParentNamespace().isGlobal()
+            ? "" : function.getParentNamespace().getName(true);
+        String prefix = namespace + "::";
+        if (!namespace.isEmpty() && requested.startsWith(prefix)) {
+            String leaf = requested.substring(prefix.length());
+            if (!leaf.isEmpty()) return leaf;
+            throw new RequestFailure("invalid_function_name",
+                "Function name has an empty leaf within namespace " + namespace + " at " +
+                canonicalAddress(function.getEntryPoint()) + ": " + requested);
+        }
+        return requested;
+    }
+
     private static String requireText(JsonObject params, String field) {
         JsonElement value = params.get(field);
         if (value == null || !value.isJsonPrimitive() || !value.getAsJsonPrimitive().isString())
@@ -1065,6 +1087,21 @@ public final class ReaGhidraBridge extends HeadlessScript {
         return value.getAsString();
     }
 
+    private static void validateAnnotationText(String text, String field) {
+        for (int index = 0; index < text.length(); index++) {
+            char character = text.charAt(index);
+            if (character == 0)
+                throw new RequestFailure("invalid_request", "Annotation " + field + " contains NUL at UTF-16 index " + index + "; Ghidra's decompiler cannot marshal NUL text");
+            if (Character.isHighSurrogate(character) && index + 1 < text.length() &&
+                Character.isLowSurrogate(text.charAt(index + 1))) {
+                index++;
+                continue;
+            }
+            if (Character.isSurrogate(character))
+                throw new RequestFailure("invalid_request", "Annotation " + field + " contains an unpaired Unicode surrogate at UTF-16 index " + index + "; Ghidra cannot preserve it as annotation text");
+        }
+    }
+
     private JsonObject analyzeFunction(JsonObject params) throws Exception {
         requireKeys(params, Set.of("procedure"));
         Function function = resolveProcedure(requireString(params, "procedure"));
@@ -1074,11 +1111,11 @@ public final class ReaGhidraBridge extends HeadlessScript {
         if (pseudocode == null) {
             pseudocode = "";
         }
-        List<Reference> incomingReferences = collectReferences(scan.instructions, "incoming")
+        List<Reference> incomingReferences = collectReferences(function, "incoming")
             .stream()
             .filter(reference -> !function.getBody().contains(reference.getFromAddress()))
             .toList();
-        List<Reference> outgoingReferences = collectReferences(scan.instructions, "outgoing");
+        List<Reference> outgoingReferences = collectReferences(function, "outgoing");
         JsonArray incoming = referenceEdges(incomingReferences);
         JsonArray outgoing = referenceEdges(outgoingReferences);
         JsonArray comments = comments(scan.instructions);
@@ -1471,6 +1508,7 @@ public final class ReaGhidraBridge extends HeadlessScript {
             : regexMatcher(expression, caseSensitive);
         JsonArray items = new JsonArray();
         for (InventoryItem item : inventory) {
+            monitor.checkCancelled();
             if (!matcher.matches(item.value)) {
                 continue;
             }
@@ -1581,33 +1619,36 @@ public final class ReaGhidraBridge extends HeadlessScript {
     }
 
     private Function resolveProcedure(String value) throws Exception {
-        Address address = tryParseAddress(value);
-        if (address != null) {
-            Function function = currentProgram.getFunctionManager().getFunctionAt(address);
-            if (function == null && address.isMemoryAddress()) {
-                function = currentProgram.getFunctionManager().getFunctionContaining(address);
-            }
-            if (function == null) {
-                throw new RequestFailure("not_found", "No procedure exists at the requested address");
-            }
-            return function;
-        }
-        List<Function> matches = new ArrayList<>();
-        for (FunctionEntry entry : procedures()) {
-            Function function = entry.function;
-            Symbol symbol = function.getSymbol();
-            String qualified = symbol == null ? function.getName() : symbol.getName(true);
-            if (function.getName().equals(value) || qualified.equals(value)) {
-                matches.add(function);
+        // Explicit address syntax wins; an unprefixed identifier is first an
+        // exact symbol name, even when every character is a hexadecimal digit.
+        boolean explicitAddress = isExplicitReaAddress(value);
+        if (!explicitAddress) {
+            List<Function> matches = new ArrayList<>();
+            for (FunctionEntry entry : procedures()) {
+                monitor.checkCancelled();
+                Function function = entry.function;
+                Symbol symbol = function.getSymbol();
+                String qualified = symbol == null ? function.getName() : symbol.getName(true);
+                if (function.getName().equals(value) || qualified.equals(value)) {
+                    matches.add(function);
+                }
             }
+            if (matches.size() > 1)
+                throw new RequestFailure("ambiguous", "Ghidra procedure name is ambiguous: " + value +
+                    "; select an exact entry address from " + matches.stream()
+                        .map(function -> canonicalAddress(function.getEntryPoint())).toList());
+            if (matches.size() == 1) return matches.get(0);
         }
-        if (matches.isEmpty()) {
-            throw new RequestFailure("not_found", "Unknown Ghidra procedure name");
-        }
-        if (matches.size() != 1) {
-            throw new RequestFailure("ambiguous", "Ghidra procedure name is ambiguous");
-        }
-        return matches.get(0);
+        // Retain legacy bare-hex address input only when no symbol matches.
+        Address address = explicitAddress ? parseReaAddress(value) : tryParseAddress(value);
+        if (address == null)
+            throw new RequestFailure("not_found", "Unknown Ghidra procedure name or address: " + value);
+        Function function = currentProgram.getFunctionManager().getFunctionAt(address);
+        if (function == null && address.isMemoryAddress())
+            function = currentProgram.getFunctionManager().getFunctionContaining(address);
+        if (function == null)
+            throw new RequestFailure("not_found", "No procedure exists at the requested address: " + value);
+        return function;
     }
 
     private JsonObject nativeApiBoundary(
@@ -2530,21 +2571,32 @@ public final class ReaGhidraBridge extends HeadlessScript {
     }
 
     private List<Reference> collectReferences(
-            List<Instruction> instructions,
+            Function function,
             String direction) throws Exception {
+        // References can target instruction interiors or originate in embedded
+        // data. Use actual body ownership, including an external's exact entry.
+        AddressSet scope = new AddressSet(function.getBody());
+        scope.add(function.getEntryPoint());
+        boolean outgoing = direction.equals("outgoing");
+        AddressIterator addresses = outgoing
+            ? currentProgram.getReferenceManager().getReferenceSourceIterator(scope, true)
+            : currentProgram.getReferenceManager().getReferenceDestinationIterator(scope, true);
         TreeMap<String, Reference> observed = new TreeMap<>();
-        for (Instruction instruction : instructions) {
+        while (addresses.hasNext()) {
             monitor.checkCancelled();
-            if (direction.equals("outgoing")) {
+            Address address = addresses.next();
+            if (outgoing) {
                 for (Reference reference : currentProgram.getReferenceManager()
-                        .getReferencesFrom(instruction.getAddress())) {
+                        .getReferencesFrom(address)) {
+                    monitor.checkCancelled();
                     addReference(observed, reference);
                 }
             }
             else {
                 ReferenceIterator iterator = currentProgram.getReferenceManager()
-                    .getReferencesTo(instruction.getAddress());
+                    .getReferencesTo(address);
                 while (iterator.hasNext()) {
+                    monitor.checkCancelled();
                     addReference(observed, iterator.next());
                 }
             }
@@ -2944,10 +2996,46 @@ public final class ReaGhidraBridge extends HeadlessScript {
         return parseReaAddress(requireString(params, name));
     }
 
+    private static boolean isExplicitReaAddress(String value) {
+        if (value.regionMatches(true, 0, "0x", 0, 2) &&
+            isHexadecimal(value, 2, value.length()))
+            return true;
+        int separator = value.toLowerCase(Locale.ROOT).lastIndexOf(":0x");
+        if (separator <= 0 || !isHexadecimal(value, separator + 3, value.length()))
+            return false;
+        // Classify the encoded space iteratively. A repeated regex alternation
+        // can exhaust Java's stack on a long ordinary symbol name.
+        for (int index = 0; index < separator; index++) {
+            char item = value.charAt(index);
+            if ((item >= 'A' && item <= 'Z') ||
+                (item >= 'a' && item <= 'z') ||
+                (item >= '0' && item <= '9') ||
+                item == '.' || item == '_' || item == '~' || item == '-')
+                continue;
+            if (item != '%' || index + 2 >= separator ||
+                !isHexadecimal(value, index + 1, index + 3))
+                return false;
+            index += 2;
+        }
+        return true;
+    }
+
+    private static boolean isHexadecimal(String value, int start, int end) {
+        if (start >= end) return false;
+        for (int index = start; index < end; index++) {
+            char item = value.charAt(index);
+            if (!((item >= '0' && item <= '9') ||
+                  (item >= 'a' && item <= 'f') ||
+                  (item >= 'A' && item <= 'F')))
+                return false;
+        }
+        return true;
+    }
+
     private Address parseReaAddress(String value) {
         Address address = tryParseAddress(value);
         if (address == null) {
-            throw new RequestFailure("invalid_request", "Unknown or invalid Ghidra address");
+            throw new RequestFailure("invalid_request", "Unknown or invalid Ghidra address: " + value);
         }
         return address;
     }
@@ -2956,22 +3044,31 @@ public final class ReaGhidraBridge extends HeadlessScript {
         try {
             String spaceName = null;
             String offset = value;
-            int separator = value.lastIndexOf(":0x");
+            int separator = value.toLowerCase(Locale.ROOT).lastIndexOf(":0x");
             if (separator >= 0) {
                 spaceName = decodeAddressSpace(value.substring(0, separator));
                 offset = value.substring(separator + 3);
             }
-            else if (value.startsWith("0x")) {
+            else if (value.startsWith("0x") || value.startsWith("0X")) {
                 offset = value.substring(2);
             }
-            if (!offset.matches("[0-9A-Fa-f]+")) {
+            if (!isHexadecimal(offset, 0, offset.length())) {
                 return null;
             }
             AddressSpace space = spaceName == null
                 ? currentProgram.getAddressFactory().getDefaultAddressSpace()
                 : currentProgram.getAddressFactory().getAddressSpace(spaceName);
-            return space == null ? null : space.getAddress(offset);
-        }
+            if (space == null) return null;
+            Address address = space.getAddress(offset);
+            BigInteger requestedOffset = new BigInteger(offset, 16);
+            BigInteger parsedOffset = new BigInteger(Long.toUnsignedString(address.getOffset()));
+            if (!requestedOffset.equals(parsedOffset))
+                throw new RequestFailure("invalid_request",
+                    "Ghidra address offset cannot be represented without truncation in space " +
+                    space.getName() + ": requested " + value + ", parsed " + canonicalAddress(address));
+            return address;
+        }
+        catch (RequestFailure failure) { throw failure; }
         catch (Exception exception) {
             return null;
         }
@@ -3055,9 +3152,29 @@ public final class ReaGhidraBridge extends HeadlessScript {
             );
         }
         catch (PatternSyntaxException exception) {
-            throw new RequestFailure("invalid_request", "Invalid regex pattern");
+            // Java wraps compiler stack exhaustion in PatternSyntaxException
+            // without retaining its cause. This producer reason is not bad syntax.
+            if (exception.getDescription().equals("Stack overflow during pattern compilation"))
+                throw regexStackExhausted(expression, "compiling");
+            throw new RequestFailure("invalid_request", "Invalid regex pattern " + expression + ": " + exception.getDescription() + " at index " + exception.getIndex());
+        }
+        catch (StackOverflowError exhausted) {
+            throw regexStackExhausted(expression, "compiling");
         }
-        return value -> pattern.matcher(value).find();
+        return value -> {
+            try {
+                return pattern.matcher(value).find();
+            }
+            catch (StackOverflowError exhausted) {
+                throw regexStackExhausted(expression, "matching");
+            }
+        };
+    }
+
+    private static RequestFailure regexStackExhausted(String expression, String stage) {
+        return new RequestFailure("regex_stack_exhausted",
+            "Ghidra's Java regex engine exhausted its stack while " + stage +
+            " pattern " + expression + ". Use literal mode or simplify the regex; the session remains usable.");
     }
 
     private static SessionDescriptor readDescriptor(Path path) throws IOException {
@@ -3114,7 +3231,7 @@ public final class ReaGhidraBridge extends HeadlessScript {
     private void requireDocument(JsonObject params) {
         String document = optionalString(params, "document");
         if (document != null && !document.equals(currentProgram.getName())) {
-            throw new RequestFailure("not_found", "Unknown Ghidra Program identity");
+            throw new RequestFailure("not_found", "Unknown Ghidra Program identity: " + document + "; active program: " + currentProgram.getName());
         }
     }
 
@@ -3226,7 +3343,16 @@ public final class ReaGhidraBridge extends HeadlessScript {
 
     private static void writeResponse(BufferedWriter writer, JsonObject response) throws IOException {
         String encoded = GSON.toJson(response);
-        writer.write(encoded);
+        // Gson leaves UTF-16 surrogates literal. Escape them in JSON so even
+        // diagnostics quoting ill-formed caller text remain lossless UTF-8.
+        int start = 0;
+        for (int index = 0; index < encoded.length(); index++) {
+            if (!Character.isSurrogate(encoded.charAt(index))) continue;
+            writer.write(encoded, start, index - start);
+            writer.write("\\u" + Integer.toHexString(encoded.charAt(index)));
+            start = index + 1;
+        }
+        writer.write(encoded, start, encoded.length() - start);
         writer.newLine();
         writer.flush();
     }