rea-agents 6.1.0 → 6.2.0

package/dist/ghidra/extensions/GhidraExtensions.js

@@ -3,7 +3,7 @@ import { constants } from "node:fs";
 import { open, realpath, writeFile, mkdir } from "node:fs/promises";
 import { isAbsolute, join } from "node:path";
 import { z } from "zod";
-import { AnalysisCancelledError } from "../../domain/analysisErrorCore.js";
+import { AnalysisCancelledError, AnalysisCapabilityUnavailableError, AnalysisUnsupportedTargetError, } from "../../domain/analysisErrorCore.js";
 import { ProviderAdapterError } from "../../domain/providerAdapterError.js";
 import { jsonObjectSchema } from "../../domain/jsonValue.js";
 import { err, ok } from "../../domain/result.js";
@@ -11,7 +11,7 @@ import { nativeAotAdapter } from "./nativeaot/NativeAotAdapter.js";
 const digest = z.string().regex(/^[a-f0-9]{64}$/u);
 /** Exact executable extension artifact committed before the session starts. */
 export const ghidraExtensionSchema = z.strictObject({
-    id: z.string().regex(/^[a-z][a-z0-9-]*$/u),
+    id: z.string().regex(/^[a-z][a-z0-9\x2d]*$/u),
     path: z.string().refine(isAbsolute, "Extension path must be absolute"),
     configured_path: z
         .string()
@@ -70,11 +70,9 @@ export const resolveGhidraExtensions = async (config, target, platform, signal)
         const configured = adapter.configuredPath(config);
         if (configured === undefined)
             continue;
-        const reason = adapter.unsupportedReason(target, platform);
-        if (reason !== null)
-            return err(new ProviderAdapterError("ghidra", "resolve_analysis_profile", {
-                diagnostics: { extension: adapter.id, reason, path: configured },
-            }));
+        const refusal = adapter.unsupportedReason(target, platform);
+        if (refusal !== null)
+            return err(extensionRefusalError(refusal, target));
         try {
             const path = await realpath(configured);
             const bytes = await readJar(path);
@@ -115,12 +113,21 @@ export const validateGhidraExtensionProfile = (extensions, config, target, platf
             adapter.entryClass !== extension.entry_class ||
             adapter.configuredPath(config) !== extension.configured_path)
             return `Ghidra extension profile lacks matching explicit local configuration: ${extension.id}`;
-        const reason = adapter.unsupportedReason(target, platform);
-        if (reason !== null)
-            return reason;
+        const refusal = adapter.unsupportedReason(target, platform);
+        if (refusal !== null)
+            return refusal.reason;
     }
     return null;
 };
+/**
+ * A deliberate host or target refusal is not an execution failure: retrying
+ * cannot change it, and its reason already names the remedy.
+ */
+const extensionRefusalError = (refusal, target) => refusal.constraint === "host"
+    ? new AnalysisCapabilityUnavailableError("ghidra", "resolve_analysis_profile", refusal.reason, { userMessage: refusal.reason })
+    : new AnalysisUnsupportedTargetError("resolve_analysis_profile", target.path, refusal.reason, 
+    // The reason names the workflows that remain available.
+    { remediationAction: refusal.reason });
 /** Snapshot committed extension bytes into the private runtime before Java loads them. */
 export const snapshotGhidraExtensions = async (extensions, runtimeRoot) => {
     if (extensions.length === 0)

package/dist/ghidra/extensions/nativeaot/NativeAotAdapter.js

@@ -5,11 +5,17 @@ export const nativeAotAdapter = {
     entryClass: "rea.extensions.nativeaot.NativeAotExtension",
     configuredPath: (config) => config.ghidraNativeAotJar,
     unsupportedReason: (target, platform) => platform !== "linux"
-        ? "NativeAOT recovery is verified on Linux only; omit REA_GHIDRA_NATIVEAOT_JAR for ordinary native analysis."
+        ? {
+            constraint: "host",
+            reason: "NativeAOT recovery is verified on Linux only; omit REA_GHIDRA_NATIVEAOT_JAR for ordinary native analysis.",
+        }
         : !["elf", "pe"].includes(target.format) ||
             target.architecture !== "x86_64" ||
             target.managed === true
-            ? "NativeAOT recovery requires an x86-64 ELF or native PE target on Linux; PE/CLI and ReadyToRun assemblies use inspect_managed_artifact; omit REA_GHIDRA_NATIVEAOT_JAR for ordinary native analysis."
+            ? {
+                constraint: "target",
+                reason: "NativeAOT recovery requires an x86-64 ELF or native PE target on Linux; PE/CLI and ReadyToRun assemblies use inspect_managed_artifact; omit REA_GHIDRA_NATIVEAOT_JAR for ordinary native analysis.",
+            }
             : null,
     validate: validateNativeAotReport,
     limitations: [

package/dist/hopper/BridgeLauncher.js

@@ -9,9 +9,8 @@ import { execFileOutput } from "../process/ExecFileOutput.js";
 import { spawnOwnedProviderProcess, } from "../process/ProviderProcess.js";
 import { waitForAbortableDelay } from "../process/ProviderDeadline.js";
 import { selectLinuxPrivateDisplayStrategy, } from "./LinuxPrivateDisplayProbe.js";
-import writeFileAtomic from "write-file-atomic";
 import { prepareHopperMachOImage, } from "./HopperMachOImage.js";
-import { acquireHopperTargetLease } from "./HopperTargetLease.js";
+import { acquireHopperTargetLease, acquireLinuxHopperApplicationLease, } from "./HopperTargetLease.js";
 const execFileAsync = promisify(execFile);
 const HOPPER_BACKGROUND_STARTUP_MS = 5_000;
 /**
@@ -36,7 +35,7 @@ export class HopperApplicationLauncher {
         this.dependencies = dependencies;
     }
     async launch(session, options = {}) {
-        const leaseResult = await this.#acquireTargetLease(session.runId);
+        const leaseResult = await this.#acquireLaunchLease(session.runId);
         if (!leaseResult.ok)
             return leaseResult;
         const lease = leaseResult.value;
@@ -86,7 +85,7 @@ export class HopperApplicationLauncher {
             const display = await this.#privateDisplay(signal);
             if (!display.ok)
                 return err(display.error);
-            const prepared = await prepareHopperApplication(this.options.launcherPath, signal);
+            const prepared = await prepareHopperApplication(this.options.launcherPath, this.options.environment, signal);
             if (!prepared)
                 return err(new HopperCancelledError());
             const linuxDemo = linuxDemoLaunch(this.options, session, argumentsForTarget, display.strategy);
@@ -101,22 +100,7 @@ export class HopperApplicationLauncher {
             });
             if (started === null)
                 return err(new HopperCancelledError());
-            const cleanup = () => cleanupOwnedProcessGroup(started.ownership).finally(() => lease?.release());
-            const ownership = {
-                run_id: session.runId,
-                pid: started.ownership.leaderPid,
-                process_group_id: started.ownership.leaderPid,
-                parent_pid: process.pid,
-                launcher: linuxDemo?.command ?? this.options.launcherPath,
-                created_at: new Date().toISOString(),
-            };
-            try {
-                await writeFileAtomic(join(session.directory, "ownership.json"), `${JSON.stringify(ownership)}\n`, { encoding: "utf8", mode: 0o600 });
-            }
-            catch (cause) {
-                await cleanupOwnedProcessGroup(started.ownership);
-                return err(new HopperStartError({ cause }));
-            }
+            const cleanup = () => cleanupOwnedProcessGroup(started.ownership);
             const ownedLauncher = {
                 ...(this.options.preparedImage === undefined
                     ? {}
@@ -125,6 +109,8 @@ export class HopperApplicationLauncher {
                 ownsProcessLifetime: true,
                 ownership: started.ownership,
                 cleanup,
+                launcherCommand: linuxDemo?.command ?? this.options.launcherPath,
+                ...(lease === undefined ? {} : { releaseLease: () => lease.release() }),
             };
             return ownsProcessLifetime
                 ? ok({
@@ -142,26 +128,35 @@ export class HopperApplicationLauncher {
             return err(hopperLaunchFailure(cause, signal));
         }
     }
-    async #acquireTargetLease(runId) {
-        if ((this.dependencies.platform ?? process.platform) !== "darwin")
+    async #acquireLaunchLease(runId) {
+        const platform = this.dependencies.platform ?? process.platform;
+        const applicationLease = platform === "linux" && usesLinuxDemo(this.options);
+        if (!applicationLease && platform !== "darwin")
             return ok(undefined);
         try {
-            const acquisition = await (this.dependencies.acquireTargetLease ?? acquireHopperTargetLease)({
-                targetPath: this.options.targetPath,
-                targetKind: this.options.targetKind,
-                loaderArgs: this.options.loaderArgs,
-                runId,
-            });
+            const acquisition = applicationLease
+                ? await (this.dependencies.acquireApplicationLease ??
+                    acquireLinuxHopperApplicationLease)({ runId })
+                : await (this.dependencies.acquireTargetLease ?? acquireHopperTargetLease)({
+                    targetPath: this.options.targetPath,
+                    targetKind: this.options.targetKind,
+                    loaderArgs: this.options.loaderArgs,
+                    runId,
+                });
             if (!acquisition.acquired)
                 return err(new HopperStartError({
                     ownerRunId: acquisition.owner.runId,
-                    userMessage: `This Hopper target is already open in REA session ${acquisition.owner.runId}. ` +
-                        "Use that REA session or close it before opening this target again.",
+                    userMessage: applicationLease
+                        ? `Linux Hopper is already active in REA session ${acquisition.owner.runId}; it cannot open ${this.options.targetPath} in another session. This build forwards new launches to the existing application. Use the owning REA session to switch targets, or close it before retrying.`
+                        : `This Hopper target is already open in REA session ${acquisition.owner.runId}. ` +
+                            "Use that REA session or close it before opening this target again.",
                 }));
             return ok(acquisition.lease);
         }
         catch (cause) {
-            return err(new HopperStartError({ cause }));
+            return err(cause instanceof HopperStartError
+                ? cause
+                : new HopperStartError({ cause }));
         }
     }
     async #writeBootstrap(session, ownsProcessLifetime, loadedPath) {
@@ -181,6 +176,7 @@ export class HopperApplicationLauncher {
         const selection = await (this.dependencies.selectPrivateDisplay ??
             selectLinuxPrivateDisplayStrategy)({
             helperPath: this.options.demoHelperPath,
+            environment: this.options.environment,
             ...(signal === undefined ? {} : { signal }),
         });
         if (signal?.aborted === true)
@@ -209,6 +205,7 @@ const launchHopperProcess = async (input) => {
         arguments: arguments_,
         runId: input.session.runId,
         expectedCommand: ownershipCommand,
+        hostEnvironment: input.options.environment,
         ...(input.signal === undefined ? {} : { signal: input.signal }),
     });
     if (input.linuxDemo !== undefined)
@@ -217,6 +214,7 @@ const launchHopperProcess = async (input) => {
             arguments: input.linuxDemo.args,
             runId: input.session.runId,
             expectedCommand: ownershipCommand,
+            hostEnvironment: input.options.environment,
             ...(input.signal === undefined ? {} : { signal: input.signal }),
         });
     return spawn(input.argumentsForTarget);
@@ -262,21 +260,16 @@ const hopperLaunchFailure = (cause, signal) => signal?.aborted === true
     : new HopperStartError({ cause });
 /** Select the version-pinned adapter from the caller's explicit launch mode. */
 export const usesLinuxDemo = (options) => options.launchMode === "verified_linux_demo";
-const prepareHopperApplication = async (launcherPath, signal) => {
+const prepareHopperApplication = async (launcherPath, environment, signal) => {
     const appBundle = hopperApplicationBundle(launcherPath);
     if (appBundle === undefined)
         return signal?.aborted !== true;
     const executablePath = join(appBundle, "Contents/MacOS/Hopper Disassembler");
-    if (await processIsRunning(executablePath))
+    if (await processIsRunning(executablePath, environment))
         return signal?.aborted !== true;
     // This reduces activation when Hopper is cold, but the vendor launcher that
     // follows may still activate its window. See HopperApplicationLauncher.
-    await execFileAsync("/usr/bin/open", [
-        "--hide",
-        "--background",
-        "-a",
-        appBundle,
-    ]);
+    await execFileAsync("/usr/bin/open", ["--hide", "--background", "-a", appBundle], { env: environment });
     return ((await waitForAbortableDelay(HOPPER_BACKGROUND_STARTUP_MS, signal)) ===
         "elapsed");
 };
@@ -286,13 +279,9 @@ const hopperApplicationBundle = (launcherPath) => {
     const candidate = dirname(dirname(dirname(launcherPath)));
     return extname(candidate) === ".app" ? candidate : undefined;
 };
-const processIsRunning = async (executablePath) => {
+const processIsRunning = async (executablePath, environment) => {
     try {
-        const processes = await execFileOutput("/bin/ps", [
-            "-ax",
-            "-o",
-            "command=",
-        ]);
+        const processes = await execFileOutput("/bin/ps", ["-ax", "-o", "command="], { env: environment });
         return processes.stdout
             .split("\n")
             .some((command) => command.trim() === executablePath);

package/dist/hopper/HopperAnalysisProfile.js

@@ -10,7 +10,7 @@ import { resolveHopperMachOImage, } from "./HopperMachOImage.js";
 /** Resolve Hopper open semantics without placing its CLI flags in BinaryTarget. */
 export const resolveHopperAnalysisProfile = async (target, options) => {
     if (target.kind !== "executable" && target.kind !== "database")
-        return ok({ profile: null, compatibility: {} });
+        return ok({ profile: null });
     let machoContainer;
     if (target.kind === "executable" && target.format === "mach-o") {
         const header = await readMachoMagic(target.path, options.signal);
@@ -37,12 +37,11 @@ export const resolveHopperAnalysisProfile = async (target, options) => {
     const loaderArgs = options.loaderArgsOverride.length === 0
         ? derived.value
         : [...options.loaderArgsOverride];
-    const compatibility = { loaderArgs: [...loaderArgs] };
     const launcherDigest = await sha256File(options.launcherPath, options.signal);
     if (!launcherDigest.ok)
         return launcherDigest;
     if (launcherDigest.value === undefined)
-        return ok({ profile: null, compatibility });
+        return ok({ profile: null });
     const provider = {
         id: options.provider.id,
         name: options.provider.name,
@@ -66,13 +65,9 @@ export const resolveHopperAnalysisProfile = async (target, options) => {
                 source: options.loaderArgsOverride.length === 0
                     ? "derived"
                     : "configured_override",
-                argument_count: loaderArgs.length,
-                arguments_sha256: createHash("sha256")
-                    .update(JSON.stringify(loaderArgs))
-                    .digest("hex"),
+                arguments: [...loaderArgs],
             },
         }),
-        compatibility,
     });
 };
 /** Derive Hopper's complete non-interactive CLI loader selection. */

package/dist/hopper/HopperCleanup.js

@@ -9,33 +9,54 @@ export const cleanupHopperSession = async (input) => {
         issues: [],
         resources: new Set(),
         cleanupResult: undefined,
-        shutdownConfirmed: false,
+        processStopped: input.resources.processSupervisor === undefined,
     };
-    await report(input.progress, 0, input.retainDocument && input.launch?.preparedImagePath === undefined
+    await report(input.progress, 0, input.retainDocument &&
+        input.resources.launch?.preparedImagePath === undefined
         ? "detaching REA from the Hopper document"
         : "requesting Hopper document shutdown");
     await requestShutdown(input, state);
     await report(input.progress, 0.35, "releasing Hopper bridge transport");
-    input.releaseTransport(input.socket);
+    if (input.resources.shutdownConfirmed ||
+        input.resources.launch?.providerLifetime !== "external-application")
+        input.releaseTransport(input.socket);
     await stopProcess(input, state);
     recordUnconfirmedDocument(input, state);
     await report(input.progress, 0.75, "removing Hopper private runtime files");
-    if (input.launch?.preparedImagePath !== undefined &&
-        !state.shutdownConfirmed) {
-        const resource = input.runtimeRoot?.path ?? input.launch.preparedImagePath;
+    if (input.resources.runtimeRoot !== undefined &&
+        (!state.processStopped ||
+            (!input.resources.shutdownConfirmed &&
+                (input.resources.launch?.preparedImagePath !== undefined ||
+                    input.resources.launch?.providerLifetime === "external-application")))) {
+        const resource = input.resources.runtimeRoot.path;
         state.resources.add(resource);
         state.issues.push({
             resource,
-            reason: "Prepared image retained because native document closure was not confirmed",
+            reason: "Private runtime retained because process or native document closure was not confirmed",
         });
     }
     else {
-        await closeRuntimeRoot(input.runtimeRoot, state);
+        await closeRuntimeRoot(input, state);
+    }
+    if (state.processStopped && input.resources.shutdownConfirmed) {
+        const launch = input.resources.launch;
+        try {
+            await launch?.releaseLease?.();
+            input.resources.launch = undefined;
+        }
+        catch (cause) {
+            state.resources.add("hopper-lease");
+            state.issues.push({
+                resource: "hopper-lease",
+                reason: cause instanceof Error ? cause.message : String(cause),
+            });
+        }
     }
     return cleanupOutcome(input, state);
 };
 const requestShutdown = async (input, state) => {
-    if (input.socket === undefined ||
+    if (input.resources.shutdownConfirmed ||
+        input.socket === undefined ||
         input.socket.destroyed ||
         input.activeRequest !== null) {
         if (input.activeRequest !== null)
@@ -45,8 +66,9 @@ const requestShutdown = async (input, state) => {
             }, "Hopper shutdown skipped because a bridge operation remained active");
         return;
     }
-    const method = (input.retainDocument && input.launch?.preparedImagePath === undefined) ||
-        input.launch?.shutdownMode === "process-cleanup"
+    const method = (input.retainDocument &&
+        input.resources.launch?.preparedImagePath === undefined) ||
+        input.resources.launch?.shutdownMode === "process-cleanup"
         ? "shutdown"
         : "shutdown_document";
     const shutdown = await input
@@ -54,22 +76,19 @@ const requestShutdown = async (input, state) => {
         .catch((cause) => err(shutdownRequestFailure(method, cause)));
     if (shutdown.ok &&
         isHopperCleanupRequired(shutdown.value) &&
-        input.launch?.shutdownMode === "process-cleanup") {
-        state.cleanupResult = await input.launch
+        input.resources.launch?.shutdownMode === "process-cleanup") {
+        state.cleanupResult = await input.resources.launch
             .cleanup()
             .catch(providerCleanupFailure);
         if (!state.cleanupResult.cleaned) {
-            state.shutdownConfirmed = await fallbackDocumentShutdown(input);
-            state.cleanupResult = await input.launch
-                .cleanup()
-                .catch(providerCleanupFailure);
+            input.resources.shutdownConfirmed = await fallbackDocumentShutdown(input);
         }
     }
     else if (shutdown.ok) {
-        state.shutdownConfirmed = isHopperShutdownAcknowledgement(shutdown.value);
+        input.resources.shutdownConfirmed = isHopperShutdownAcknowledgement(shutdown.value);
     }
     if (!shutdown.ok ||
-        (!state.shutdownConfirmed && state.cleanupResult === undefined))
+        (!input.resources.shutdownConfirmed && state.cleanupResult === undefined))
         input.logger.warn({
             status: shutdown.ok ? "invalid-acknowledgement" : "failed",
             ...(shutdown.ok ? {} : shutdownFailureDetails(shutdown.error)),
@@ -125,7 +144,7 @@ const describeFailureCause = (cause) => {
     return { type: typeof cause };
 };
 const stopProcess = async (input, state) => {
-    const supervisor = input.processSupervisor;
+    const supervisor = input.resources.processSupervisor;
     if (supervisor === undefined)
         return;
     const stopped = await supervisor.stop(state.cleanupResult === undefined
@@ -141,9 +160,11 @@ const stopProcess = async (input, state) => {
     }
     input.logger.info(diagnostic, "Owned Hopper launcher shutdown completed");
     if (stopped.status !== "incomplete") {
-        if (input.launch?.shutdownMode === "process-cleanup" &&
+        if (input.resources.launch?.shutdownMode === "process-cleanup" &&
             stopped.status !== "not-owned")
-            state.shutdownConfirmed = true;
+            input.resources.shutdownConfirmed = true;
+        state.processStopped = true;
+        input.resources.processSupervisor = undefined;
         return;
     }
     const processGroupId = supervisor.launch.ownership?.processGroupId;
@@ -155,8 +176,14 @@ const stopProcess = async (input, state) => {
     input.logger.warn({ reason: stopped.reason }, "Owned launcher cleanup failed closed");
 };
 const recordUnconfirmedDocument = (input, state) => {
-    if ((input.socket === undefined && input.launch === undefined) ||
-        state.shutdownConfirmed)
+    if (input.socket === undefined &&
+        state.processStopped &&
+        input.resources.launch?.providerLifetime === "launcher-process") {
+        // Startup never connected a document; the verified provider lifetime ended.
+        input.resources.shutdownConfirmed = true;
+    }
+    if ((input.socket === undefined && input.resources.launch === undefined) ||
+        input.resources.shutdownConfirmed)
         return;
     state.resources.add("hopper-document");
     state.issues.push({
@@ -166,9 +193,11 @@ const recordUnconfirmedDocument = (input, state) => {
             : `bridge operation ${input.activeRequest.operation} remained active after caller ${input.activeRequest.callerState}`,
     });
 };
-const closeRuntimeRoot = async (runtimeRoot, state) => {
+const closeRuntimeRoot = async (input, state) => {
+    const runtimeRoot = input.resources.runtimeRoot;
     try {
         await runtimeRoot?.close();
+        input.resources.runtimeRoot = undefined;
     }
     catch (cause) {
         const resource = runtimeRoot?.path ?? "hopper-runtime-root";
@@ -186,9 +215,9 @@ const cleanupOutcome = (input, state) => {
         return ok(null);
     return err(new ProviderCleanupError("hopper", [...state.resources], {
         issues: cleanupIssueDetails(state.issues),
-        ...(input.runtimeRoot === undefined
+        ...(input.resources.runtimeRoot === undefined
             ? {}
-            : { runtime_root: input.runtimeRoot.path }),
+            : { runtime_root: input.resources.runtimeRoot.path }),
         ...(input.activeRequest === null
             ? {}
             : { active_request: activityDetails(input.activeRequest) }),