rea-agents 6.5.0 → 6.7.0

package/dist/ghidra/GhidraPspExtension.js

@@ -2,10 +2,15 @@ import { createHash } from "node:crypto";
 import { lstat, opendir, realpath } from "node:fs/promises";
 import { isAbsolute, join } from "node:path";
 import { z } from "zod";
-import { openRegularFile, sameRegularFileState, } from "../filesystem/RegularFile.js";
+import { sameRegularFileState } from "../filesystem/RegularFile.js";
 import { AnalysisCancelledError, AnalysisCapabilityUnavailableError, } from "../domain/analysisErrorCore.js";
+import { AnalysisError } from "../domain/analysisErrorBase.js";
 import { err, ok } from "../domain/result.js";
 import { parseGhidraJavaProperties } from "./GhidraJavaProperties.js";
+import { ArtifactReaderFailure } from "../artifacts/ArtifactReader.js";
+import { AnalysisCleanupLease } from "../artifacts/AnalysisCleanupLease.js";
+import { OwnedDirectoryHandle } from "../filesystem/OwnedDirectoryHandle.js";
+import { assertArtifactReadActive, artifactFileCancellationCause, artifactFilePrimaryFailure, bindArtifactFileCleanup, withArtifactRegularFile, } from "../artifacts/ArtifactFileOperation.js";
 /** Installed processor code and data, distinct from REA's analysis-extension ABI. */
 export const ghidraPspExtensionSchema = z.strictObject({
     id: z.literal("ghidra-allegrex"),
@@ -26,26 +31,29 @@ const REQUIRED = [
     "data/languages/allegrex.cspec",
 ];
 /** Read-only fingerprint of all installed files; no home scanning or installation. */
-export const inspectGhidraPspExtension = async (root, ghidraVersion, signal) => {
-    signal?.throwIfAborted();
+export const inspectGhidraPspExtension = async (root, ghidraVersion, resources, signal) => {
+    try {
+        return await resources.run(() => fingerprint(root, ghidraVersion, resources, signal));
+    }
+    catch (cause) {
+        throw ghidraPspInspectionError(cause);
+    }
+};
+const fingerprint = async (root, ghidraVersion, resources, signal) => {
+    assertArtifactReadActive(signal);
     if (!isAbsolute(root) || (await realpath(root)) !== root)
         throw new Error("The installed Allegrex directory must be a canonical non-symlink path.");
     const files = [];
     let entries = 1; // The root itself consumes one inventory entry.
     const visit = async (relative, depth) => {
-        signal?.throwIfAborted();
+        assertArtifactReadActive(signal);
         if (depth > MAX_DEPTH)
             throw new Error("Allegrex extension directory nesting exceeds the inspection limit.");
         const path = join(root, relative);
         const metadata = await lstat(path);
         if (metadata.isDirectory()) {
-            const children = [];
-            for await (const child of await opendir(path)) {
-                signal?.throwIfAborted();
-                if (++entries > MAX_ENTRIES)
-                    throw new Error("Allegrex extension inventory exceeds the inspection limit.");
-                children.push(child.name);
-            }
+            const children = await readChildren(path, MAX_ENTRIES - entries, resources, signal);
+            entries += children.length;
             children.sort();
             for (const child of children)
                 await visit(relative === "" ? child : `${relative}/${child}`, depth + 1);
@@ -66,10 +74,9 @@ export const inspectGhidraPspExtension = async (root, ghidraVersion, signal) =>
     let bytesRead = 0;
     let properties = Buffer.alloc(0);
     for (const relative of files) {
-        signal?.throwIfAborted();
+        assertArtifactReadActive(signal);
         const path = join(root, relative);
-        const handle = await openRegularFile(path, { symlinks: "reject", signal });
-        try {
+        await withArtifactRegularFile(path, resources, signal, async (handle) => {
             const before = await handle.stat();
             if (!Number.isSafeInteger(before.size) ||
                 before.size > MAX_BYTES - bytesRead)
@@ -80,27 +87,31 @@ export const inspectGhidraPspExtension = async (root, ghidraVersion, signal) =>
             const buffer = Buffer.alloc(Math.min(65536, before.size + 1));
             let offset = 0;
             const chunks = [];
-            while (offset < before.size) {
-                signal?.throwIfAborted();
-                const read = await handle.read(buffer, 0, Math.min(buffer.length, before.size - offset), offset);
-                if (read.bytesRead === 0)
-                    throw new Error(`Truncated Allegrex component: ${relative}`);
-                const chunk = buffer.subarray(0, read.bytesRead);
+            // Serial reads keep final close behind every native read. One extra byte
+            // detects growth without a stream's read-ahead or unbounded allocation.
+            while (offset <= before.size) {
+                assertArtifactReadActive(signal);
+                const { bytesRead } = await handle.read(buffer, 0, Math.min(buffer.length, before.size - offset + 1), offset);
+                assertArtifactReadActive(signal);
+                if (bytesRead === 0)
+                    break;
+                offset += bytesRead;
+                if (offset > before.size)
+                    throw new Error(`Allegrex component changed during inspection: ${relative}`);
+                const chunk = buffer.subarray(0, bytesRead);
                 hash.update(chunk);
                 if (relative === "extension.properties")
                     chunks.push(Buffer.from(chunk));
-                offset += read.bytesRead;
             }
+            if (offset !== before.size)
+                throw new Error(`Truncated Allegrex component: ${relative}`);
             if (!sameRegularFileState(before, await handle.stat()) ||
                 !sameRegularFileState(before, await lstat(path)))
                 throw new Error(`Allegrex component changed during inspection: ${relative}`);
             bytesRead += before.size;
             if (relative === "extension.properties")
                 properties = Buffer.concat(chunks);
-        }
-        finally {
-            await handle.close();
-        }
+        });
     }
     // Ghidra's extension.properties version is the compatible Ghidra version,
     // not the extension release (e.g. v21.4); content identity supplies the latter.
@@ -111,7 +122,7 @@ export const inspectGhidraPspExtension = async (root, ghidraVersion, signal) =>
     if (property("name") !== "ghidra-allegrex" ||
         property("version") !== ghidraVersion)
         throw new Error(`Allegrex extension metadata does not match the selected Ghidra ${ghidraVersion}; install or rebuild a compatible extension.`);
-    signal?.throwIfAborted();
+    assertArtifactReadActive(signal);
     return {
         id: "ghidra-allegrex",
         root,
@@ -120,21 +131,80 @@ export const inspectGhidraPspExtension = async (root, ghidraVersion, signal) =>
     };
 };
 /** Resolve prerequisites before opening or admitting cached PSP analysis. */
-export const resolveGhidraPspExtension = async (installation, signal) => {
-    if (signal?.aborted)
-        return err(new AnalysisCancelledError("resolve_analysis_profile"));
+export const resolveGhidraPspExtension = async (installation, resources, signal) => {
     try {
+        assertArtifactReadActive(signal);
         if (installation.status !== "available" ||
             installation.platform !== "linux" ||
             installation.architecture !== "x64")
             throw new Error("The initial PSP profile requires a supported Linux x64 Ghidra installation.");
         const root = join(await realpath(installation.installDir), "Ghidra", "Extensions", "ghidra-allegrex");
-        return ok(await inspectGhidraPspExtension(root, installation.providerVersion, signal));
+        return ok(await inspectGhidraPspExtension(root, installation.providerVersion, resources, signal));
     }
     catch (cause) {
-        if (signal?.aborted)
-            return err(new AnalysisCancelledError("resolve_analysis_profile"));
-        const reason = `PSP_EXTENSION_UNAVAILABLE: ${cause instanceof Error ? cause.message : String(cause)} Use a compatible caller-installed ghidra-allegrex under GHIDRA_INSTALL_DIR/Ghidra/Extensions; REA does not install it.`;
-        return err(new AnalysisCapabilityUnavailableError("ghidra", "resolve_analysis_profile", reason, { cause, userMessage: reason }));
+        return err(ghidraPspInspectionError(cause));
+    }
+};
+/** Preserve the producer's primary failure and its live cleanup dependencies. */
+const ghidraPspInspectionError = (cause) => {
+    if (cause instanceof AnalysisError)
+        return cause;
+    const cleanup = cause instanceof ArtifactReaderFailure ? cause.cleanup : undefined;
+    const primary = artifactFilePrimaryFailure(cause);
+    const reason = `PSP_EXTENSION_UNAVAILABLE: ${primary instanceof Error ? primary.message : String(primary)} Use a compatible caller-installed ghidra-allegrex under GHIDRA_INSTALL_DIR/Ghidra/Extensions; REA does not install it.`;
+    const error = cause instanceof ArtifactReaderFailure && cause.reason === "cancelled"
+        ? new AnalysisCancelledError("resolve_analysis_profile", {
+            cause: artifactFileCancellationCause(cause),
+            cleanup,
+        })
+        : new AnalysisCapabilityUnavailableError("ghidra", "resolve_analysis_profile", reason, {
+            cause,
+            userMessage: reason,
+            cleanup,
+        });
+    bindArtifactFileCleanup(cause, error);
+    return error;
+};
+/** Close before descending, retaining the exact directory owner on uncertainty. */
+const readChildren = async (path, remainingEntries, resources, signal) => {
+    assertArtifactReadActive(signal);
+    const owner = new OwnedDirectoryHandle(await opendir(path));
+    let outcome;
+    try {
+        const names = [];
+        for (;;) {
+            assertArtifactReadActive(signal);
+            const child = await owner.handle.read();
+            assertArtifactReadActive(signal);
+            if (child === null)
+                break;
+            if (names.length >= remainingEntries)
+                throw new Error("Allegrex extension inventory exceeds the inspection limit.");
+            names.push(child.name);
+        }
+        outcome = { kind: "completed", names };
+    }
+    catch (cause) {
+        outcome = { kind: "failed", cause };
+    }
+    const lease = new AnalysisCleanupLease(() => owner.close(), [path]);
+    const attempt = await resources.release({
+        kind: "lease",
+        resource: path,
+        lease,
+    });
+    if (attempt.kind === "failed") {
+        const primary = outcome.kind === "failed"
+            ? outcome.cause
+            : signal?.aborted
+                ? new ArtifactReaderFailure("cancelled", "PSP inspection cancelled during directory close", { cause: signal.reason })
+                : attempt.cause;
+        const error = ghidraPspInspectionError(ArtifactReaderFailure.withCleanup(primary, ArtifactReaderFailure.cleanupObservation(attempt.cause, path)));
+        lease.bindCleanupError(error);
+        throw error;
     }
+    if (outcome.kind === "failed")
+        throw outcome.cause;
+    assertArtifactReadActive(signal);
+    return outcome.names;
 };

package/dist/ghidra/GhidraPspProfile.js

@@ -1,4 +1,4 @@
-import { ghidraMipsGnuAttributesUnsupportedReason, ghidraMipsUnsupportedReason, } from "./GhidraMipsProfile.js";
+import { ghidraMipsGnuAttributesUnsupportedReason, ghidraMipsIncompleteDeclarationsReason, ghidraMipsUnsupportedReason, } from "./GhidraMipsProfile.js";
 import { ghidraPowerPcUnsupportedReason } from "./GhidraPowerPcProfile.js";
 import { ghidraRiscvUnsupportedReason } from "./GhidraRiscvProfile.js";
 /** Allegrex's ELF machine declaration, not a filename or inferred instruction. */
@@ -23,6 +23,9 @@ export const ghidraProcessorUnsupportedReason = (target) => {
     const gnuAttributesReason = ghidraMipsGnuAttributesUnsupportedReason(metadata);
     if (gnuAttributesReason !== null)
         return gnuAttributesReason;
+    const incomplete = ghidraMipsIncompleteDeclarationsReason(metadata);
+    if (incomplete !== null)
+        return incomplete;
     if (metadata.elfClass !== 32 || metadata.byteOrder !== "little")
         return "The PSP Allegrex profile requires little-endian ELF32.";
     if (metadata.type !== 2)

package/dist/ghidra/GhidraRawBinaryLanguage.js

@@ -1,8 +1,9 @@
 /**
- * Map caller-visible CPU families to little-endian generic Ghidra
- * languages with a supported generic compiler specification. These are
- * analysis conventions, not evidence of the target's original compiler.
- * Big-endian, Thumb-only, and Cortex-M variants are out of scope.
+ * Map caller-visible CPU families to generic Ghidra languages with a
+ * supported generic compiler specification. These are analysis conventions,
+ * not evidence of the target's original compiler. Each family has one fixed
+ * byte order: m68k is big-endian and the others are little-endian. Big-endian
+ * ARM, Thumb-only, Cortex-M, and other processor variants are out of scope.
  */
 export const ghidraRawBinaryLanguage = (architecture) => {
     switch (architecture) {
@@ -12,6 +13,14 @@ export const ghidraRawBinaryLanguage = (architecture) => {
                 compilerSpecId: "default",
                 defaultAddressSpace: "RAM",
             };
+        case "m68k":
+            // Ghidra's default 68000 language decodes the 68040 superset; no
+            // MC68000-only variant is declared in the 68000 processor module.
+            return {
+                languageId: "68000:BE:32:default",
+                compilerSpecId: "default",
+                defaultAddressSpace: "ram",
+            };
         case "x86":
             return {
                 languageId: "x86:LE:32:default",

package/dist/ghidra/GhidraReleasePolicy.js

@@ -0,0 +1,93 @@
+/** Ghidra build whose bridge behavior this REA release verifies. */
+export const SUPPORTED_GHIDRA_VERSION = "12.1.4";
+/** Verified JDK major; admission uses the installation's declared bounds. */
+export const SUPPORTED_GHIDRA_JAVA_MAJOR = 21;
+const GHIDRA_RELEASE_PATTERN = /^(\d+)\.(\d+)(?:\.(\d+))?([-+].*)?$/u;
+/** 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";
+};
+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, suffix: match[4] ?? "" };
+};
+/**
+ * The version spelling Ghidra's `ApplicationVersion.toString` uses in its
+ * settings directory: numeric components normalized, a zero patch and an
+ * empty tag omitted. A build-metadata (`+`) suffix has no such spelling.
+ */
+export const ghidraConfigurationVersion = (raw) => {
+    const version = parseGhidraRelease(raw);
+    if (version === undefined || version.suffix.startsWith("+"))
+        return undefined;
+    const patch = version.patch === 0 ? "" : `.${String(version.patch)}`;
+    const suffix = version.suffix === "-" ? "" : version.suffix;
+    return `${String(version.major)}.${String(version.minor)}${patch}${suffix}`;
+};
+const integerGroup = (value) => {
+    if (value === undefined)
+        return undefined;
+    const parsed = Number(value);
+    return Number.isSafeInteger(parsed) ? parsed : undefined;
+};

package/dist/ghidra/GhidraRequestQueue.js

@@ -1,4 +1,6 @@
+import { ProviderCleanupError } from "../domain/providerCleanupError.js";
 import { err } from "../domain/result.js";
+import { GhidraSessionError, } from "./GhidraSessionError.js";
 /** FIFO that admits one Ghidra Program request at a time. */
 export class GhidraRequestQueue {
     execute;
@@ -17,16 +19,16 @@ export class GhidraRequestQueue {
         if (this.#closedFailure !== undefined)
             return Promise.resolve(err(this.#closedFailure));
         if (options.signal?.aborted === true)
-            return Promise.resolve(err(this.failure("cancelled", "Ghidra request was cancelled")));
+            return Promise.resolve(err(this.#cancelled(options.signal)));
         return new Promise((resolve) => {
             let entry;
             const onAbort = options.signal === undefined
                 ? undefined
-                : () => this.#rejectQueued(entry, err(this.failure("cancelled", "Ghidra request was cancelled")));
+                : () => this.#rejectQueued(entry, err(this.#cancelled(options.signal)));
             entry = {
                 method,
                 parameters,
-                signal: options.signal,
+                options,
                 resolve,
                 onAbort,
             };
@@ -55,51 +57,61 @@ export class GhidraRequestQueue {
         if (entry === undefined)
             return;
         this.#release(entry);
-        if (entry.signal?.aborted === true) {
-            entry.resolve(err(this.failure("cancelled", "Ghidra request was cancelled")));
+        if (entry.options.signal?.aborted === true) {
+            entry.resolve(err(this.#cancelled(entry.options.signal)));
             this.#drain();
             return;
         }
         this.#active = true;
-        let executionSettled = false;
-        let activeCancellation;
-        const onAbort = entry.signal === undefined
-            ? undefined
-            : () => {
-                if (executionSettled)
-                    return;
-                this.failQueued(this.failure("process", "Ghidra session closed after active request cancellation"));
-                activeCancellation = this.onActiveCancellation();
-            };
-        if (onAbort !== undefined)
-            entry.signal?.addEventListener("abort", onAbort, { once: true });
-        void this.execute(entry.method, entry.parameters, entry.signal === undefined ? {} : { signal: entry.signal })
-            .then(async (result) => {
-            if (activeCancellation !== undefined) {
-                try {
-                    await activeCancellation;
-                }
-                catch (cause) {
-                    result = err(this.failure("process", cause instanceof Error
-                        ? `Ghidra cleanup after cancellation failed: ${cause.message}`
-                        : "Ghidra cleanup after cancellation failed", cause));
-                }
-            }
-            executionSettled = true;
-            entry.resolve(result);
-        })
-            .catch((cause) => {
-            executionSettled = true;
-            entry.resolve(err(this.failure("protocol", "Ghidra serial request execution rejected unexpectedly", cause)));
-        })
+        void this.#executeEntry(entry)
+            .then(entry.resolve)
             .finally(() => {
-            if (entry.signal !== undefined && onAbort !== undefined)
-                entry.signal.removeEventListener("abort", onAbort);
             this.#active = false;
             if (this.#closedFailure === undefined)
                 this.#drain();
         });
     }
+    async #executeEntry(entry) {
+        let cancellation;
+        const onAbort = () => {
+            this.failQueued(this.failure("process", "Ghidra session closed after active request cancellation"));
+            cancellation = {
+                failure: this.#cancelled(entry.options.signal),
+                // Capture rejection immediately, including a synchronous callback throw.
+                // Execution and finalization may settle in either order.
+                cleanup: Promise.resolve()
+                    .then(() => this.onActiveCancellation())
+                    .then((value) => ({ kind: "returned", value }), (cause) => ({ kind: "rejected", cause })),
+            };
+        };
+        entry.options.signal?.addEventListener("abort", onAbort, { once: true });
+        try {
+            let result;
+            try {
+                result = await this.execute(entry.method, entry.parameters, entry.options);
+            }
+            catch (cause) {
+                result = err(cause instanceof GhidraSessionError
+                    ? cause
+                    : this.failure("protocol", "Ghidra serial request execution rejected unexpectedly", cause));
+            }
+            if (cancellation === undefined)
+                return result;
+            const primary = result.ok ? cancellation.failure : result.error;
+            const cleanup = await cancellation.cleanup;
+            if (cleanup.kind === "rejected")
+                return err(this.#withUnexpectedCleanupRejection(primary, cleanup.cause));
+            return err(cleanup.value.ok
+                ? primary
+                : primary.withCleanupFailure(cleanup.value.error));
+        }
+        finally {
+            entry.options.signal?.removeEventListener("abort", onAbort);
+        }
+    }
+    #cancelled(signal) {
+        return this.failure("cancelled", "Ghidra request was cancelled", signal?.reason, signal === undefined ? {} : { cancellation: { reason: signal.reason } });
+    }
     #rejectQueued(entry, result) {
         const index = this.#queue.indexOf(entry);
         if (index < 0)
@@ -108,8 +120,20 @@ export class GhidraRequestQueue {
         this.#release(entry);
         entry.resolve(result);
     }
+    #withUnexpectedCleanupRejection(primary, cause) {
+        const described = this.failure(primary.kind, primary.message, cause);
+        const rejection = described.diagnostics.failure_cause;
+        const cleanupFailure = new ProviderCleanupError("ghidra", ["Ghidra cancellation cleanup"], {
+            reason: "Cancellation cleanup rejected before release was confirmed",
+            unexpected_cleanup_rejection: rejection ?? { type: typeof cause },
+        }, { cause });
+        return primary.withCleanupFailure(cleanupFailure, {
+            ...primary.diagnostics,
+            unexpected_cleanup_rejection: rejection ?? { type: typeof cause },
+        });
+    }
     #release(entry) {
-        if (entry.signal !== undefined && entry.onAbort !== undefined)
-            entry.signal.removeEventListener("abort", entry.onAbort);
+        if (entry.options.signal !== undefined && entry.onAbort !== undefined)
+            entry.options.signal.removeEventListener("abort", entry.onAbort);
     }
 }