rea-agents 6.1.0 → 6.2.0

package/dist/hopper/HopperClient.js

@@ -2,6 +2,8 @@ import { randomBytes, randomUUID } from "node:crypto";
 import { access } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
+import writeFileAtomic from "write-file-atomic";
+import { analysisErrorWithCleanupFailure } from "../application/binary/AnalysisClientCleanup.js";
 import { AnalysisCapabilityUnavailableError } from "../domain/analysisErrorCore.js";
 import { HopperCancelledError, HopperProcessError, HopperProtocolError, HopperRemoteError, HopperStartError, HopperTimeoutError, } from "../domain/hopperErrors.js";
 import {} from "../domain/analysisErrorBase.js";
@@ -14,7 +16,7 @@ import { ProviderStartupDeadline } from "../process/ProviderDeadline.js";
 import { ProviderRunLineage } from "../process/ProviderRunLineage.js";
 import { ProviderProcessSupervisor, } from "../process/ProviderProcess.js";
 import { hopperOperationStage } from "./HopperOperationStage.js";
-import { cleanupHopperSession } from "./HopperCleanup.js";
+import { cleanupHopperSession, } from "./HopperCleanup.js";
 import { parseHopperServerInfo, } from "./HopperSessionValues.js";
 import { connectHopperSocketOnce } from "./HopperSocketConnection.js";
 import { hopperLauncherFailureDiagnostic } from "./HopperProcessDiagnostic.js";
@@ -37,9 +39,12 @@ export class HopperClient {
     #responses;
     #logger;
     #socket;
-    #launch;
-    #process;
-    #runtimeRoot;
+    #resources = {
+        launch: undefined,
+        processSupervisor: undefined,
+        runtimeRoot: undefined,
+        shutdownConfirmed: false,
+    };
     #token;
     #lineage = new ProviderRunLineage();
     #nextId = 1;
@@ -61,7 +66,7 @@ export class HopperClient {
     #onSocketClose = () => {
         if (this.#closing)
             return;
-        const launch = this.#launch;
+        const launch = this.#resources.launch;
         if (launch?.providerLifetime === "launcher-process" &&
             this.#launcherExitCode !== undefined)
             return;
@@ -166,7 +171,7 @@ export class HopperClient {
     /** Launch the bridge once and complete its authenticated health handshake. */
     start(signal) {
         if (this.#closePromise !== undefined) {
-            return this.#closePromise.then(() => this.start(signal));
+            return this.#closePromise.then((closed) => closed.ok ? this.start(signal) : closed);
         }
         if (this.#startPromise !== undefined)
             return this.#startPromise;
@@ -193,19 +198,7 @@ export class HopperClient {
         void started.then((result) => {
             release();
             if (!result.ok) {
-                if (result.error instanceof HopperProcessError)
-                    this.#rememberProcessFailure(result.error, []);
-                else if (this.#operationFailure === undefined &&
-                    (result.error instanceof HopperTimeoutError ||
-                        result.error instanceof HopperStartError))
-                    this.#operationFailure = {
-                        state: result.error instanceof HopperTimeoutError
-                            ? "not_started"
-                            : "unknown",
-                        exitCode: null,
-                        startupFailure: true,
-                        requests: [],
-                    };
+                this.#rememberStartupFailure(result.error);
                 reset();
             }
         }, (cause) => {
@@ -219,9 +212,12 @@ export class HopperClient {
         if (isAborted(signal))
             return err(new HopperCancelledError());
         this.#operationFailure = undefined;
-        if (this.#socket !== undefined || this.#runtimeRoot !== undefined) {
+        if (this.#socket !== undefined ||
+            this.#resources.launch !== undefined ||
+            this.#resources.runtimeRoot !== undefined) {
             return err(new HopperProtocolError("Hopper client is already started"));
         }
+        this.#resources.shutdownConfirmed = false;
         const deadline = new ProviderStartupDeadline(this.#options.startupTimeoutMs, signal);
         try {
             return await this.#startWithin(deadline);
@@ -232,7 +228,7 @@ export class HopperClient {
     }
     async #startWithin(deadline) {
         try {
-            this.#runtimeRoot = await PrivateRuntimeRoot.create({
+            this.#resources.runtimeRoot = await PrivateRuntimeRoot.create({
                 parent: SESSION_ROOT,
                 prefix: "rea-",
             });
@@ -241,10 +237,9 @@ export class HopperClient {
             return err(new HopperStartError({ cause }));
         }
         if (deadline.signal.aborted) {
-            await this.#cleanup();
-            return err(startupInterruption(deadline));
+            return this.#startupFailure(startupInterruption(deadline));
         }
-        const socketPath = join(this.#runtimeRoot.path, "bridge.sock");
+        const socketPath = join(this.#resources.runtimeRoot.path, "bridge.sock");
         this.#token = randomBytes(32).toString("hex");
         this.#lineage.reset();
         this.#launcherExitCode = undefined;
@@ -252,47 +247,76 @@ export class HopperClient {
         const runId = this.#options.runId ?? randomUUID();
         const launched = await this.#options.launcher
             .launch({
-            directory: this.#runtimeRoot.path,
+            directory: this.#resources.runtimeRoot.path,
             socketPath,
             token: this.#token,
             runId,
         }, { signal: deadline.signal })
             .catch((cause) => err(new HopperStartError({ cause })));
         if (!launched.ok) {
-            await this.#cleanup();
-            return deadline.signal.aborted
-                ? err(startupInterruption(deadline))
-                : launched;
+            return this.#startupFailure(deadline.signal.aborted
+                ? startupInterruption(deadline)
+                : launched.error);
         }
-        this.#launch = launched.value;
+        this.#resources.launch = launched.value;
         this.#attachLauncher(launched.value);
+        const ownership = launched.value.ownership;
+        if (ownership !== undefined) {
+            try {
+                await writeFileAtomic(join(this.#resources.runtimeRoot.path, "ownership.json"), `${JSON.stringify({
+                    run_id: runId,
+                    pid: ownership.leaderPid,
+                    process_group_id: ownership.processGroupId,
+                    parent_pid: process.pid,
+                    launcher: launched.value.launcherCommand ?? null,
+                    created_at: new Date().toISOString(),
+                })}\n`, { encoding: "utf8", mode: 0o600 });
+            }
+            catch (cause) {
+                return this.#startupFailure(new HopperStartError({ cause }));
+            }
+        }
         const connected = await this.#connect(socketPath, deadline);
         if (!connected.ok) {
-            await this.#cleanup();
-            return connected;
+            return this.#startupFailure(connected.error);
         }
         const remainingMs = deadline.remainingMs();
         if (remainingMs <= 0) {
-            await this.#cleanup();
-            return err(new HopperTimeoutError(this.#options.startupTimeoutMs));
+            return this.#startupFailure(new HopperTimeoutError(this.#options.startupTimeoutMs));
         }
         const health = await this.#request("health", {}, {
             timeoutMs: remainingMs,
             signal: deadline.signal,
         });
         if (!health.ok) {
-            await this.#cleanup();
-            return deadline.signal.aborted
-                ? err(startupInterruption(deadline))
-                : health;
+            return this.#startupFailure(deadline.signal.aborted ? startupInterruption(deadline) : health.error);
         }
         const parsed = parseHopperServerInfo(health.value, runId);
-        if (parsed.ok)
-            await this.#lineage.observe(this.#launch);
-        else
-            await this.#cleanup();
+        if (!parsed.ok)
+            return this.#startupFailure(parsed.error);
+        await this.#lineage.observe(this.#resources.launch);
         return parsed;
     }
+    async #startupFailure(primary) {
+        this.#rememberStartupFailure(primary);
+        const closed = await this.#cleanup();
+        return err(closed.ok
+            ? primary
+            : analysisErrorWithCleanupFailure(primary, closed.error, "open_binary"));
+    }
+    #rememberStartupFailure(failure) {
+        if (failure instanceof HopperProcessError)
+            this.#rememberProcessFailure(failure, []);
+        else if (this.#operationFailure === undefined &&
+            (failure instanceof HopperTimeoutError ||
+                failure instanceof HopperStartError))
+            this.#operationFailure = {
+                state: failure instanceof HopperTimeoutError ? "not_started" : "unknown",
+                exitCode: null,
+                startupFailure: true,
+                requests: [],
+            };
+    }
     /** Invoke one declared operation, returning timeout and cancellation as values. */
     async callTool(name, arguments_ = {}, options = {}) {
         const started = await this.start(options.signal);
@@ -305,12 +329,8 @@ export class HopperClient {
             ? err(new AnalysisCapabilityUnavailableError("hopper", name, result.error.safeMessage))
             : result;
     }
-    /** Stop the bridge, settle outstanding requests, and remove session artifacts. */
-    close() {
-        return this.closeWithOutcome().then(() => undefined);
-    }
     /** Stop the bridge and report whether every owned resource was verified clean. */
-    closeWithOutcome(options = {}) {
+    close(options = {}) {
         const starting = this.#startPromise;
         const controller = this.#startupController;
         controller?.abort();
@@ -338,9 +358,7 @@ export class HopperClient {
         try {
             return await cleanupHopperSession({
                 socket: this.#socket,
-                launch: this.#launch,
-                processSupervisor: this.#process,
-                runtimeRoot: this.#runtimeRoot,
+                resources: this.#resources,
                 activeRequest: this.#requests.activity(),
                 progress: options.progress,
                 logger: this.#logger,
@@ -356,14 +374,16 @@ export class HopperClient {
             });
         }
         finally {
-            this.#socket = undefined;
-            this.#process = undefined;
-            this.#launch = undefined;
-            this.#runtimeRoot = undefined;
-            this.#token = undefined;
-            this.#responses.reset();
-            this.#launcherExitCode = undefined;
-            this.#launcherFailureDiagnostic = undefined;
+            if (this.#socket?.destroyed === true)
+                this.#socket = undefined;
+            if (this.#socket === undefined)
+                this.#token = undefined;
+            if (this.#socket === undefined)
+                this.#responses.reset();
+            if (this.#resources.processSupervisor === undefined) {
+                this.#launcherExitCode = undefined;
+                this.#launcherFailureDiagnostic = undefined;
+            }
             this.#closing = false;
         }
     }
@@ -374,10 +394,10 @@ export class HopperClient {
             if (this.#closing)
                 return err(new HopperProcessError(null));
             if (this.#launcherExitCode !== undefined &&
-                this.#launch !== undefined &&
-                (this.#launch.providerLifetime === "launcher-process" ||
+                this.#resources.launch !== undefined &&
+                (this.#resources.launch.providerLifetime === "launcher-process" ||
                     this.#launcherExitCode !== 0)) {
-                const failure = await this.#launcherStartupFailure(this.#launch.providerLifetime === "launcher-process", this.#launcherExitCode, deadline);
+                const failure = await this.#launcherStartupFailure(this.#resources.launch.providerLifetime === "launcher-process", this.#launcherExitCode, deadline);
                 return deadline.interruption === "cancelled"
                     ? err(await this.#startupInterruption(deadline))
                     : err(failure);
@@ -406,10 +426,11 @@ export class HopperClient {
     async #startupInterruption(deadline) {
         if (deadline.interruption === "cancelled")
             return new HopperCancelledError();
-        return new HopperTimeoutError(deadline.timeoutMs, undefined, undefined, "not_started", "launch", this.#launcherOutcome((await this.#process?.waitForOutputClose(0)) ?? false));
+        return new HopperTimeoutError(deadline.timeoutMs, undefined, undefined, "not_started", "launch", this.#launcherOutcome((await this.#resources.processSupervisor?.waitForOutputClose(0)) ??
+            false));
     }
     #launcherOutcome(outputClosed) {
-        const snapshot = this.#process?.snapshot();
+        const snapshot = this.#resources.processSupervisor?.snapshot();
         const token = this.#token;
         if (snapshot === undefined)
             return undefined;
@@ -426,7 +447,7 @@ export class HopperClient {
         };
     }
     async #launcherStartupFailure(ownsProviderLifetime, exitCode, deadline) {
-        const process = this.#process;
+        const process = this.#resources.processSupervisor;
         // Descendants may inherit the helper's pipes. Bound drainage independently
         // from readiness, and report whether producer output actually closed.
         const outputClosed = (await process?.waitForOutputClose(Math.min(1_000, deadline.remainingMs()))) ?? false;
@@ -502,7 +523,7 @@ export class HopperClient {
         socket.off("close", this.#onSocketClose);
     }
     #attachLauncher(launch) {
-        this.#process = new ProviderProcessSupervisor(launch, {
+        this.#resources.processSupervisor = new ProviderProcessSupervisor(launch, {
             onDiagnostic: (event) => this.#onLauncherDiagnostic(launch, event),
         });
     }

package/dist/hopper/HopperMachOImage.js

@@ -18,7 +18,7 @@ export const hopperMachOImageSchema = z.strictObject({
 });
 /** Validate the selected FAT64 slice without depending on Apple's lipo tool. */
 export const resolveHopperMachOImage = async (target, signal) => {
-    const invalid = (reason) => err(new BinaryTargetError(target.path, reason));
+    const invalid = (reason, cause) => err(new BinaryTargetError(target.path, reason, cause === undefined ? undefined : { cause }));
     if (signal?.aborted)
         return err(new AnalysisCancelledError("open_binary"));
     let file;
@@ -26,7 +26,8 @@ export const resolveHopperMachOImage = async (target, signal) => {
         file = await open(target.path, "r");
     }
     catch (cause) {
-        return invalid(`Cannot read FAT64 source for Hopper image preparation: ${cause instanceof Error ? cause.message : String(cause)}`);
+        // Keep the OS error so a read-permission denial reports access_denied.
+        return invalid(`Cannot read FAT64 source for Hopper image preparation: ${cause instanceof Error ? cause.message : String(cause)}`, cause);
     }
     try {
         const read = async (offset, length) => {

package/dist/hopper/HopperProvider.js

@@ -1,8 +1,9 @@
+import { snapshotEnvironment } from "../process/snapshotEnvironment.js";
 import { fileURLToPath } from "node:url";
 import { accessSync, constants } from "node:fs";
 import { createAnalysisExecution } from "../application/AnalysisProvider.js";
 import { AnalysisCapabilityUnavailableError } from "../domain/analysisErrorCore.js";
-import { err } from "../domain/result.js";
+import { err, ok } from "../domain/result.js";
 import { HopperApplicationLauncher } from "./BridgeLauncher.js";
 import { hopperLoaderArgsForTarget, resolveHopperAnalysisProfile, } from "./HopperAnalysisProfile.js";
 import { mapHopperFileOffset } from "./HopperFileOffset.js";
@@ -10,26 +11,26 @@ import { HopperRegexSearch } from "./HopperRegexSearch.js";
 import { HopperClient } from "./HopperClient.js";
 import { hopperMachOImageSchema } from "./HopperMachOImage.js";
 import { CAPABILITIES, HOPPER_PROVIDER_IDENTITY, } from "./HopperProviderCapabilities.js";
-export { HOPPER_PROVIDER_IDENTITY, HOPPER_OPERATIONS, } from "./HopperProviderCapabilities.js";
-const IDENTITY = HOPPER_PROVIDER_IDENTITY;
 /** Concrete analysis provider backed by REA's private Hopper bridge. */
 export class HopperProvider {
     config;
     logger;
     platform;
+    environment;
     /**
      * Host platform, injected so availability and launch-mode decisions can be
      * exercised for any host rather than only the machine running the suite.
      * Mirrors `GhidraProvider`, which already threads its installation host's
      * platform the same way.
      */
-    constructor(config, logger, platform = process.platform) {
+    constructor(config, logger, environment, platform = process.platform) {
         this.config = config;
         this.logger = logger;
         this.platform = platform;
+        this.environment = snapshotEnvironment(environment, platform);
     }
     identity() {
-        return IDENTITY;
+        return HOPPER_PROVIDER_IDENTITY;
     }
     capabilities() {
         return CAPABILITIES;
@@ -104,15 +105,15 @@ export class HopperProvider {
         return resolveHopperAnalysisProfile(target, {
             launcherPath: this.config.hopperLauncherPath,
             loaderArgsOverride: this.config.hopperLoaderArgs,
-            provider: IDENTITY,
+            provider: HOPPER_PROVIDER_IDENTITY,
             ...(options?.signal === undefined ? {} : { signal: options.signal }),
         });
     }
     createClient(target, profile, context) {
         if (target.kind !== "executable" && target.kind !== "database")
             return {
-                execute: (operation) => Promise.resolve(err(new AnalysisCapabilityUnavailableError(IDENTITY.id, operation, `Hopper cannot open ${target.kind} targets directly. Inventory or extract the artifact first.`))),
-                close: () => Promise.resolve(),
+                execute: (operation) => Promise.resolve(err(new AnalysisCapabilityUnavailableError(HOPPER_PROVIDER_IDENTITY.id, operation, `Hopper cannot open ${target.kind} targets directly. Inventory or extract the artifact first.`))),
+                close: () => Promise.resolve(ok(null)),
             };
         const preparation = profile?.parameters.prepared_image;
         const parsedImage = preparation === undefined
@@ -120,8 +121,8 @@ export class HopperProvider {
             : hopperMachOImageSchema.safeParse(preparation);
         if (parsedImage?.success === false)
             return {
-                execute: (operation) => Promise.resolve(err(new AnalysisCapabilityUnavailableError(IDENTITY.id, operation, "Hopper prepared-image profile is malformed; resolve the analysis profile again."))),
-                close: () => Promise.resolve(),
+                execute: (operation) => Promise.resolve(err(new AnalysisCapabilityUnavailableError(HOPPER_PROVIDER_IDENTITY.id, operation, "Hopper prepared-image profile is malformed; resolve the analysis profile again."))),
+                close: () => Promise.resolve(ok(null)),
             };
         const preparedImage = parsedImage?.data;
         const container = preparedImage === undefined
@@ -133,11 +134,12 @@ export class HopperProvider {
         if (!derivedLoaderArgs.ok)
             return {
                 execute: () => Promise.resolve(err(derivedLoaderArgs.error)),
-                close: () => Promise.resolve(),
+                close: () => Promise.resolve(ok(null)),
             };
-        const executionProvider = profile?.provider ?? IDENTITY;
+        const executionProvider = profile?.provider ?? HOPPER_PROVIDER_IDENTITY;
         const client = new HopperClient({
             launcher: new HopperApplicationLauncher({
+                environment: this.environment,
                 launcherPath: this.config.hopperLauncherPath,
                 targetPath: target.path,
                 targetKind: target.kind,
@@ -229,13 +231,9 @@ export class HopperProvider {
                 ];
             },
             operationHealthSnapshot: () => client.operationHealth(),
-            closeWithOutcome: async (options) => {
+            close: async (options) => {
                 await regexSearch.close();
-                return client.closeWithOutcome(options);
-            },
-            close: async () => {
-                await regexSearch.close();
-                await client.close();
+                return client.close(options);
             },
         };
     }

package/dist/hopper/HopperRegexSearch.js

@@ -9,11 +9,6 @@ const MATCHING_DEADLINE_MS = 5_000;
 const inputSchema = z.strictObject({
     ...analysisSearchInput,
     mode: z.literal("regex"),
-    document: z.string().nullish(),
-    case_sensitive: z
-        .boolean()
-        .nullish()
-        .transform((value) => value ?? false),
 });
 const replySchema = z.discriminatedUnion("status", [
     z.strictObject({
@@ -68,7 +63,9 @@ export class HopperRegexSearch {
                     },
                 }),
         };
-        const inventory = await this.client.callTool(operation === "search_strings" ? "list_strings" : "list_procedures", input.data.document == null ? {} : { document: input.data.document }, inventoryOptions);
+        const inventory = await this.client.callTool(operation === "search_strings" ? "list_strings" : "list_procedures", input.data.document === undefined
+            ? {}
+            : { document: input.data.document }, inventoryOptions);
         if (!inventory.ok)
             return inventory;
         const parsed = z.array(analysisStringSchema).safeParse(inventory.value);