rea-agents 6.3.0 → 6.5.0

package/dist/adb/AdbShellOutput.js

@@ -0,0 +1,307 @@
+/**
+ * Parsers for fixed observation commands REA runs through `adb shell`.
+ *
+ * Formats follow toybox output on Android 8+ (verified against an Android 14
+ * emulator). Unparseable lines are retained rather than dropped so callers
+ * can see the format drift instead of silently losing rows.
+ */
+const PROCESS_LINE = /^(\S+)\s+(\d+)\s+(\d+)\s+(\d+)\s+(\d+)\s+(\S+)\s+(\S+)\s+(\S+)\s+(.+)$/u;
+/** Parse `ps -A` output; the header line is preserved verbatim as `columns`. */
+export const parseProcessListOutput = (stdout) => {
+    const processes = [];
+    const unparsedLines = [];
+    let columns = null;
+    for (const rawLine of stdout.split(/\r?\n/u)) {
+        const line = rawLine.trimEnd();
+        if (line === "")
+            continue;
+        if (/^USER\s+PID\s+PPID\b/u.test(line)) {
+            columns = line.trim();
+            continue;
+        }
+        const match = PROCESS_LINE.exec(line);
+        if (match === null) {
+            unparsedLines.push(line);
+            continue;
+        }
+        processes.push({
+            user: match[1],
+            pid: Number(match[2]),
+            ppid: Number.isSafeInteger(Number(match[3])) ? Number(match[3]) : null,
+            rss: Number.isSafeInteger(Number(match[5])) ? Number(match[5]) : null,
+            state: match[8],
+            name: match[9].trim(),
+        });
+    }
+    return { columns, processes, unparsedLines };
+};
+const FEATURE_LINE = /^feature:([^=\s]+)(?:=(0x[0-9a-fA-F]+|\d+))?$/u;
+const parseFeatureVersion = (text) => text.startsWith("0x") ? Number.parseInt(text.slice(2), 16) : Number(text);
+/** Parse `pm list features` output, including hex GL versions. */
+export const parseFeatureListOutput = (stdout) => {
+    const features = [];
+    const unparsedLines = [];
+    for (const rawLine of stdout.split(/\r?\n/u)) {
+        const line = rawLine.trim();
+        if (line === "")
+            continue;
+        const match = FEATURE_LINE.exec(line);
+        if (match === null) {
+            unparsedLines.push(line);
+            continue;
+        }
+        features.push({
+            name: match[1],
+            version: match[2] === undefined ? null : parseFeatureVersion(match[2]),
+        });
+    }
+    return { features, unparsedLines };
+};
+const SERVICE_LINE = /^\s*(?:\d+\s+)?([A-Za-z0-9._$/-]+):\s*\[([^\]]*)\]\s*$/u;
+/** Parse `service list` output, tolerating numbered and plain formats. */
+export const parseServiceListOutput = (stdout) => {
+    const services = [];
+    const unparsedLines = [];
+    for (const rawLine of stdout.split(/\r?\n/u)) {
+        const line = rawLine.trimEnd();
+        if (line.trim() === "" || /^Found \d+ services:/u.test(line.trim()))
+            continue;
+        const match = SERVICE_LINE.exec(line);
+        if (match === null) {
+            if (line.trim() !== "")
+                unparsedLines.push(line.trim());
+            continue;
+        }
+        services.push({
+            name: match[1],
+            interface: match[2] === "" ? null : match[2],
+        });
+    }
+    return { services, unparsedLines };
+};
+const SIZE_PAIR = /^Physical size:\s+(\d+)x(\d+)$/u;
+const SIZE_OVERRIDE = /^Override size:\s+(\d+)x(\d+)$/u;
+const DENSITY_PHYSICAL = /^Physical density:\s+(\d+)$/u;
+const DENSITY_OVERRIDE = /^Override density:\s+(\d+)$/u;
+/** Parse `wm size` output into physical and optional override sizes. */
+export const parseWmSizeOutput = (stdout) => {
+    let physical = null;
+    let override = null;
+    for (const line of stdout.split(/\r?\n/u)) {
+        const trimmed = line.trim();
+        const physicalMatch = SIZE_PAIR.exec(trimmed);
+        if (physicalMatch !== null)
+            physical = {
+                width: Number(physicalMatch[1]),
+                height: Number(physicalMatch[2]),
+            };
+        const overrideMatch = SIZE_OVERRIDE.exec(trimmed);
+        if (overrideMatch !== null)
+            override = {
+                width: Number(overrideMatch[1]),
+                height: Number(overrideMatch[2]),
+            };
+    }
+    return { physical, override };
+};
+/** Parse `wm density` output. Older builds print a bare number. */
+export const parseWmDensityOutput = (stdout) => {
+    let physical = null;
+    let override = null;
+    for (const line of stdout.split(/\r?\n/u)) {
+        const trimmed = line.trim();
+        const physicalMatch = DENSITY_PHYSICAL.exec(trimmed);
+        if (physicalMatch !== null)
+            physical = Number(physicalMatch[1]);
+        const overrideMatch = DENSITY_OVERRIDE.exec(trimmed);
+        if (overrideMatch !== null)
+            override = Number(overrideMatch[1]);
+    }
+    return { physical, override };
+};
+/** Parse focus declarations from `dumpsys window windows` or `displays`. */
+export const parseWindowFocusOutput = (stdout) => {
+    let focusedWindow = null;
+    let focusedApp = null;
+    for (const line of stdout.split(/\r?\n/u)) {
+        const trimmed = line.trim();
+        if (focusedWindow === null && trimmed.startsWith("mCurrentFocus="))
+            focusedWindow = trimmed.slice("mCurrentFocus=".length).trim();
+        if (focusedApp === null && trimmed.startsWith("mFocusedApp="))
+            focusedApp = trimmed.slice("mFocusedApp=".length).trim();
+    }
+    return { focusedWindow, focusedApp };
+};
+const DETAIL_LINE = /^\s+([A-Za-z][A-Za-z0-9_]*)=(.*)$/u;
+/**
+ * Project `dumpsys package PACKAGE` output. Only the listed fields are
+ * extracted; the input is version-dependent and everything else is ignored
+ * by design rather than guessed.
+ */
+export const parseDumpsysPackageOutput = (stdout) => {
+    const details = {
+        versionName: null,
+        versionCode: null,
+        firstInstallTime: null,
+        lastUpdateTime: null,
+        installerPackageName: null,
+        userId: null,
+        pkgFlags: null,
+    };
+    let inPermissions = false;
+    let permissions = 0;
+    for (const line of stdout.split(/\r?\n/u)) {
+        if (line.trim().startsWith("requested permissions:")) {
+            inPermissions = true;
+            continue;
+        }
+        // Android 10 and 11 mark restricted entries as "NAME: restricted=true".
+        if (inPermissions &&
+            /^\s{2,}[A-Za-z0-9._]+(?:: restricted=true)?$/u.test(line)) {
+            permissions += 1;
+            continue;
+        }
+        inPermissions = false;
+        const match = DETAIL_LINE.exec(line);
+        if (match === null)
+            continue;
+        const key = match[1];
+        const value = match[2].trim();
+        if (key === "versionName" && details.versionName === null)
+            details.versionName = value === "" ? null : value;
+        else if (key === "versionCode" && details.versionCode === null) {
+            const parsed = /^(\d+)/u.exec(value);
+            if (parsed !== null)
+                details.versionCode = Number(parsed[1]);
+        }
+        else if (key === "firstInstallTime" && details.firstInstallTime === null)
+            details.firstInstallTime = value === "" ? null : value;
+        else if (key === "lastUpdateTime" && details.lastUpdateTime === null)
+            details.lastUpdateTime = value === "" ? null : value;
+        else if (key === "installerPackageName" &&
+            details.installerPackageName === null)
+            details.installerPackageName = value === "" ? null : value;
+        else if (key === "userId" && details.userId === null) {
+            const parsed = /^(\d+)/u.exec(value);
+            if (parsed !== null)
+                details.userId = Number(parsed[1]);
+        }
+        else if (key === "pkgFlags" && details.pkgFlags === null)
+            details.pkgFlags = value === "" ? null : value;
+    }
+    return { ...details, requestedPermissions: permissions };
+};
+/**
+ * Parse `settings get` output. Android prints the literal string `null` for
+ * absent keys; that is reported as a device-side null observation.
+ */
+export const parseSettingsGetOutput = (stdout) => {
+    const trimmed = stdout.replace(/\r?\n$/u, "");
+    if (trimmed === "null")
+        return { value: null, deviceReportedNull: true };
+    return { value: trimmed, deviceReportedNull: false };
+};
+/** Parse the host-side completion line from `adb bugreport`. */
+export const parseBugreportCopiedPath = (stdout) => {
+    const match = /^Bug report copied to (.+)\r?$/mu.exec(stdout.trim());
+    return match === null ? null : match[1];
+};
+/** Read the device's `Failure [REASON]` verdict from package-change output. */
+export const packageChangeFailureReason = (output) => /Failure \[([^\]]+)\]/u.exec(output)?.[1] ?? null;
+/**
+ * Parse `adb install`/`adb uninstall` output. adb can print `Failure [...]`
+ * with a zero exit code, so the text decides, not the exit status.
+ */
+export const parsePackageChangeOutput = (stdout) => {
+    const text = stdout.trim();
+    if (/^Success$/mu.test(text))
+        return { status: "success", reason: null };
+    return {
+        status: "failure",
+        reason: packageChangeFailureReason(text) ??
+            (text === "" ? null : text.slice(0, 512)),
+    };
+};
+/**
+ * Parse `cmd package resolve-activity --brief` output: the component is the
+ * last non-empty line.
+ */
+export const parseResolveActivityOutput = (stdout) => {
+    const lines = stdout
+        .split(/\r?\n/u)
+        .map((line) => line.trim())
+        .filter((line) => line !== "" && !/^No activity found$/iu.test(line));
+    return lines.length === 0 ? null : lines[lines.length - 1];
+};
+/**
+ * Parse the complete `am start -W` report. `Starting:` records an attempt;
+ * hard errors and any non-ok Activity Manager status determine the verdict.
+ */
+export const parseAmStartOutput = (stdout, stderr = "") => {
+    const normalizedStdout = stdout.replaceAll("\r\n", "\n");
+    const starting = /^Starting:[ \t]+Intent[ \t]*\{(.*)\}[ \t]*$/mu.exec(normalizedStdout);
+    const startedActivity = starting?.[1]?.trim() ?? null;
+    const activityMatch = /^Activity:[ \t]*(.*)$/mu.exec(normalizedStdout);
+    const activity = activityMatch?.[1]?.trim() || null;
+    const statuses = [...normalizedStdout.matchAll(/^Status:[ \t]*(.*)$/gmu)].map((match) => match[1].trim());
+    const nonOkStatus = statuses.find((status) => status.toLowerCase() !== "ok");
+    const reportedStatus = nonOkStatus ?? statuses[0] ?? null;
+    const error = [normalizedStdout, stderr.replaceAll("\r\n", "\n")]
+        .flatMap((stream) => stream.split("\n"))
+        .map((line) => line.trim())
+        .map((line) => ({
+        line,
+        match: /^(?:Error|Exception)(?::|\b)(.*)$/iu.exec(line),
+    }))
+        .find(({ match }) => match !== null);
+    const errorReason = error?.match?.[1]?.trim() || error?.line || null;
+    const statusReason = nonOkStatus === ""
+        ? "am start reported an empty status"
+        : nonOkStatus === undefined
+            ? null
+            : `am start reported status: ${nonOkStatus}`;
+    const reason = errorReason ??
+        statusReason ??
+        (/^Warning:/mu.test(normalizedStdout.trim())
+            ? normalizedStdout.trim().slice(0, 512)
+            : null);
+    if (errorReason !== null || nonOkStatus !== undefined)
+        return {
+            status: "refused",
+            startedActivity,
+            activity,
+            reportedStatus,
+            reason: reason ?? "am start did not report a successful launch",
+        };
+    if (startedActivity !== null)
+        return {
+            status: "started",
+            startedActivity,
+            activity,
+            reportedStatus,
+            reason: null,
+        };
+    const text = `${normalizedStdout}\n${stderr.replaceAll("\r\n", "\n")}`.trim();
+    return {
+        status: "refused",
+        startedActivity,
+        activity,
+        reportedStatus,
+        reason: reason ??
+            (text === "" ? "am start returned no activity" : text.slice(0, 512)),
+    };
+};
+const PNG_SIGNATURE = Buffer.from([
+    0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a,
+]);
+/** Read image dimensions from a PNG header, or null for other payloads. */
+export const parsePngDimensions = (bytes) => {
+    if (bytes.length < 24 ||
+        !Buffer.from(bytes.subarray(0, 8)).equals(PNG_SIGNATURE))
+        return { width: null, height: null };
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    return {
+        width: view.getUint32(16),
+        height: view.getUint32(20),
+    };
+};

package/dist/android/AndroidTargetSnapshot.js

@@ -1,36 +1,118 @@
-import { constants, createReadStream } from "node:fs";
-import { chmod, copyFile } from "node:fs/promises";
 import { createHash } from "node:crypto";
+import { chmod, open, rm, stat } from "node:fs/promises";
 import { join } from "node:path";
+import { Transform } from "node:stream";
+import { pipeline } from "node:stream/promises";
 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");
-    for await (const chunk of createReadStream(path))
-        hash.update(chunk);
-    return hash.digest("hex");
-};
+import { openRegularFile, sameRegularFileState, } from "../filesystem/RegularFile.js";
 /** Bind decompiler input to the admitted artifact, even if the original changes. */
-export const snapshotAndroidTarget = async (path, sha256, root, operation) => {
+export const snapshotAndroidTarget = async (path, sha256, root, operation, signal) => {
     const snapshot = join(root, "target.apk");
-    await copyFile(path, snapshot, constants.COPYFILE_EXCL);
-    await chmod(snapshot, 0o400);
-    if ((await hashAndroidFile(snapshot)) !== sha256)
-        throw new AnalysisInputError(operation, undefined, [
+    try {
+        await copyAndroidSnapshot(path, snapshot, sha256, signal);
+        signal?.throwIfAborted();
+        await chmod(snapshot, 0o400);
+        return snapshot;
+    }
+    catch (cause) {
+        if (!(cause instanceof AndroidSnapshotChangedError))
+            throw cause;
+        throw new AnalysisInputError(operation, { cause }, [
             {
                 path: ["path"],
                 reason: "invalid_value",
-                message: "APK bytes changed after admission; retry against a stable file.",
+                message: `APK bytes changed after admission at ${path}; retry against a stable file.`,
             },
         ]);
-    return snapshot;
+    }
 };
 /** Fingerprint the actual immutable engine bytes executed for this observation. */
-export const snapshotAndroidEngine = async (source, sha256, root, operation) => {
+export const snapshotAndroidEngine = async (source, sha256, root, operation, signal) => {
     const path = join(root, "engine.jar");
-    await copyFile(source, path, constants.COPYFILE_EXCL);
-    await chmod(path, 0o400);
-    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 };
+    try {
+        const observed = await copyAndroidSnapshot(source, path, sha256, signal);
+        signal?.throwIfAborted();
+        await chmod(path, 0o400);
+        return { path, sha256: observed };
+    }
+    catch (cause) {
+        if (!(cause instanceof AndroidSnapshotChangedError))
+            throw cause;
+        throw new AnalysisCapabilityUnavailableError("jadx", operation, `REA_JADX_MCP_JAR bytes changed during admission at ${source}; retry with a stable engine file.`, { cause });
+    }
+};
+const copyAndroidSnapshot = async (sourcePath, snapshotPath, expectedSha256, signal) => {
+    signal?.throwIfAborted();
+    const source = await openRegularFile(sourcePath, {
+        symlinks: "follow",
+        signal,
+    });
+    let destination;
+    let inputStream;
+    let outputStream;
+    let removeSnapshot = false;
+    let copiedBytes = 0;
+    const hash = createHash("sha256");
+    try {
+        const initial = await source.stat();
+        signal?.throwIfAborted();
+        const digest = new Transform({
+            transform(chunk, _encoding, callback) {
+                copiedBytes += chunk.length;
+                if (copiedBytes > initial.size) {
+                    callback(new AndroidSnapshotChangedError(`Android input grew while being copied: ${sourcePath}`));
+                    return;
+                }
+                hash.update(chunk);
+                callback(null, chunk);
+            },
+        });
+        try {
+            destination = await open(snapshotPath, "wx", 0o600);
+            signal?.throwIfAborted();
+            inputStream = source.createReadStream({
+                start: 0,
+                end: initial.size,
+                autoClose: false,
+            });
+            outputStream = destination.createWriteStream({ autoClose: false });
+            await pipeline(inputStream, digest, outputStream, { signal });
+            signal?.throwIfAborted();
+            await verifySourceState(source, sourcePath, initial, copiedBytes);
+            const observedSha256 = hash.digest("hex");
+            if (observedSha256 !== expectedSha256)
+                throw new AndroidSnapshotChangedError(`Android snapshot digest mismatch for ${sourcePath}`);
+            return observedSha256;
+        }
+        catch (cause) {
+            removeSnapshot = destination !== undefined;
+            throw cause;
+        }
+    }
+    finally {
+        // Non-auto-closing streams retain a reference to their FileHandle even
+        // after pipeline completion. Release those references before awaiting
+        // descriptor closure, after the admitted source state has been verified.
+        inputStream?.destroy();
+        outputStream?.destroy();
+        try {
+            await Promise.all([source.close(), destination?.close()]);
+        }
+        finally {
+            if (removeSnapshot)
+                await rm(snapshotPath, { force: true }).catch(() => undefined);
+        }
+    }
+};
+const verifySourceState = async (handle, path, initial, observedBytes) => {
+    const [opened, currentPath] = await Promise.all([handle.stat(), stat(path)]);
+    if (observedBytes !== initial.size ||
+        !sameRegularFileState(initial, opened) ||
+        !sameRegularFileState(initial, currentPath))
+        throw new AndroidSnapshotChangedError(`Android input changed while being read: ${path}`);
 };
+class AndroidSnapshotChangedError extends Error {
+    constructor(message, options) {
+        super(message, options);
+    }
+}

package/dist/android/JadxAnalysis.js

@@ -12,7 +12,7 @@ const methodsOf = (summary) => {
             reported_signature: method.signature,
             overload_index: index,
             is_constructor: method.is_constructor,
-            dex_descriptor: null,
+            dex_descriptor: method.dex_descriptor,
         };
     });
 };
@@ -79,13 +79,21 @@ const searchClasses = async (tools, request, loaded, engine) => {
             (page.items.length === 0 && classes.length < total))
             throw new AnalysisOutputError(request.operation, "JADX class pagination is incomplete");
     } while (classes.length < total);
-    if (new Set(classes).size !== classes.length || total !== loaded.class_count)
-        throw new AnalysisOutputError(request.operation, "JADX class inventory is duplicated or differs from the loaded class count");
+    if (total !== loaded.class_count)
+        throw new AnalysisOutputError(request.operation, "JADX class inventory count differs from the loaded class count");
+    const occurrences = new Map();
+    for (const name of classes)
+        occurrences.set(name, (occurrences.get(name) ?? 0) + 1);
+    const matchingNames = classes.filter((name) => name.includes(request.input.query));
+    const duplicateNames = [...occurrences]
+        .filter(([name, count]) => count > 1 && name.includes(request.input.query))
+        .map(([name, count]) => ({ name, occurrences: count }));
     return androidResultSchemas.search_android_classes.parse({
         engine,
         query: request.input.query,
         total_classes: total,
-        matches: classes.filter((name) => name.includes(request.input.query)),
+        matches: matchingNames,
+        duplicate_names: duplicateNames,
         coverage: "complete",
     });
 };
@@ -159,18 +167,29 @@ export const analyzeJadxRequest = async (tools, request, loaded, engine) => {
 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, `References require a unique method name; ${summary.full_name}.${methodName} has ${candidates.length} overloads. No unambiguous reference result is available.`);
+    if (methodName === undefined && request.input.overload_index !== undefined)
+        inputFailure(request, "overload_index", "Method name is required for an overload index.");
+    if (candidates.length > 1 && request.input.overload_index === undefined)
+        inputFailure(request, "overload_index", `Select one of ${candidates.length} overloads: ${candidates.map((method) => `${method.overload_index}: ${method.reported_signature}`).join("; ")}`);
+    const index = request.input.overload_index ?? 0;
+    const selected = methodName === undefined ? undefined : candidates[index];
+    if (methodName !== undefined && selected === undefined)
+        inputFailure(request, "overload_index", `Index ${index} is outside the ${candidates.length} matching overloads.`);
     const expectedTarget = methodName === undefined
         ? summary.full_name
         : `${summary.full_name}.${methodName}`;
     const xrefs = jadxXrefsSchema.parse(await tools.json(methodName === undefined ? "get_xrefs_to_class" : "get_xrefs_to_method", {
         class_name: summary.full_name,
-        ...(methodName === undefined ? {} : { method_name: methodName }),
+        ...(methodName === undefined
+            ? {}
+            : { method_name: methodName, overload_index: index }),
         limit: 2_147_483_647,
         resolve_line: false,
     }));
     if (xrefs.target !== expectedTarget ||
+        (selected !== undefined &&
+            (xrefs.overload_index !== index ||
+                xrefs.reported_signature !== selected.reported_signature)) ||
         xrefs.total !== xrefs.count ||
         xrefs.count !== xrefs.items.length)
         throw new AnalysisOutputError(request.operation, "JADX references are incomplete or refer to another target");
@@ -178,6 +197,9 @@ const traceReferences = async (tools, request, summary, engine) => {
         engine,
         class_name: summary.full_name,
         method_name: methodName ?? null,
+        overload_index: selected?.overload_index ?? null,
+        reported_signature: selected?.reported_signature ?? null,
+        dex_descriptor: selected?.dex_descriptor ?? null,
         total: xrefs.total,
         references: xrefs.items.map((reference) => ({
             kind: reference.kind,
@@ -187,7 +209,10 @@ const traceReferences = async (tools, request, summary, engine) => {
             top_class: reference.top_class,
             source_line: null,
             dex_offset: null,
+            direct_invokes: reference.direct_invokes ?? null,
+            direct_invokes_exhaustive: reference.direct_invokes_exhaustive ?? null,
         })),
         coverage: "complete",
+        reference_unit: "using_node",
     });
 };