rea-agents 0.2.1

package/dist/application/BinarySession.js

@@ -0,0 +1,173 @@
+import { parseBinaryTarget } from "../domain/binaryTarget.js";
+import { HopperCancelledError, NoBinaryOpenError, } from "../domain/errors.js";
+import { err, ok } from "../domain/result.js";
+import { EvidenceLedger } from "./EvidenceLedger.js";
+/**
+ * Owns the single active target shared by CLI and MCP adapters.
+ *
+ * Target transitions are serialized because each client dispatches Hopper API
+ * work on its dedicated Python thread, and switching targets tears that bridge
+ * down. A failed switch recreates the previous target instead of retaining a
+ * client whose bridge was already shut down.
+ */
+export class BinarySession {
+    provider;
+    #active;
+    #transition = Promise.resolve();
+    #calls = new Set();
+    #createClient;
+    #providerIdentity;
+    #evidence = new EvidenceLedger({ maxRecords: 10_000 });
+    constructor(provider) {
+        this.provider = provider;
+        this.#createClient =
+            typeof provider === "function"
+                ? provider
+                : (target) => provider.createClient(target);
+        this.#providerIdentity =
+            typeof provider === "function"
+                ? { id: "unidentified", name: "Unidentified provider", version: null }
+                : provider.identity();
+    }
+    /** Identify the provider producing evidence for this session. */
+    providerIdentity() {
+        return this.#providerIdentity;
+    }
+    /** Add one successful public observation to the session ledger. */
+    recordEvidence(evidence) {
+        this.#evidence.record(evidence);
+    }
+    /** Return a deterministic snapshot without clearing session evidence. */
+    exportEvidenceBundle() {
+        return this.#evidence.export();
+    }
+    /** Atomically merge a validated evidence bundle into this session. */
+    importEvidenceBundle(bundle) {
+        return this.#evidence.import(bundle);
+    }
+    /**
+     * Open or switch targets after draining calls against the current target.
+     * Returns the switch failure even if best-effort restoration also fails.
+     */
+    open(path, options = {}) {
+        return this.#serialize(async () => {
+            if (isAborted(options.signal))
+                return err(new HopperCancelledError());
+            const parsed = await parseBinaryTarget(path, process.cwd(), process.arch, options.targetKind);
+            if (!parsed.ok)
+                return parsed;
+            if (isAborted(options.signal))
+                return err(new HopperCancelledError());
+            if (this.#active?.target.path === parsed.value.path)
+                return ok(parsed.value);
+            await this.#drainCalls();
+            const previous = this.#active;
+            this.#active = undefined;
+            await previous?.client.close();
+            const client = this.#createClient(parsed.value);
+            const started = await client.execute("health", {}, options);
+            if (!started.ok) {
+                await client.close();
+                await this.#restore(previous);
+                return started;
+            }
+            if (isAborted(options.signal)) {
+                await client.close();
+                await this.#restore(previous);
+                return err(new HopperCancelledError());
+            }
+            this.#active = { target: parsed.value, client };
+            return ok(parsed.value);
+        });
+    }
+    /** Close the active target, if any. */
+    close() {
+        return this.#serialize(async () => {
+            const previous = this.#active;
+            this.#active = undefined;
+            await this.#drainCalls();
+            await previous?.client.close();
+            this.#evidence.clear();
+            return ok(null);
+        });
+    }
+    /** Describe the active binary session. */
+    status() {
+        const target = this.#active?.target;
+        return target === undefined
+            ? { open: false }
+            : {
+                open: true,
+                path: target.path,
+                sha256: target.sha256,
+                format: target.format,
+                kind: target.kind,
+                architecture: target.architecture ?? null,
+            };
+    }
+    /** Return the immutable artifact identity captured before Hopper launched. */
+    activeTarget() {
+        return this.#active?.target;
+    }
+    /**
+     * Invoke a Hopper tool against the active target.
+     * Calls may overlap, but a pending target transition prevents new calls from
+     * entering until the transition has settled.
+     */
+    async execute(name, arguments_, options) {
+        const transitioned = await this.#waitForTransition(options?.signal);
+        if (!transitioned.ok)
+            return transitioned;
+        const active = this.#active;
+        if (active === undefined)
+            return err(new NoBinaryOpenError());
+        const call = active.client.execute(name, arguments_, options);
+        this.#calls.add(call);
+        try {
+            return await call;
+        }
+        finally {
+            this.#calls.delete(call);
+        }
+    }
+    #serialize(operation) {
+        const result = this.#transition.then(operation, operation);
+        this.#transition = result.then(() => undefined, () => undefined);
+        return result;
+    }
+    async #drainCalls() {
+        await Promise.allSettled(this.#calls);
+    }
+    async #restore(previous) {
+        if (previous === undefined)
+            return;
+        const client = this.#createClient(previous.target);
+        const started = await client.execute("health", {});
+        if (started.ok)
+            this.#active = { target: previous.target, client };
+        else
+            await client.close();
+    }
+    async #waitForTransition(signal) {
+        if (signal?.aborted === true)
+            return err(new HopperCancelledError());
+        if (signal === undefined) {
+            await this.#transition;
+            return ok(undefined);
+        }
+        return new Promise((resolve) => {
+            const onAbort = () => {
+                resolve(err(new HopperCancelledError()));
+            };
+            signal.addEventListener("abort", onAbort, { once: true });
+            this.#transition.then(() => {
+                signal.removeEventListener("abort", onAbort);
+                resolve(signal.aborted ? err(new HopperCancelledError()) : ok(undefined));
+            }, () => {
+                signal.removeEventListener("abort", onAbort);
+                resolve(signal.aborted ? err(new HopperCancelledError()) : ok(undefined));
+            });
+        });
+    }
+}
+const isAborted = (signal) => signal?.aborted === true;

package/dist/application/DirectAnalysis.js

@@ -0,0 +1,31 @@
+import { parseConfig } from "../config.js";
+import { createBinarySession } from "./runtime.js";
+import { silentLogger } from "../logger.js";
+import { createEvidence } from "../domain/evidence.js";
+/**
+ * Open one binary, execute one tool, and always release the bridge session.
+ * Unlike MCP mode, every CLI invocation is intentionally isolated and does not
+ * retain a target or bridge resources for a subsequent command.
+ */
+export const runDirectAnalysis = async (path, tool, arguments_, logger = silentLogger) => {
+    const config = parseConfig(process.env);
+    if (!config.ok)
+        return { error: config.error._tag, message: config.error.message };
+    const session = createBinarySession(config.value, logger);
+    try {
+        const opened = await session.open(path);
+        if (!opened.ok)
+            return { error: opened.error._tag, message: opened.error.message };
+        const result = await session.execute(tool, arguments_);
+        return result.ok
+            ? createEvidence(opened.value, session.providerIdentity(), {
+                operation: tool,
+                parameters: arguments_,
+                result: result.value,
+            })
+            : { error: result.error._tag, message: result.error.message };
+    }
+    finally {
+        await session.close();
+    }
+};

package/dist/application/Doctor.js

@@ -0,0 +1,110 @@
+import { constants } from "node:fs";
+import { access } from "node:fs/promises";
+import { readdir } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { parseBinaryTarget } from "../domain/binaryTarget.js";
+import { probeHomebrew } from "./homebrew.js";
+const execFileAsync = promisify(execFile);
+const DEFAULT_HOPPER = "/Applications/Hopper Disassembler.app/Contents/MacOS/hopper";
+/**
+ * Check requirements and an optional target without mutating the host.
+ * Every failed check includes remediation suitable for either the one-shot CLI
+ * or an agent consuming the structured result.
+ */
+export const runDoctor = async (target, host = systemDoctorHost()) => {
+    const checks = [];
+    const nodeMajor = parseMajor(host.nodeVersion);
+    checks.push(check("node", nodeMajor >= 22, host.nodeVersion, "Install Node.js 22 or newer."));
+    const macosVersion = host.platform === "darwin" ? await host.macosVersion() : undefined;
+    const macosMajor = macosVersion === undefined ? 0 : parseMajor(macosVersion);
+    checks.push(check("macos", host.platform === "darwin" && macosMajor >= 12, macosVersion ?? host.platform, "Hopper requires macOS 12 or newer."));
+    const candidates = [
+        host.configuredHopperPath,
+        DEFAULT_HOPPER,
+        ...(await host.manualHopperPaths()),
+        await host.brewHopperPath(),
+    ].filter((value) => value !== undefined);
+    let hopperPath;
+    for (const candidate of new Set(candidates))
+        if (await host.executable(candidate)) {
+            hopperPath = candidate;
+            break;
+        }
+    checks.push(check("hopper", hopperPath !== undefined, hopperPath, "Install Hopper with: brew install --cask hopper-disassembler, or set HOPPER_LAUNCHER_PATH."));
+    if (target !== undefined)
+        checks.push(check("target", await host.validTarget(target), target, "Supply a readable local app or program path."));
+    return {
+        healthy: checks.every(({ ok }) => ok),
+        ...(hopperPath === undefined ? {} : { hopperPath }),
+        checks,
+    };
+};
+/** Create diagnostics backed by the current process and host commands. */
+export const systemDoctorHost = () => ({
+    platform: process.platform,
+    nodeVersion: process.versions.node,
+    ...(process.env.HOPPER_LAUNCHER_PATH === undefined
+        ? {}
+        : { configuredHopperPath: process.env.HOPPER_LAUNCHER_PATH }),
+    async macosVersion() {
+        try {
+            return (await execFileAsync("sw_vers", ["-productVersion"])).stdout.trim();
+        }
+        catch {
+            return undefined;
+        }
+    },
+    async validTarget(path) {
+        return (await parseBinaryTarget(path)).ok;
+    },
+    async executable(path) {
+        try {
+            await access(path, constants.X_OK);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    },
+    async brewHopperPath() {
+        return probeHomebrew(async (command) => {
+            try {
+                const prefix = (await execFileAsync(command, [
+                    "--prefix",
+                    "--cask",
+                    "hopper-disassembler",
+                ])).stdout.trim();
+                return `${prefix}/Hopper Disassembler.app/Contents/MacOS/hopper`;
+            }
+            catch {
+                return undefined;
+            }
+        });
+    },
+    async manualHopperPaths() {
+        const roots = ["/Applications", join(homedir(), "Applications")];
+        const paths = [];
+        for (const root of roots) {
+            try {
+                for (const entry of await readdir(root, { withFileTypes: true })) {
+                    if (entry.isDirectory() && /^Hopper.*\.app$/i.test(entry.name))
+                        paths.push(join(root, entry.name, "Contents/MacOS/hopper"));
+                }
+            }
+            catch {
+                // A missing or unreadable optional application directory is not fatal.
+            }
+        }
+        return paths;
+    },
+});
+const parseMajor = (version) => Number.parseInt(version.split(".")[0] ?? "0", 10);
+const check = (name, ok, detail, remediation) => ({
+    name,
+    ok,
+    ...(detail === undefined ? {} : { detail }),
+    ...(ok ? {} : { remediation }),
+});

package/dist/application/EnhancedTools.js

@@ -0,0 +1,357 @@
+import { enhancedInputSchemas } from "../contracts/enhancedInputs.js";
+import { AnalysisProtocolError } from "../domain/errors.js";
+import { parseDocuments, parseFunctionDossier, parseAddressedPage, parseListCount, parseRelatedAddresses, parseSegments, } from "../domain/hopperValues.js";
+import { err, ok } from "../domain/result.js";
+import { categorizeSwiftTypes, discoverObjcClasses, discoverObjcProtocols, discoverSwiftClasses, } from "../domain/symbolAnalysis.js";
+/**
+ * Composes official Hopper operations into bounded reverse-engineering tools.
+ * Inputs are parsed again at this application boundary even though MCP normally
+ * validates them, allowing direct callers to use the same service safely.
+ */
+export class EnhancedTools {
+    analysis;
+    constructor(analysis) {
+        this.analysis = analysis;
+    }
+    /** Parse inputs again at the direct-call boundary, then dispatch exhaustively. */
+    execute(name, input, signal) {
+        switch (name) {
+            case "swift_classes": {
+                const parsed = enhancedInputSchemas.swift_classes.safeParse(input);
+                return parsed.success
+                    ? this.#swiftClasses(parsed.data.pattern, signal)
+                    : invalidInput(name, parsed.error);
+            }
+            case "get_objc_classes": {
+                const parsed = enhancedInputSchemas.get_objc_classes.safeParse(input);
+                return parsed.success
+                    ? this.#objcClasses(parsed.data.pattern, signal)
+                    : invalidInput(name, parsed.error);
+            }
+            case "get_objc_protocols":
+                return this.#objcProtocols(signal);
+            case "batch_decompile": {
+                const parsed = enhancedInputSchemas.batch_decompile.safeParse(input);
+                return parsed.success
+                    ? this.#batchDecompile(parsed.data.addresses, signal)
+                    : invalidInput(name, parsed.error);
+            }
+            case "get_call_graph": {
+                const parsed = enhancedInputSchemas.get_call_graph.safeParse(input);
+                return parsed.success
+                    ? this.#callGraph(parsed.data, signal)
+                    : invalidInput(name, parsed.error);
+            }
+            case "analyze_swift_types":
+                return this.#analyzeSwiftTypes(signal);
+            case "find_xrefs_to_name": {
+                const parsed = enhancedInputSchemas.find_xrefs_to_name.safeParse(input);
+                return parsed.success
+                    ? this.#findXrefs(parsed.data.name, signal)
+                    : invalidInput(name, parsed.error);
+            }
+            case "binary_overview": {
+                const parsed = enhancedInputSchemas.binary_overview.safeParse(input);
+                return parsed.success
+                    ? this.#binaryOverview(parsed.data, signal)
+                    : invalidInput(name, parsed.error);
+            }
+            case "analyze_function": {
+                const parsed = enhancedInputSchemas.analyze_function.safeParse(input);
+                return parsed.success
+                    ? this.#analyzeFunction(parsed.data, signal)
+                    : invalidInput(name, parsed.error);
+            }
+            case "trace_feature": {
+                const parsed = enhancedInputSchemas.trace_feature.safeParse(input);
+                return parsed.success
+                    ? this.#traceFeature(parsed.data, signal)
+                    : invalidInput(name, parsed.error);
+            }
+        }
+    }
+    async #analyzeFunction(input, signal) {
+        const result = await this.#call("analyze_function", input, signal);
+        return result.ok ? parseFunctionDossier(result.value) : result;
+    }
+    async #swiftClasses(pattern, signal) {
+        const procedures = await this.#allProcedures(signal);
+        return procedures.ok
+            ? ok(discoverSwiftClasses(procedures.value, pattern))
+            : procedures;
+    }
+    async #objcClasses(pattern, signal) {
+        const names = await this.#allAddressed("list_names", signal);
+        return names.ok ? ok(discoverObjcClasses(names.value, pattern)) : names;
+    }
+    async #objcProtocols(signal) {
+        const names = await this.#allAddressed("list_names", signal);
+        return names.ok ? ok(discoverObjcProtocols(names.value)) : names;
+    }
+    async #batchDecompile(addresses, signal) {
+        if (addresses.length === 0)
+            return ok({ error: "No addresses provided" });
+        const entries = await Promise.all(addresses.map(async (address) => {
+            const result = await this.#call("procedure_pseudo_code", { procedure: address }, signal);
+            return [
+                address,
+                result.ok
+                    ? result.value === null || result.value === ""
+                        ? "No output"
+                        : result.value
+                    : `Error: ${result.error.message}`,
+            ];
+        }));
+        return ok(Object.fromEntries(entries));
+    }
+    async #callGraph(input, signal) {
+        const relation = input.direction === "forward" ? "callees" : "callers";
+        const tool = input.direction === "forward" ? "procedure_callees" : "procedure_callers";
+        const discovered = new Set([input.address]);
+        const queue = [
+            { address: input.address, depth: 0 },
+        ];
+        let queueIndex = 0;
+        const graph = {};
+        while (queueIndex < queue.length) {
+            const current = queue[queueIndex++];
+            if (current === undefined || current.depth >= input.depth) {
+                continue;
+            }
+            const level = String(current.depth);
+            graph[level] ??= [];
+            const result = await this.#call(tool, { procedure: current.address }, signal);
+            if (!result.ok) {
+                graph[level].push({
+                    address: current.address,
+                    error: result.error.message,
+                });
+                continue;
+            }
+            const related = parseRelatedAddresses(result.value, relation);
+            if (!related.ok) {
+                graph[level].push({
+                    address: current.address,
+                    error: related.error.message,
+                });
+                continue;
+            }
+            graph[level].push({
+                address: current.address,
+                calls: [...related.value],
+            });
+            if (current.depth + 1 < input.depth) {
+                for (const address of related.value) {
+                    if (!discovered.has(address)) {
+                        discovered.add(address);
+                        queue.push({ address, depth: current.depth + 1 });
+                    }
+                }
+            }
+        }
+        return ok(graph);
+    }
+    async #analyzeSwiftTypes(signal) {
+        const procedures = await this.#allProcedures(signal);
+        return procedures.ok
+            ? ok(categorizeSwiftTypes(procedures.value))
+            : procedures;
+    }
+    async #findXrefs(name, signal) {
+        const resolved = await this.#call("address_name", { address: name }, signal);
+        if (!resolved.ok)
+            return resolved;
+        const address = resolveAddress(resolved.value);
+        if (address === undefined)
+            return ok({ error: `Could not resolve name: ${name}` });
+        const xrefs = await this.#call("xrefs", { address }, signal);
+        if (!xrefs.ok)
+            return xrefs;
+        return ok(Array.isArray(xrefs.value) ? { xrefs: xrefs.value } : xrefs.value);
+    }
+    async #binaryOverview(input, signal) {
+        const [segmentsResult, documentsResult, procedures, stringsResult] = await Promise.all([
+            this.#call("list_segments", {}, signal),
+            this.#call("list_documents", {}, signal),
+            this.#allProcedures(signal),
+            this.#call("list_strings", {}, signal),
+        ]);
+        if (!segmentsResult.ok)
+            return segmentsResult;
+        if (!documentsResult.ok)
+            return documentsResult;
+        if (!procedures.ok)
+            return procedures;
+        if (!stringsResult.ok)
+            return stringsResult;
+        const segments = parseSegments(segmentsResult.value);
+        if (!segments.ok)
+            return segments;
+        const documents = parseDocuments(documentsResult.value);
+        if (!documents.ok)
+            return documents;
+        const stringCount = parseListCount(stringsResult.value, "strings");
+        if (!stringCount.ok)
+            return stringCount;
+        return ok({
+            document: documents.value[0] ?? "unknown",
+            detail: input.detail,
+            segments: segments.value
+                .slice(0, input.limit)
+                .map(({ name, start, end }) => input.detail === "detailed"
+                ? { name, start, end, length: addressDistance(start, end) }
+                : { name, start, end }),
+            segment_count: segments.value.length,
+            procedure_count: procedures.value.length,
+            string_count: stringCount.value,
+        });
+    }
+    async #traceFeature(input, signal) {
+        const searched = await this.#literalMatches(input, signal);
+        if (!searched.ok)
+            return searched;
+        const residual = new Set();
+        const traced = await this.#traceReferences(searched.value.matches, input.limit, input.max_operations - searched.value.operations, signal);
+        if (!traced.ok)
+            return traced;
+        for (const reason of traced.value.residual)
+            residual.add(reason);
+        const operations = searched.value.operations + traced.value.operations;
+        if (operations >= input.max_operations)
+            residual.add("Investigation reached the operation budget.");
+        if (searched.value.matches.length >= input.limit)
+            residual.add("Literal matches reached the configured limit.");
+        return ok({
+            query: input.query,
+            search_mode: "literal",
+            operations_used: operations,
+            operation_budget: input.max_operations,
+            matches: searched.value.matches,
+            references: traced.value.references,
+            truncated: residual.size > 0,
+            residual_unknowns: [...residual],
+        });
+    }
+    async #literalMatches(input, signal) {
+        let operations = 0;
+        const matches = [];
+        const needle = input.case_sensitive
+            ? input.query
+            : input.query.toLowerCase();
+        for (const [tool, type] of [
+            ["list_strings", "string"],
+            ["list_procedures", "procedure"],
+        ]) {
+            let offset = 0;
+            while (operations < input.max_operations &&
+                matches.length < input.limit) {
+                operations += 1;
+                const result = await this.#call(tool, { offset, limit: 500 }, signal);
+                if (!result.ok)
+                    return result;
+                const page = parseAddressedPage(result.value);
+                if (!page.ok)
+                    return page;
+                for (const item of page.value.items) {
+                    const haystack = input.case_sensitive
+                        ? item.name
+                        : item.name.toLowerCase();
+                    if (haystack.includes(needle))
+                        matches.push({ type, address: item.address, value: item.name });
+                    if (matches.length >= input.limit)
+                        break;
+                }
+                if (!page.value.hasMore || page.value.nextOffset === null)
+                    break;
+                offset = page.value.nextOffset;
+            }
+        }
+        return ok({ matches, operations });
+    }
+    async #traceReferences(matches, limit, operationBudget, signal) {
+        let operations = 0;
+        const references = [];
+        const residual = new Set();
+        for (const match of matches) {
+            if (operations >= operationBudget) {
+                residual.add("Reference traversal stopped at the operation budget.");
+                break;
+            }
+            operations += 1;
+            const xrefs = await this.#call("xrefs", { address: match.address }, signal);
+            if (!xrefs.ok)
+                return xrefs;
+            if (!Array.isArray(xrefs.value))
+                return err(new AnalysisProtocolError("xrefs returned a non-array result"));
+            for (const source of xrefs.value) {
+                if (typeof source !== "string")
+                    return err(new AnalysisProtocolError("xrefs returned a non-address value"));
+                if (operations >= operationBudget) {
+                    residual.add("Containing-procedure resolution stopped at the operation budget.");
+                    break;
+                }
+                operations += 1;
+                const resolved = await this.#call("resolve_containing_procedure", { address: source }, signal);
+                if (!resolved.ok)
+                    return resolved;
+                references.push({
+                    target_address: match.address,
+                    source_address: source,
+                    containing_procedure: resolved.value,
+                });
+                if (references.length >= limit) {
+                    residual.add("Reference results reached the configured limit.");
+                    break;
+                }
+            }
+            if (references.length >= limit)
+                break;
+        }
+        return ok({
+            references,
+            operations,
+            residual: [...residual],
+        });
+    }
+    async #allProcedures(signal) {
+        return this.#allAddressed("list_procedures", signal);
+    }
+    async #allAddressed(tool, signal) {
+        const entries = [];
+        let offset = 0;
+        while (true) {
+            const result = await this.#call(tool, { offset, limit: 500 }, signal);
+            if (!result.ok)
+                return result;
+            const page = parseAddressedPage(result.value);
+            if (!page.ok)
+                return page;
+            entries.push(...page.value.items);
+            if (!page.value.hasMore || page.value.nextOffset === null) {
+                return ok(entries);
+            }
+            if (page.value.nextOffset <= offset) {
+                return err(new AnalysisProtocolError(`${tool} returned a non-advancing pagination offset`));
+            }
+            offset = page.value.nextOffset;
+        }
+    }
+    #call(name, arguments_, signal) {
+        return this.analysis.execute(name, arguments_, signal === undefined ? {} : { signal });
+    }
+}
+const invalidInput = (name, cause) => Promise.resolve(err(new AnalysisProtocolError(`Invalid ${name} input after MCP validation`, {
+    cause,
+})));
+const resolveAddress = (value) => {
+    if (typeof value === "string" && value.length > 0)
+        return value;
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return undefined;
+    }
+    const candidate = value.address ?? value.name;
+    return typeof candidate === "string" && candidate.length > 0
+        ? candidate
+        : undefined;
+};
+const addressDistance = (start, end) => Math.max(0, Number.parseInt(end, 16) - Number.parseInt(start, 16));