rea-agents 4.0.1 → 5.0.0

package/bridge/native/ReaNativeUI.swift

@@ -22,15 +22,17 @@ func attribute(_ element: AXUIElement, _ key: String) -> CFTypeRef? {
   var value: CFTypeRef?
   return AXUIElementCopyAttributeValue(element, key as CFString, &value) == .success ? value : nil
 }
-func childCount(_ element: AXUIElement) -> Int {
+func childCount(_ element: AXUIElement) -> ChildCount {
   var count = 0
-  return AXUIElementGetAttributeValueCount(element, kAXChildrenAttribute as CFString, &count) == .success ? count : 0
+  let status = AXUIElementGetAttributeValueCount(element, kAXChildrenAttribute as CFString, &count)
+  return captureChildCount(status: status.rawValue, success: AXError.success.rawValue, value: count)
 }
-func children(_ element: AXUIElement, limit: Int) -> [AXUIElement] {
-  var value: CFArray?
-  let count = min(limit, childCount(element))
-  if count == 0 { return [] }
-  return AXUIElementCopyAttributeValues(element, kAXChildrenAttribute as CFString, 0, count, &value) == .success ? value as? [AXUIElement] ?? [] : []
+func children(_ element: AXUIElement, count: Int) -> ChildBatch<AXUIElement> {
+  captureChildValues(requestedCount: count) {
+    var value: CFArray?
+    guard AXUIElementCopyAttributeValues(element, kAXChildrenAttribute as CFString, 0, count, &value) == .success else { return nil }
+    return value as? [AXUIElement]
+  }
 }
 func text(_ element: AXUIElement, _ key: String) -> Any { (attribute(element, key) as? String) ?? NSNull() as Any }
 func windowBounds(_ element: AXUIElement) -> CGRect? {
@@ -87,7 +89,11 @@ func observe(_ request: Request) async throws -> [String: Any] {
     var element = root
     for index in action.path ?? [] {
       var selectedChild: CFArray?
-      guard index >= 0 && index < childCount(element),
+      let count = childCount(element)
+      guard let available = count.value else {
+        try fail("element-count-unavailable", "Cannot validate selected accessibility path because child count failed with AXError \(count.error ?? -1)")
+      }
+      guard index >= 0 && index < available,
         AXUIElementCopyAttributeValues(element, kAXChildrenAttribute as CFString, index, 1, &selectedChild) == .success,
         let item = (selectedChild as? [AXUIElement])?.first else { try fail("element-missing", "Selected accessibility path no longer exists") }
       element = item
@@ -103,21 +109,29 @@ func observe(_ request: Request) async throws -> [String: Any] {
     }
     guard outcome == .success else { try fail("action-failed", "Accessibility action failed with AXError \(outcome.rawValue)") }
   }
-  var nodes: [[String: Any]] = []; var truncated = false
+  var nodes: [[String: Any]] = []; var truncated = false; var gaps: [String] = []
   if request.accessibility, let root = selected {
     var pending: [(AXUIElement, [Int])] = [(root, [])]
     while let (element, path) = pending.popLast() {
       if nodes.count >= request.max_nodes { truncated = true; break }
-      let totalChildren = childCount(element)
+      let childCountResult = childCount(element)
       var actions: CFArray?
       AXUIElementCopyActionNames(element, &actions)
-      nodes.append(["path": path, "role": text(element, kAXRoleAttribute), "title": text(element, kAXTitleAttribute), "value": text(element, kAXValueAttribute), "actions": actions as? [String] ?? [], "children_count": totalChildren])
+      nodes.append(["path": path, "role": text(element, kAXRoleAttribute), "title": text(element, kAXTitleAttribute), "value": text(element, kAXValueAttribute), "actions": actions as? [String] ?? [], "children_count": childCountResult.value.map { $0 as Any } ?? NSNull()])
+      guard let totalChildren = childCountResult.value else {
+        truncated = true
+        gaps.append("AX child count unavailable at path \(path): AXError \(childCountResult.error ?? -1)")
+        continue
+      }
       if path.count >= 32 { if totalChildren > 0 { truncated = true }; continue }
       let available = max(0, request.max_nodes - nodes.count - pending.count)
       let count = min(available, totalChildren)
-      let items = children(element, limit: count)
+      let batch = children(element, count: count)
+      if !batch.complete { truncated = true }
       if totalChildren > count { truncated = true }
-      for index in (0..<count).reversed() { pending.append((items[index], path + [index])) }
+      for (index, item) in batch.values.enumerated().reversed() {
+        pending.append((item, path + [index]))
+      }
     }
   }
   var screenshot: Any = NSNull()
@@ -139,18 +153,18 @@ func observe(_ request: Request) async throws -> [String: Any] {
     }
     screenshot = ["mime_type": "image/png", "base64": png.base64EncodedString(), "sha256": SHA256.hash(data: png).map({ String(format: "%02x", $0) }).joined(), "width": image.width, "height": image.height]
   }
-  return ["window": ["pid": request.pid, "window_id": request.window_id, "executable": request.executable, "launch_time": launch, "title": window[kCGWindowName as String] as? String ?? ""], "nodes": nodes, "truncated": truncated, "screenshot": screenshot, "gaps": request.accessibility ? [] : ["Accessibility capture was disabled"]]
+  return ["window": ["pid": request.pid, "window_id": request.window_id, "executable": request.executable, "launch_time": launch, "title": window[kCGWindowName as String] as? String ?? ""], "nodes": nodes, "truncated": truncated, "screenshot": screenshot, "gaps": request.accessibility ? gaps : ["Accessibility capture was disabled"]]
 }
 Task { @MainActor in
   do {
     let request = try JSONDecoder().decode(Request.self, from: Data(CommandLine.arguments[1].utf8))
     let result = try await observe(request)
-    let output = try JSONSerialization.data(withJSONObject: ["ok": true, "result": result], options: [.sortedKeys])
+    let output = try serializeHelperOutput(["ok": true, "result": result])
     FileHandle.standardOutput.write(output)
   } catch {
     let failure = error as? BoundaryFailure
     let output: [String: Any] = ["ok": false, "code": failure?.code ?? "capture-failed", "message": failure?.message ?? error.localizedDescription]
-    if let data = try? JSONSerialization.data(withJSONObject: output, options: [.sortedKeys]) { FileHandle.standardOutput.write(data) }
+    if let data = try? serializeHelperOutput(output) { FileHandle.standardOutput.write(data) }
   }
   exit(0)
 }

package/dist/android/AndroidTargetSnapshot.js

@@ -0,0 +1,36 @@
+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, AnalysisCapabilityUnavailableError, } from "../domain/analysisErrorCore.js";
+/** Stream a local file digest without retaining the APK or JAR in memory. */
+export const hashAndroidFile = async (path) => {
+    const hash = createHash("sha256");
+    for await (const chunk of createReadStream(path))
+        hash.update(chunk);
+    return hash.digest("hex");
+};
+/** 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, sha256, root, operation) => {
+    const path = join(root, "engine.jar");
+    await copyFile(source, path, constants.COPYFILE_EXCL);
+    await chmod(path, 0o400);
+    if ((await hashAndroidFile(path)) !== sha256)
+        throw new AnalysisCapabilityUnavailableError("jadx", operation, "REA_JADX_MCP_JAR bytes changed during admission; retry with a stable engine file.");
+    return { path, sha256 };
+};

package/dist/android/JadxAnalysis.js

@@ -0,0 +1,193 @@
+import { androidResultSchemas } from "../domain/android/androidAnalysis.js";
+import { AnalysisCapabilityUnavailableError, AnalysisInputError, AnalysisOutputError, } from "../domain/analysisErrorCore.js";
+import { jadxAppSchema, jadxClassPageSchema, jadxClassSchema, jadxLoadSchema, jadxMethodSchema, jadxXrefsSchema, normalizeJadxText, } from "./JadxProtocol.js";
+import { JADX_RELEASE } from "./JadxRelease.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 = [];
+    const pageSize = 4096;
+    let total;
+    do {
+        const page = jadxClassPageSchema.parse(await tools.json("list_classes", {
+            offset: classes.length,
+            limit: pageSize,
+        }));
+        if ((total !== undefined && total !== page.total) ||
+            page.offset !== classes.length ||
+            page.limit !== pageSize ||
+            page.items.length > pageSize)
+            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 ${JADX_RELEASE.version} 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, `References require a unique method name; ${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,57 @@
+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";
+import { JADX_JAR_CONFIGURATION_REMEDIATION } from "./JadxRelease.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. The metadata bridge has real-provider verification on macOS arm64.`);
+    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(JADX_JAR_CONFIGURATION_REMEDIATION);
+    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)}`);
+        }
+    }
+    const jvmArguments = [];
+    for (const [name, prefix, suffix] of [
+        ["REA_JADX_HEAP_MIB", "-Xmx", "m"],
+        ["REA_JADX_ACTIVE_PROCESSOR_COUNT", "-XX:ActiveProcessorCount=", ""],
+    ]) {
+        const value = environment[name];
+        if (value === undefined)
+            continue;
+        if (!/^[1-9]\d*$/u.test(value) || !Number.isSafeInteger(Number(value)))
+            throw unavailable(`${name} must be a positive safe integer; received ${value}.`);
+        if (name === "REA_JADX_ACTIVE_PROCESSOR_COUNT" &&
+            Number(value) > 2_147_483_647)
+            throw unavailable(`${name} exceeds the JVM's signed 32-bit processor-count range.`);
+        jvmArguments.push(`${prefix}${value}${suffix}`);
+    }
+    return { jar: await realpath(jar), java, jvmArguments };
+};

package/dist/android/JadxMcpTransport.js

@@ -0,0 +1,172 @@
+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_OPERATION_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;
+    #frameBuffer = Buffer.alloc(0);
+    #frameLength = 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)),
+        }, { captureStdout: false });
+        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;
+    }
+    /** Scope both the byte budget and diagnostic retention to the next serialized request. */
+    beginOperation() {
+        this.#bytes = 0;
+        this.#supervisor?.resetOutput();
+    }
+    async #stop() {
+        this.#closed = true;
+        this.#frameBuffer = Buffer.alloc(0);
+        this.#frameLength = 0;
+        // 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_OPERATION_BYTES)
+            this.#fail(new Error(`JADX operation output exceeds ${MAX_OPERATION_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_OPERATION_BYTES) {
+            this.#fail(new Error(`JADX operation output exceeds ${MAX_OPERATION_BYTES} bytes; no complete result is available`));
+            return;
+        }
+        try {
+            let offset = 0;
+            while (offset < bytes.length) {
+                const newline = bytes.indexOf(10, offset);
+                const end = newline === -1 ? bytes.length : newline;
+                const fragment = bytes.subarray(offset, end);
+                const frameBytes = this.#frameLength + fragment.length;
+                if (frameBytes > MAX_FRAME_BYTES)
+                    throw new Error(`JADX MCP frame exceeds ${MAX_FRAME_BYTES} bytes`);
+                this.#appendFrame(fragment, frameBytes);
+                if (newline === -1)
+                    return;
+                const line = this.#frameBuffer
+                    .subarray(0, this.#frameLength)
+                    .toString("utf8");
+                this.#frameBuffer = Buffer.alloc(0);
+                this.#frameLength = 0;
+                this.onmessage?.(deserializeMessage(line));
+                offset = newline + 1;
+            }
+        }
+        catch (cause) {
+            this.#fail(cause instanceof Error ? cause : new Error(String(cause)));
+        }
+    };
+    #appendFrame(fragment, frameBytes) {
+        if (frameBytes > this.#frameBuffer.length) {
+            const capacity = Math.min(MAX_FRAME_BYTES, Math.max(frameBytes, this.#frameBuffer.length * 2, 1));
+            const grown = Buffer.allocUnsafe(capacity);
+            this.#frameBuffer.copy(grown, 0, 0, this.#frameLength);
+            this.#frameBuffer = grown;
+        }
+        fragment.copy(this.#frameBuffer, this.#frameLength);
+        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))));
+    }
+}

package/dist/android/JadxProtocol.js

@@ -0,0 +1,109 @@
+import { z } from "zod";
+import { AnalysisOutputError } from "../domain/analysisErrorCore.js";
+import { jsonValueSchema } from "../domain/jsonValue.js";
+const count = z.number().int().nonnegative();
+/** Values observed inside the exact JVM producing the analysis. */
+export const jadxRuntimeSchema = z.object({
+    engine_reported_version: z.string().min(1),
+    max_heap_bytes: z.number().int().positive().safe(),
+    available_processors: z.number().int().positive(),
+    java_version: z.string().min(1),
+    metadata_scope: z.literal("parsed_members"),
+});
+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,
+    };
+};