rea-agents 6.2.0 → 6.4.0

package/dist/adb/AdbShellOutput.js

@@ -0,0 +1,309 @@
+/**
+ * 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 LS_LINE = /^([bcdlps-][rwxstST-]{9})\s+(?:(\d+)\s+)?(\S+)\s+(\S+)\s+(?:(\d+)\s+)?([\d-]{10})\s+([\d:]{4,8})\s+(.+)$/u;
+/** Parse `ls -la` output, including `total` headers and symlink targets. */
+export const parseLsOutput = (stdout) => {
+    const entries = [];
+    const unparsedLines = [];
+    for (const rawLine of stdout.split(/\r?\n/u)) {
+        const line = rawLine.trimEnd();
+        if (line === "" || line.startsWith("total "))
+            continue;
+        const match = LS_LINE.exec(line);
+        if (match === null) {
+            if (line.trim() !== "")
+                unparsedLines.push(line);
+            continue;
+        }
+        const permissions = match[1];
+        let name = match[8].trim();
+        let linkTarget = null;
+        const linkArrow = name.indexOf(" -> ");
+        if (linkArrow !== -1 && permissions.startsWith("l")) {
+            linkTarget = name.slice(linkArrow + 4);
+            name = name.slice(0, linkArrow);
+        }
+        entries.push({
+            name,
+            kind: permissions.startsWith("d")
+                ? "directory"
+                : permissions.startsWith("l")
+                    ? "symlink"
+                    : permissions.startsWith("-")
+                        ? "file"
+                        : "other",
+            permissions,
+            owner: match[3] ?? null,
+            group: match[4] ?? null,
+            bytes: match[5] === undefined ? null : Number(match[5]),
+            date: `${match[6] ?? ""} ${match[7] ?? ""}`.trim() || null,
+            link_target: linkTarget,
+        });
+    }
+    return { entries, 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 the focus declarations from `dumpsys window windows`. */
+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;
+        }
+        if (inPermissions && /^\s{2,}[A-Za-z0-9._]+$/.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];
+};
+/**
+ * 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 };
+    const failure = /Failure \[([^\]]+)\]/u.exec(text);
+    return {
+        status: "failure",
+        reason: failure?.[1] ?? (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 `am start` output. Success prints `Starting: Intent { ... }`;
+ * refusals print lines starting with `Error:` or `Warning:` and activity
+ * classes that do not exist name the component.
+ */
+export const parseAmStartOutput = (stdout) => {
+    const text = stdout.trim();
+    const starting = /^Starting:\s+Intent\s*\{(.*)\}\s*$/mu.exec(text);
+    if (starting !== null)
+        return {
+            status: "started",
+            startedActivity: starting[1].trim(),
+            reason: null,
+        };
+    const error = /^(?:Error|Warning|Exception)(?::|\b)(.*)$/mu.exec(text);
+    return {
+        status: "refused",
+        startedActivity: null,
+        reason: error?.[1]?.trim() ??
+            (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/JadxConfiguration.js

@@ -23,7 +23,8 @@ class JadxConfigurationFailure extends Error {
 /** Inspect the same JAR and Java prerequisites that gate actual execution. */
 export const inspectJadxAvailability = async (environment, signal) => {
     try {
-        const configuration = await readJadxConfiguration(environment, signal);
+        const configuration = await readJadxConfigurationInputs(environment, signal);
+        await validateJadxConfigurationContents(configuration, environment, signal);
         return {
             status: "available",
             code: null,
@@ -49,42 +50,61 @@ export const inspectJadxAvailability = async (environment, signal) => {
         throw cause;
     }
 };
-/** Resolve caller-selected tools and preserve the same prerequisite diagnostics. */
-export const resolveJadxConfiguration = async (environment, operation, signal) => {
+/** Resolve caller-selected paths and JVM options without probing their contents. */
+export const resolveJadxConfigurationInputs = async (environment, operation, signal) => {
     try {
-        return await readJadxConfiguration(environment, signal);
+        return await readJadxConfigurationInputs(environment, signal);
     }
     catch (cause) {
         if (signal?.aborted === true)
             throw cause;
         if (!(cause instanceof JadxConfigurationFailure))
             throw cause;
-        const output = cause.diagnostics;
-        throw new AnalysisCapabilityUnavailableError("jadx", operation, cause.message, {
-            cause,
-            userMessage: cause.message,
-            ...(typeof output.stdout === "string" &&
-                typeof output.stderr === "string"
-                ? {
-                    capturedOutput: {
-                        stdout: output.stdout,
-                        stderr: output.stderr,
-                        truncated: output.output_truncated === true,
-                    },
-                }
-                : {}),
-        });
+        throw projectConfigurationFailure(operation, cause);
     }
 };
-const readJadxConfiguration = async (environment, signal) => {
+/** Probe Java and archive prerequisites before starting a new engine session. */
+export const validateJadxConfiguration = async (configuration, environment, operation, signal) => {
+    try {
+        await validateJadxConfigurationContents(configuration, environment, signal);
+    }
+    catch (cause) {
+        if (signal?.aborted === true)
+            throw cause;
+        if (!(cause instanceof JadxConfigurationFailure))
+            throw cause;
+        throw projectConfigurationFailure(operation, cause);
+    }
+};
+const readJadxConfigurationInputs = async (environment, signal) => {
+    signal?.throwIfAborted();
     requireSupportedHost();
     const jar = await resolveJar(environment);
     const java = await resolveJava(environment, signal);
     await requireJavaHomeExecutable(environment.JAVA_HOME, java);
-    const jvmArguments = resolveJvmArguments(environment);
-    await inspectJavaRuntime(java, environment, signal);
-    await requireEngineArchive(jar, signal);
-    return { jar, java, jvmArguments };
+    signal?.throwIfAborted();
+    return { jar, java, jvmArguments: resolveJvmArguments(environment) };
+};
+const validateJadxConfigurationContents = async (configuration, environment, signal) => {
+    signal?.throwIfAborted();
+    await inspectJavaRuntime(configuration.java, environment, signal);
+    await requireEngineArchive(configuration.jar, signal);
+};
+const projectConfigurationFailure = (operation, cause) => {
+    const output = cause.diagnostics;
+    return new AnalysisCapabilityUnavailableError("jadx", operation, cause.message, {
+        cause,
+        userMessage: cause.message,
+        ...(typeof output.stdout === "string" && typeof output.stderr === "string"
+            ? {
+                capturedOutput: {
+                    stdout: output.stdout,
+                    stderr: output.stderr,
+                    truncated: output.output_truncated === true,
+                },
+            }
+            : {}),
+    });
 };
 const requireEngineArchive = async (jar, signal) => {
     // These classes are consumed directly by ReaJadxBridge.java. This checks the