rea-agents 6.5.0 → 6.7.0

package/dist/android/JadxProvider.js

@@ -1,23 +1,28 @@
-import { z } from "zod";
+import { ArtifactResourceScope } from "../artifacts/ArtifactResourceScope.js";
+import { AnalysisCleanupLease } from "../artifacts/AnalysisCleanupLease.js";
+import { analysisClientFailureForOperation } from "../providers/AnalysisClientFailure.js";
+import { throwIfJadxInterrupted } from "./JadxInterruption.js";
 import { chmod, copyFile } from "node:fs/promises";
 import { join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { AnalysisError } from "../domain/analysisErrorBase.js";
-import { AnalysisCancelledError, AnalysisCapabilityUnavailableError, AnalysisOutputError, AnalysisInputError, AnalysisTimeoutError, } from "../domain/analysisErrorCore.js";
-import { ProviderAdapterError } from "../domain/providerAdapterError.js";
+import { AnalysisCancelledError, AnalysisCapabilityUnavailableError, AnalysisInputError, } from "../domain/analysisErrorCore.js";
 import { ProviderCleanupError } from "../domain/providerCleanupError.js";
-import { projectAnalysisError } from "../domain/analysisErrorProjection.js";
+import { analysisErrorWithCleanupFailure } from "../domain/analysisErrorCleanup.js";
 import { err, ok } from "../domain/result.js";
 import { createJadxWorkspaceRoot, } from "./JadxWorkspaceRoot.js";
 import { snapshotAndroidEngine, snapshotAndroidTarget, } from "./AndroidTargetSnapshot.js";
-import { hashStableFile } from "../filesystem/StableFileHash.js";
+import { hashStableFile, stableFileHashCause, } from "../filesystem/StableFileHash.js";
 import { RegularFileChangedError } from "../filesystem/RegularFile.js";
-import { inspectJadxAvailability, resolveJadxConfigurationInputs, validateJadxConfiguration, } from "./JadxConfiguration.js";
+import { RegularFileCleanupFailure } from "../filesystem/OwnedRegularFile.js";
+import { inspectJadxAvailability, resolveJadxConfigurationInputs, resolveJadxOperationTimeout, validateJadxConfiguration, } from "./JadxConfiguration.js";
 import { JadxSession } from "./JadxSession.js";
-const OPERATION_TIMEOUT_MS = 120_000;
+import { captureJadxFailure } from "./JadxFailure.js";
 const BRIDGE_SOURCE = fileURLToPath(new URL("../../bridge/android/ReaJadxBridge.java", import.meta.url));
 const waitForTurn = (predecessor, request, signal) => new Promise((resolve, reject) => {
-    const abort = () => reject(new AnalysisCancelledError(request.operation));
+    const abort = () => reject(new AnalysisCancelledError(request.operation, {
+        cause: signal?.reason,
+    }));
     signal?.addEventListener("abort", abort, { once: true });
     if (signal?.aborted === true)
         abort();
@@ -26,42 +31,6 @@ const waitForTurn = (predecessor, request, signal) => new Promise((resolve, reje
         resolve();
     });
 });
-const executionError = (context) => {
-    const { cause, request, timeout, signal, session } = context;
-    if (signal?.aborted === true)
-        return new AnalysisCancelledError(request.operation);
-    if (timeout.aborted)
-        return new AnalysisTimeoutError(request.operation, OPERATION_TIMEOUT_MS);
-    if (cause instanceof AnalysisError)
-        return cause;
-    const protocolFailure = session?.transport.failureReason();
-    if (protocolFailure !== undefined && protocolFailure !== null)
-        return new AnalysisOutputError(request.operation, protocolFailure, {
-            cause,
-        });
-    if (cause instanceof z.ZodError)
-        return new AnalysisOutputError(request.operation, "JADX response violated the pinned upstream protocol", { cause });
-    if (session !== undefined && !session.initialized()) {
-        const stderr = session.transport.diagnostics();
-        const reason = `Java could not start REA's Android bridge using ${session.transport.options.command}: ${cause instanceof Error ? cause.message : String(cause)}.${stderr.length === 0 ? "" : ` Java diagnostics: ${stderr}`} Select a full JDK including jdk.compiler via JAVA_HOME, or a working java on PATH; verify it with java --list-modules. A JRE cannot compile REA's source bridge. If the JDK works, verify the REA bridge and configured JADX JAR installation.`;
-        return new AnalysisCapabilityUnavailableError("jadx", request.operation, reason, {
-            cause,
-            userMessage: reason,
-            capturedOutput: {
-                stdout: "",
-                stderr,
-                truncated: session.transport.diagnosticsTruncated(),
-            },
-        });
-    }
-    return new ProviderAdapterError("jadx", request.operation, {
-        cause,
-        diagnostics: {
-            reason: cause instanceof Error ? cause.message : String(cause),
-            stderr: session?.transport.diagnostics() ?? "",
-        },
-    });
-};
 const androidTargetChanged = (operation, path, cause) => new AnalysisInputError(operation, cause === undefined ? undefined : { cause }, [
     {
         path: ["path"],
@@ -70,55 +39,87 @@ const androidTargetChanged = (operation, path, cause) => new AnalysisInputError(
     },
 ]);
 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) => {
+const hashAndroidSource = async (path, operation, signal, retainFailedClose) => {
     try {
-        return (await hashStableFile(path, signal)).sha256;
+        return (await hashStableFile(path, { signal, retainFailedClose })).sha256;
     }
     catch (cause) {
-        if (signal.aborted)
-            throw cause;
-        if (cause instanceof RegularFileChangedError)
-            throw androidSourceChanged(operation, path, cause);
+        const physical = stableFileHashCause(cause);
+        if (physical instanceof RegularFileChangedError)
+            throw androidSourceChanged(operation, path, physical);
         throw cause;
     }
 };
+const cleanupResources = (resources) => [
+    ...(resources.session === undefined
+        ? []
+        : [resources.session.transport.runId]),
+    ...(resources.root === undefined ? [] : [resources.root.path]),
+    ...resources.fileHandles.values(),
+];
+/** The retained acquisition record owns both retry and current resource attribution. */
+const cleanupFailure = (resources, cleanup) => (resources.previousError === undefined
+    ? cleanup
+    : analysisErrorWithCleanupFailure(resources.previousError, cleanup, resources.operation)).bindCleanupResourceOwner({
+    get cleanupResources() {
+        return cleanupResources(resources);
+    },
+});
 const cleanup = async (resources) => {
-    const { session, root, previousError } = resources;
-    const diagnostics = {
-        previous_error: previousError === undefined ? null : projectAnalysisError(previousError),
-    };
+    const { session, root } = resources;
+    let sessionCloseFailed = false;
+    let sessionCloseCause;
     try {
         await session?.close();
         resources.session = undefined;
     }
     catch (cause) {
-        // Retain an uncertain workspace until the caller can resolve process ownership.
-        const error = new ProviderCleanupError("jadx", [
-            session?.transport.runId ?? "unknown",
-            ...(root === undefined ? [] : [root.path]),
-        ], {
-            ...diagnostics,
-            reason: cause instanceof Error ? cause.message : String(cause),
-            provider_cleanup: cause instanceof ProviderCleanupError
-                ? (cause.diagnostics ?? null)
-                : null,
-        }, { cause: previousError ?? cause });
-        if (previousError?.partialObservation !== undefined)
-            error.retainPartialObservation(previousError.partialObservation);
-        return err(error);
+        // Still drain independent hash descriptors, but keep the workspace until
+        // this session's process ownership is proven stopped.
+        sessionCloseFailed = true;
+        sessionCloseCause = cause;
+    }
+    const fileCloseCauses = [];
+    for (const owner of resources.fileHandles.keys()) {
+        try {
+            await owner.close();
+            if (resources.operationCause instanceof RegularFileCleanupFailure &&
+                resources.operationCause.owner === owner)
+                resources.previousError?.resolveCleanup();
+            resources.fileHandles.delete(owner);
+        }
+        catch (cause) {
+            fileCloseCauses.push(cause);
+        }
+    }
+    if (sessionCloseFailed || fileCloseCauses.length > 0) {
+        const cleanupCauses = [
+            ...(sessionCloseFailed ? [sessionCloseCause] : []),
+            ...fileCloseCauses,
+        ];
+        const cleanupError = new ProviderCleanupError("jadx", cleanupResources(resources), {
+            reason: cleanupCauses
+                .map((failure) => failure instanceof Error ? failure.message : String(failure))
+                .join("; "),
+            cleanup_causes: cleanupCauses.map((failure) => failure instanceof Error ? failure.message : String(failure)),
+            provider_cleanup: cleanupCauses.map((failure) => failure instanceof ProviderCleanupError
+                ? (failure.diagnostics ?? null)
+                : null),
+        }, {
+            operation: resources.operation,
+            cause: new AggregateError(cleanupCauses, "JADX resource cleanup failed"),
+        });
+        return err(cleanupFailure(resources, cleanupError));
     }
     try {
         await root?.close();
         resources.root = undefined;
     }
     catch (cause) {
-        const error = new ProviderCleanupError("jadx", [root?.path ?? "unknown"], {
-            ...diagnostics,
+        const error = new ProviderCleanupError("jadx", cleanupResources(resources), {
             reason: cause instanceof Error ? cause.message : String(cause),
-        }, { cause: previousError ?? cause });
-        if (previousError?.partialObservation !== undefined)
-            error.retainPartialObservation(previousError.partialObservation);
-        return err(error);
+        }, { operation: resources.operation, cause });
+        return err(cleanupFailure(resources, error));
     }
     return ok(undefined);
 };
@@ -131,6 +132,16 @@ export class JadxProvider {
     #retained;
     #idle;
     #shutdown = new AbortController();
+    #prerequisites = new ArtifactResourceScope();
+    #inspections = new Set();
+    #prerequisiteOwner = {
+        retain: (owner, resource) => this.#prerequisites.retain({
+            kind: "lease",
+            resource,
+            lease: AnalysisCleanupLease.forCloseOwner(owner, resource),
+        }),
+        run: (operation) => this.#prerequisites.run(operation),
+    };
     #closePromise;
     constructor(environment, launcher) {
         this.environment = environment;
@@ -138,12 +149,22 @@ export class JadxProvider {
     }
     /** Report actual local prerequisites without starting JADX or opening a target. */
     inspectAvailability(signal) {
-        return inspectJadxAvailability(this.environment, signal);
+        const pending = inspectJadxAvailability(this.environment, {
+            resourceOwner: this.#prerequisiteOwner,
+            signal: signal === undefined
+                ? this.#shutdown.signal
+                : AbortSignal.any([signal, this.#shutdown.signal]),
+        });
+        this.#inspections.add(pending);
+        void pending.then(() => this.#inspections.delete(pending), () => this.#inspections.delete(pending));
+        return pending;
     }
     /** Serialize expensive work and bind both raw and normalized results to the APK. */
     async execute(target, request, options) {
         if (this.#shutdown.signal.aborted)
-            return err(new AnalysisCancelledError(request.operation));
+            return err(new AnalysisCancelledError(request.operation, {
+                cause: this.#shutdown.signal.reason,
+            }));
         const signal = options?.signal === undefined
             ? this.#shutdown.signal
             : AbortSignal.any([options.signal, this.#shutdown.signal]);
@@ -155,13 +176,17 @@ export class JadxProvider {
         try {
             await waitForTurn(predecessor, request, signal);
         }
-        catch {
+        catch (cause) {
             void predecessor.then(release);
-            return err(new AnalysisCancelledError(request.operation));
+            return err(cause instanceof AnalysisError
+                ? cause
+                : new AnalysisCancelledError(request.operation, { cause }));
         }
         try {
             if (signal.aborted)
-                return err(new AnalysisCancelledError(request.operation));
+                return err(new AnalysisCancelledError(request.operation, {
+                    cause: signal.reason,
+                }));
             clearTimeout(this.#idle);
             if (this.#pendingCleanup !== undefined) {
                 const retired = await this.#retire();
@@ -183,7 +208,17 @@ export class JadxProvider {
         clearTimeout(this.#idle);
         this.#closePromise ??= this.#tail
             .then(async () => {
+            await Promise.allSettled(this.#inspections);
             const retired = await this.#retire();
+            try {
+                await this.#prerequisites.close();
+            }
+            catch (cause) {
+                const cleanup = analysisClientFailureForOperation(cause, "jadx", "close_binary");
+                if (!retired.ok)
+                    throw analysisErrorWithCleanupFailure(retired.error, cleanup, "close_binary").bindCleanupDependencies([retired.error, cleanup]);
+                throw cleanup;
+            }
             if (!retired.ok)
                 throw retired.error;
         })
@@ -196,17 +231,32 @@ export class JadxProvider {
     async #retire() {
         if (this.#pendingCleanup === undefined && this.#retained !== undefined) {
             this.#pendingCleanup = {
+                operation: "close_binary",
                 session: this.#retained.session,
                 root: this.#retained.root,
+                fileHandles: new Map(),
                 previousError: undefined,
+                operationCause: undefined,
+                reportedErrors: [],
             };
             this.#retained = undefined;
         }
         if (this.#pendingCleanup === undefined)
             return ok(undefined);
-        const result = await cleanup(this.#pendingCleanup);
-        if (result.ok)
+        const pending = this.#pendingCleanup;
+        const result = await cleanup(pending);
+        if (result.ok) {
+            for (const reportedError of pending.reportedErrors)
+                reportedError.deref()?.resolveCleanup();
+            pending.reportedErrors = [];
             this.#pendingCleanup = undefined;
+        }
+        else {
+            pending.reportedErrors = [
+                ...pending.reportedErrors.filter((reportedError) => reportedError.deref() !== undefined),
+                new WeakRef(result.error),
+            ];
+        }
         return result;
     }
     #scheduleIdle() {
@@ -218,22 +268,34 @@ export class JadxProvider {
         this.#idle.unref();
     }
     async #execute(target, request, options) {
-        const timeout = AbortSignal.timeout(OPERATION_TIMEOUT_MS);
+        // The deadline is fixed per provider environment; an unusable value is
+        // refused before any file handle, workspace, or engine is acquired.
+        const timeoutMs = resolveJadxOperationTimeout(this.environment, request.operation);
+        if (!timeoutMs.ok)
+            return timeoutMs;
+        const timeout = AbortSignal.timeout(timeoutMs.value);
         const signal = options?.signal === undefined
             ? timeout
             : AbortSignal.any([options.signal, timeout]);
         let root;
         let session;
+        const fileHandles = new Map();
+        const retainFailedClose = (path) => (owner) => {
+            fileHandles.set(owner, path);
+        };
         try {
             if (target.format !== "apk")
                 throw new AnalysisCapabilityUnavailableError("jadx", request.operation, `Target ${target.path} is ${target.format}; provide one standalone APK.`);
             const configuration = await resolveJadxConfigurationInputs(this.environment, request.operation, signal);
-            signal.throwIfAborted();
-            const jarHash = await hashAndroidSource(configuration.jar, request.operation, signal);
-            const bridgeHash = await hashAndroidSource(BRIDGE_SOURCE, request.operation, signal);
+            throwIfJadxInterrupted(signal);
+            const jarHash = await hashAndroidSource(configuration.jar, request.operation, signal, retainFailedClose(configuration.jar));
+            const bridgeHash = await hashAndroidSource(BRIDGE_SOURCE, request.operation, signal, retainFailedClose(BRIDGE_SOURCE));
             let targetHash;
             try {
-                targetHash = (await hashStableFile(target.path, signal)).sha256;
+                targetHash = (await hashStableFile(target.path, {
+                    signal,
+                    retainFailedClose: retainFailedClose(target.path),
+                })).sha256;
             }
             catch (cause) {
                 if (signal.aborted)
@@ -267,7 +329,11 @@ export class JadxProvider {
             }
             let retained = this.#retained;
             if (retained === undefined) {
-                await validateJadxConfiguration(configuration, this.environment, request.operation, signal);
+                await validateJadxConfiguration(configuration, this.environment, request.operation, {
+                    resourceOwner: this.#prerequisiteOwner,
+                    signal,
+                    operationDeadline: { signal: timeout, timeoutMs: timeoutMs.value },
+                });
                 root = await createJadxWorkspaceRoot();
                 const workspaceSignal = root.failureSignal === undefined
                     ? signal
@@ -277,10 +343,10 @@ export class JadxProvider {
                 const bridge = join(root.path, "ReaJadxBridge.java");
                 await copyFile(BRIDGE_SOURCE, bridge);
                 await chmod(bridge, 0o400);
-                const copiedBridgeHash = await hashAndroidSource(bridge, request.operation, workspaceSignal);
+                const copiedBridgeHash = await hashAndroidSource(bridge, request.operation, workspaceSignal, retainFailedClose(bridge));
                 if (copiedBridgeHash !== bridgeHash)
                     throw androidSourceChanged(request.operation, BRIDGE_SOURCE, undefined);
-                workspaceSignal.throwIfAborted();
+                throwIfJadxInterrupted(workspaceSignal);
                 session = new JadxSession({
                     command: configuration.java,
                     arguments: [
@@ -315,29 +381,38 @@ export class JadxProvider {
                 jarHash: retained.jarHash,
                 bridgeHash: retained.bridgeHash,
                 signal: activeSignal,
+                timeoutMs: timeoutMs.value,
             }));
-            activeSignal.throwIfAborted();
+            throwIfJadxInterrupted(activeSignal);
             this.#retained = retained;
             return outcome;
         }
         catch (cause) {
-            const previousError = executionError({
+            const failure = captureJadxFailure({
                 cause,
                 request,
                 timeout,
+                timeoutMs: timeoutMs.value,
                 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;
             this.#retained = undefined;
-            this.#pendingCleanup = { session, root, previousError };
+            this.#pendingCleanup = {
+                operation: request.operation,
+                session,
+                root,
+                fileHandles,
+                get previousError() {
+                    return failure();
+                },
+                operationCause: cause,
+                reportedErrors: [],
+            };
             const retired = await this.#retire();
-            return retired.ok ? err(previousError) : retired;
+            return retired.ok ? err(failure()) : retired;
         }
     }
 }

package/dist/android/JadxRelease.js

@@ -8,7 +8,7 @@ export const JADX_RELEASE = Object.freeze({
 /** Identity of REA's metadata bridge, distinct from the producing engine. */
 export const JADX_BRIDGE_IDENTITY = Object.freeze({
     name: "rea-jadx-bridge",
-    version: "1",
+    version: "4",
 });
 /** Remediation when `REA_JADX_MCP_JAR` is missing or not an absolute path. */
 export const JADX_JAR_CONFIGURATION_REMEDIATION = `Set REA_JADX_MCP_JAR to the absolute path of a caller-supplied jadx-headless-mcp ${JADX_RELEASE.version} JAR. REA does not download or install it.`;
@@ -16,6 +16,10 @@ export const JADX_JAR_CONFIGURATION_REMEDIATION = `Set REA_JADX_MCP_JAR to the a
 export const JADX_JAVA_RUNTIME_REMEDIATION = "Select a full JDK including jdk.compiler via JAVA_HOME or PATH, then verify it with java --list-modules. REA does not install Java.";
 /** Remediation when a JADX JVM resource override is malformed. */
 export const JADX_JVM_OPTIONS_REMEDIATION = "Set REA_JADX_HEAP_MIB to a positive integer (heap size in MiB) and REA_JADX_ACTIVE_PROCESSOR_COUNT to a positive integer within the JVM's signed 32-bit range.";
+/** Whole-operation deadline used when REA_JADX_OPERATION_TIMEOUT_MS is unset. */
+export const DEFAULT_JADX_OPERATION_TIMEOUT_MS = 120_000;
+/** Remediation when the JADX operation deadline override is malformed. */
+export const JADX_OPERATION_TIMEOUT_REMEDIATION = `Set REA_JADX_OPERATION_TIMEOUT_MS to a decimal millisecond count from 1 to 2147483647, or unset it to keep the ${String(DEFAULT_JADX_OPERATION_TIMEOUT_MS)} ms default.`;
 /** Remediation when the host cannot run the Android JADX subprocess. */
 export const JADX_UNSUPPORTED_HOST_REMEDIATION = "Use Linux, macOS, or Windows x64 with its bundled native controls for Android JADX analysis.";
 /** Remediation when the Windows native backend cannot take process ownership. */

package/dist/android/JadxSession.js

@@ -1,11 +1,12 @@
+import { throwIfJadxInterrupted } from "./JadxInterruption.js";
 import { Client } from "@modelcontextprotocol/client";
 import { createAnalysisExecution, } from "../application/AnalysisProvider.js";
-import { AnalysisCapabilityUnavailableError, AnalysisInputError, AnalysisOutputError, } from "../domain/analysisErrorCore.js";
+import { AnalysisCapabilityUnavailableError, AnalysisInputError, AnalysisOutputError, AnalysisResourceConstraintError, } from "../domain/analysisErrorCore.js";
 import { jsonValueSchema } from "../domain/jsonValue.js";
 import { ProviderAdapterError } from "../domain/providerAdapterError.js";
 import { analyzeJadxRequest } from "./JadxAnalysis.js";
 import { JadxMcpTransport } from "./JadxMcpTransport.js";
-import { jadxLoadSchema, jadxInputFailureSchema, jadxRuntimeSchema, parseJadxEnvelope, parseJadxJson, } from "./JadxProtocol.js";
+import { jadxLoadSchema, parseJadxFailure, jadxRuntimeSchema, parseJadxEnvelope, parseJadxJson, } from "./JadxProtocol.js";
 import { JADX_BRIDGE_IDENTITY, JADX_RELEASE, JADX_PROVIDER_IDENTITY, JADX_LIMITATIONS, } from "./JadxRelease.js";
 /** One owned engine connection; its wire protocol stays inside the Android adapter. */
 export class JadxSession {
@@ -23,7 +24,7 @@ export class JadxSession {
     }
     /** Analyze one admitted immutable APK, checking producer identity and selectors. */
     async execute(context) {
-        const { request, target, snapshot, jarHash, signal } = context;
+        const { request, target, snapshot, jarHash, signal, timeoutMs } = context;
         this.#partialContext = {
             operation: request.operation,
             selectedPath: request.input.path,
@@ -36,11 +37,13 @@ export class JadxSession {
         this.#serverVersion = null;
         this.#engineVersion = null;
         const abort = () => {
-            void this.transport.close().catch(() => undefined);
+            void this.transport.interrupt(signal.reason).catch(() => undefined);
         };
         signal.addEventListener("abort", abort, { once: true });
         try {
-            signal.throwIfAborted();
+            if (signal.aborted)
+                abort();
+            throwIfJadxInterrupted(signal);
             this.transport.beginOperation();
             if (!this.#connected) {
                 await this.#client.connect(this.transport, { timeout: 30_000 });
@@ -52,7 +55,7 @@ export class JadxSession {
             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);
+            const tools = this.#tools(request, target, signal, timeoutMs);
             const runtime = jadxRuntimeSchema.parse(await tools.json("rea_jvm_status", {}));
             this.#engineVersion = runtime.engine_reported_version;
             if (runtime.engine_reported_version !== JADX_RELEASE.version)
@@ -133,23 +136,41 @@ export class JadxSession {
             await this.transport.close();
         }
     }
-    #tools(request, target, signal) {
+    #tools(request, target, signal, timeoutMs) {
         const call = async (name, input) => {
-            signal.throwIfAborted();
-            const response = await this.#client.callTool({ name, arguments: input }, { timeout: 120_000, signal });
+            throwIfJadxInterrupted(signal);
+            // Keep an explicit bound: omitting it falls back to the SDK's 60-second default.
+            const response = await this.#client.callTool({ name, arguments: input }, { timeout: timeoutMs, signal });
             const observedResponse = jsonValueSchema.parse(response);
             const call = { operation: name, input, response: observedResponse };
             this.#observedCalls.push(call);
             const envelope = parseJadxEnvelope(response, request.operation);
             if (envelope.failed) {
-                if (envelope.text.startsWith("{")) {
-                    const failure = jadxInputFailureSchema.safeParse(parseJadxJson(envelope.text, request.operation));
-                    if (failure.success)
+                const failure = parseJadxFailure(envelope.text);
+                if (failure !== undefined) {
+                    if (name === "load_apk" && failure.kind === "jvm-memory-failure")
+                        throw new AnalysisResourceConstraintError(request.operation, "memory", `The JADX JVM could not allocate memory during ${name}${failure.message ? `: ${failure.message}` : ""}`, {
+                            observed_max_heap_bytes: failure.max_heap_bytes,
+                            memory_area: failure.memory_area,
+                        }, {
+                            retryable: false,
+                            remediationAction: failure.memory_area === "heap"
+                                ? "Increase REA_JADX_HEAP_MIB (MiB) in the environment that starts REA, within the host or container memory budget. Review JAVA_TOOL_OPTIONS and other JVM heap overrides. The observed heap is this run's limit, not the heap the APK requires."
+                                : "Review the JVM allocation failure and the host or container memory limits. The observed maximum heap does not establish which memory region was exhausted; increasing heap alone may not help.",
+                            diagnostics: {
+                                upstream_operation: name,
+                                reason: failure.message ?? null,
+                                exception_type: failure.exception_type,
+                                target_path: target.path,
+                                target_sha256: target.sha256,
+                            },
+                        });
+                    if (failure.kind === "invalid-input")
                         throw new AnalysisInputError(request.operation, undefined, [
                             {
-                                path: [failure.data.field],
+                                path: [failure.field],
                                 reason: "invalid_value",
-                                message: failure.data.message,
+                                message: failure.message,
                             },
                         ]);
                 }