rea-agents 6.0.0 → 6.1.0

package/dist/hopper/HopperMachOImage.js

@@ -0,0 +1,196 @@
+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) => err(new BinaryTargetError(target.path, reason));
+    if (signal?.aborted)
+        return err(new AnalysisCancelledError("open_binary"));
+    let file;
+    try {
+        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)}`);
+    }
+    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

@@ -5,7 +5,10 @@ import { AnalysisCapabilityUnavailableError } from "../domain/analysisErrorCore.
 import { err } 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;
@@ -111,7 +114,22 @@ export class HopperProvider {
                 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);
+        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(IDENTITY.id, operation, "Hopper prepared-image profile is malformed; resolve the analysis profile again."))),
+                close: () => Promise.resolve(),
+            };
+        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)),
@@ -123,6 +141,14 @@ export class HopperProvider {
                 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 +164,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 +228,15 @@ export class HopperProvider {
                     },
                 ];
             },
-            closeWithOutcome: (options) => client.closeWithOutcome(options),
-            close: () => client.close(),
+            operationHealthSnapshot: () => client.operationHealth(),
+            closeWithOutcome: async (options) => {
+                await regexSearch.close();
+                return client.closeWithOutcome(options);
+            },
+            close: async () => {
+                await regexSearch.close();
+                await client.close();
+            },
         };
     }
 }

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.",
+            ]
+            : []),
     ]),
 })));

package/dist/hopper/HopperRegexSearch.js

@@ -0,0 +1,137 @@
+import { Worker } from "node:worker_threads";
+import { z } from "zod";
+import { AnalysisCancelledError, AnalysisOutputError, AnalysisResourceConstraintError, } from "../domain/analysisErrorCore.js";
+import { analysisStringSchema } from "../domain/hopperValues.js";
+import { HopperRemoteError } from "../domain/hopperErrors.js";
+import { err, ok } from "../domain/result.js";
+import { analysisSearchInput } from "../contracts/analysisSearchContract.js";
+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({
+        status: z.literal("matched"),
+        indices: z.array(z.number().int().nonnegative()),
+    }),
+    z.strictObject({ status: z.literal("invalid_pattern"), reason: z.string() }),
+]);
+/** Match collected native facts off Hopper's API thread, with cancellable lifetime. */
+export class HopperRegexSearch {
+    client;
+    #active = new Map();
+    constructor(client) {
+        this.client = client;
+    }
+    execute(operation, parameters, options) {
+        const controller = new AbortController();
+        const signal = options?.signal === undefined
+            ? controller.signal
+            : AbortSignal.any([controller.signal, options.signal]);
+        const pending = this.#execute(operation, parameters, {
+            ...options,
+            signal,
+        });
+        this.#active.set(controller, pending);
+        void pending.then(() => this.#active.delete(controller), () => this.#active.delete(controller));
+        return pending;
+    }
+    /** Abort matching workers before their provider session closes. */
+    async close() {
+        for (const controller of this.#active.keys())
+            controller.abort();
+        await Promise.all(this.#active.values());
+    }
+    async #execute(operation, parameters, options) {
+        const input = inputSchema.safeParse(parameters);
+        if (!input.success)
+            return err(new HopperRemoteError(-32000, `Invalid search arguments: ${input.error.message}`, { diagnosticType: "invalid_request", operation }));
+        const inventoryOptions = {
+            ...options,
+            ...(options.progress === undefined
+                ? {}
+                : {
+                    progress: {
+                        report: (update) => options.progress?.report({
+                            ...update,
+                            completed: update.total === null || update.total === 0
+                                ? 0
+                                : Math.min(0.5, update.completed / update.total / 2),
+                            total: 1,
+                        }) ?? Promise.resolve(),
+                    },
+                }),
+        };
+        const inventory = await this.client.callTool(operation === "search_strings" ? "list_strings" : "list_procedures", input.data.document == null ? {} : { document: input.data.document }, inventoryOptions);
+        if (!inventory.ok)
+            return inventory;
+        const parsed = z.array(analysisStringSchema).safeParse(inventory.value);
+        if (!parsed.success)
+            return err(new AnalysisOutputError(operation, "Hopper search inventory is malformed"));
+        if (options.signal?.aborted)
+            return err(new AnalysisCancelledError(operation));
+        await options.progress
+            ?.report({
+            phase: "hopper_regex",
+            completed: 0.5,
+            total: 1,
+            message: "Matching inventory in cancellable regex worker",
+        })
+            .catch(() => undefined);
+        if (options.signal?.aborted)
+            return err(new AnalysisCancelledError(operation));
+        let worker;
+        try {
+            worker = new Worker(new URL("./HopperRegexWorker.js", import.meta.url), {
+                workerData: {
+                    pattern: input.data.pattern,
+                    caseSensitive: input.data.case_sensitive,
+                    values: parsed.data.map((item) => item.value),
+                },
+            });
+        }
+        catch (cause) {
+            return err(new AnalysisOutputError(operation, `Cannot start regex worker: ${cause instanceof Error ? cause.message : String(cause)}`, { cause }));
+        }
+        try {
+            return await new Promise((resolve) => {
+                const finish = (result) => {
+                    clearTimeout(timer);
+                    options.signal?.removeEventListener("abort", onAbort);
+                    resolve(result);
+                };
+                const onAbort = () => finish(err(new AnalysisCancelledError(operation)));
+                const timer = setTimeout(() => finish(err(new AnalysisResourceConstraintError(operation, "cpu", "Regex matching exceeded its supervised deadline; the Hopper API thread remains available.", { matching_deadline_ms: MATCHING_DEADLINE_MS }, {
+                    remediationAction: "Simplify the ECMAScript Unicode regex or use literal mode, then retry in the same session.",
+                }))), MATCHING_DEADLINE_MS);
+                options.signal?.addEventListener("abort", onAbort, { once: true });
+                if (options.signal?.aborted)
+                    onAbort();
+                worker.once("message", (message) => {
+                    const reply = replySchema.safeParse(message);
+                    if (!reply.success)
+                        return finish(err(new AnalysisOutputError(operation, "Regex worker reply is malformed")));
+                    if (reply.data.status === "invalid_pattern")
+                        return finish(err(new HopperRemoteError(-32000, `Invalid regex pattern: ${reply.data.reason}`, { diagnosticType: "invalid_request", operation })));
+                    const indices = reply.data.indices;
+                    if (indices.some((index, position) => index >= parsed.data.length ||
+                        (position > 0 && index <= (indices[position - 1] ?? -1))))
+                        return finish(err(new AnalysisOutputError(operation, "Regex worker returned invalid inventory indices")));
+                    const selected = new Set(indices);
+                    finish(ok(parsed.data.filter((_, index) => selected.has(index))));
+                });
+                worker.once("error", (cause) => finish(err(new AnalysisOutputError(operation, `Regex worker failed: ${cause.message}`, { cause }))));
+                worker.once("exit", (code) => finish(err(new AnalysisOutputError(operation, `Regex worker exited without a result (${code})`))));
+            });
+        }
+        finally {
+            await worker.terminate();
+        }
+    }
+}

package/dist/hopper/HopperRegexWorker.js

@@ -0,0 +1,27 @@
+import { parentPort, workerData } from "node:worker_threads";
+import { z } from "zod";
+const input = z
+    .strictObject({
+    pattern: z.string().min(1),
+    caseSensitive: z.boolean(),
+    values: z.array(z.string()),
+})
+    .parse(workerData);
+let expression;
+try {
+    expression = new RegExp(input.pattern, input.caseSensitive ? "u" : "iu");
+}
+catch (cause) {
+    parentPort?.postMessage({
+        status: "invalid_pattern",
+        reason: cause instanceof Error ? cause.message : String(cause),
+    });
+}
+if (expression !== undefined) {
+    const indices = [];
+    for (const [index, value] of input.values.entries()) {
+        if (expression.test(value))
+            indices.push(index);
+    }
+    parentPort?.postMessage({ status: "matched", indices });
+}