rea-agents 6.1.0 → 6.3.0

package/dist/android/JadxSession.js

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

package/dist/application/BinaryTargetResolver.js

@@ -1,8 +1,10 @@
 import { constants } from "node:fs";
 import { createHash } from "node:crypto";
-import { access, open, realpath, stat, } from "node:fs/promises";
+import { access, lstat, realpath, stat, } from "node:fs/promises";
 import { extname, isAbsolute, resolve } from "node:path";
 import { BinaryTargetError } from "../domain/configurationErrors.js";
+import { openRegularFile, sameRegularFileState, } from "../filesystem/RegularFile.js";
+import { AnalysisCancelledError } from "../domain/analysisErrorCore.js";
 import { err, ok } from "../domain/result.js";
 import { resolveAppBundleExecutable, } from "./AppBundleExecutable.js";
 import { validateDosComLength, } from "../domain/dosCom.js";
@@ -14,30 +16,41 @@ import { parseExecutableHeader, parsePeRecord, } from "../domain/binaryTarget.js
  * FAT Mach-O inputs select only a host-compatible architecture so setup remains
  * non-interactive; unsupported or ambiguous inputs are returned as typed errors.
  */
-export const parseBinaryTarget = async (input, cwd = process.cwd(), hostArchitecture = process.arch, targetKind, formatHint) => {
+export const parseBinaryTarget = async (input, options = {}) => {
+    const cwd = options.cwd ?? process.cwd();
+    const hostArchitecture = options.hostArchitecture ?? process.arch;
+    const { targetKind, formatHint, signal } = options;
     const candidate = isAbsolute(input) ? input : resolve(cwd, input);
     try {
+        throwIfTargetResolutionCancelled(signal);
         await access(candidate, constants.R_OK);
+        throwIfTargetResolutionCancelled(signal);
         const canonical = await realpath(candidate);
+        throwIfTargetResolutionCancelled(signal);
         const resolved = await resolveAppBundle(canonical);
+        throwIfTargetResolutionCancelled(signal);
         if (!resolved.ok)
             return err(resolved.error);
         const { executable: path, infoPlist } = resolved.value;
         const bundle = infoPlist === undefined ? {} : { bundleInfoPlist: infoPlist };
-        const handle = await open(path, "r");
+        const handle = await openRegularFile(path, {
+            symlinks: "reject",
+            signal,
+        });
         try {
-            if (!(await handle.stat()).isFile())
-                return err(new BinaryTargetError(path, "target is not a regular file"));
+            throwIfTargetResolutionCancelled(signal);
+            const metadata = await handle.stat();
+            throwIfTargetResolutionCancelled(signal);
             if (formatHint === "dos-com") {
                 if (targetKind !== undefined && targetKind !== "executable")
                     return err(new BinaryTargetError(path, "DOS COM format requires an executable target kind"));
-                const length = validateDosComLength((await handle.stat()).size);
+                const length = validateDosComLength(metadata.size);
                 if (!length.ok)
                     return err(new BinaryTargetError(path, length.error));
                 return ok({
                     path,
                     sourcePath: canonical,
-                    sha256: await sha256Handle(handle),
+                    sha256: await sha256Handle(handle, path, metadata, signal),
                     kind: "executable",
                     format: "dos-com",
                     architecture: "x86",
@@ -49,29 +62,29 @@ export const parseBinaryTarget = async (input, cwd = process.cwd(), hostArchitec
                 return ok({
                     path,
                     sourcePath: process.platform === "win32" ? candidate : canonical,
-                    sha256: await sha256Handle(handle),
+                    sha256: await sha256Handle(handle, path, metadata, signal),
                     kind: "database",
                     format: "analysis-database",
                 });
-            const artifactFormat = await detectArtifactFormat(path, handle);
+            const artifactFormat = await detectArtifactFormat(path, handle, signal);
             if (artifactFormat !== undefined) {
                 const identity = {
                     path,
                     sourcePath: process.platform === "win32" ? candidate : canonical,
-                    sha256: await sha256Handle(handle),
+                    sha256: await sha256Handle(handle, path, metadata, signal),
                 };
                 return isArchiveFormat(artifactFormat)
                     ? ok({ ...identity, kind: "archive", format: artifactFormat })
                     : ok({ ...identity, kind: "artifact", format: artifactFormat });
             }
-            const detected = await readExecutableMetadata(handle, hostArchitecture);
+            const detected = await readExecutableMetadata(handle, hostArchitecture, signal);
             if (!detected.ok)
                 return err(new BinaryTargetError(path, detected.error));
             return ok({
                 path,
                 sourcePath: process.platform === "win32" ? candidate : canonical,
                 ...bundle,
-                sha256: await sha256Handle(handle),
+                sha256: await sha256Handle(handle, path, metadata, signal),
                 kind: "executable",
                 ...detected.value,
             });
@@ -81,6 +94,10 @@ export const parseBinaryTarget = async (input, cwd = process.cwd(), hostArchitec
         }
     }
     catch (cause) {
+        if (cause instanceof AnalysisCancelledError)
+            return err(cause);
+        if (cause instanceof BinaryTargetError)
+            return err(cause);
         if (!(cause instanceof Error))
             throw cause;
         const code = filesystemErrorCode(cause);
@@ -103,14 +120,24 @@ const targetFailureReason = (code, detail) => {
             return `permission denied while reading target: ${detail}`;
         case "EISDIR":
             return `target is a directory, not a readable file: ${detail}`;
+        case "ENOTFILE":
+            return "target is not a regular file";
+        case "ELOOP":
+            return `target changed while being opened: ${detail}`;
         default:
             return `target could not be read (${code}): ${detail}`;
     }
 };
-const detectArtifactFormat = async (path, handle) => {
+const throwIfTargetResolutionCancelled = (signal) => {
+    if (signal?.aborted === true)
+        throw new AnalysisCancelledError("resolve_binary_target");
+};
+const detectArtifactFormat = async (path, handle, signal) => {
+    throwIfTargetResolutionCancelled(signal);
     const lower = path.toLowerCase();
     const magic = Buffer.alloc(8);
     const observed = await handle.read(magic, 0, magic.length, 0);
+    throwIfTargetResolutionCancelled(signal);
     if (hasZipSignature(magic.subarray(0, observed.bytesRead))) {
         return zipPackageFormatForPath(lower) ?? "zip";
     }
@@ -122,10 +149,13 @@ const detectArtifactFormat = async (path, handle) => {
         magic.subarray(0, 4).toString("ascii") === "xar!")
         return "pkg";
     if (lower.endsWith(".dmg")) {
+        throwIfTargetResolutionCancelled(signal);
         const size = (await handle.stat()).size;
+        throwIfTargetResolutionCancelled(signal);
         if (size >= 512) {
             const trailer = Buffer.alloc(4);
             const read = await handle.read(trailer, 0, trailer.length, size - 512);
+            throwIfTargetResolutionCancelled(signal);
             if (read.bytesRead === 4 && trailer.toString("ascii") === "koly")
                 return "dmg";
         }
@@ -142,17 +172,25 @@ const namedArtifactFormat = (lowerPath) => {
     return /\.(?:m?js|cjs)$/u.test(lowerPath) ? "javascript" : undefined;
 };
 const isArchiveFormat = (format) => ["zip", "ipa", "apk", "msix", "appx", "asar", "dmg", "pkg"].includes(format);
-const sha256Handle = async (handle) => {
+const sha256Handle = async (handle, path, initial, signal) => {
     const hash = createHash("sha256");
     const chunk = Buffer.allocUnsafe(64 * 1024);
     let position = 0;
     while (true) {
+        throwIfTargetResolutionCancelled(signal);
         const observed = await handle.read(chunk, 0, chunk.length, position);
+        throwIfTargetResolutionCancelled(signal);
         if (observed.bytesRead === 0)
             break;
         hash.update(chunk.subarray(0, observed.bytesRead));
         position += observed.bytesRead;
     }
+    throwIfTargetResolutionCancelled(signal);
+    const [opened, currentPath] = await Promise.all([handle.stat(), lstat(path)]);
+    if (!sameRegularFileState(initial, opened) ||
+        !sameRegularFileState(initial, currentPath) ||
+        position !== initial.size)
+        throw new BinaryTargetError(path, "target changed while being read");
     return hash.digest("hex");
 };
 const resolveAppBundle = async (path) => {
@@ -165,16 +203,22 @@ const resolveAppBundle = async (path) => {
         }));
     return resolveAppBundleExecutable(path);
 };
-const readExecutableMetadata = async (handle, hostArchitecture) => {
+const readExecutableMetadata = async (handle, hostArchitecture, signal) => {
+    throwIfTargetResolutionCancelled(signal);
     const prefix = Buffer.alloc(4096);
     const prefixRead = await handle.read(prefix, 0, prefix.length, 0);
+    throwIfTargetResolutionCancelled(signal);
     const bytes = prefix.subarray(0, prefixRead.bytesRead);
+    // Header commitments such as Mach-O load commands and FAT slices are
+    // checked against the whole file, not the probed prefix.
+    const fileSize = (await handle.stat()).size;
+    throwIfTargetResolutionCancelled(signal);
     if (bytes.length >= 2 && bytes[0] === 0x4d && bytes[1] === 0x5a) {
         const offset = mzWindowsHeaderOffset(bytes);
         if (offset !== null) {
             if (offset < 64)
                 return err("invalid Windows new-header offset in MZ image");
-            return readPeMetadata(handle, offset);
+            return readPeMetadata(handle, offset, signal);
         }
         // MZ relocation records may extend past the initial probe; their format
         // bounds are at most 65535 records inside a 65535-paragraph header.
@@ -182,12 +226,12 @@ const readExecutableMetadata = async (handle, hostArchitecture) => {
             ? bytes.readUInt16LE(24) + bytes.readUInt16LE(6) * 4
             : 0;
         const headerBytes = bytes.length >= 28 ? bytes.readUInt16LE(8) * 16 : 0;
-        const fileSize = (await handle.stat()).size;
         if (tableEnd > bytes.length &&
             tableEnd <= headerBytes &&
             tableEnd <= fileSize) {
             const table = Buffer.alloc(tableEnd);
             const observed = await handle.read(table, 0, table.length, 0);
+            throwIfTargetResolutionCancelled(signal);
             return parseExecutableHeader(table.subarray(0, observed.bytesRead), hostArchitecture, fileSize);
         }
         return parseExecutableHeader(bytes, hostArchitecture, fileSize);
@@ -201,15 +245,18 @@ const readExecutableMetadata = async (handle, hostArchitecture) => {
             if (count <= 128 && required > bytes.length) {
                 const header = Buffer.alloc(required);
                 const headerRead = await handle.read(header, 0, header.length, 0);
-                return parseExecutableHeader(header.subarray(0, headerRead.bytesRead), hostArchitecture);
+                throwIfTargetResolutionCancelled(signal);
+                return parseExecutableHeader(header.subarray(0, headerRead.bytesRead), hostArchitecture, fileSize);
             }
         }
     }
-    return parseExecutableHeader(bytes, hostArchitecture);
+    return parseExecutableHeader(bytes, hostArchitecture, fileSize);
 };
-const readPeMetadata = async (handle, offset) => {
+const readPeMetadata = async (handle, offset, signal) => {
+    throwIfTargetResolutionCancelled(signal);
     const fileHeader = Buffer.alloc(24);
     const fileHeaderRead = await handle.read(fileHeader, 0, fileHeader.length, offset);
+    throwIfTargetResolutionCancelled(signal);
     if (fileHeaderRead.bytesRead !== fileHeader.length)
         return err("invalid or truncated PE header");
     const signature = fileHeader.toString("ascii", 0, 2);
@@ -220,6 +267,7 @@ const readPeMetadata = async (handle, offset) => {
         return err("invalid PE optional header size");
     const record = Buffer.alloc(24 + optionalHeaderSize);
     const recordRead = await handle.read(record, 0, record.length, offset);
+    throwIfTargetResolutionCancelled(signal);
     return recordRead.bytesRead === record.length
         ? parsePeRecord(record)
         : err("invalid or truncated PE header");

package/dist/application/BrowserEvidence.js

@@ -27,21 +27,16 @@ export const createBrowserEvidence = (operation, input, result, provider) => cre
 });
 const browserParameters = (input, result) => {
     if (!("cdp_endpoint" in input)) {
-        if ("before_scenario" in input &&
-            input.before_scenario !== undefined &&
-            input.after_scenario !== undefined)
+        if ("before_scenario" in input)
             return {
                 comparison_kind: "browser_scenario",
                 before_browser: input.before_scenario.browser,
                 after_browser: input.after_scenario.browser,
                 before_start_origin: input.before_scenario.scenario.start_origin,
                 after_start_origin: input.after_scenario.scenario.start_origin,
-                normalization_sha256: commitBrowserScenarioNormalization(input.normalization ?? { rules: [] }).sha256,
+                normalization_sha256: commitBrowserScenarioNormalization(input.normalization).sha256,
             };
-        if (input.before !== undefined &&
-            input.after !== undefined &&
-            "inspection" in input.before &&
-            "inspection" in input.after)
+        if ("inspection" in input.before && "inspection" in input.after)
             return {
                 before_target_id: input.before.inspection.target.target_id,
                 before_capture_ended_at: input.before.inspection.capture_window.ended_at,

package/dist/application/BrowserScenarioEvidence.js

@@ -1,25 +1,9 @@
-import { canonicalDigest } from "../domain/comparisonSemantics.js";
-import { sanitizeBrowserUrl } from "../domain/browserObservation.js";
+import { digestCanonicalValue } from "../domain/canonicalDigest.js";
 import { createEvidence, } from "../domain/evidence.js";
-import { jsonValueSchema } from "../domain/jsonValue.js";
+import { jsonObjectSchema, jsonValueSchema } from "../domain/jsonValue.js";
 const browserScenarioParameters = (scenario) => ({
-    scenario_sha256: canonicalDigest(scenario, "Browser scenario"),
-    browser_mode: scenario.browser.mode,
-    ...(scenario.browser.mode === "launch"
-        ? { browser_headless: scenario.browser.headless }
-        : {}),
-    start_url: sanitizeBrowserUrl(scenario.start_url.url),
-    environment: scenario.environment,
-    actions: scenario.actions.map(({ step_id, action }) => ({
-        step_id,
-        action,
-    })),
-    action_timeouts_ms: scenario.actions.map((item) => "timeout_ms" in item ? (item.timeout_ms ?? null) : null),
-    secret_declarations: scenario.secrets.map(({ secret_id, environment_variable }) => ({
-        secret_id,
-        environment_variable,
-    })),
-    capture: scenario.capture,
+    ...jsonObjectSchema.parse(scenario),
+    scenario_sha256: digestCanonicalValue(scenario, "Browser scenario"),
 });
 /** Create Evidence without retaining resolved scenario secret values. */
 export const createBrowserScenarioEvidence = (scenario, capture, provider) => createEvidence(undefined, provider, {

package/dist/application/CapabilityInventory.js

@@ -37,6 +37,21 @@ const ENHANCED_REQUIREMENTS = {
         "resolve_containing_procedure",
     ],
 };
+/** Contract kinds whose operations run on the active session target. */
+const ACTIVE_TARGET_KINDS = new Set([
+    "official-proxy",
+    "enhanced",
+    "native-provider",
+    "artifact-provider",
+]);
+/** Native contracts defined only for an active Mach-O executable. */
+const MACHO_TARGET_OPERATIONS = new Set([
+    "inspect_macho",
+    "list_architectures",
+    "observe_native_calls",
+    "observe_native_ui",
+    "capture_native_ui_scenario",
+]);
 const NAVIGATION_CONTEXT_MODES = [
     {
         name: "current_selection",
@@ -61,6 +76,7 @@ export const buildCapabilityInventory = (sessionStatus, policy, clientFeatures =
             kind: contract.kind,
             targetOpen: status.open,
             targetKind: status.kind,
+            targetFormat: status.format,
             descriptors,
             policy,
         });
@@ -125,6 +141,9 @@ const availabilityFor = (context) => {
     const workflowAvailability = workflowAvailabilityFor(context);
     if (workflowAvailability !== null)
         return workflowAvailability;
+    const hostDecision = hostAvailability(context);
+    if (hostDecision !== null)
+        return hostDecision;
     const targetDecision = targetAvailability(context);
     if (targetDecision !== null)
         return targetDecision;
@@ -226,7 +245,7 @@ const workflowAvailabilityFor = ({ name, kind, policy, }) => {
                     ? "unsupported_host"
                     : "provider_missing",
                 remediation: policy.androidAnalysisAvailability?.reason ??
-                    "Set REA_JADX_MCP_JAR to a caller-supplied jadx-headless-mcp 0.7.1 JAR and provide a full JDK on Linux or macOS.",
+                    "Set REA_JADX_MCP_JAR to a caller-supplied jadx-headless-mcp 0.7.1 JAR and provide a full JDK on Linux, macOS, or Windows x64 with its matching bundled native controls.",
             };
     const browser = browserProviderAvailability(name, kind, policy);
     if (browser !== null)
@@ -286,8 +305,22 @@ const browserProviderAvailability = (name, kind, policy) => {
             remediation: "Start REA with its browser observation provider available.",
         };
 };
-const targetAvailability = ({ kind, targetKind, targetOpen, }) => {
-    if (!targetOpen && (kind === "official-proxy" || kind === "enhanced"))
+/**
+ * Opening another target cannot make an operation run on an unsupported host.
+ * Composed operations are decided by their requirements, which another
+ * provider may satisfy.
+ */
+const hostAvailability = ({ descriptors, kind, name, }) => {
+    if (kind === "enhanced")
+        return null;
+    const descriptor = descriptors.get(name);
+    return descriptor?.available === false &&
+        descriptor.availability_code === "unsupported_host"
+        ? { reason: "unsupported_host", remediation: descriptor.reason }
+        : null;
+};
+const targetAvailability = ({ name, kind, targetKind, targetFormat, targetOpen, }) => {
+    if (!targetOpen && ACTIVE_TARGET_KINDS.has(kind))
         return {
             reason: "target_required",
             remediation: "Call open_binary with a supported local target.",
@@ -300,6 +333,13 @@ const targetAvailability = ({ kind, targetKind, targetOpen, }) => {
             reason: "target_unsupported",
             remediation: "Inventory or extract a native executable, then call open_binary on that executable.",
         };
+    if (targetOpen &&
+        MACHO_TARGET_OPERATIONS.has(name) &&
+        (targetKind !== "executable" || targetFormat !== "mach-o"))
+        return {
+            reason: "target_unsupported",
+            remediation: "Call open_binary with a Mach-O executable or an app bundle whose main executable is Mach-O.",
+        };
     return null;
 };
 const providerAvailability = ({ descriptors, kind, name, }) => {
@@ -316,12 +356,6 @@ const providerAvailability = ({ descriptors, kind, name, }) => {
             reason: "provider_missing",
             remediation: "Install or configure a provider that declares this operation.",
         };
-    if (!descriptor.available &&
-        descriptor.availability_code === "unsupported_host")
-        return {
-            reason: "unsupported_host",
-            remediation: descriptor.reason,
-        };
     return descriptor.available
         ? { reason: "available", remediation: null }
         : {