rea-agents 1.6.0 → 2.0.0

package/dist/hopper/HopperClient.js

@@ -1,11 +1,16 @@
 import { randomBytes, randomUUID } from "node:crypto";
-import { access, mkdtemp, rm } from "node:fs/promises";
-import { createConnection } from "node:net";
+import { access } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { HopperCancelledError, HopperProcessError, HopperProtocolError, HopperStartError, hopperStartupFailure, HopperTimeoutError, } from "../domain/errors.js";
 import { err, ok } from "../domain/result.js";
 import { silentLogger } from "../logger.js";
+import { PendingOperations } from "../process/PendingOperations.js";
+import { PrivateRuntimeRoot } from "../process/PrivateRuntimeRoot.js";
+import { ProviderStartupDeadline } from "../process/ProviderDeadline.js";
+import { ProviderProcessSupervisor, } from "../process/ProviderProcess.js";
+import { isHopperCleanupRequired, isHopperShutdownAcknowledgement, parseHopperServerInfo, } from "./HopperSessionValues.js";
+import { connectHopperSocketOnce } from "./HopperSocketConnection.js";
 import { parseResponseLine, responseResult } from "./protocol.js";
 const MAX_LINE_BYTES = 10 * 1024 * 1024;
 const SHUTDOWN_TIMEOUT_MS = 30_000;
@@ -20,11 +25,12 @@ const SESSION_ROOT = process.platform === "darwin" ? "/tmp" : tmpdir();
  */
 export class HopperClient {
     #options;
-    #pending = new Map();
+    #pending = new PendingOperations();
     #logger;
     #socket;
     #launch;
-    #directory;
+    #process;
+    #runtimeRoot;
     #token;
     #nextId = 1;
     #buffer = "";
@@ -33,6 +39,16 @@ export class HopperClient {
     #startupController;
     #startPromise;
     #closePromise;
+    #onSocketData = (chunk) => {
+        this.#onData(chunk);
+    };
+    #onSocketError = () => {
+        this.#failAll(new HopperProcessError(null));
+    };
+    #onSocketClose = () => {
+        if (!this.#closing)
+            this.#failAll(new HopperProcessError(null));
+    };
     constructor(options) {
         this.#logger = options.logger ?? silentLogger;
         this.#options = {
@@ -49,68 +65,104 @@ export class HopperClient {
         if (this.#startPromise !== undefined)
             return this.#startPromise;
         const controller = new AbortController();
-        const startupSignal = signal === undefined
-            ? controller.signal
-            : AbortSignal.any([signal, controller.signal]);
-        const started = this.#start(startupSignal);
+        const onAbort = () => controller.abort(signal?.reason);
+        if (signal?.aborted === true)
+            onAbort();
+        else
+            signal?.addEventListener("abort", onAbort, { once: true });
+        const started = this.#start(controller.signal);
         this.#startupController = controller;
         this.#startPromise = started;
-        void started.then((result) => {
-            if (!result.ok && this.#startPromise === started) {
+        const release = () => {
+            signal?.removeEventListener("abort", onAbort);
+        };
+        const reset = () => {
+            if (this.#startPromise === started) {
                 this.#startPromise = undefined;
                 if (this.#startupController === controller) {
                     this.#startupController = undefined;
                 }
             }
+        };
+        void started.then((result) => {
+            release();
+            if (!result.ok)
+                reset();
+        }, () => {
+            release();
+            reset();
         });
         return started;
     }
     async #start(signal) {
         if (isAborted(signal))
             return err(new HopperCancelledError());
-        if (this.#socket !== undefined || this.#directory !== undefined) {
+        if (this.#socket !== undefined || this.#runtimeRoot !== undefined) {
             return err(new HopperProtocolError("Hopper client is already started"));
         }
+        const deadline = new ProviderStartupDeadline(this.#options.startupTimeoutMs, signal);
         try {
-            this.#directory = await mkdtemp(join(SESSION_ROOT, "rea-"));
+            return await this.#startWithin(deadline);
+        }
+        finally {
+            deadline.dispose();
+        }
+    }
+    async #startWithin(deadline) {
+        try {
+            this.#runtimeRoot = await PrivateRuntimeRoot.create({
+                parent: SESSION_ROOT,
+                prefix: "rea-",
+            });
         }
         catch (cause) {
             return err(new HopperStartError({ cause }));
         }
-        if (isAborted(signal)) {
+        if (deadline.signal.aborted) {
             await this.#cleanup();
-            return err(new HopperCancelledError());
+            return err(startupInterruption(deadline));
         }
-        const socketPath = join(this.#directory, "bridge.sock");
+        const socketPath = join(this.#runtimeRoot.path, "bridge.sock");
         this.#token = randomBytes(32).toString("hex");
         this.#launcherExitCode = undefined;
         const runId = randomUUID();
-        const launched = await this.#options.launcher.launch({
-            directory: this.#directory,
+        const launched = await this.#options.launcher
+            .launch({
+            directory: this.#runtimeRoot.path,
             socketPath,
             token: this.#token,
             runId,
-        }, signal === undefined ? {} : { signal });
+        }, { signal: deadline.signal })
+            .catch((cause) => err(new HopperStartError({ cause })));
         if (!launched.ok) {
             await this.#cleanup();
-            return launched;
+            return deadline.signal.aborted
+                ? err(startupInterruption(deadline))
+                : launched;
         }
         this.#launch = launched.value;
         this.#attachLauncher(launched.value);
-        const connected = await this.#connect(socketPath, signal);
+        const connected = await this.#connect(socketPath, deadline);
         if (!connected.ok) {
             await this.#cleanup();
             return connected;
         }
+        const remainingMs = deadline.remainingMs();
+        if (remainingMs <= 0) {
+            await this.#cleanup();
+            return err(new HopperTimeoutError(this.#options.startupTimeoutMs));
+        }
         const health = await this.#request("health", {}, {
-            timeoutMs: this.#options.startupTimeoutMs,
-            ...(signal === undefined ? {} : { signal }),
+            timeoutMs: remainingMs,
+            signal: deadline.signal,
         });
         if (!health.ok) {
             await this.#cleanup();
-            return health;
+            return deadline.signal.aborted
+                ? err(startupInterruption(deadline))
+                : health;
         }
-        const parsed = parseServerInfo(health.value, runId);
+        const parsed = parseHopperServerInfo(health.value, runId);
         if (!parsed.ok)
             await this.#cleanup();
         return parsed;
@@ -148,43 +200,45 @@ export class HopperClient {
         this.#closing = true;
         try {
             const socket = this.#socket;
-            let cleanupAttempted = false;
+            let cleanupResult;
             if (socket !== undefined && !socket.destroyed) {
                 const shutdown = await this.#request("shutdown", {}, { timeoutMs: SHUTDOWN_TIMEOUT_MS }).catch(() => err(new HopperProcessError(null)));
                 if (shutdown.ok &&
-                    isCleanupRequired(shutdown.value) &&
+                    isHopperCleanupRequired(shutdown.value) &&
                     this.#launch?.shutdownByCleanup === true &&
                     this.#launch.cleanup !== undefined) {
-                    cleanupAttempted = true;
-                    const cleanup = await this.#launch.cleanup();
-                    if (!cleanup.cleaned) {
+                    cleanupResult = await this.#launch
+                        .cleanup()
+                        .catch(providerCleanupFailure);
+                    if (!cleanupResult.cleaned) {
                         await this.#fallbackDocumentShutdown();
-                        const retried = await this.#launch.cleanup();
-                        if (!retried.cleaned)
-                            this.#logger.warn({ reason: retried.reason }, "Owned launcher cleanup failed closed");
+                        cleanupResult = await this.#launch
+                            .cleanup()
+                            .catch(providerCleanupFailure);
                     }
                 }
-                else if (!shutdown.ok || !isShutdownAcknowledgement(shutdown.value))
+                else if (!shutdown.ok ||
+                    !isHopperShutdownAcknowledgement(shutdown.value))
                     this.#logger.warn({ status: shutdown.ok ? "invalid-acknowledgement" : "failed" }, "Hopper document shutdown was not confirmed");
             }
             this.#failAll(new HopperProcessError(null));
+            if (socket !== undefined)
+                this.#detachSocket(socket);
             socket?.destroy();
             this.#socket = undefined;
-            if (this.#launch?.ownsProcessLifetime === true) {
-                if (this.#launch.cleanup !== undefined && !cleanupAttempted) {
-                    const cleanup = await this.#launch.cleanup();
-                    if (!cleanup.cleaned)
-                        this.#logger.warn({ reason: cleanup.reason }, "Owned launcher cleanup failed closed");
-                }
-                else
-                    this.#launch.process.kill("SIGTERM");
+            if (this.#process !== undefined) {
+                const stopped = await this.#process.stop(cleanupResult === undefined ? {} : { cleanupResult });
+                if (stopped.status === "incomplete")
+                    this.#logger.warn({ reason: stopped.reason }, "Owned launcher cleanup failed closed");
             }
+            this.#process = undefined;
             this.#launch = undefined;
-            if (this.#directory !== undefined) {
-                await rm(this.#directory, { recursive: true, force: true });
-                this.#directory = undefined;
-            }
+            const runtimeRoot = this.#runtimeRoot;
+            this.#runtimeRoot = undefined;
+            await runtimeRoot?.close();
             this.#token = undefined;
+            this.#buffer = "";
+            this.#launcherExitCode = undefined;
         }
         finally {
             this.#closing = false;
@@ -192,14 +246,13 @@ export class HopperClient {
     }
     async #fallbackDocumentShutdown() {
         const fallback = await this.#request("shutdown_document", {}, { timeoutMs: SHUTDOWN_TIMEOUT_MS }).catch(() => err(new HopperProcessError(null)));
-        if (!fallback.ok || !isShutdownAcknowledgement(fallback.value))
+        if (!fallback.ok || !isHopperShutdownAcknowledgement(fallback.value))
             this.#logger.warn({ status: fallback.ok ? "invalid-acknowledgement" : "failed" }, "Hopper document shutdown fallback was not confirmed");
     }
-    async #connect(socketPath, signal) {
-        const deadline = Date.now() + this.#options.startupTimeoutMs;
-        while (Date.now() < deadline) {
-            if (signal?.aborted === true)
-                return err(new HopperCancelledError());
+    async #connect(socketPath, deadline) {
+        while (deadline.remainingMs() > 0) {
+            if (deadline.signal.aborted)
+                return err(startupInterruption(deadline));
             if (this.#closing)
                 return err(new HopperProcessError(null));
             if (this.#launcherExitCode !== undefined &&
@@ -209,18 +262,18 @@ export class HopperClient {
                 await access(socketPath);
             }
             catch {
-                if (!(await waitForDelay(50, signal)))
-                    return err(new HopperCancelledError());
+                if ((await deadline.wait(50)) === "aborted")
+                    return err(startupInterruption(deadline));
                 continue;
             }
-            const attempt = await connectOnce(socketPath);
+            const attempt = await connectHopperSocketOnce(socketPath, deadline.signal);
             if (attempt.ok) {
                 this.#socket = attempt.value;
                 this.#attachSocket(attempt.value);
                 return ok(undefined);
             }
-            if (!(await waitForDelay(50, signal)))
-                return err(new HopperCancelledError());
+            if ((await deadline.wait(50)) === "aborted")
+                return err(startupInterruption(deadline));
         }
         return err(new HopperTimeoutError(this.#options.startupTimeoutMs));
     }
@@ -235,28 +288,15 @@ export class HopperClient {
         const id = this.#nextId++;
         const startedAt = performance.now();
         const timeoutMs = options.timeoutMs ?? this.#options.requestTimeoutMs;
-        const response = new Promise((resolve) => {
-            const onAbort = options.signal === undefined
-                ? undefined
-                : () => {
-                    this.#abandon(id, err(new HopperCancelledError()));
-                };
-            const timer = setTimeout(() => {
-                this.#abandon(id, err(new HopperTimeoutError(timeoutMs)));
-            }, timeoutMs);
-            this.#pending.set(id, {
-                resolve,
-                timer,
-                signal: options.signal,
-                onAbort,
-            });
-            options.signal?.addEventListener("abort", onAbort ?? (() => undefined), {
-                once: true,
-            });
+        const response = this.#pending.wait(id, {
+            timeoutMs,
+            ...(options.signal === undefined ? {} : { signal: options.signal }),
+            timeoutValue: () => err(new HopperTimeoutError(timeoutMs)),
+            cancelledValue: () => err(new HopperCancelledError()),
         });
         socket.write(`${JSON.stringify({ id, token, method, params })}\n`, (cause) => {
             if (cause !== undefined && cause !== null)
-                this.#settle(id, err(new HopperProcessError(null)));
+                this.#pending.settle(id, err(new HopperProcessError(null)));
         });
         const result = await response;
         this.#logger[result.ok ? "debug" : "warn"]({
@@ -269,31 +309,41 @@ export class HopperClient {
     }
     #attachSocket(socket) {
         socket.setEncoding("utf8");
-        socket.on("data", (chunk) => {
-            this.#onData(chunk);
-        });
-        socket.on("error", () => {
-            this.#failAll(new HopperProcessError(null));
-        });
-        socket.on("close", () => {
-            if (!this.#closing)
-                this.#failAll(new HopperProcessError(null));
-        });
+        socket.on("data", this.#onSocketData);
+        socket.on("error", this.#onSocketError);
+        socket.on("close", this.#onSocketClose);
+    }
+    #detachSocket(socket) {
+        socket.off("data", this.#onSocketData);
+        socket.off("error", this.#onSocketError);
+        socket.off("close", this.#onSocketClose);
     }
     #attachLauncher(launch) {
-        launch.process.stderr?.on("data", (chunk) => {
+        this.#process = new ProviderProcessSupervisor(launch, {
+            onDiagnostic: (event) => this.#onLauncherDiagnostic(launch, event),
+        });
+    }
+    #onLauncherDiagnostic(launch, event) {
+        if (event.type === "output" && event.stream === "stderr") {
             this.#options.onDiagnostic?.({
                 type: "launcher-stderr",
-                bytes: chunk.byteLength,
+                bytes: event.bytes,
             });
+            return;
+        }
+        if (event.type === "error") {
+            this.#logger.warn({ message: event.message }, "Hopper launcher process emitted an error");
+            return;
+        }
+        if (event.type !== "exit")
+            return;
+        this.#launcherExitCode = event.code;
+        this.#options.onDiagnostic?.({
+            type: "launcher-exit",
+            code: event.code,
         });
-        launch.process.on("exit", (code) => {
-            this.#launcherExitCode = code;
-            this.#options.onDiagnostic?.({ type: "launcher-exit", code });
-            if (launch.ownsProcessLifetime && !this.#closing) {
-                this.#failAll(new HopperProcessError(code));
-            }
-        });
+        if (launch.ownsProcessLifetime && !this.#closing)
+            this.#failAll(new HopperProcessError(event.code));
     }
     #onData(chunk) {
         this.#buffer += chunk;
@@ -325,81 +375,23 @@ export class HopperClient {
             }
             return;
         }
-        this.#settle(parsed.value.id, responseResult(parsed.value));
+        this.#pending.settle(parsed.value.id, responseResult(parsed.value));
     }
     #abortProtocol(message, cause) {
         this.#failAll(new HopperProtocolError(message, { cause }));
         this.#socket?.destroy();
     }
-    #settle(id, result) {
-        const pending = this.#pending.get(id);
-        if (pending === undefined)
-            return;
-        this.#pending.delete(id);
-        clearTimeout(pending.timer);
-        if (pending.signal !== undefined && pending.onAbort !== undefined) {
-            pending.signal.removeEventListener("abort", pending.onAbort);
-        }
-        pending.resolve(result);
-    }
-    #abandon(id, result) {
-        if (!this.#pending.has(id))
-            return;
-        this.#settle(id, result);
-    }
     #failAll(error) {
-        for (const id of this.#pending.keys())
-            this.#settle(id, err(error));
+        this.#pending.failAll(() => err(error));
     }
 }
 const isAborted = (signal) => signal?.aborted === true;
-const waitForDelay = (milliseconds, signal) => {
-    if (signal?.aborted === true)
-        return Promise.resolve(false);
-    return new Promise((resolve) => {
-        const timer = setTimeout(() => {
-            signal?.removeEventListener("abort", onAbort);
-            resolve(true);
-        }, milliseconds);
-        const onAbort = () => {
-            clearTimeout(timer);
-            resolve(false);
-        };
-        signal?.addEventListener("abort", onAbort, { once: true });
-    });
-};
-const connectOnce = async (socketPath) => new Promise((resolve) => {
-    const socket = createConnection(socketPath);
-    socket.once("connect", () => {
-        resolve(ok(socket));
-    });
-    socket.once("error", (cause) => {
-        socket.destroy();
-        resolve(err(new HopperStartError({ cause })));
-    });
+const startupInterruption = (deadline) => deadline.cancelled
+    ? new HopperCancelledError()
+    : new HopperTimeoutError(deadline.timeoutMs);
+const providerCleanupFailure = (cause) => ({
+    cleaned: false,
+    reason: cause instanceof Error
+        ? `owned provider cleanup failed: ${cause.message}`
+        : "owned provider cleanup failed",
 });
-const isShutdownAcknowledgement = (value) => {
-    if (typeof value !== "object" || value === null || Array.isArray(value))
-        return false;
-    if (value.shutdown !== true)
-        return false;
-    if (value.analysis_stopped === true && value.document_closed === true)
-        return true;
-    return false;
-};
-const isCleanupRequired = (value) => typeof value === "object" &&
-    value !== null &&
-    !Array.isArray(value) &&
-    value.shutdown === true &&
-    value.cleanup_required === true;
-const parseServerInfo = (value, expectedRunId) => {
-    if (typeof value === "object" &&
-        value !== null &&
-        !Array.isArray(value) &&
-        value.name === "REA Hopper bridge" &&
-        typeof value.version === "string" &&
-        value.run_id === expectedRunId) {
-        return ok({ name: value.name, version: value.version });
-    }
-    return err(new HopperProtocolError("Hopper bridge health result is invalid"));
-};

package/dist/hopper/HopperProvider.js

@@ -1,15 +1,19 @@
 import { fileURLToPath } from "node:url";
+import { accessSync, constants } from "node:fs";
 import { createAnalysisExecution } from "../application/AnalysisProvider.js";
 import { AnalysisCapabilityUnavailableError } from "../domain/errors.js";
 import { err } from "../domain/result.js";
 import { ENHANCED_TOOL_CONTRACTS, OFFICIAL_TOOL_CONTRACTS, } from "../contracts/toolContracts.js";
 import { HopperApplicationLauncher } from "./BridgeLauncher.js";
+import { hopperLoaderArgsForTarget, resolveHopperAnalysisProfile, } from "./HopperAnalysisProfile.js";
 import { HopperClient } from "./HopperClient.js";
-const IDENTITY = Object.freeze({
+/** Public identity committed by every Hopper-backed observation. */
+export const HOPPER_PROVIDER_IDENTITY = Object.freeze({
     id: "hopper",
     name: "Hopper Disassembler",
     version: null,
 });
+const IDENTITY = HOPPER_PROVIDER_IDENTITY;
 const MUTATING_OPERATIONS = new Set([
     "set_address_name",
     "set_addresses_names",
@@ -18,11 +22,12 @@ const MUTATING_OPERATIONS = new Set([
     "set_inline_comment",
     "unset_bookmark",
 ]);
-const PROVIDER_TOOL_CONTRACTS = [
+/** Tool contracts implemented directly by the Hopper adapter. */
+export const HOPPER_PROVIDER_TOOL_CONTRACTS = Object.freeze([
     ...OFFICIAL_TOOL_CONTRACTS,
     ...ENHANCED_TOOL_CONTRACTS.filter((contract) => contract.name === "analyze_function"),
-];
-const CAPABILITIES = Object.freeze(PROVIDER_TOOL_CONTRACTS.map((contract) => Object.freeze({
+]);
+const CAPABILITIES = Object.freeze(HOPPER_PROVIDER_TOOL_CONTRACTS.map((contract) => Object.freeze({
     provider: IDENTITY,
     operation: contract.name,
     inputContractVersion: 1,
@@ -63,12 +68,98 @@ export class HopperProvider {
     capabilities() {
         return CAPABILITIES;
     }
-    createClient(target) {
+    inspectAvailability() {
+        const diagnostics = {
+            launcher_path: this.config.hopperLauncherPath,
+            platform: process.platform,
+        };
+        if (process.platform !== "darwin" && process.platform !== "linux")
+            return {
+                status: "unavailable",
+                code: "unsupported_host",
+                reason: `Hopper integration is not supported on ${process.platform}.`,
+                diagnostics,
+            };
+        try {
+            accessSync(this.config.hopperLauncherPath, constants.X_OK);
+            return {
+                status: "available",
+                code: null,
+                reason: null,
+                diagnostics,
+            };
+        }
+        catch {
+            return {
+                status: "unavailable",
+                code: "executable_missing",
+                reason: `Hopper launcher is missing or not executable: ${this.config.hopperLauncherPath}`,
+                diagnostics,
+            };
+        }
+    }
+    inspectTargetSupport(target) {
+        const diagnostics = {
+            target_kind: target.kind,
+            target_format: target.format,
+            architecture: target.architecture ?? null,
+        };
+        if (target.kind !== "executable" && target.kind !== "database")
+            return {
+                status: "unsupported",
+                code: "target_kind_unsupported",
+                reason: `Hopper cannot directly analyze ${target.kind} targets.`,
+                diagnostics,
+            };
+        if (target.kind === "database")
+            return {
+                status: "supported",
+                code: null,
+                reason: null,
+                diagnostics,
+            };
+        if (!["mach-o", "elf", "pe"].includes(target.format))
+            return {
+                status: "unsupported",
+                code: "target_format_unsupported",
+                reason: `Hopper cannot open ${target.format} through this adapter.`,
+                diagnostics,
+            };
+        if (target.architecture === undefined)
+            return {
+                status: "unsupported",
+                code: "architecture_unsupported",
+                reason: "Hopper requires a supported concrete target architecture.",
+                diagnostics,
+            };
+        return {
+            status: "supported",
+            code: null,
+            reason: null,
+            diagnostics,
+        };
+    }
+    resolveAnalysisProfile(target, options) {
+        return resolveHopperAnalysisProfile(target, {
+            launcherPath: this.config.hopperLauncherPath,
+            loaderArgsOverride: this.config.hopperLoaderArgs,
+            provider: IDENTITY,
+            ...(options?.signal === undefined ? {} : { signal: options.signal }),
+        });
+    }
+    createClient(target, profile) {
         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(),
             };
+        const derivedLoaderArgs = hopperLoaderArgsForTarget(target);
+        if (!derivedLoaderArgs.ok)
+            return {
+                execute: () => Promise.resolve(err(derivedLoaderArgs.error)),
+                close: () => Promise.resolve(),
+            };
+        const executionProvider = profile?.provider ?? IDENTITY;
         const client = new HopperClient({
             launcher: new HopperApplicationLauncher({
                 launcherPath: this.config.hopperLauncherPath,
@@ -76,7 +167,7 @@ export class HopperProvider {
                 targetKind: target.kind,
                 loaderArgs: this.config.hopperLoaderArgs.length > 0
                     ? this.config.hopperLoaderArgs
-                    : target.loaderArgs,
+                    : derivedLoaderArgs.value,
                 bridgeScriptPath: fileURLToPath(new URL("../../bridge/hopper_bridge.py", import.meta.url)),
                 ...(process.platform === "linux"
                     ? {
@@ -93,7 +184,8 @@ export class HopperProvider {
                 return result.ok
                     ? {
                         ok: true,
-                        value: createAnalysisExecution(result.value, IDENTITY, {
+                        value: createAnalysisExecution(result.value, executionProvider, {
+                            ...(profile === undefined ? {} : { analysisProfile: profile }),
                             limitations: [
                                 "Results depend on Hopper's completed static analysis.",
                             ],

package/dist/hopper/HopperSessionValues.js

@@ -0,0 +1,27 @@
+import { HopperProtocolError } from "../domain/errors.js";
+import { err, ok } from "../domain/result.js";
+/** Validate the bridge identity and exact per-launch run identifier. */
+export const parseHopperServerInfo = (value, expectedRunId) => {
+    if (typeof value === "object" &&
+        value !== null &&
+        !Array.isArray(value) &&
+        value.name === "REA Hopper bridge" &&
+        typeof value.version === "string" &&
+        value.run_id === expectedRunId)
+        return ok({ name: value.name, version: value.version });
+    return err(new HopperProtocolError("Hopper bridge health result is invalid"));
+};
+/** Require Hopper to confirm both analysis and document shutdown. */
+export const isHopperShutdownAcknowledgement = (value) => {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return false;
+    if (value.shutdown !== true)
+        return false;
+    return value.analysis_stopped === true && value.document_closed === true;
+};
+/** Detect the verified Linux bridge response that requires group cleanup. */
+export const isHopperCleanupRequired = (value) => typeof value === "object" &&
+    value !== null &&
+    !Array.isArray(value) &&
+    value.shutdown === true &&
+    value.cleanup_required === true;