rea-agents 4.0.1 → 4.1.0

package/dist/android/AndroidTargetSnapshot.js

@@ -0,0 +1,34 @@
+import { constants, createReadStream } from "node:fs";
+import { chmod, copyFile } from "node:fs/promises";
+import { createHash } from "node:crypto";
+import { join } from "node:path";
+import { AnalysisInputError } 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");
+};
+/** Bind decompiler input to the admitted artifact, even if the original changes. */
+export const snapshotAndroidTarget = async (path, sha256, root, operation) => {
+    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, [
+            {
+                path: ["path"],
+                reason: "invalid_value",
+                message: "APK bytes changed after admission; retry against a stable file.",
+            },
+        ]);
+    return snapshot;
+};
+/** Fingerprint the actual immutable engine bytes executed for this observation. */
+export const snapshotAndroidEngine = async (source, root) => {
+    const path = join(root, "engine.jar");
+    await copyFile(source, path, constants.COPYFILE_EXCL);
+    await chmod(path, 0o400);
+    return { path, sha256: await hashAndroidFile(path) };
+};

package/dist/android/JadxAnalysis.js

@@ -0,0 +1,191 @@
+import { androidResultSchemas } from "../domain/androidAnalysis.js";
+import { AnalysisCapabilityUnavailableError, AnalysisInputError, AnalysisOutputError, } from "../domain/analysisErrorCore.js";
+import { jadxAppSchema, jadxClassPageSchema, jadxClassSchema, jadxLoadSchema, jadxMethodSchema, jadxXrefsSchema, normalizeJadxText, } from "./JadxProtocol.js";
+const methodsOf = (summary) => {
+    const seen = new Map();
+    return summary.methods.map((method) => {
+        const index = seen.get(method.name) ?? 0;
+        seen.set(method.name, index + 1);
+        return {
+            name: method.name,
+            reported_signature: method.signature,
+            overload_index: index,
+            is_constructor: method.is_constructor,
+            dex_descriptor: null,
+        };
+    });
+};
+const inputFailure = (request, field, message) => {
+    throw new AnalysisInputError(request.operation, undefined, [
+        { path: [field], reason: "invalid_value", message },
+    ]);
+};
+const classSummary = async (tools, request) => {
+    const raw = await tools.json("get_class_summary", {
+        class_name: request.input.class_name,
+    });
+    if (raw !== null &&
+        typeof raw === "object" &&
+        !Array.isArray(raw) &&
+        typeof raw.error === "string")
+        throw new AnalysisOutputError(request.operation, `JADX class summary failed: ${raw.error}`);
+    const summary = jadxClassSchema.safeParse(raw);
+    if (!summary.success)
+        throw new AnalysisOutputError(request.operation, "JADX class summary failed or was malformed; negative counts are not an empty class", { cause: summary.error });
+    const value = summary.data;
+    if (value.full_name !== request.input.class_name)
+        inputFailure(request, "class_name", `Exact class ${request.input.class_name} resolved to ${value.full_name}; use the fully qualified class name from search_android_classes.`);
+    if (value.method_count !== value.methods.length ||
+        value.field_count !== value.fields.length ||
+        value.inner_class_count !== value.inner_classes.length)
+        throw new AnalysisOutputError(request.operation, "JADX class member counts do not match the returned inventory");
+    return value;
+};
+const inspectPackage = async (tools, loaded, engine) => {
+    const app = jadxAppSchema.parse(await tools.json("get_app_info", {}));
+    const manifest = normalizeJadxText(await tools.text("get_android_manifest", {}));
+    return androidResultSchemas.inspect_android_package.parse({
+        engine,
+        package_name: app.package || null,
+        version_name: app.version_name || null,
+        version_code: app.version_code || null,
+        min_sdk: app.min_sdk || null,
+        target_sdk: app.target_sdk || null,
+        permissions: app.permissions,
+        manifest,
+        class_count: loaded.class_count,
+        resource_count: loaded.resource_count,
+        signature_verification: "not_performed",
+    });
+};
+const searchClasses = async (tools, request, loaded, engine) => {
+    const classes = [];
+    let total;
+    do {
+        const page = jadxClassPageSchema.parse(await tools.json("list_classes", {
+            offset: classes.length,
+            limit: 200,
+        }));
+        if ((total !== undefined && total !== page.total) ||
+            page.offset !== classes.length ||
+            page.limit !== 200 ||
+            page.items.length > 200)
+            throw new AnalysisOutputError(request.operation, "JADX class pagination changed identity or counts");
+        total = page.total;
+        classes.push(...page.items);
+        if (classes.length > total ||
+            (page.items.length === 0 && classes.length < total))
+            throw new AnalysisOutputError(request.operation, "JADX class pagination is incomplete");
+    } while (classes.length < total);
+    if (new Set(classes).size !== classes.length || total !== loaded.class_count)
+        throw new AnalysisOutputError(request.operation, "JADX class inventory is duplicated or differs from the loaded class count");
+    return androidResultSchemas.search_android_classes.parse({
+        engine,
+        query: request.input.query,
+        total_classes: total,
+        matches: classes.filter((name) => name.includes(request.input.query)),
+        coverage: "complete",
+    });
+};
+const matchingMethods = (summary, request) => {
+    const candidates = methodsOf(summary).filter((method) => method.name === request.input.method_name);
+    if (request.input.method_name !== undefined && candidates.length === 0)
+        inputFailure(request, "method_name", `Method ${summary.full_name}.${request.input.method_name} was not found; inspect_android_class lists available methods.`);
+    return candidates;
+};
+const inspectMethod = async (tools, request, summary, engine) => {
+    const candidates = matchingMethods(summary, request);
+    if (candidates.length > 1 && request.input.overload_index === undefined)
+        inputFailure(request, "overload_index", `Select one of ${candidates.length} overloads: ${candidates.map((method) => `${method.overload_index}: ${method.reported_signature}`).join("; ")}`);
+    const index = request.input.overload_index ?? 0;
+    const selected = candidates[index];
+    if (selected === undefined)
+        inputFailure(request, "overload_index", `Index ${index} is outside the ${candidates.length} matching overloads.`);
+    const body = jadxMethodSchema.parse(await tools.json("get_method_body", {
+        class_name: summary.full_name,
+        method_name: request.input.method_name,
+        overload_index: index,
+        smali_fallback: true,
+    }));
+    if (body.class_name !== summary.full_name ||
+        body.method_name !== request.input.method_name ||
+        body.overload_index !== index ||
+        body.overload_count !== candidates.length)
+        throw new AnalysisOutputError(request.operation, "JADX returned a different method or overload inventory");
+    if (body.body.startsWith("// ERROR:"))
+        throw new AnalysisOutputError(request.operation, `JADX did not produce method source: ${body.body}`);
+    if (body.mode === "smali" && candidates.length > 1)
+        throw new AnalysisCapabilityUnavailableError("jadx", request.operation, `JADX 0.7.1 smali fallback joins all same-name overloads for ${summary.full_name}.${request.input.method_name}; it cannot establish source for only overload ${index}.`);
+    return androidResultSchemas.inspect_android_method.parse({
+        engine,
+        class_name: summary.full_name,
+        method: selected,
+        overload_count: candidates.length,
+        representation: body.mode,
+        body_status: body.body.length === 0 ||
+            body.body ===
+                "// method exists but has no decompiled body (native/abstract)"
+            ? "not_available"
+            : "available",
+        fell_back: body.fell_back,
+        markers: body.markers,
+        source: normalizeJadxText(body.body),
+    });
+};
+/** Normalize only the selected analyst outcome and reject ambiguous engine selectors. */
+export const analyzeJadxRequest = async (tools, request, loaded, engine) => {
+    if (request.operation === "inspect_android_package")
+        return inspectPackage(tools, loaded, engine);
+    if (request.operation === "search_android_classes")
+        return searchClasses(tools, request, loaded, engine);
+    const summary = await classSummary(tools, request);
+    if (request.operation === "inspect_android_class")
+        return androidResultSchemas.inspect_android_class.parse({
+            engine,
+            class_name: summary.full_name,
+            methods: methodsOf(summary),
+            fields: summary.fields.map((field) => ({
+                name: field.name,
+                reported_type: field.type,
+            })),
+            inner_classes: summary.inner_classes,
+        });
+    if (request.operation === "inspect_android_method")
+        return inspectMethod(tools, request, summary, engine);
+    return traceReferences(tools, request, summary, engine);
+};
+const traceReferences = async (tools, request, summary, engine) => {
+    const methodName = request.input.method_name;
+    const candidates = matchingMethods(summary, request);
+    if (candidates.length > 1)
+        throw new AnalysisCapabilityUnavailableError("jadx", request.operation, `JADX 0.7.1 references select the first same-name method; ${summary.full_name}.${methodName} has ${candidates.length} overloads. No unambiguous reference result is available.`);
+    const expectedTarget = methodName === undefined
+        ? summary.full_name
+        : `${summary.full_name}.${methodName}`;
+    const xrefs = jadxXrefsSchema.parse(await tools.json(methodName === undefined ? "get_xrefs_to_class" : "get_xrefs_to_method", {
+        class_name: summary.full_name,
+        ...(methodName === undefined ? {} : { method_name: methodName }),
+        limit: 2_147_483_647,
+        resolve_line: false,
+    }));
+    if (xrefs.target !== expectedTarget ||
+        xrefs.total !== xrefs.count ||
+        xrefs.count !== xrefs.items.length)
+        throw new AnalysisOutputError(request.operation, "JADX references are incomplete or refer to another target");
+    return androidResultSchemas.trace_android_references.parse({
+        engine,
+        class_name: summary.full_name,
+        method_name: methodName ?? null,
+        total: xrefs.total,
+        references: xrefs.items.map((reference) => ({
+            kind: reference.kind,
+            name: reference.name,
+            reported_full_name: reference.full_name,
+            containing_class: reference.containing_class,
+            top_class: reference.top_class,
+            source_line: null,
+            dex_offset: null,
+        })),
+        coverage: "complete",
+    });
+};

package/dist/android/JadxConfiguration.js

@@ -0,0 +1,41 @@
+import { access, realpath, stat } from "node:fs/promises";
+import { constants } from "node:fs";
+import { isAbsolute, join } from "node:path";
+import { AnalysisCapabilityUnavailableError } from "../domain/analysisErrorCore.js";
+/** Admit explicit local tooling without installing or changing host configuration. */
+export const resolveJadxConfiguration = async (environment, operation) => {
+    const unavailable = (reason) => new AnalysisCapabilityUnavailableError("jadx", operation, reason);
+    if (process.platform !== "linux" && process.platform !== "darwin")
+        throw unavailable(`Android JADX subprocess ownership is unsupported on ${process.platform}; use Linux or macOS. Only Linux has real-provider verification.`);
+    const jar = environment.REA_JADX_MCP_JAR;
+    if (environment.JAVA_HOME !== undefined && !isAbsolute(environment.JAVA_HOME))
+        throw unavailable("JAVA_HOME must select an existing JDK by absolute path; omit it to use java on PATH.");
+    if (jar === undefined || !isAbsolute(jar))
+        throw unavailable("Set REA_JADX_MCP_JAR to the absolute path of a caller-supplied jadx-headless-mcp 0.7.1 JAR. REA does not download or install it.");
+    const java = environment.JAVA_HOME === undefined
+        ? "java"
+        : join(environment.JAVA_HOME, "bin", "java");
+    try {
+        await access(jar, constants.R_OK);
+        if (!(await stat(jar)).isFile())
+            throw unavailable(`REA_JADX_MCP_JAR is not a regular file: ${jar}`);
+    }
+    catch (cause) {
+        if (cause instanceof AnalysisCapabilityUnavailableError)
+            throw cause;
+        throw unavailable(`Cannot read REA_JADX_MCP_JAR ${jar}: ${cause instanceof Error ? cause.message : String(cause)}`);
+    }
+    if (environment.JAVA_HOME !== undefined) {
+        try {
+            await access(java, constants.R_OK | constants.X_OK);
+            if (!(await stat(java)).isFile())
+                throw unavailable(`JAVA_HOME java is not a regular file: ${java}`);
+        }
+        catch (cause) {
+            if (cause instanceof AnalysisCapabilityUnavailableError)
+                throw cause;
+            throw unavailable(`Cannot execute JAVA_HOME java ${java}: ${cause instanceof Error ? cause.message : String(cause)}`);
+        }
+    }
+    return { jar: await realpath(jar), java };
+};

package/dist/android/JadxMcpTransport.js

@@ -0,0 +1,145 @@
+import { deserializeMessage, serializeMessage, } from "@modelcontextprotocol/client";
+import { randomUUID } from "node:crypto";
+import { ProviderProcessSupervisor, spawnOwnedProviderProcess, } from "../process/ProviderProcess.js";
+import { cleanupOwnedProcessGroup } from "../process/ProcessOwnership.js";
+import { ProviderCleanupError } from "../domain/providerCleanupError.js";
+const MAX_FRAME_BYTES = 8 * 1024 * 1024;
+const MAX_SESSION_BYTES = 32 * 1024 * 1024;
+/** SDK-framed stdio with REA-owned process cleanup rather than an unowned child. */
+export class JadxMcpTransport {
+    options;
+    launcher;
+    onclose;
+    onerror;
+    onmessage;
+    runId = randomUUID();
+    #spawned;
+    #supervisor;
+    #buffer = Buffer.alloc(0);
+    #bytes = 0;
+    #started = false;
+    #closed = false;
+    #closePromise;
+    #starting;
+    #failure = null;
+    constructor(options, launcher = spawnOwnedProviderProcess) {
+        this.options = options;
+        this.launcher = launcher;
+    }
+    /** Acquires exactly one protocol process after the SDK installs callbacks. */
+    start() {
+        if (this.#started || this.#closed)
+            throw new Error("JADX transport cannot be restarted");
+        this.#started = true;
+        this.#starting = this.#acquire();
+        return this.#starting;
+    }
+    async #acquire() {
+        const spawned = await this.launcher({
+            ...this.options,
+            runId: this.runId,
+            stdin: "pipe",
+        });
+        this.#spawned = spawned;
+        this.#supervisor = new ProviderProcessSupervisor({
+            ...spawned,
+            ownsProcessLifetime: true,
+            cleanup: spawned.cleanup ?? (() => cleanupOwnedProcessGroup(spawned.ownership)),
+        });
+        if (spawned.process.stdin === undefined ||
+            spawned.process.stdin === null ||
+            spawned.process.stdout === null)
+            throw new Error("JADX launcher did not supply protocol stdin/stdout");
+        spawned.process.stdout.on("data", this.#read);
+        spawned.process.stderr?.on("data", this.#countStderr);
+        spawned.process.on("error", this.#error);
+        spawned.process.once("exit", this.#exit);
+        spawned.process.stdin.on("error", this.#error);
+        if (this.#closed)
+            throw new Error("JADX transport closed during startup");
+    }
+    /** Writes SDK-serialized messages and observes stream backpressure. */
+    async send(message) {
+        const input = this.#spawned?.process.stdin;
+        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));
+        });
+    }
+    /** Verifies owned process exit before declaring the transport closed. */
+    close() {
+        this.#closePromise ??= this.#stop();
+        return this.#closePromise;
+    }
+    /** Captured provider stderr without persisting inherited environment values. */
+    diagnostics() {
+        return this.#supervisor?.snapshot().stderr.text ?? "";
+    }
+    /** Preserve the failed protocol/resource constraint after the SDK closes requests. */
+    failureReason() {
+        return this.#failure;
+    }
+    async #stop() {
+        this.#closed = true;
+        // A cancellation may race acquisition. Join it before inspecting ownership.
+        await this.#starting?.catch(() => undefined);
+        const process = this.#spawned?.process;
+        process?.stdout?.off("data", this.#read);
+        process?.stderr?.off("data", this.#countStderr);
+        process?.off("error", this.#error);
+        process?.off("exit", this.#exit);
+        process?.stdin?.off("error", this.#error);
+        const stopped = await this.#supervisor?.stop();
+        this.onclose?.();
+        if (stopped?.status === "incomplete")
+            throw new ProviderCleanupError("jadx", [this.runId], {
+                reason: stopped.reason,
+                stderr: this.diagnostics(),
+            });
+    }
+    #error = (error) => {
+        this.onerror?.(error);
+    };
+    #exit = () => {
+        this.onclose?.();
+    };
+    #countStderr = (chunk) => {
+        this.#bytes += Buffer.byteLength(chunk);
+        if (this.#bytes > MAX_SESSION_BYTES)
+            this.#fail(new Error(`JADX session output exceeds ${MAX_SESSION_BYTES} bytes; no complete result is available`));
+    };
+    #read = (chunk) => {
+        if (this.#closed)
+            return;
+        const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        this.#bytes += bytes.length;
+        if (this.#bytes > MAX_SESSION_BYTES) {
+            this.#fail(new Error(`JADX session output exceeds ${MAX_SESSION_BYTES} bytes; no complete result is available`));
+            return;
+        }
+        this.#buffer = Buffer.concat([this.#buffer, bytes]);
+        try {
+            let newline;
+            while ((newline = this.#buffer.indexOf(10)) !== -1) {
+                if (newline > MAX_FRAME_BYTES)
+                    throw new Error(`JADX MCP frame exceeds ${MAX_FRAME_BYTES} bytes`);
+                const line = this.#buffer.subarray(0, newline).toString("utf8");
+                this.#buffer = this.#buffer.subarray(newline + 1);
+                this.onmessage?.(deserializeMessage(line));
+            }
+            if (this.#buffer.length > MAX_FRAME_BYTES)
+                throw new Error(`JADX MCP frame exceeds ${MAX_FRAME_BYTES} bytes`);
+        }
+        catch (cause) {
+            this.#fail(cause instanceof Error ? cause : new Error(String(cause)));
+        }
+    };
+    #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))));
+    }
+}

package/dist/android/JadxProtocol.js

@@ -0,0 +1,101 @@
+import { z } from "zod";
+import { AnalysisOutputError } from "../domain/analysisErrorCore.js";
+import { jsonValueSchema } from "../domain/jsonValue.js";
+const count = z.number().int().nonnegative();
+export const jadxLoadSchema = z.object({
+    state: z.literal("LOADED"),
+    apk_path: z.string(),
+    class_count: count,
+    resource_count: count,
+    threads: z.literal(1),
+    resources: z.literal("full"),
+});
+export const jadxAppSchema = z.object({
+    package: z.string(),
+    version_name: z.string(),
+    version_code: z.string(),
+    min_sdk: z.string(),
+    target_sdk: z.string(),
+    permissions: z.array(z.string()),
+});
+export const jadxClassPageSchema = z.object({
+    total: count,
+    offset: count,
+    limit: count,
+    items: z.array(z.string()),
+});
+export const jadxClassSchema = z.object({
+    full_name: z.string(),
+    name: z.string(),
+    method_count: count,
+    field_count: count,
+    inner_class_count: count,
+    methods: z.array(z.object({
+        name: z.string(),
+        signature: z.string(),
+        is_constructor: z.boolean(),
+        def_pos: z.number().int(),
+    })),
+    fields: z.array(z.object({ name: z.string(), type: z.string(), def_pos: z.number().int() })),
+    inner_classes: z.array(z.string()),
+});
+export const jadxMethodSchema = z.object({
+    class_name: z.string(),
+    method_name: z.string(),
+    full_name: z.string(),
+    overload_index: count,
+    overload_count: count,
+    mode: z.enum(["java", "smali"]),
+    fell_back: z.boolean(),
+    markers: z.array(z.string()),
+    body: z.string(),
+});
+export const jadxXrefsSchema = z.object({
+    target: z.string(),
+    total: count,
+    count,
+    resolve_line: z.literal(false),
+    items: z.array(z.object({
+        kind: z.string(),
+        name: z.string(),
+        full_name: z.string(),
+        containing_class: z.string(),
+        top_class: z.string(),
+        def_pos: z.number().int(),
+    })),
+});
+const toolResponse = z.object({
+    content: z
+        .array(z.object({ type: z.literal("text"), text: z.string() }))
+        .length(1),
+    isError: z.boolean().optional(),
+});
+/** Parse the upstream text-only envelope, preserving errors at the producing boundary. */
+export const parseJadxEnvelope = (response, operation) => {
+    const parsed = toolResponse.safeParse(response);
+    if (!parsed.success || parsed.data.content[0] === undefined)
+        throw new AnalysisOutputError(operation, "JADX returned an unsupported MCP content envelope");
+    return {
+        text: parsed.data.content[0].text,
+        failed: parsed.data.isError === true,
+    };
+};
+/** Decode an upstream JSON text payload without trusting its contents. */
+export const parseJadxJson = (text, operation) => {
+    try {
+        return jsonValueSchema.parse(JSON.parse(text));
+    }
+    catch (cause) {
+        throw new AnalysisOutputError(operation, "JADX returned malformed JSON text", { cause });
+    }
+};
+/** Upstream byte truncation is reported rather than promoted to a complete source. */
+export const normalizeJadxText = (text) => {
+    const marker = /\n\n\.\.\. \[truncated: exceeds (\d+) bytes, total (\d+) bytes\]$/u.exec(text);
+    const total = marker?.[2] === undefined ? null : Number(marker[2]);
+    return {
+        status: marker === null ? "complete" : "partial",
+        text,
+        reported_total_bytes: total !== null && Number.isSafeInteger(total) ? total : null,
+    };
+};

package/dist/android/JadxProvider.js

@@ -0,0 +1,170 @@
+import { z } from "zod";
+import { AnalysisError } from "../domain/analysisErrorBase.js";
+import { AnalysisCancelledError, AnalysisCapabilityUnavailableError, AnalysisOutputError, AnalysisTimeoutError, } from "../domain/analysisErrorCore.js";
+import { ProviderAdapterError } from "../domain/providerAdapterError.js";
+import { ProviderCleanupError } from "../domain/providerCleanupError.js";
+import { err, ok } from "../domain/result.js";
+import { PrivateRuntimeRoot } from "../process/PrivateRuntimeRoot.js";
+import { snapshotAndroidEngine, snapshotAndroidTarget, } from "./AndroidTargetSnapshot.js";
+import { resolveJadxConfiguration } from "./JadxConfiguration.js";
+import { JadxSession } from "./JadxSession.js";
+const OPERATION_TIMEOUT_MS = 120_000;
+const waitForTurn = (predecessor, request, signal) => new Promise((resolve, reject) => {
+    const abort = () => reject(new AnalysisCancelledError(request.operation));
+    signal?.addEventListener("abort", abort, { once: true });
+    if (signal?.aborted === true)
+        abort();
+    void predecessor.then(() => {
+        signal?.removeEventListener("abort", abort);
+        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 });
+    return new ProviderAdapterError("jadx", request.operation, {
+        cause,
+        diagnostics: {
+            reason: cause instanceof Error ? cause.message : String(cause),
+            stderr: session?.transport.diagnostics() ?? "",
+        },
+    });
+};
+const cleanup = async (session, root, previous) => {
+    const diagnostics = {
+        previous_error: previous.ok
+            ? null
+            : { tag: previous.error._tag, message: previous.error.message },
+    };
+    try {
+        await session?.close();
+    }
+    catch (cause) {
+        // Retain an uncertain workspace until the caller can resolve process ownership.
+        return err(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 }));
+    }
+    try {
+        await root?.close();
+    }
+    catch (cause) {
+        return err(new ProviderCleanupError("jadx", [root?.path ?? "unknown"], {
+            ...diagnostics,
+            reason: cause instanceof Error ? cause.message : String(cause),
+        }, { cause }));
+    }
+    return previous;
+};
+/** One queued engine per REA instance, with a fresh owned workspace for every request. */
+export class JadxProvider {
+    environment;
+    launcher;
+    #tail = Promise.resolve();
+    #cleanupFailure;
+    constructor(environment = process.env, launcher) {
+        this.environment = environment;
+        this.launcher = launcher;
+    }
+    /** Serialize expensive work and bind both raw and normalized results to the APK. */
+    async execute(target, request, options) {
+        const predecessor = this.#tail;
+        let release = () => { };
+        this.#tail = new Promise((resolve) => {
+            release = resolve;
+        });
+        try {
+            await waitForTurn(predecessor, request, options?.signal);
+        }
+        catch {
+            void predecessor.then(release);
+            return err(new AnalysisCancelledError(request.operation));
+        }
+        try {
+            if (options?.signal?.aborted === true)
+                return err(new AnalysisCancelledError(request.operation));
+            if (this.#cleanupFailure !== undefined)
+                return err(this.#cleanupFailure);
+            const outcome = await this.#execute(target, request, options);
+            if (!outcome.ok && outcome.error.cleanupIncomplete)
+                this.#cleanupFailure = outcome.error;
+            return outcome;
+        }
+        finally {
+            release();
+        }
+    }
+    async #execute(target, request, options) {
+        const timeout = AbortSignal.timeout(OPERATION_TIMEOUT_MS);
+        const signal = options?.signal === undefined
+            ? timeout
+            : AbortSignal.any([options.signal, timeout]);
+        let root;
+        let session;
+        let outcome;
+        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.throwIfAborted();
+            root = await PrivateRuntimeRoot.create({ prefix: "rea-android-" });
+            const engine = await snapshotAndroidEngine(configuration.jar, root.path);
+            const snapshot = await snapshotAndroidTarget(target.path, target.sha256, root.path, request.operation);
+            signal.throwIfAborted();
+            session = new JadxSession({
+                command: configuration.java,
+                arguments: [
+                    "-Xmx512m",
+                    "-XX:ActiveProcessorCount=1",
+                    "-jar",
+                    engine.path,
+                    "--threads",
+                    "1",
+                    "--max-source-bytes",
+                    "1048576",
+                    "--decompile-timeout-ms",
+                    "90000",
+                ],
+                cwd: root.path,
+                hostEnvironment: this.environment,
+                env: { _JAVA_OPTIONS: "-Xmx512m -XX:ActiveProcessorCount=1" },
+            }, this.launcher);
+            outcome = ok(await session.execute({
+                request,
+                target,
+                snapshot,
+                jarHash: engine.sha256,
+                signal,
+            }));
+        }
+        catch (cause) {
+            outcome = err(executionError({
+                cause,
+                request,
+                timeout,
+                signal: options?.signal,
+                session,
+            }));
+        }
+        return cleanup(session, root, outcome);
+    }
+}