rea-agents 6.0.0 → 6.2.0

package/dist/hopper/HopperAnalysisProfile.js

@@ -1,26 +1,47 @@
 import { createHash } from "node:crypto";
 import { createReadStream } from "node:fs";
 import { createAnalysisProfile } from "../domain/analysisProfile.js";
-import { AnalysisCancelledError } from "../domain/analysisErrorCore.js";
+import { AnalysisCancelledError, AnalysisCapabilityUnavailableError, } from "../domain/analysisErrorCore.js";
+import { BinaryTargetError } from "../domain/configurationErrors.js";
 import { ProviderAdapterError } from "../domain/providerAdapterError.js";
 import {} from "../domain/analysisErrorBase.js";
 import { err, ok } from "../domain/result.js";
+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: {} });
-    const derived = hopperLoaderArgsForTarget(target);
+        return ok({ profile: null });
+    let machoContainer;
+    if (target.kind === "executable" && target.format === "mach-o") {
+        const header = await readMachoMagic(target.path, options.signal);
+        if (!header.ok)
+            return header;
+        machoContainer = [0xcafebabf, 0xbfbafeca].includes(header.value)
+            ? "fat64"
+            : [0xcafebabe, 0xbebafeca].includes(header.value)
+                ? "fat32"
+                : "thin";
+    }
+    let preparedImage;
+    if (target.kind === "executable" &&
+        machoContainer === "fat64" &&
+        options.loaderArgsOverride.length === 0) {
+        const resolved = await resolveHopperMachOImage(target, options.signal);
+        if (!resolved.ok)
+            return resolved;
+        preparedImage = resolved.value;
+    }
+    const derived = hopperLoaderArgsForTarget(target, preparedImage === undefined ? machoContainer : "thin");
     if (!derived.ok)
         return derived;
     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,
@@ -34,21 +55,23 @@ export const resolveHopperAnalysisProfile = async (target, options) => {
             available_architectures: [
                 ...(target.availableArchitectures ?? []),
             ].sort(),
+            ...(machoContainer === undefined
+                ? {}
+                : { macho_container: machoContainer }),
+            ...(preparedImage === undefined
+                ? {}
+                : { prepared_image: { ...preparedImage } }),
             loader: {
                 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. */
-export const hopperLoaderArgsForTarget = (target) => {
+export const hopperLoaderArgsForTarget = (target, machoContainer) => {
     if (target.kind === "database")
         return ok([]);
     if (target.kind !== "executable")
@@ -57,7 +80,9 @@ export const hopperLoaderArgsForTarget = (target) => {
     const flag = hopperArchitectureFlag(architecture);
     switch (target.format) {
         case "mach-o":
-            return ok((target.availableArchitectures?.length ?? 0) > 1
+            if (machoContainer === undefined)
+                return err(new AnalysisCapabilityUnavailableError("hopper", "resolve_analysis_profile", "Mach-O container kind is unknown; resolve the Hopper analysis profile before starting its client."));
+            return ok(machoContainer === "fat32" || machoContainer === "fat64"
                 ? ["-l", "FAT", flag, "-l", "Mach-O"]
                 : ["-l", "Mach-O", flag]);
         case "elf":
@@ -81,6 +106,34 @@ const hopperArchitectureFlag = (architecture) => {
             return "--aarch64";
     }
 };
+const readMachoMagic = async (path, signal) => {
+    if (signalIsAborted(signal))
+        return err(new AnalysisCancelledError("open_binary"));
+    const stream = createReadStream(path, { start: 0, end: 3 });
+    const onAbort = () => {
+        stream.destroy();
+    };
+    signal?.addEventListener("abort", onAbort, { once: true });
+    try {
+        const chunks = [];
+        for await (const chunk of stream)
+            chunks.push(Buffer.from(chunk));
+        if (signalIsAborted(signal))
+            return err(new AnalysisCancelledError("open_binary"));
+        const bytes = Buffer.concat(chunks);
+        return bytes.length === 4
+            ? ok(bytes.readUInt32BE(0))
+            : err(new BinaryTargetError(path, "Mach-O header became truncated before Hopper loader selection"));
+    }
+    catch (cause) {
+        return signalIsAborted(signal)
+            ? err(new AnalysisCancelledError("open_binary"))
+            : err(new BinaryTargetError(path, `Cannot read the Mach-O container header: ${cause instanceof Error ? cause.message : String(cause)}`, { cause }));
+    }
+    finally {
+        signal?.removeEventListener("abort", onAbort);
+    }
+};
 const sha256File = async (path, signal) => {
     if (signalIsAborted(signal))
         return err(new AnalysisCancelledError("open_binary"));

package/dist/hopper/HopperCleanup.js

@@ -9,22 +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
+    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");
-    await closeRuntimeRoot(input.runtimeRoot, state);
+    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: "Private runtime retained because process or native document closure was not confirmed",
+        });
+    }
+    else {
+        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)
@@ -34,7 +66,9 @@ const requestShutdown = async (input, state) => {
             }, "Hopper shutdown skipped because a bridge operation remained active");
         return;
     }
-    const method = input.retainDocument || 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
@@ -42,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)),
@@ -113,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
@@ -129,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;
@@ -143,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({
@@ -154,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";
@@ -174,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) }),