rea-agents 4.1.0 → 5.0.0

package/dist/generatedPackageMetadata.js

@@ -1,9 +1,9 @@
 /** Generated from package.json and package-lock.json; do not edit. */
 export const PACKAGE_METADATA = {
     name: "rea-agents",
-    version: "4.1.0", // x-release-please-version
+    version: "5.0.0", // x-release-please-version
     serverSdkVersion: "2.3.1",
     clientSdkVersion: "2.3.1",
     coreSdkVersion: "2.3.1",
-    skillVersion: "26",
+    skillVersion: "27",
 };

package/dist/ghidra/GhidraFunctionValues.js

@@ -1,12 +1,12 @@
 import { z } from "zod";
-import { nativeFunctionAnnotationsInputSchema, nativeFunctionAnnotationsSchema, } from "../domain/nativeFunctionAnnotations.js";
-import { nativeDataTypeSchema } from "../domain/nativeDataType.js";
-import { nativeInstructionSchema, nativeCallTargetsSchema, } from "../domain/nativeInstruction.js";
+import { nativeFunctionAnnotationsInputSchema, nativeFunctionAnnotationsSchema, } from "../domain/native/nativeFunctionAnnotations.js";
+import { nativeDataTypeSchema } from "../domain/native/nativeDataType.js";
+import { nativeInstructionSchema, nativeCallTargetsSchema, } from "../domain/native/nativeInstruction.js";
 import { AnalysisInputError, AnalysisOutputError, } from "../domain/analysisErrorCore.js";
 import { functionBodyEntryAgrees, functionInstructionWindowSchema, functionDossierSchema, } from "../domain/hopperValues.js";
 import { jsonObjectSchema, jsonValueSchema, } from "../domain/jsonValue.js";
-import { nativeApiBoundarySchema } from "../domain/nativeApiBoundary.js";
-import { nativeValueFlowSchema } from "../domain/nativeValueFlow.js";
+import { nativeApiBoundarySchema } from "../domain/native/nativeApiBoundary.js";
+import { nativeValueFlowSchema } from "../domain/native/nativeValueFlow.js";
 import { err, ok } from "../domain/result.js";
 import { ghidraIdentifierSchema, ghidraCanonicalAddressSchema, ghidraFunctionClassificationSchema as classification, ghidraFunctionBodySchema as ghidraFunctionBody, ghidraProcedureIdentitySchema as procedureIdentity, } from "./GhidraInventoryValues.js";
 /** Function analysis and annotation operations admitted by the Ghidra adapter. */

package/dist/ghidra/GhidraInstallation.js

@@ -2,10 +2,8 @@ import { spawnSync } from "node:child_process";
 import { constants } from "node:fs";
 import { accessSync, readFileSync } from "node:fs";
 import { posix, win32 } from "node:path";
-/** Exact Ghidra build whose Java bridge contract this REA release supports. */
-export const SUPPORTED_GHIDRA_VERSION = "12.1.4";
-/** Exact JDK major documented by the supported Ghidra release. */
-export const SUPPORTED_GHIDRA_JAVA_MAJOR = 21;
+import { ghidraApplicationProperties, ghidraJavaMajorAccepted, ghidraJavaRangeLabel, ghidraJavaRequirement, ghidraReleaseAccepted, ghidraReleaseCompatibility, ghidraReleaseLine, ghidraVersionDetail, SUPPORTED_GHIDRA_JAVA_MAJOR, SUPPORTED_GHIDRA_VERSION, } from "./GhidraInstallationPolicy.js";
+export { SUPPORTED_GHIDRA_JAVA_MAJOR, SUPPORTED_GHIDRA_VERSION };
 /** Inspect an installation without importing a target or modifying Ghidra. */
 export const inspectGhidraInstallation = (options, host = systemGhidraInstallationHost()) => {
     const platform = options.platform ?? process.platform;
@@ -95,7 +93,7 @@ const installationCoordinates = (options, platform, architecture, host) => {
         nativeDecompilerPath,
         properties: properties === undefined
             ? undefined
-            : { providerVersion: propertyValue(properties, "application.version") },
+            : ghidraApplicationProperties(properties),
         javaCommand,
         java: host.probeJava(javaCommand, ghidraJavaEnvironment(options.javaHome, process.env, platform)),
     };
@@ -106,7 +104,7 @@ const installationChecks = ({ coordinates, platform, architecture, javaHome, hos
         passed: coordinates.installDir !== null,
         code: "not_configured",
         detail: coordinates.installDir ?? "GHIDRA_INSTALL_DIR is not set",
-        remediation: "Set GHIDRA_INSTALL_DIR to an extracted Ghidra 12.1.4 release directory.",
+        remediation: `Set GHIDRA_INSTALL_DIR to an extracted Ghidra ${ghidraReleaseLine()} release directory.`,
     }),
     installationCheck({
         name: "platform",
@@ -133,16 +131,7 @@ const installationChecks = ({ coordinates, platform, architecture, javaHome, hos
             "Ghidra application properties unavailable",
         remediation: "Point GHIDRA_INSTALL_DIR at the root of an extracted official Ghidra release.",
     }),
-    installationCheck({
-        name: "version",
-        passed: coordinates.properties?.providerVersion === SUPPORTED_GHIDRA_VERSION,
-        code: coordinates.properties?.providerVersion === null ||
-            coordinates.properties?.providerVersion === undefined
-            ? "version_unresolved"
-            : "unsupported_version",
-        detail: coordinates.properties?.providerVersion ?? "unknown",
-        remediation: `Install Ghidra ${SUPPORTED_GHIDRA_VERSION}, or update REA for a different Ghidra build.`,
-    }),
+    versionCheck(coordinates.properties),
     installationCheck({
         name: "headless",
         passed: coordinates.analyzeHeadlessPath !== null &&
@@ -161,7 +150,7 @@ const installationChecks = ({ coordinates, platform, architecture, javaHome, hos
                 "matching macOS native decompiler was not found"),
         remediation: "REA does not build native tools. Build Ghidra's native components for this macOS architecture or provide an installation containing Ghidra/Features/Decompiler/os/<platform>/decompile.",
     }),
-    javaCheck(coordinates.java, coordinates.javaCommand, javaHome),
+    javaCheck(coordinates.java, coordinates.javaCommand, javaHome, coordinates.properties),
 ];
 /** Project an installation probe into caller-visible, secret-free diagnostics. */
 export const ghidraInstallationDiagnostics = (inspection) => ({
@@ -212,33 +201,48 @@ const installationCheck = (options) => options.passed
         detail: options.detail,
         remediation: options.remediation,
     };
-const javaCheck = (observation, command, configuredHome) => {
+const versionCheck = (properties) => {
+    const raw = properties?.providerVersion;
+    return installationCheck({
+        name: "version",
+        passed: ghidraReleaseAccepted(raw),
+        code: ghidraReleaseCompatibility(raw).status === "unsupported"
+            ? "unsupported_version"
+            : "version_unresolved",
+        detail: ghidraVersionDetail(raw),
+        remediation: `Install a Ghidra ${ghidraReleaseLine()} release (verified with ${SUPPORTED_GHIDRA_VERSION}), or update REA for another Ghidra line.`,
+    });
+};
+const javaCheck = (observation, command, configuredHome, properties) => {
+    const requirement = ghidraJavaRequirement(properties);
+    const range = ghidraJavaRangeLabel(requirement);
     const supported = observation !== undefined &&
-        observation.major === SUPPORTED_GHIDRA_JAVA_MAJOR &&
+        ghidraJavaMajorAccepted(observation.major, requirement) &&
         observation.bits === 64 &&
         observation.runtime === "jdk";
     const detail = observation === undefined
-        ? command
-        : `${observation.version}; ${String(observation.bits)}-bit; ${observation.runtime === "jdk" ? "JDK" : "runtime only"}; ${observation.home}`;
+        ? requirement.unresolved === null
+            ? command
+            : `${command}; ${requirement.unresolved}`
+        : `${observation.version}; ${String(observation.bits)}-bit; ${observation.runtime === "jdk" ? "JDK" : "runtime only"}; ${observation.home}; accepted ${range}`;
     return installationCheck({
         name: "java",
         passed: supported,
-        code: observation === undefined ? "runtime_missing" : "unsupported_version",
+        code: requirement.unresolved !== null
+            ? "version_unresolved"
+            : observation === undefined
+                ? "runtime_missing"
+                : "unsupported_version",
         detail,
-        remediation: configuredHome === undefined
-            ? "Install a 64-bit JDK 21 or set JAVA_HOME before starting REA."
-            : "Update JAVA_HOME to the root of a 64-bit JDK 21 installation.",
+        remediation: javaRemediation(requirement, configuredHome, range),
     });
 };
-const propertyValue = (content, name) => {
-    for (const line of content.split(/\r?\n/u)) {
-        const separator = line.indexOf("=");
-        if (separator < 0 || line.slice(0, separator).trim() !== name)
-            continue;
-        const value = line.slice(separator + 1).trim();
-        return value.length === 0 ? null : value;
-    }
-    return null;
+const javaRemediation = (requirement, configuredHome, range) => {
+    if (requirement.unresolved !== null)
+        return `The Ghidra installation's Java bounds could not be read (${requirement.unresolved}). Install a 64-bit full JDK inside the declared application.java.min and application.java.max.`;
+    return configuredHome === undefined
+        ? `Install ${range}, or set JAVA_HOME before starting REA.`
+        : `Update JAVA_HOME to the root of ${range} installation.`;
 };
 const systemGhidraInstallationHost = () => ({
     readText(path) {

package/dist/ghidra/GhidraInstallationPolicy.js

@@ -0,0 +1,140 @@
+/** Ghidra build whose bridge behavior this REA release verifies. */
+export const SUPPORTED_GHIDRA_VERSION = "12.1.4";
+/**
+ * JDK major used when an installation omits `application.java.min`.
+ * Admission uses that installation's `application.java.min` and
+ * `application.java.max`. An empty maximum means the release sets no upper bound.
+ */
+export const SUPPORTED_GHIDRA_JAVA_MAJOR = 21;
+const GHIDRA_RELEASE_PATTERN = /^(\d+)\.(\d+)(?:\.(\d+))?([-+].*)?$/u;
+const JAVA_MAJOR_PATTERN = /^(\d+)(?:\.\d+)*$/u;
+/** Read the version and Java bounds Ghidra publishes for one installation. */
+export const ghidraApplicationProperties = (content) => ({
+    providerVersion: propertyValue(content, "application.version"),
+    javaMinimum: parseJavaBound(propertyValue(content, "application.java.min")),
+    javaMaximum: parseJavaBound(propertyValue(content, "application.java.max")),
+});
+/** Classify `application.version` against the verified release line. */
+export const ghidraReleaseCompatibility = (raw) => {
+    if (raw === null || raw === undefined)
+        return { status: "unresolved", raw: null };
+    const version = parseGhidraRelease(raw);
+    if (version === undefined)
+        return { status: "unresolved", raw };
+    if (raw === SUPPORTED_GHIDRA_VERSION)
+        return { status: "verified", version, raw };
+    const verified = verifiedGhidraRelease();
+    return version.major === verified.major && version.minor === verified.minor
+        ? { status: "compatible", version, raw }
+        : { status: "unsupported", version, raw };
+};
+/**
+ * Limitation recorded when a session runs a compatible build other than the
+ * verified release. The observed version stays on the provider identity.
+ */
+export const unverifiedGhidraBuildLimitation = (providerVersion) => {
+    const compatibility = ghidraReleaseCompatibility(providerVersion);
+    if (compatibility.status !== "compatible")
+        return undefined;
+    return `This session uses Ghidra ${providerVersion}. The bridge is verified against ${SUPPORTED_GHIDRA_VERSION}; other ${ghidraReleaseLine()} builds are accepted and the observed version is reported.`;
+};
+/** Release line accepted by this bridge, such as `12.1.x`. */
+export const ghidraReleaseLine = () => {
+    const verified = verifiedGhidraRelease();
+    return `${String(verified.major)}.${String(verified.minor)}.x`;
+};
+/** Detail for the installation version check, including the accepted line. */
+export const ghidraVersionDetail = (raw) => {
+    const compatibility = ghidraReleaseCompatibility(raw);
+    switch (compatibility.status) {
+        case "unresolved":
+            return compatibility.raw ?? "unknown";
+        case "verified":
+            return compatibility.raw;
+        case "compatible":
+            return `${compatibility.raw}; compatible ${ghidraReleaseLine()} release (verified build ${SUPPORTED_GHIDRA_VERSION})`;
+        case "unsupported":
+            return `${compatibility.raw}; accepted releases are ${ghidraReleaseLine()} (verified build ${SUPPORTED_GHIDRA_VERSION})`;
+        default: {
+            const unreachable = compatibility;
+            return unreachable;
+        }
+    }
+};
+/** Whether this release line can run the packaged bridge. */
+export const ghidraReleaseAccepted = (raw) => {
+    const status = ghidraReleaseCompatibility(raw).status;
+    return status === "verified" || status === "compatible";
+};
+/** Resolve JDK majors from `application.java.min` and `application.java.max`. */
+export const ghidraJavaRequirement = (properties) => {
+    const minimum = properties?.javaMinimum ?? { status: "absent" };
+    const maximum = properties?.javaMaximum ?? { status: "absent" };
+    if (minimum.status === "unresolved")
+        return unresolvedJavaRequirement(`application.java.min=${minimum.raw}`);
+    if (maximum.status === "unresolved")
+        return unresolvedJavaRequirement(`application.java.max=${maximum.raw}`);
+    const minimumMajor = minimum.status === "major" ? minimum.major : SUPPORTED_GHIDRA_JAVA_MAJOR;
+    const maximumMajor = maximum.status === "major" ? maximum.major : null;
+    if (maximumMajor !== null && maximumMajor < minimumMajor)
+        return unresolvedJavaRequirement(`application.java.max=${String(maximumMajor)} is below application.java.min=${String(minimumMajor)}`);
+    return { minimumMajor, maximumMajor, unresolved: null };
+};
+/** Caller-facing description of one resolved or unreadable JDK range. */
+export const ghidraJavaRangeLabel = (requirement) => {
+    if (requirement.unresolved !== null)
+        return "a 64-bit full JDK matching the installation's declared Java bounds";
+    if (requirement.maximumMajor === null)
+        return `a 64-bit full JDK ${String(requirement.minimumMajor)} or newer`;
+    if (requirement.maximumMajor === requirement.minimumMajor)
+        return `a 64-bit full JDK ${String(requirement.minimumMajor)}`;
+    return `a 64-bit full JDK ${String(requirement.minimumMajor)} through ${String(requirement.maximumMajor)}`;
+};
+/** Whether an observed JDK satisfies the installation's declared range. */
+export const ghidraJavaMajorAccepted = (major, requirement) => requirement.unresolved === null &&
+    major >= requirement.minimumMajor &&
+    (requirement.maximumMajor === null || major <= requirement.maximumMajor);
+const verifiedGhidraRelease = () => {
+    const version = parseGhidraRelease(SUPPORTED_GHIDRA_VERSION);
+    if (version === undefined)
+        throw new TypeError(`SUPPORTED_GHIDRA_VERSION ${SUPPORTED_GHIDRA_VERSION} is not a Ghidra release`);
+    return version;
+};
+const parseGhidraRelease = (raw) => {
+    const match = GHIDRA_RELEASE_PATTERN.exec(raw);
+    const major = integerGroup(match?.[1]);
+    const minor = integerGroup(match?.[2]);
+    if (match === null || major === undefined || minor === undefined)
+        return undefined;
+    const patch = match[3] === undefined ? 0 : integerGroup(match[3]);
+    return patch === undefined ? undefined : { major, minor, patch };
+};
+const parseJavaBound = (raw) => {
+    if (raw === null)
+        return { status: "absent" };
+    const major = integerGroup(JAVA_MAJOR_PATTERN.exec(raw)?.[1]);
+    return major === undefined
+        ? { status: "unresolved", raw }
+        : { status: "major", major };
+};
+const integerGroup = (value) => {
+    if (value === undefined)
+        return undefined;
+    const parsed = Number(value);
+    return Number.isSafeInteger(parsed) ? parsed : undefined;
+};
+const unresolvedJavaRequirement = (unresolved) => ({
+    minimumMajor: SUPPORTED_GHIDRA_JAVA_MAJOR,
+    maximumMajor: null,
+    unresolved,
+});
+const propertyValue = (content, name) => {
+    for (const line of content.split(/\r?\n/u)) {
+        const separator = line.indexOf("=");
+        if (separator < 0 || line.slice(0, separator).trim() !== name)
+            continue;
+        const value = line.slice(separator + 1).trim();
+        return value.length === 0 ? null : value;
+    }
+    return null;
+};

package/dist/ghidra/GhidraInventoryValues.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { nativeLoadImageObservationSchema } from "../domain/nativeLoadImage.js";
+import { nativeLoadImageObservationSchema } from "../domain/native/nativeLoadImage.js";
 import { AnalysisInputError, AnalysisOutputError, } from "../domain/analysisErrorCore.js";
 import { functionBodySchema, functionBodyEntryAgrees, } from "../domain/hopperValues.js";
 import { jsonValueSchema } from "../domain/jsonValue.js";

package/dist/ghidra/GhidraLauncher.js

@@ -75,7 +75,7 @@ export class GhidraHeadlessLauncher {
                 expectedCommand: null,
                 windowsVerbatimArguments: platform === "win32",
                 platform,
-                env: ghidraLaunchEnvironment(paths, this.options.javaHome, platform),
+                env: ghidraLaunchEnvironment(paths, this.options.javaHome, platform, command.command),
             });
             await writeGhidraRuntimeFile(paths.ownershipPath, `${JSON.stringify({
                 run_id: session.runId,
@@ -190,10 +190,15 @@ export const ghidraHeadlessArguments = (options) => [
     "-scriptPath",
     dirname(options.bridgeScriptPath),
     ...(options.dosCom === true
-        ? ["-preScript", "ReaGhidraPrepareCom.java"]
+        ? [
+            "-preScript",
+            join(dirname(options.bridgeScriptPath), "ReaGhidraPrepareCom.java"),
+        ]
         : []),
     "-postScript",
-    basename(options.bridgeScriptPath),
+    // Ghidra checks the caller's cwd before scriptPath for a basename. Select
+    // the packaged source explicitly so unrelated entries cannot shadow it.
+    options.bridgeScriptPath,
     options.descriptorPath,
 ];
 const ghidraRuntimePaths = (runtimeRoot) => ({
@@ -238,7 +243,7 @@ const writeGhidraRuntimeFile = async (path, content, platform) => {
     }
     await writeFileAtomic(path, content, { encoding: "utf8", mode: 0o600 });
 };
-const ghidraLaunchEnvironment = (paths, javaHome, platform) => {
+const ghidraLaunchEnvironment = (paths, javaHome, platform, executable) => {
     return {
         ...ghidraJavaEnvironment(javaHome, process.env, platform),
         ...ghidraHeadlessJavaOptions(paths.homeRoot, paths.tempRoot, platform),
@@ -246,6 +251,9 @@ const ghidraLaunchEnvironment = (paths, javaHome, platform) => {
         TMPDIR: paths.tempRoot,
         ...(platform === "win32"
             ? {
+                // Batch FOR /F launches another command interpreter through ComSpec.
+                // Use the same executable with the spelling consumed by cmd.exe.
+                ComSpec: executable.replaceAll("/", "\\"),
                 USERPROFILE: paths.homeRoot,
                 APPDATA: paths.configRoot,
                 LOCALAPPDATA: paths.cacheRoot,

package/dist/ghidra/GhidraLoadImageAttest.js

@@ -0,0 +1,36 @@
+import { jsonValueSchema } from "../domain/jsonValue.js";
+import { nativeLoadImageObservationSchema, nativeLoadImageSchema, } from "../domain/native/nativeLoadImage.js";
+import { ProviderAdapterError } from "../domain/providerAdapterError.js";
+import { err, ok } from "../domain/result.js";
+import { attestGhidraDosComLoadImage, attestGhidraDosLoadImage, } from "./GhidraLoadImageValues.js";
+/** Independently verify measured load-image observations for admitted DOS targets. */
+export const attestGhidraNativeLoadImage = async (target, operation, measured, client, mapSessionError) => {
+    const observations = nativeLoadImageObservationSchema.parse(measured);
+    if (target.format !== "dos-mz" && target.format !== "dos-com") {
+        return ok(jsonValueSchema.parse(nativeLoadImageSchema.parse({
+            status: "unsupported",
+            reason: "Independent load-image verification currently supports DOS MZ and explicit DOS COM targets only.",
+            observations,
+            limitations: [
+                "Other formats expose measured mappings and source identities; no format-specific verification was performed.",
+            ],
+        })));
+    }
+    if (client.readTargetSnapshot === undefined)
+        return err(new ProviderAdapterError("ghidra", operation, {
+            diagnostics: {
+                reason: "The Ghidra client does not expose its immutable target snapshot for independent load-image verification.",
+            },
+        }));
+    const snapshot = await client.readTargetSnapshot();
+    if (!snapshot.ok)
+        return err(mapSessionError(snapshot.error));
+    const attested = (target.format === "dos-com"
+        ? attestGhidraDosComLoadImage
+        : attestGhidraDosLoadImage)(snapshot.value, target.sha256 ?? "", observations);
+    if (!attested.ok)
+        return err(new ProviderAdapterError("ghidra", operation, {
+            diagnostics: { reason: attested.error },
+        }));
+    return ok(jsonValueSchema.parse(attested.value));
+};

package/dist/ghidra/GhidraLoadImageValues.js

@@ -1,5 +1,5 @@
 import { createHash } from "node:crypto";
-import { nativeLoadImageSchema, } from "../domain/nativeLoadImage.js";
+import { nativeLoadImageSchema, } from "../domain/native/nativeLoadImage.js";
 import { parseDosMzHeader } from "../domain/dosMz.js";
 import { validateDosComLength } from "../domain/dosCom.js";
 import { err, ok } from "../domain/result.js";