rea-agents 6.5.0 → 6.7.0

package/dist/android/JadxJavaProbe.js

@@ -0,0 +1,246 @@
+import { randomUUID } from "node:crypto";
+import { AnalysisError, } from "../domain/analysisErrorBase.js";
+import { AnalysisCancelledError, AnalysisCapabilityUnavailableError, AnalysisTimeoutError, } from "../domain/analysisErrorCore.js";
+import { ProviderAdapterError } from "../domain/providerAdapterError.js";
+import { analysisErrorWithCleanupFailure } from "../domain/analysisErrorCleanup.js";
+import { jsonValueSchema } from "../domain/jsonValue.js";
+import { err, ok } from "../domain/result.js";
+import { prepareOwnedCommand, runOwnedCommand, OwnedCommandFailure, } from "../process/OwnedCommand.js";
+import { DarwinProcessOwnershipInspectionError } from "../process/DarwinProcessRunTokenReader.js";
+import { retainOwnedCommandCleanup } from "../providers/OwnedCommandCleanup.js";
+import { analysisClientFailureForOperation } from "../providers/AnalysisClientFailure.js";
+const JAVA_MODULE_LISTING_TIMEOUT_MS = 10_000;
+const JAVA_MODULE_LISTING_MAX_OUTPUT_BYTES = 1024 * 1024;
+const refusal = (code, message, diagnostics, kind) => err({ code, message, diagnostics, kind });
+const capturedOutput = (snapshot) => ({
+    stdout: snapshot.stdout.text,
+    stderr: snapshot.stderr.text,
+    stdout_bytes: snapshot.stdout.observedBytes,
+    stderr_bytes: snapshot.stderr.observedBytes,
+    truncated: snapshot.diagnosticTruncated === true || snapshot.outputIncomplete === true,
+    exit_code: snapshot.exitCode ?? null,
+    signal: snapshot.signal ?? null,
+});
+const projectRefusal = (failure, operation, cause, output) => {
+    const { stdout: _stdout, stderr: _stderr, ...facts } = failure.diagnostics;
+    return new AnalysisCapabilityUnavailableError("jadx", operation, failure.message, {
+        cause,
+        userMessage: failure.message,
+        diagnostics: {
+            ...facts,
+            failure_kind: failure.kind,
+            failure_code: failure.code,
+        },
+        ...(output === undefined ? {} : { capturedOutput: output }),
+    });
+};
+/** Interpret one complete module listing before joining final cleanup. */
+export const inspectJadxJava = async (java, environment, options) => {
+    const operation = options.operation ?? "inspect_jadx_configuration";
+    try {
+        return await options.resourceOwner.run(async () => {
+            let observed;
+            try {
+                await prepareOwnedCommand(options.signal);
+                await runOwnedCommand({
+                    command: java,
+                    arguments: ["--list-modules"],
+                    runId: randomUUID(),
+                    expectedCommand: null,
+                    hostEnvironment: environment,
+                    sweepTokenOwnedProcesses: true,
+                }, {
+                    timeoutMs: options.timeoutMs ?? JAVA_MODULE_LISTING_TIMEOUT_MS,
+                    diagnosticBytes: JAVA_MODULE_LISTING_MAX_OUTPUT_BYTES,
+                    acceptNonZeroExit: true,
+                    observeCompleted: (snapshot) => {
+                        observed = parseJavaModules(java, snapshot);
+                    },
+                }, {
+                    signal: options.signal,
+                    ...(options.launcher === undefined
+                        ? {}
+                        : { launcher: options.launcher }),
+                });
+                if (observed === undefined)
+                    throw new Error("Java probe completed without an observation");
+                return observed;
+            }
+            catch (cause) {
+                const command = cause instanceof OwnedCommandFailure ? cause : undefined;
+                const preparation = command?.preparationFailure ??
+                    (cause instanceof DarwinProcessOwnershipInspectionError
+                        ? cause
+                        : undefined);
+                const output = command?.snapshot == null
+                    ? preparation?.capturedOutput
+                    : capturedOutput(command.snapshot);
+                const cleanups = retainOwnedCommandCleanup(cause, options.resourceOwner, "jadx", operation);
+                let primary;
+                if (observed !== undefined && !observed.ok) {
+                    if (cleanups.length === 0)
+                        return observed;
+                    primary = projectRefusal(observed.error, operation, cause, output);
+                }
+                else if (command?.reason === "cancelled" &&
+                    command.cancellation !== undefined) {
+                    const reason = command.cancellation.reason;
+                    const errorOptions = {
+                        cause: reason,
+                        ...(output === undefined ? {} : { capturedOutput: output }),
+                        ...(observed?.ok === true
+                            ? {
+                                diagnostics: {
+                                    java_module_observation: {
+                                        compiler: observed.value.compiler,
+                                        major: observed.value.major,
+                                    },
+                                },
+                            }
+                            : {}),
+                    };
+                    primary =
+                        options.operationDeadline?.signal.aborted === true &&
+                            reason === options.operationDeadline.signal.reason
+                            ? new AnalysisTimeoutError(operation, options.operationDeadline.timeoutMs, errorOptions)
+                            : new AnalysisCancelledError(operation, errorOptions);
+                }
+                else if (observed?.ok === true &&
+                    command?.cleanupOwner !== undefined) {
+                    primary = new ProviderAdapterError("jadx", operation, {
+                        cause,
+                        ...(output === undefined ? {} : { capturedOutput: output }),
+                        diagnostics: {
+                            stage: "cleanup",
+                            java_module_observation: {
+                                compiler: observed.value.compiler,
+                                major: observed.value.major,
+                            },
+                        },
+                    });
+                }
+                else if (preparation !== undefined) {
+                    primary = new ProviderAdapterError("jadx", operation, {
+                        cause,
+                        ...(output === undefined ? {} : { capturedOutput: output }),
+                        diagnostics: {
+                            stage: "ownership_preparation",
+                            ...(preparation.compilerOutcome === undefined
+                                ? {}
+                                : {
+                                    compiler_outcome: jsonValueSchema.parse(preparation.compilerOutcome),
+                                }),
+                        },
+                    });
+                }
+                else if (cause instanceof AnalysisError) {
+                    primary = cause;
+                }
+                else {
+                    const failure = commandProbeRefusal(java, command, cause, options.timeoutMs ?? JAVA_MODULE_LISTING_TIMEOUT_MS);
+                    if (cleanups.length === 0)
+                        return err(failure);
+                    primary = projectRefusal(failure, operation, cause, output);
+                }
+                for (const cleanup of cleanups)
+                    primary = analysisErrorWithCleanupFailure(primary, cleanup, operation).bindCleanupDependencies([primary, cleanup]);
+                throw primary;
+            }
+        });
+    }
+    catch (cause) {
+        if (cause instanceof AnalysisError)
+            throw cause;
+        throw analysisClientFailureForOperation(cause, "jadx", operation);
+    }
+};
+const commandProbeRefusal = (java, command, cause, timeoutMs) => {
+    const output = command?.snapshot == null ? undefined : capturedOutput(command.snapshot);
+    const processError = command?.processError ?? (cause instanceof Error ? cause : undefined);
+    const systemCode = processError === undefined ? undefined : Reflect.get(processError, "code");
+    const limited = command?.reason === "output-limit";
+    const timedOut = command?.reason === "timeout";
+    return {
+        code: systemCode === "ENOENT"
+            ? "runtime_missing"
+            : limited || timedOut
+                ? "version_unresolved"
+                : "runtime_unavailable",
+        kind: systemCode === "ENOENT" ? "java_runtime" : "java_probe",
+        message: limited
+            ? `The selected Java launcher ${java} exceeded the ${JAVA_MODULE_LISTING_MAX_OUTPUT_BYTES / (1024 * 1024)} MiB output budget while listing modules. REA retained partial output but could not establish compiler or version availability. Inspect the selected launcher for verbose or unbounded output; java --list-modules should return a concise module listing.`
+            : timedOut
+                ? `The selected Java launcher ${java} did not finish the module-listing probe within ${timeoutMs / 1000} seconds. Inspect its startup responsiveness and verify it with java --list-modules.`
+                : `Cannot inspect selected Java runtime ${java}: ${systemCode === "ENOENT" ? "spawn java ENOENT" : cause instanceof Error ? cause.message : cause === undefined ? `exit ${String(output?.exit_code ?? "unknown")}${output?.signal == null ? "" : ` (${output.signal})`}` : String(cause)}. Review the selected launcher and retained diagnostics.`,
+        diagnostics: {
+            java_executable: java,
+            phase: "module-inspection",
+            exit_code: output?.exit_code ?? null,
+            process_error_code: typeof systemCode === "string" ? systemCode : null,
+            signal: output?.signal ?? null,
+            killed: null,
+            stdout: output?.stdout ?? "",
+            stderr: output?.stderr ?? "",
+            output_truncated: output?.truncated ?? true,
+            ...(limited
+                ? {
+                    failure: "output_limit",
+                    output_limit_bytes: JAVA_MODULE_LISTING_MAX_OUTPUT_BYTES,
+                }
+                : {}),
+            ...(timedOut
+                ? { failure: "probe_terminated", deadline_ms: timeoutMs }
+                : {}),
+        },
+    };
+};
+const parseJavaModules = (java, snapshot) => {
+    if (snapshot.exitCode !== 0 || snapshot.signal !== null)
+        return err(commandProbeRefusal(java, { reason: "process", snapshot, processError: undefined }, undefined, JAVA_MODULE_LISTING_TIMEOUT_MS));
+    const stdout = snapshot.stdout.text;
+    const stderr = snapshot.stderr.text;
+    const compiler = /^jdk\.compiler(?:@|$)/mu.test(stdout);
+    if (!compiler)
+        return refusal("runtime_missing", `Selected Java runtime ${java} does not provide jdk.compiler. Select a full JDK including jdk.compiler via JAVA_HOME or PATH; verify it with java --list-modules. A JRE cannot compile REA's source bridge.`, {
+            java_executable: java,
+            phase: "module-inspection",
+            jdk_compiler: false,
+            stdout,
+            stderr,
+            output_truncated: false,
+        }, "java_runtime");
+    const major = /^java\.base@(\d+)(?:[.+_-]|$)/mu.exec(stdout)?.[1];
+    if (major === undefined)
+        return refusal("version_unresolved", `The selected Java launcher ${java} did not report a parseable java.base version in its module listing. Inspect the launcher output and verify it with java --list-modules.`, {
+            java_executable: java,
+            phase: "module-inspection",
+            jdk_compiler: true,
+            java_major: null,
+            stdout,
+            stderr,
+            output_truncated: false,
+        }, "java_probe");
+    const majorNumber = Number(major);
+    if (!Number.isSafeInteger(majorNumber) || majorNumber <= 0)
+        return refusal("version_unresolved", `The selected Java launcher ${java} reported an invalid java.base major version. Review the retained module listing.`, {
+            java_executable: java,
+            phase: "module-inspection",
+            jdk_compiler: true,
+            java_major: null,
+            unparsed_java_major: major,
+            stdout,
+            stderr,
+            output_truncated: false,
+        }, "java_probe");
+    if (majorNumber < 17)
+        return refusal("unsupported_version", `Selected Java runtime ${java} must be JDK 17 or newer and include jdk.compiler; verify it with java --list-modules.`, {
+            java_executable: java,
+            phase: "module-inspection",
+            jdk_compiler: true,
+            java_major: major ?? null,
+            stdout,
+            stderr,
+            output_truncated: false,
+        }, "java_runtime");
+    return ok({ compiler: true, major: majorNumber });
+};

package/dist/android/JadxMcpTransport.js

@@ -23,7 +23,7 @@ export class JadxMcpTransport {
     #closed = false;
     #closePromise;
     #starting;
-    #failure = null;
+    #failure;
     constructor(options, launcher = spawnOwnedProviderProcess) {
         this.options = options;
         this.launcher = launcher;
@@ -33,7 +33,10 @@ export class JadxMcpTransport {
         if (this.#started || this.#closed)
             throw new Error("JADX transport cannot be restarted");
         this.#started = true;
-        this.#starting = this.#acquire();
+        this.#starting = this.#acquire().catch((cause) => {
+            this.#failure ??= { kind: "process", cause };
+            throw cause;
+        });
         return this.#starting;
     }
     async #acquire() {
@@ -54,6 +57,7 @@ export class JadxMcpTransport {
             spawned.process.stdout === null)
             throw new Error("JADX launcher did not supply protocol stdin/stdout");
         spawned.process.stdout.on("data", this.#read);
+        spawned.process.stdout.on("error", this.#error);
         spawned.process.stderr?.on("data", this.#countStderr);
         spawned.process.on("error", this.#error);
         spawned.process.once("exit", this.#exit);
@@ -67,7 +71,20 @@ export class JadxMcpTransport {
         if (this.#closed || input === undefined || input === null)
             throw new Error("JADX protocol process is not writable");
         await new Promise((resolve, reject) => {
-            input.write(serializeMessage(message), (cause) => cause === null || cause === undefined ? resolve() : reject(cause));
+            try {
+                input.write(serializeMessage(message), (cause) => {
+                    if (cause === null || cause === undefined)
+                        resolve();
+                    else {
+                        this.#failure ??= { kind: "process", cause };
+                        reject(cause);
+                    }
+                });
+            }
+            catch (cause) {
+                this.#failure ??= { kind: "process", cause };
+                reject(cause);
+            }
         });
     }
     /** Verifies owned process exit before declaring the transport closed. */
@@ -78,16 +95,30 @@ export class JadxMcpTransport {
         });
         return this.#closePromise;
     }
+    /** Keep the interruption reason distinct from errors produced by its teardown. */
+    interrupt(reason) {
+        this.#failure ??= { kind: "interrupted", reason };
+        return this.close();
+    }
     /** Captured provider stderr without persisting inherited environment values. */
     diagnostics() {
-        return this.#supervisor?.snapshot().stderr.text ?? "";
-    }
-    /** Whether the retained startup/operation diagnostics lost bytes. */
-    diagnosticsTruncated() {
-        return this.#supervisor?.snapshot().diagnosticTruncated ?? false;
+        const owner = this.#supervisor;
+        if (owner === undefined)
+            return undefined;
+        const snapshot = owner.snapshot();
+        return {
+            stdout: "",
+            stderr: snapshot.stderr.text,
+            stderr_bytes: snapshot.stderr.observedBytes,
+            truncated: snapshot.diagnosticTruncated === true || !owner.observedOutputClose(),
+            ...(snapshot.exitCode === undefined
+                ? {}
+                : { exit_code: snapshot.exitCode }),
+            ...(snapshot.signal === undefined ? {} : { signal: snapshot.signal }),
+        };
     }
     /** Preserve the failed protocol/resource constraint after the SDK closes requests. */
-    failureReason() {
+    observedFailure() {
         return this.#failure;
     }
     /** Scope both the byte budget and diagnostic retention to the next serialized request. */
@@ -103,6 +134,7 @@ export class JadxMcpTransport {
         await this.#starting?.catch(() => undefined);
         const process = this.#spawned?.process;
         process?.stdout?.off("data", this.#read);
+        process?.stdout?.off("error", this.#error);
         process?.stderr?.off("data", this.#countStderr);
         process?.off("error", this.#error);
         process?.off("exit", this.#exit);
@@ -120,13 +152,17 @@ export class JadxMcpTransport {
         if (stopped?.status === "incomplete")
             throw new ProviderCleanupError("jadx", [this.runId], {
                 reason: stopped.reason,
-                stderr: this.diagnostics(),
+                stderr: this.diagnostics()?.stderr ?? "",
             });
     }
     #error = (error) => {
+        this.#failure ??= { kind: "process", cause: error };
         this.onerror?.(error);
+        // Reject pending SDK work after joining the same owned teardown on every path.
+        void this.close().catch((cause) => this.onerror?.(cause instanceof Error ? cause : new Error(String(cause))));
     };
     #exit = () => {
+        this.#failure ??= { kind: "exit" };
         this.onclose?.();
     };
     #countStderr = (chunk) => {
@@ -181,10 +217,7 @@ export class JadxMcpTransport {
         this.#frameLength = frameBytes;
     }
     #fail(error) {
-        this.#failure ??= error.message;
-        this.onerror?.(error);
-        // Closing immediately rejects the SDK's outstanding request. The owner
-        // awaits close again and retains a cleanup failure in the returned Result.
-        void this.close().catch((cause) => this.onerror?.(cause instanceof Error ? cause : new Error(String(cause))));
+        this.#failure ??= { kind: "protocol", cause: error };
+        this.#error(error);
     }
 }

package/dist/android/JadxProtocol.js

@@ -3,12 +3,36 @@ import { AnalysisOutputError } from "../domain/analysisErrorCore.js";
 import { jsonValueSchema } from "../domain/jsonValue.js";
 import { dexDescriptorSchema } from "../domain/android/androidAnalysis.js";
 const count = z.number().int().nonnegative();
+/** Typed allocation failures authored before upstream erases the JVM exception. */
+const jadxMemoryFailureSchema = z.strictObject({
+    kind: z.literal("jvm-memory-failure"),
+    memory_area: z.enum(["heap", "unknown"]),
+    exception_type: z.literal("java.lang.OutOfMemoryError"),
+    message: z.string().optional(),
+    max_heap_bytes: z.number().int().positive().safe(),
+});
 /** Selector failures authored by REA's bridge, separate from arbitrary engine errors. */
-export const jadxInputFailureSchema = z.strictObject({
+const jadxInputFailureSchema = z.strictObject({
     kind: z.literal("invalid-input"),
     field: z.enum(["class_name", "method_name", "overload_index"]),
     message: z.string().min(1),
 });
+const bridgeFailureSchema = z.discriminatedUnion("kind", [
+    jadxInputFailureSchema,
+    jadxMemoryFailureSchema,
+]);
+/** Arbitrary upstream failure text stays text unless it matches a named bridge contract. */
+export const parseJadxFailure = (text) => {
+    let candidate;
+    try {
+        candidate = JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+    const parsed = bridgeFailureSchema.safeParse(candidate);
+    return parsed.success ? parsed.data : undefined;
+};
 /** Values observed inside the exact JVM producing the analysis. */
 export const jadxRuntimeSchema = z.object({
     engine_reported_version: z.string().min(1),
@@ -34,7 +58,9 @@ export const jadxAppSchema = z.object({
     permissions: z.array(z.string()),
 });
 export const jadxClassPageSchema = z.object({
-    total: count,
+    scope: z.literal("top_level"),
+    total_classes: count,
+    next_offset: count,
     offset: count,
     limit: count,
     items: z.array(z.string()),
@@ -61,6 +87,7 @@ export const jadxMethodSchema = z.object({
     full_name: z.string(),
     overload_index: count,
     overload_count: count,
+    dex_descriptor: dexDescriptorSchema,
     mode: z.enum(["java", "smali"]),
     fell_back: z.boolean(),
     markers: z.array(z.string()),