rea-agents 6.2.0 → 6.4.0

package/dist/android/JadxProvider.js

@@ -9,8 +9,10 @@ import { ProviderCleanupError } from "../domain/providerCleanupError.js";
 import { projectAnalysisError } from "../domain/analysisErrorProjection.js";
 import { err, ok } from "../domain/result.js";
 import { PrivateRuntimeRoot } from "../process/PrivateRuntimeRoot.js";
-import { snapshotAndroidEngine, hashAndroidFile, snapshotAndroidTarget, } from "./AndroidTargetSnapshot.js";
-import { inspectJadxAvailability, resolveJadxConfiguration, } from "./JadxConfiguration.js";
+import { snapshotAndroidEngine, snapshotAndroidTarget, } from "./AndroidTargetSnapshot.js";
+import { hashStableFile } from "../filesystem/StableFileHash.js";
+import { RegularFileChangedError } from "../filesystem/RegularFile.js";
+import { inspectJadxAvailability, resolveJadxConfigurationInputs, validateJadxConfiguration, } from "./JadxConfiguration.js";
 import { JadxSession } from "./JadxSession.js";
 const OPERATION_TIMEOUT_MS = 120_000;
 const BRIDGE_SOURCE = fileURLToPath(new URL("../../bridge/android/ReaJadxBridge.java", import.meta.url));
@@ -60,6 +62,26 @@ const executionError = (context) => {
         },
     });
 };
+const androidTargetChanged = (operation, path, cause) => new AnalysisInputError(operation, cause === undefined ? undefined : { cause }, [
+    {
+        path: ["path"],
+        reason: "invalid_value",
+        message: `APK bytes changed after admission at ${path}; retry against a stable file.`,
+    },
+]);
+const androidSourceChanged = (operation, source, cause) => new AnalysisCapabilityUnavailableError("jadx", operation, `Selected JADX input bytes changed during admission at ${source}; retry with a stable installation.`, cause === undefined ? undefined : { cause });
+const hashAndroidSource = async (path, operation, signal) => {
+    try {
+        return (await hashStableFile(path, signal)).sha256;
+    }
+    catch (cause) {
+        if (signal.aborted)
+            throw cause;
+        if (cause instanceof RegularFileChangedError)
+            throw androidSourceChanged(operation, path, cause);
+        throw cause;
+    }
+};
 const cleanup = async (resources) => {
     const { session, root, previousError } = resources;
     const diagnostics = {
@@ -71,7 +93,7 @@ const cleanup = async (resources) => {
     }
     catch (cause) {
         // Retain an uncertain workspace until the caller can resolve process ownership.
-        return err(new ProviderCleanupError("jadx", [
+        const error = new ProviderCleanupError("jadx", [
             session?.transport.runId ?? "unknown",
             ...(root === undefined ? [] : [root.path]),
         ], {
@@ -80,17 +102,23 @@ const cleanup = async (resources) => {
             provider_cleanup: cause instanceof ProviderCleanupError
                 ? (cause.diagnostics ?? null)
                 : null,
-        }, { cause: previousError ?? cause }));
+        }, { cause: previousError ?? cause });
+        if (previousError?.partialObservation !== undefined)
+            error.retainPartialObservation(previousError.partialObservation);
+        return err(error);
     }
     try {
         await root?.close();
         resources.root = undefined;
     }
     catch (cause) {
-        return err(new ProviderCleanupError("jadx", [root?.path ?? "unknown"], {
+        const error = new ProviderCleanupError("jadx", [root?.path ?? "unknown"], {
             ...diagnostics,
             reason: cause instanceof Error ? cause.message : String(cause),
-        }, { cause: previousError ?? cause }));
+        }, { cause: previousError ?? cause });
+        if (previousError?.partialObservation !== undefined)
+            error.retainPartialObservation(previousError.partialObservation);
+        return err(error);
     }
     return ok(undefined);
 };
@@ -199,18 +227,23 @@ export class JadxProvider {
         try {
             if (target.format !== "apk")
                 throw new AnalysisCapabilityUnavailableError("jadx", request.operation, `Target ${target.path} is ${target.format}; provide one standalone APK.`);
-            const configuration = await resolveJadxConfiguration(this.environment, request.operation, signal);
+            const configuration = await resolveJadxConfigurationInputs(this.environment, request.operation, signal);
             signal.throwIfAborted();
-            const jarHash = await hashAndroidFile(configuration.jar);
-            const bridgeHash = await hashAndroidFile(BRIDGE_SOURCE);
-            if ((await hashAndroidFile(target.path)) !== target.sha256)
-                throw new AnalysisInputError(request.operation, undefined, [
-                    {
-                        path: ["path"],
-                        reason: "invalid_value",
-                        message: "APK bytes changed after admission; retry against a stable file.",
-                    },
-                ]);
+            const jarHash = await hashAndroidSource(configuration.jar, request.operation, signal);
+            const bridgeHash = await hashAndroidSource(BRIDGE_SOURCE, request.operation, signal);
+            let targetHash;
+            try {
+                targetHash = (await hashStableFile(target.path, signal)).sha256;
+            }
+            catch (cause) {
+                if (signal.aborted)
+                    throw cause;
+                if (cause instanceof RegularFileChangedError)
+                    throw androidTargetChanged(request.operation, target.path, cause);
+                throw cause;
+            }
+            if (targetHash !== target.sha256)
+                throw androidTargetChanged(request.operation, target.path);
             const key = JSON.stringify({
                 path: target.path,
                 sha256: target.sha256,
@@ -234,14 +267,16 @@ export class JadxProvider {
             }
             let retained = this.#retained;
             if (retained === undefined) {
+                await validateJadxConfiguration(configuration, this.environment, request.operation, signal);
                 root = await PrivateRuntimeRoot.create({ prefix: "rea-android-" });
-                const engine = await snapshotAndroidEngine(configuration.jar, jarHash, root.path, request.operation);
-                const snapshot = await snapshotAndroidTarget(target.path, target.sha256, root.path, request.operation);
+                const engine = await snapshotAndroidEngine(configuration.jar, jarHash, root.path, request.operation, signal);
+                const snapshot = await snapshotAndroidTarget(target.path, target.sha256, root.path, request.operation, signal);
                 const bridge = join(root.path, "ReaJadxBridge.java");
                 await copyFile(BRIDGE_SOURCE, bridge);
                 await chmod(bridge, 0o400);
-                if ((await hashAndroidFile(bridge)) !== bridgeHash)
-                    throw new AnalysisCapabilityUnavailableError("jadx", request.operation, "REA Android bridge bytes changed during admission; retry with a stable installation.");
+                const copiedBridgeHash = await hashAndroidSource(bridge, request.operation, signal);
+                if (copiedBridgeHash !== bridgeHash)
+                    throw androidSourceChanged(request.operation, BRIDGE_SOURCE, undefined);
                 signal.throwIfAborted();
                 session = new JadxSession({
                     command: configuration.java,
@@ -287,6 +322,9 @@ export class JadxProvider {
                 signal: options?.signal,
                 session,
             });
+            const partialObservation = session?.partialObservation();
+            if (partialObservation !== undefined)
+                previousError.retainPartialObservation(partialObservation);
             // Admission can fail before selecting an existing session for execution.
             root ??= this.#retained?.root;
             session ??= this.#retained?.session;

package/dist/android/JadxSession.js

@@ -13,12 +13,28 @@ export class JadxSession {
     #client = new Client({ name: "rea-android-adapter", version: "1" });
     #loaded;
     #connected = false;
+    #partialContext;
+    #observedCalls = [];
+    #serverName = null;
+    #serverVersion = null;
+    #engineVersion = null;
     constructor(options, launcher) {
         this.transport = new JadxMcpTransport(options, launcher);
     }
     /** Analyze one admitted immutable APK, checking producer identity and selectors. */
     async execute(context) {
         const { request, target, snapshot, jarHash, signal } = context;
+        this.#partialContext = {
+            operation: request.operation,
+            selectedPath: request.input.path,
+            target,
+            jarHash,
+            bridgeHash: context.bridgeHash,
+        };
+        this.#observedCalls = [];
+        this.#serverName = null;
+        this.#serverVersion = null;
+        this.#engineVersion = null;
         const abort = () => {
             void this.transport.close().catch(() => undefined);
         };
@@ -26,17 +42,19 @@ export class JadxSession {
         try {
             signal.throwIfAborted();
             this.transport.beginOperation();
-            const raw = [];
             if (!this.#connected) {
                 await this.#client.connect(this.transport, { timeout: 30_000 });
                 this.#connected = true;
             }
             const server = this.#client.getServerVersion();
+            this.#serverName = server?.name ?? null;
+            this.#serverVersion = server?.version ?? null;
             if (server?.name !== JADX_BRIDGE_IDENTITY.name ||
                 server.version !== JADX_BRIDGE_IDENTITY.version)
                 throw new AnalysisCapabilityUnavailableError("jadx", request.operation, `Expected ${JADX_BRIDGE_IDENTITY.name} ${JADX_BRIDGE_IDENTITY.version}; server reported ${server?.name ?? "unknown"} ${server?.version ?? "unknown"}.`);
-            const tools = this.#tools(request, target, signal, raw);
+            const tools = this.#tools(request, target, signal);
             const runtime = jadxRuntimeSchema.parse(await tools.json("rea_jvm_status", {}));
+            this.#engineVersion = runtime.engine_reported_version;
             if (runtime.engine_reported_version !== JADX_RELEASE.version)
                 throw new AnalysisCapabilityUnavailableError("jadx", request.operation, `Expected engine ${JADX_RELEASE.version}; JAR reported ${runtime.engine_reported_version}.`);
             const loaded = this.#loaded ??
@@ -63,7 +81,7 @@ export class JadxSession {
                     bridge_sha256: context.bridgeHash,
                     jar_sha256: jarHash,
                     loaded,
-                    calls: raw,
+                    calls: this.#observedCalls,
                 },
                 subject: target,
                 limitations: JADX_LIMITATIONS,
@@ -76,6 +94,32 @@ export class JadxSession {
             signal.removeEventListener("abort", abort);
         }
     }
+    /** Facts and upstream replies retained if a later request step fails. */
+    partialObservation() {
+        const context = this.#partialContext;
+        if (context === undefined)
+            return undefined;
+        return {
+            provider_id: "jadx",
+            operation: context.operation,
+            target: {
+                selected_path: context.selectedPath,
+                path: context.target.path,
+                sha256: context.target.sha256,
+                format: "apk",
+            },
+            provider_facts: {
+                jar_sha256: context.jarHash,
+                bridge_sha256: context.bridgeHash,
+                bridge_name: JADX_BRIDGE_IDENTITY.name,
+                bridge_version: JADX_BRIDGE_IDENTITY.version,
+                server_name: this.#serverName,
+                server_version: this.#serverVersion,
+                engine_version: this.#engineVersion,
+            },
+            calls: this.#observedCalls,
+        };
+    }
     /** Whether the selected Java runtime established the REA bridge protocol. */
     initialized() {
         return this.#connected;
@@ -89,16 +133,14 @@ export class JadxSession {
             await this.transport.close();
         }
     }
-    #tools(request, target, signal, raw) {
+    #tools(request, target, signal) {
         const call = async (name, input) => {
             signal.throwIfAborted();
             const response = await this.#client.callTool({ name, arguments: input }, { timeout: 120_000, signal });
+            const observedResponse = jsonValueSchema.parse(response);
+            const call = { operation: name, input, response: observedResponse };
+            this.#observedCalls.push(call);
             const envelope = parseJadxEnvelope(response, request.operation);
-            raw.push({
-                operation: name,
-                input,
-                response: jsonValueSchema.parse(response),
-            });
             if (envelope.failed) {
                 if (envelope.text.startsWith("{")) {
                     const failure = jadxInputFailureSchema.safeParse(parseJadxJson(envelope.text, request.operation));

package/dist/apktool/ApktoolConfiguration.js

@@ -0,0 +1,84 @@
+import { AnalysisCancelledError } from "../domain/analysisErrorCore.js";
+import { isAbsolute } from "node:path";
+import { execFileOutput, execFileOutputFailure, } from "../process/ExecFileOutput.js";
+/** Environment key selecting the caller's apktool launcher. */
+export const APKTOOL_COMMAND_ENV = "REA_APKTOOL_COMMAND";
+const VERSION_TIMEOUT_MS = 20_000;
+const VERSION_MAX_OUTPUT_BYTES = 64 * 1024;
+/**
+ * Resolve the caller-supplied apktool launcher. `REA_APKTOOL_COMMAND` must
+ * be absolute so the selection stays explicit; without it, apktool is
+ * resolved from `PATH` at run time. Both the upstream wrapper script and
+ * `java -jar` launcher scripts work: REA only runs `<command> --version`
+ * and `<command> d ...`.
+ */
+export const resolveApktoolCommand = (environment) => {
+    const configured = environment[APKTOOL_COMMAND_ENV];
+    if (configured === undefined || configured.trim() === "")
+        return { command: "apktool", commandSource: "path" };
+    if (!isAbsolute(configured))
+        throw new ApktoolConfigurationFailure("not_absolute", `${APKTOOL_COMMAND_ENV} must be an absolute path to the apktool launcher`, { configured_command: configured });
+    return { command: configured, commandSource: "environment" };
+};
+export class ApktoolConfigurationFailure extends Error {
+    code;
+    diagnostics;
+    constructor(code, message, diagnostics = {}, options) {
+        super(message, options);
+        this.code = code;
+        this.diagnostics = diagnostics;
+    }
+}
+/** Read the version from `apktool --version` output (first non-empty line). */
+export const parseApktoolVersionOutput = (stdout) => {
+    const line = stdout
+        .split(/\r?\n/u)
+        .map((entry) => entry.trim())
+        .find((entry) => entry !== "");
+    return { version: line === undefined ? null : line };
+};
+/** Probe the selected apktool launcher without decoding anything. */
+export const inspectApktoolClient = async (selection, signal, environment = process.env) => {
+    try {
+        const { stdout } = await execFileOutput(selection.command, ["--version"], {
+            timeout: VERSION_TIMEOUT_MS,
+            stopSignal: "SIGTERM",
+            maxBuffer: VERSION_MAX_OUTPUT_BYTES,
+            env: { ...process.env, ...environment },
+            ...(signal === undefined ? {} : { signal }),
+        });
+        return parseApktoolVersionOutput(stdout);
+    }
+    catch (cause) {
+        const failure = execFileOutputFailure(cause);
+        if (signal?.aborted || failure?.code === "ABORT_ERR")
+            throw new AnalysisCancelledError("inspect_apktool_client", { cause });
+        if (failure?.code === "ENOENT")
+            throw new ApktoolConfigurationFailure("command_missing", `The selected apktool launcher was not found: ${selection.command}`, {
+                selected_command: selection.command,
+                command_source: selection.commandSource,
+                remediation: `Set ${APKTOOL_COMMAND_ENV} to an absolute apktool launcher (the upstream wrapper or a java -jar script)`,
+            }, { cause });
+        throw new ApktoolConfigurationFailure("version_unresolved", "The selected apktool launcher did not report a usable version", {
+            selected_command: selection.command,
+            ...(failure === undefined
+                ? {}
+                : {
+                    exit_code: failure.code,
+                    stderr_excerpt: failure.stderr.slice(0, 512),
+                }),
+        }, { cause });
+    }
+};
+/** Availability in the shape shared by every provider. */
+const rejectionCodeOf = (code) => code === "command_missing"
+    ? "executable_missing"
+    : code === "not_absolute"
+        ? "not_configured"
+        : "version_unresolved";
+export const apktoolConfigurationAvailability = (cause) => ({
+    status: "unavailable",
+    code: rejectionCodeOf(cause.code),
+    reason: cause.message,
+    diagnostics: { ...cause.diagnostics },
+});

package/dist/apktool/ApktoolDecodeOutput.js

@@ -0,0 +1,59 @@
+/**
+ * Parsers for the decoded workspace `apktool d --no-src` produces.
+ *
+ * Apktool's apktool.yml is a small YAML document; the facts REA projects
+ * are flat enough that line-oriented extraction stays honest without a
+ * YAML dependency, and unrecognized content is ignored rather than guessed.
+ */
+/**
+ * Project version and SDK facts from apktool.yml. Values keep apktool's
+ * own spelling (version codes can print as `45` or `45.1`).
+ */
+export const parseApktoolYml = (yml) => {
+    const metadata = {
+        versionName: null,
+        versionCode: null,
+        minSdkVersion: null,
+        targetSdkVersion: null,
+    };
+    for (const line of yml.split(/\r?\n/u)) {
+        const versionName = /^\s*versionName:\s*(?:'([^']*)'|(.*))$/u.exec(line);
+        if (versionName !== null && metadata.versionName === null)
+            metadata.versionName = (versionName[1] ?? versionName[2] ?? "").trim();
+        const versionCode = /^\s*versionCode:\s*(?:'([^']*)'|(.*))$/u.exec(line);
+        if (versionCode !== null && metadata.versionCode === null)
+            metadata.versionCode = (versionCode[1] ?? versionCode[2] ?? "").trim();
+        const minSdk = /minSdkVersion:\s*'?([0-9]+)'?/u.exec(line);
+        if (minSdk !== null && metadata.minSdkVersion === null)
+            metadata.minSdkVersion = minSdk[1];
+        const targetSdk = /targetSdkVersion:\s*'?([0-9]+)'?/u.exec(line);
+        if (targetSdk !== null && metadata.targetSdkVersion === null)
+            metadata.targetSdkVersion = targetSdk[1];
+    }
+    return metadata;
+};
+/** Read the package attribute from decoded AndroidManifest.xml text. */
+export const parseManifestPackage = (manifest) => {
+    const match = /<manifest[^>]*\spackage="([^"]+)"/u.exec(manifest);
+    return match === null ? null : match[1];
+};
+/**
+ * Project `<string name="...">value</string>` entries from one decoded
+ * strings.xml. Values are preserved exactly as apktool printed them —
+ * escaped entities stay escaped — and entries containing nested markup
+ * are counted as unparsed rather than flattened.
+ */
+export const parseDecodedStrings = (stringsXml) => {
+    const entries = [];
+    let unparsedCount = 0;
+    const pattern = /<string\s+name="([^"]+)"[^>]*>([\s\S]*?)<\/string>/gu;
+    for (let match = pattern.exec(stringsXml); match !== null; match = pattern.exec(stringsXml)) {
+        const value = match[2];
+        if (value.includes("<")) {
+            unparsedCount += 1;
+            continue;
+        }
+        entries.push({ name: match[1], value: value.trim() });
+    }
+    return { entries, unparsedCount };
+};