rea-agents 6.0.0 → 6.2.0

package/dist/hopper/HopperFileOffset.js

@@ -0,0 +1,237 @@
+import { createHash } from "node:crypto";
+import { constants } from "node:fs";
+import { open } from "node:fs/promises";
+import { z } from "zod";
+import { AnalysisAccessDeniedError, AnalysisArtifactChangedError, AnalysisCancelledError, AnalysisCapabilityUnavailableError, AnalysisOutputError, } from "../domain/analysisErrorCore.js";
+import { BinaryTargetError } from "../domain/configurationErrors.js";
+import { readFatSliceDeclarations, validateFatSlice, } from "../domain/apple/machoContainer.js";
+import { err, ok } from "../domain/result.js";
+const OPERATION = "address_to_file_offset";
+const MAX_FAT_ARCHITECTURES = 128;
+const PREFIX_BYTES = 8 + MAX_FAT_ARCHITECTURES * 32;
+const observationSchema = z.strictObject({
+    address: z.string().regex(/^0x[0-9a-f]+$/u),
+    provider_file_offset: z
+        .number()
+        .int()
+        .nonnegative()
+        .max(Number.MAX_SAFE_INTEGER),
+    provider_source_path: z.string().nullable(),
+    provider_image_header_hex: z
+        .string()
+        .regex(/^[a-f0-9]{24}$/u)
+        .nullable(),
+});
+/** Bind native image-relative offsets to coordinates in the admitted source bytes. */
+export async function mapHopperFileOffset(target, value, signal) {
+    const parsed = observationSchema.safeParse(value);
+    if (!parsed.success)
+        return err(new AnalysisOutputError(OPERATION, "Hopper's native file mapping observation is malformed"));
+    const observation = parsed.data;
+    const partial = (reason) => ({
+        operation: OPERATION,
+        ...observation,
+        original_file_offset: { available: false, reason },
+    });
+    const unavailable = (reason) => err(new AnalysisCapabilityUnavailableError("hopper", OPERATION, reason, {
+        partialObservation: partial(reason),
+    }));
+    if (target.kind !== "executable")
+        return unavailable("The selected database digest does not identify its original executable bytes. Open that executable to verify original-file coordinates; read_bytes still exposes the database's native bytes.");
+    if (signal?.aborted)
+        return err(new AnalysisCancelledError(OPERATION, {
+            partialObservation: partial("Source verification was cancelled"),
+        }));
+    try {
+        const captured = await snapshotFromPath(target.path, signal);
+        if (!captured.ok)
+            return err(new AnalysisArtifactChangedError(OPERATION, target.path, captured.error, {
+                partialObservation: partial(captured.error),
+            }));
+        const snapshot = captured.value;
+        if (signal?.aborted)
+            return err(new AnalysisCancelledError(OPERATION, {
+                partialObservation: partial("Source verification was cancelled"),
+            }));
+        if (snapshot.sha256 !== target.sha256) {
+            const reason = `Source ${target.path} differs from the admitted artifact: expected SHA-256 ${target.sha256}, observed ${snapshot.sha256}. Reopen the changed source for a new analysis identity.`;
+            return err(new AnalysisArtifactChangedError(OPERATION, target.path, reason, {
+                partialObservation: partial(reason),
+            }));
+        }
+        const mapped = originalOffset(snapshot, observation);
+        if (!mapped.ok)
+            return unavailable(mapped.error);
+        return ok({
+            address: observation.address,
+            file_offset: mapped.value + observation.provider_file_offset,
+            provider_file_offset: observation.provider_file_offset,
+            image_base_file_offset: mapped.value,
+            source_path: target.path,
+        });
+    }
+    catch (cause) {
+        if (signal?.aborted)
+            return err(new AnalysisCancelledError(OPERATION, {
+                cause,
+                partialObservation: partial("Source verification was cancelled"),
+            }));
+        const reason = `Cannot verify original source bytes: ${cause instanceof Error ? cause.message : String(cause)}`;
+        const code = typeof cause === "object" && cause !== null && "code" in cause
+            ? cause.code
+            : undefined;
+        if (code === "EACCES" || code === "EPERM")
+            return err(new AnalysisAccessDeniedError(OPERATION, target.path, code, {
+                cause,
+                partialObservation: partial(reason),
+            }));
+        return err(new BinaryTargetError(target.path, reason, {
+            cause,
+            partialObservation: partial(reason),
+        }));
+    }
+}
+async function snapshotFromPath(path, signal) {
+    const file = await open(path, constants.O_RDONLY | constants.O_NONBLOCK);
+    try {
+        if (!(await file.stat()).isFile())
+            return err(`Source ${path} is no longer a regular file. Restore the admitted executable or reopen a regular source.`);
+        return ok(await readSourceSnapshot(file, signal));
+    }
+    finally {
+        await file.close();
+    }
+}
+function fatLayout(prefix) {
+    const magic = prefix.length < 4 ? 0 : prefix.readUInt32BE(0);
+    if (![0xcafebabe, 0xbebafeca, 0xcafebabf, 0xbfbafeca].includes(magic))
+        return ok(null);
+    if (prefix.length < 8)
+        return err("The original FAT header is truncated");
+    const littleEndian = magic === 0xbebafeca || magic === 0xbfbafeca;
+    const wide = magic === 0xcafebabf || magic === 0xbfbafeca;
+    const count = littleEndian ? prefix.readUInt32LE(4) : prefix.readUInt32BE(4);
+    if (count === 0 || count > MAX_FAT_ARCHITECTURES)
+        return err("FAT architecture count is outside the supported 1..128 range");
+    const tableEnd = 8 + count * (wide ? 32 : 20);
+    const table = prefix.subarray(8, tableEnd);
+    const parsed = readFatSliceDeclarations(table, { count, wide, littleEndian });
+    if (parsed.status !== "parsed")
+        return err(parsed.reason);
+    if (wide) {
+        for (const slice of parsed.slices)
+            if ((littleEndian
+                ? table.readUInt32LE(slice.index * 32 + 28)
+                : table.readUInt32BE(slice.index * 32 + 28)) !== 0)
+                return err(`FAT64 architecture ${slice.index} has a nonzero reserved field`);
+    }
+    return ok({ slices: parsed.slices, tableEnd });
+}
+async function readSourceSnapshot(file, signal) {
+    const prefix = Buffer.alloc(PREFIX_BYTES);
+    const hash = createHash("sha256");
+    let size = 0;
+    let layout;
+    const headers = new Map();
+    const capture = (bytes, position) => {
+        if (layout?.ok !== true || layout.value === null)
+            return;
+        for (const slice of layout.value.slices) {
+            const start = Math.max(position, slice.offset);
+            const end = Math.min(position + bytes.length, slice.offset + 12);
+            if (end <= start)
+                continue;
+            let header = headers.get(slice.index);
+            if (header === undefined) {
+                header = Buffer.alloc(12);
+                headers.set(slice.index, header);
+            }
+            bytes.copy(header, start - slice.offset, start - position, end - position);
+        }
+    };
+    for await (const chunk of file.createReadStream({
+        start: 0,
+        autoClose: false,
+        ...(signal === undefined ? {} : { signal }),
+    })) {
+        const bytes = Buffer.from(chunk);
+        hash.update(bytes);
+        if (size < prefix.length)
+            bytes.copy(prefix, size, 0, Math.min(bytes.length, prefix.length - size));
+        if (layout === undefined && size + bytes.length >= prefix.length) {
+            layout = fatLayout(prefix);
+            capture(prefix, 0);
+        }
+        capture(bytes, size);
+        size += bytes.length;
+    }
+    if (layout === undefined) {
+        layout = fatLayout(prefix.subarray(0, size));
+        capture(prefix.subarray(0, size), 0);
+    }
+    return { layout, headers, size, sha256: hash.digest("hex") };
+}
+function originalOffset(snapshot, observation) {
+    const { layout, size, headers } = snapshot;
+    if (!layout.ok)
+        return layout;
+    if (layout.value === null)
+        return observation.provider_file_offset < size
+            ? ok(0)
+            : err("Provider mapping lies outside the admitted executable bytes");
+    const header = observation.provider_image_header_hex === null
+        ? null
+        : Buffer.from(observation.provider_image_header_hex, "hex");
+    const loadedMagic = header?.readUInt32BE(0);
+    if (header === null ||
+        loadedMagic === undefined ||
+        ![0xfeedface, 0xfeedfacf, 0xcefaedfe, 0xcffaedfe].includes(loadedMagic))
+        return err("Hopper did not expose the loaded Mach-O header needed to identify its FAT slice");
+    const little = loadedMagic === 0xcefaedfe || loadedMagic === 0xcffaedfe;
+    const cpu = little ? header.readUInt32LE(4) : header.readUInt32BE(4);
+    const subtype = little ? header.readUInt32LE(8) : header.readUInt32BE(8);
+    const matches = [];
+    const ranges = [...layout.value.slices].sort((a, b) => a.offset - b.offset);
+    for (let index = 1; index < ranges.length; index++) {
+        const previous = ranges[index - 1];
+        const current = ranges[index];
+        if (previous !== undefined &&
+            current !== undefined &&
+            current.offset < previous.offset + previous.size)
+            return err("Original FAT slices overlap");
+    }
+    for (const slice of layout.value.slices) {
+        const reason = validateFatSlice(slice, size, layout.value.tableEnd);
+        if (reason !== null)
+            return err(reason);
+        const embedded = headers.get(slice.index);
+        if (slice.size < 12 || embedded === undefined)
+            return err(`FAT architecture ${slice.index} has a truncated Mach-O header`);
+        const embeddedMagic = embedded.readUInt32BE(0);
+        if (![0xfeedface, 0xfeedfacf, 0xcefaedfe, 0xcffaedfe].includes(embeddedMagic))
+            return err(`FAT architecture ${slice.index} does not contain a Mach-O image`);
+        const embeddedLittle = embeddedMagic === 0xcefaedfe || embeddedMagic === 0xcffaedfe;
+        const identityError = validateFatSlice(slice, size, layout.value.tableEnd, {
+            cpuType: embeddedLittle
+                ? embedded.readUInt32LE(4)
+                : embedded.readUInt32BE(4),
+            cpuSubtype: embeddedLittle
+                ? embedded.readUInt32LE(8)
+                : embedded.readUInt32BE(8),
+        });
+        if (identityError !== null)
+            return err(identityError);
+        if (slice.cpuType === cpu && slice.cpuSubtype === subtype)
+            matches.push(slice);
+    }
+    const selected = matches.length === 1 ? matches[0] : undefined;
+    if (selected === undefined)
+        return err(`Original FAT slice matching Hopper's loaded header is ${matches.length === 0 ? "missing" : "ambiguous"}`);
+    if (headers.get(selected.index)?.equals(header) !== true)
+        return err("Original FAT slice header disagrees with Hopper's loaded header");
+    if (observation.provider_file_offset >= selected.size)
+        return err("Provider mapping lies outside the loaded FAT slice");
+    if (!Number.isSafeInteger(selected.offset + observation.provider_file_offset))
+        return err("Original file offset exceeds the exact JSON integer range");
+    return ok(selected.offset);
+}

package/dist/hopper/HopperMachOImage.js

@@ -0,0 +1,197 @@
+import { createHash } from "node:crypto";
+import { open } from "node:fs/promises";
+import { z } from "zod";
+import { BinaryTargetError } from "../domain/configurationErrors.js";
+import { AnalysisCancelledError } from "../domain/analysisErrorCore.js";
+import { readFatSliceDeclarations, validateFatSlice, } from "../domain/apple/machoContainer.js";
+import { HopperCancelledError, HopperStartError, } from "../domain/hopperErrors.js";
+import { err, ok } from "../domain/result.js";
+/** Stable source coordinates committed before preparing an owned thin image. */
+export const hopperMachOImageSchema = z.strictObject({
+    method: z.literal("fat64_thin_slice"),
+    architecture_count: z.number().int().min(1).max(128),
+    container_table_sha256: z.string().regex(/^[a-f0-9]{64}$/u),
+    source_offset: z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER),
+    byte_length: z.number().int().positive().max(Number.MAX_SAFE_INTEGER),
+    cpu_type: z.number().int().nonnegative(),
+    cpu_subtype: z.number().int().nonnegative(),
+});
+/** Validate the selected FAT64 slice without depending on Apple's lipo tool. */
+export const resolveHopperMachOImage = async (target, signal) => {
+    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;
+    try {
+        file = await open(target.path, "r");
+    }
+    catch (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) => {
+            const bytes = Buffer.alloc(length);
+            const { bytesRead } = await file.read(bytes, 0, length, offset);
+            return bytes.subarray(0, bytesRead);
+        };
+        const header = await read(0, 8);
+        const magic = header.length === 8 ? header.readUInt32BE(0) : 0;
+        if (magic !== 0xcafebabf && magic !== 0xbfbafeca)
+            return invalid("FAT64 source header changed before Hopper image preparation");
+        const littleEndian = magic === 0xbfbafeca;
+        const count = littleEndian
+            ? header.readUInt32LE(4)
+            : header.readUInt32BE(4);
+        const size = (await file.stat()).size;
+        const tableEnd = 8 + count * 32;
+        if (count === 0 || count > 128 || tableEnd > size)
+            return invalid("FAT64 architecture table is truncated or exceeds the supported 128 entries");
+        const table = await read(8, count * 32);
+        const parsed = readFatSliceDeclarations(table, {
+            count,
+            wide: true,
+            littleEndian,
+        });
+        if (parsed.status === "malformed")
+            return invalid(parsed.reason);
+        const cpuTypes = { x86: 7, x86_64: 0x1000007, arm: 12, arm64: 0x100000c };
+        const matches = [];
+        const ranges = [];
+        for (const slice of parsed.slices) {
+            if (signal?.aborted)
+                return err(new AnalysisCancelledError("open_binary"));
+            const rangeError = validateFatSlice(slice, size, tableEnd);
+            if (rangeError !== null)
+                return invalid(rangeError);
+            const reserved = littleEndian
+                ? table.readUInt32LE(slice.index * 32 + 28)
+                : table.readUInt32BE(slice.index * 32 + 28);
+            if (reserved !== 0)
+                return invalid(`FAT64 architecture ${slice.index} has a nonzero reserved field`);
+            if (slice.size < 12)
+                return invalid(`FAT64 architecture ${slice.index} has a truncated Mach-O header`);
+            const embedded = await read(slice.offset, 12);
+            if (embedded.length !== 12)
+                return invalid(`FAT64 architecture ${slice.index} became truncated`);
+            const thinMagic = embedded.readUInt32BE(0);
+            if (![0xfeedface, 0xfeedfacf, 0xcefaedfe, 0xcffaedfe].includes(thinMagic))
+                return invalid(`FAT64 architecture ${slice.index} does not contain a Mach-O image`);
+            const little = thinMagic === 0xcefaedfe || thinMagic === 0xcffaedfe;
+            const identity = {
+                cpuType: little ? embedded.readUInt32LE(4) : embedded.readUInt32BE(4),
+                cpuSubtype: little
+                    ? embedded.readUInt32LE(8)
+                    : embedded.readUInt32BE(8),
+            };
+            const identityError = validateFatSlice(slice, size, tableEnd, identity);
+            if (identityError !== null)
+                return invalid(identityError);
+            ranges.push(slice);
+            if (slice.cpuType === cpuTypes[target.architecture])
+                matches.push(slice);
+        }
+        ranges.sort((a, b) => a.offset - b.offset);
+        for (let index = 1; index < ranges.length; index++) {
+            const previous = ranges[index - 1];
+            const current = ranges[index];
+            if (previous !== undefined &&
+                current !== undefined &&
+                current.offset < previous.offset + previous.size)
+                return invalid("FAT64 slices overlap");
+        }
+        const selected = matches.length === 1 ? matches[0] : undefined;
+        if (selected === undefined)
+            return invalid(`FAT64 selection for ${target.architecture} is ${matches.length === 0 ? "missing" : "ambiguous"}; extract the exact architecture into a thin image before opening it`);
+        return ok({
+            method: "fat64_thin_slice",
+            architecture_count: count,
+            container_table_sha256: createHash("sha256")
+                .update(header)
+                .update(table)
+                .digest("hex"),
+            source_offset: selected.offset,
+            byte_length: selected.size,
+            cpu_type: selected.cpuType,
+            cpu_subtype: selected.cpuSubtype,
+        });
+    }
+    catch (cause) {
+        return invalid(`Cannot validate FAT64 image: ${cause instanceof Error ? cause.message : String(cause)}`);
+    }
+    finally {
+        await file.close();
+    }
+};
+/** Copy a selected slice and verify the entire original source in the same pass. */
+export const prepareHopperMachOImage = async (sourcePath, sourceSha256, image, destination, signal) => {
+    if (signal?.aborted)
+        return err(new HopperCancelledError());
+    try {
+        const source = await open(sourcePath, "r");
+        try {
+            const output = await open(destination, "wx", 0o600);
+            try {
+                const hash = createHash("sha256");
+                const tableHash = createHash("sha256");
+                const tableEnd = 8 + image.architecture_count * 32;
+                const thinHeader = [];
+                let position = 0;
+                let copied = 0;
+                for await (const chunk of source.createReadStream({
+                    autoClose: false,
+                })) {
+                    if (signal?.aborted)
+                        return err(new HopperCancelledError());
+                    const bytes = Buffer.from(chunk);
+                    hash.update(bytes);
+                    if (position < tableEnd)
+                        tableHash.update(bytes.subarray(0, Math.min(bytes.length, tableEnd - position)));
+                    const start = Math.max(0, image.source_offset - position);
+                    const end = Math.min(bytes.length, image.source_offset + image.byte_length - position);
+                    if (end > start) {
+                        if (copied < 12)
+                            thinHeader.push(bytes.subarray(start, Math.min(end, start + 12 - copied)));
+                        await output.writeFile(bytes.subarray(start, end));
+                        copied += end - start;
+                    }
+                    position += bytes.length;
+                }
+                const observed = hash.digest("hex");
+                const header = Buffer.concat(thinHeader);
+                const magic = header.length === 12 ? header.readUInt32BE(0) : 0;
+                const little = magic === 0xcefaedfe || magic === 0xcffaedfe;
+                const headerMatches = header.length === 12 &&
+                    [0xfeedface, 0xfeedfacf, 0xcefaedfe, 0xcffaedfe].includes(magic) &&
+                    (little ? header.readUInt32LE(4) : header.readUInt32BE(4)) ===
+                        image.cpu_type &&
+                    (little ? header.readUInt32LE(8) : header.readUInt32BE(8)) ===
+                        image.cpu_subtype;
+                if (tableHash.digest("hex") !== image.container_table_sha256 ||
+                    !headerMatches)
+                    return err(new HopperStartError({
+                        userMessage: `FAT64 source ${sourcePath} no longer agrees with its committed architecture table or selected Mach-O header. Open the stable source again.`,
+                    }));
+                if (observed !== sourceSha256 || copied !== image.byte_length)
+                    return err(new HopperStartError({
+                        userMessage: `FAT64 source ${sourcePath} changed before launch: expected SHA-256 ${sourceSha256}, observed ${observed}; copied ${copied} of ${image.byte_length} selected bytes. Open the stable source again.`,
+                    }));
+                return ok(destination);
+            }
+            finally {
+                await output.close();
+            }
+        }
+        finally {
+            await source.close();
+        }
+    }
+    catch (cause) {
+        return signal?.aborted
+            ? err(new HopperCancelledError())
+            : err(new HopperStartError({
+                cause,
+                userMessage: `Cannot prepare the selected FAT64 image from ${sourcePath}: ${cause instanceof Error ? cause.message : String(cause)}`,
+            }));
+    }
+};

package/dist/hopper/HopperOperationStage.js

@@ -0,0 +1,6 @@
+/** Classify Hopper wire operations at their provider boundary. */
+export const hopperOperationStage = (operation) => {
+    if (operation === "health")
+        return "connection";
+    return operation === "procedure_pseudo_code" ? "decompilation" : "analysis";
+};

package/dist/hopper/HopperProvider.js

@@ -1,32 +1,36 @@
+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";
+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;
@@ -101,28 +105,52 @@ 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 derivedLoaderArgs = hopperLoaderArgsForTarget(target);
+        const preparation = profile?.parameters.prepared_image;
+        const parsedImage = preparation === undefined
+            ? undefined
+            : hopperMachOImageSchema.safeParse(preparation);
+        if (parsedImage?.success === false)
+            return {
+                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
+            ? profile?.parameters.macho_container
+            : "thin";
+        const derivedLoaderArgs = hopperLoaderArgsForTarget(target, container === "thin" || container === "fat32" || container === "fat64"
+            ? container
+            : undefined);
         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,
+                ...(preparedImage === undefined
+                    ? {}
+                    : {
+                        preparedImage: {
+                            image: preparedImage,
+                            sourceSha256: target.sha256,
+                        },
+                    }),
                 loaderArgs: this.config.hopperLoaderArgs.length > 0
                     ? this.config.hopperLoaderArgs
                     : derivedLoaderArgs.value,
@@ -138,25 +166,46 @@ export class HopperProvider {
             logger: this.logger.child({ layer: "bridge" }),
             onDiagnostic: (diagnostic) => this.logger.info(diagnostic, "Hopper bridge reported a diagnostic"),
         });
+        const regexSearch = new HopperRegexSearch(client);
         return {
             execute: async (operation, parameters, options) => {
-                const result = await client.callTool(operation, parameters, options);
-                return result.ok
+                const result = (operation === "search_strings" ||
+                    operation === "search_procedures") &&
+                    parameters.mode === "regex"
+                    ? await regexSearch.execute(operation, parameters, options)
+                    : await client.callTool(operation, parameters, options);
+                if (!result.ok)
+                    return result;
+                const mapped = operation === "address_to_file_offset"
+                    ? await mapHopperFileOffset(target, result.value, options?.signal)
+                    : result;
+                return mapped.ok
                     ? {
                         ok: true,
-                        value: createAnalysisExecution(result.value, executionProvider, {
+                        value: createAnalysisExecution(mapped.value, executionProvider, {
+                            rawResult: result.value,
                             ...(profile === undefined ? {} : { analysisProfile: profile }),
                             limitations: [
-                                "Results depend on Hopper's completed static analysis.",
+                                ...(preparedImage === undefined
+                                    ? []
+                                    : [
+                                        "REA loaded a verified thin Mach-O slice from the original FAT64 source. Identity and file offsets refer to the original file. The owned temporary image and its Hopper document close together, including on MCP shutdown.",
+                                    ]),
+                                ...(CAPABILITIES.find((descriptor) => descriptor.operation === operation)?.limitations ?? []),
+                                ...(operation === "read_bytes"
+                                    ? [
+                                        "Hopper byte reads stop at the containing segment's exclusive end; a readable prefix is returned with complete=false when the requested range crosses it.",
+                                    ]
+                                    : []),
                                 ...(operation === "procedure_references"
                                     ? [
-                                        "Hopper's public Python API does not expose flow classification for calls without resolved targets; unresolved_calls is empty and its coverage is unknown.",
+                                        "Native CallReference classifications and unresolved targets are preserved. Detailed reference flags and coverage beyond reported CallReference objects remain unknown.",
                                     ]
                                     : []),
                             ],
                         }),
                     }
-                    : result;
+                    : mapped;
             },
             runtimeLineageSnapshots: () => {
                 const observation = client.runtimeLineage();
@@ -181,8 +230,11 @@ export class HopperProvider {
                     },
                 ];
             },
-            closeWithOutcome: (options) => client.closeWithOutcome(options),
-            close: () => client.close(),
+            operationHealthSnapshot: () => client.operationHealth(),
+            close: async (options) => {
+                await regexSearch.close();
+                return client.close(options);
+            },
         };
     }
 }

package/dist/hopper/HopperProviderCapabilities.js

@@ -38,7 +38,6 @@ export const HOPPER_OPERATIONS = Object.freeze([
     "set_addresses_names",
     "set_bookmark",
     "set_comment",
-    "set_current_document",
     "set_inline_comment",
     "unset_bookmark",
     "xrefs",
@@ -69,5 +68,24 @@ export const CAPABILITIES = Object.freeze(HOPPER_OPERATIONS.map((operation) => O
     }),
     limitations: Object.freeze([
         "Results depend on Hopper's completed static analysis.",
+        ...(operation === "address_to_file_offset"
+            ? [
+                "Original-file coordinates require source bytes matching the selected executable digest. A changed, unavailable, or database-only source retains native mapping facts in partial error evidence.",
+            ]
+            : []),
+        ...(operation === "search_strings" || operation === "search_procedures"
+            ? [
+                "Regex mode uses ECMAScript Unicode semantics in a supervised worker with a five-second matching deadline. Cancellation or deadline failure stops matching without blocking Hopper; literal mode retains native casefold semantics.",
+            ]
+            : []),
+        ...(operation === "list_strings" ||
+            operation === "search_strings" ||
+            operation === "analyze_function"
+            ? [
+                "String values cover native typed objects. Hopper may split long literals into adjacent unterminated fragments; string searches match each object independently.",
+                "Undecodable typed objects retain native display text with an explicit decoding unknown; these values do not establish decoded source literals.",
+                "Reported string encodings are inferred from typed bytes and native display; the original source's intended encoding is unknown.",
+            ]
+            : []),
     ]),
 })));