rea-agents 0.2.1

package/dist/hopper/BridgeLauncher.js

@@ -0,0 +1,130 @@
+import { spawn } from "node:child_process";
+import { execFile } from "node:child_process";
+import { chmod, writeFile } from "node:fs/promises";
+import { basename, dirname, extname, join } from "node:path";
+import { promisify } from "node:util";
+import { HopperCancelledError, HopperStartError } from "../domain/errors.js";
+import { err, ok } from "../domain/result.js";
+const execFileAsync = promisify(execFile);
+const HOPPER_BACKGROUND_STARTUP_MS = 5_000;
+/**
+ * Launches Hopper through its documented CLI and injects only REA's owned bridge.
+ *
+ * Hopper's `hopper` helper internally issues an AppleScript `activate` command.
+ * Consequently, opening a target may bring Hopper to the foreground even though
+ * REA first asks macOS to start the application hidden and in the background.
+ * REA cannot reliably suppress that activation without replacing Hopper's
+ * supported launcher; callers must treat possible foreground UI as an upstream
+ * Hopper constraint, not as evidence that analysis failed.
+ *
+ * The returned process is the short-lived launcher helper, not the Hopper app,
+ * so REA does not claim ownership of the application's lifetime.
+ */
+export class HopperApplicationLauncher {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    async launch(session, options = {}) {
+        const bootstrapPath = `${session.directory}/bootstrap.py`;
+        const source = [
+            `REA_SOCKET = ${JSON.stringify(session.socketPath)}`,
+            `REA_TOKEN = ${JSON.stringify(session.token)}`,
+            `exec(compile(open(${JSON.stringify(this.options.bridgeScriptPath)}, 'rb').read(), ${JSON.stringify(this.options.bridgeScriptPath)}, 'exec'))`,
+            "",
+        ].join("\n");
+        try {
+            await writeFile(bootstrapPath, source, { encoding: "utf8", mode: 0o600 });
+            await chmod(bootstrapPath, 0o600);
+        }
+        catch (cause) {
+            return err(new HopperStartError({ cause }));
+        }
+        const action = this.options.targetKind === "database" ? "--database" : "--executable";
+        const args = [
+            ...this.options.loaderArgs,
+            "--analysis",
+            "--python",
+            bootstrapPath,
+            action,
+            this.options.targetPath,
+        ];
+        try {
+            if (options.signal?.aborted === true)
+                return err(new HopperCancelledError());
+            const prepared = await prepareHopperApplication(this.options.launcherPath, options.signal);
+            if (!prepared)
+                return err(new HopperCancelledError());
+            const child = spawn(this.options.launcherPath, args, {
+                stdio: ["ignore", "ignore", "pipe"],
+            });
+            const started = await new Promise((resolve) => {
+                const onSpawn = () => {
+                    child.off("error", onError);
+                    resolve(ok(undefined));
+                };
+                const onError = (cause) => {
+                    child.off("spawn", onSpawn);
+                    resolve(err(new HopperStartError({ cause })));
+                };
+                child.once("spawn", onSpawn);
+                child.once("error", onError);
+            });
+            if (!started.ok)
+                return started;
+            return ok({ process: child, ownsProcessLifetime: false });
+        }
+        catch (cause) {
+            return err(new HopperStartError({ cause }));
+        }
+    }
+}
+const prepareHopperApplication = async (launcherPath, signal) => {
+    const appBundle = hopperApplicationBundle(launcherPath);
+    if (appBundle === undefined)
+        return signal?.aborted !== true;
+    const executablePath = join(appBundle, "Contents/MacOS/Hopper Disassembler");
+    if (await processIsRunning(executablePath))
+        return signal?.aborted !== true;
+    // This reduces activation when Hopper is cold, but the vendor launcher that
+    // follows may still activate its window. See HopperApplicationLauncher.
+    await execFileAsync("/usr/bin/open", [
+        "--hide",
+        "--background",
+        "-a",
+        appBundle,
+    ]);
+    return waitForDelay(HOPPER_BACKGROUND_STARTUP_MS, signal);
+};
+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 hopperApplicationBundle = (launcherPath) => {
+    if (basename(launcherPath) !== "hopper")
+        return undefined;
+    const candidate = dirname(dirname(dirname(launcherPath)));
+    return extname(candidate) === ".app" ? candidate : undefined;
+};
+const processIsRunning = async (executablePath) => {
+    try {
+        const processes = await execFileAsync("/bin/ps", ["-ax", "-o", "command="]);
+        return processes.stdout
+            .split("\n")
+            .some((command) => command.trim() === executablePath);
+    }
+    catch {
+        return false;
+    }
+};

package/dist/hopper/HopperClient.js

@@ -0,0 +1,314 @@
+import { randomBytes } from "node:crypto";
+import { access, mkdtemp, rm } from "node:fs/promises";
+import { createConnection } from "node:net";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { HopperCancelledError, HopperProcessError, HopperProtocolError, HopperStartError, HopperTimeoutError, } from "../domain/errors.js";
+import { err, ok } from "../domain/result.js";
+import { silentLogger } from "../logger.js";
+import { parseResponseLine, responseResult } from "./protocol.js";
+const MAX_LINE_BYTES = 10 * 1024 * 1024;
+const SESSION_ROOT = process.platform === "darwin" ? "/tmp" : tmpdir();
+/**
+ * Owns one authenticated NDJSON-over-Unix-socket bridge session.
+ *
+ * Each instance creates a private directory and random bearer token, correlates
+ * concurrent requests by numeric id, and removes its artifacts on close. It
+ * only terminates launch processes explicitly marked as owned; the normal
+ * Hopper launcher does not confer ownership of the GUI application.
+ */
+export class HopperClient {
+    #options;
+    #pending = new Map();
+    #logger;
+    #socket;
+    #launch;
+    #directory;
+    #token;
+    #nextId = 1;
+    #buffer = "";
+    #closing = false;
+    #startPromise;
+    #closePromise;
+    constructor(options) {
+        this.#logger = options.logger ?? silentLogger;
+        this.#options = {
+            ...options,
+            requestTimeoutMs: options.requestTimeoutMs ?? 30_000,
+            startupTimeoutMs: options.startupTimeoutMs ?? 120_000,
+        };
+    }
+    /** Launch the bridge once and complete its authenticated health handshake. */
+    start(signal) {
+        this.#startPromise ??= this.#start(signal);
+        return this.#startPromise;
+    }
+    async #start(signal) {
+        if (signal?.aborted === true)
+            return err(new HopperCancelledError());
+        if (this.#socket !== undefined || this.#directory !== undefined) {
+            return err(new HopperProtocolError("Hopper client is already started"));
+        }
+        try {
+            this.#directory = await mkdtemp(join(SESSION_ROOT, "rea-"));
+        }
+        catch (cause) {
+            return err(new HopperStartError({ cause }));
+        }
+        const socketPath = join(this.#directory, "bridge.sock");
+        this.#token = randomBytes(32).toString("hex");
+        const launched = await this.#options.launcher.launch({
+            directory: this.#directory,
+            socketPath,
+            token: this.#token,
+        }, signal === undefined ? {} : { signal });
+        if (!launched.ok) {
+            await this.close();
+            return launched;
+        }
+        this.#launch = launched.value;
+        this.#attachLauncher(launched.value);
+        const connected = await this.#connect(socketPath, signal);
+        if (!connected.ok) {
+            await this.close();
+            return connected;
+        }
+        const health = await this.#request("health", {}, {
+            timeoutMs: this.#options.startupTimeoutMs,
+            ...(signal === undefined ? {} : { signal }),
+        });
+        if (!health.ok) {
+            await this.close();
+            return health;
+        }
+        const parsed = parseServerInfo(health.value);
+        if (!parsed.ok)
+            await this.close();
+        return parsed;
+    }
+    /** Invoke one declared operation, returning timeout and cancellation as values. */
+    async callTool(name, arguments_ = {}, options = {}) {
+        const started = await this.start(options.signal);
+        if (!started.ok)
+            return started;
+        return this.#request(name, arguments_, options);
+    }
+    /** Stop the bridge, settle outstanding requests, and remove session artifacts. */
+    close() {
+        this.#closePromise ??= Promise.resolve().then(() => this.#close());
+        return this.#closePromise;
+    }
+    async #close() {
+        this.#closing = true;
+        try {
+            const socket = this.#socket;
+            if (socket !== undefined && !socket.destroyed) {
+                await this.#request("shutdown", {}, { timeoutMs: 500 }).catch(() => err(new HopperProcessError(null)));
+            }
+            this.#failAll(new HopperProcessError(null));
+            socket?.destroy();
+            this.#socket = undefined;
+            if (this.#launch?.ownsProcessLifetime === true) {
+                this.#launch.process.kill("SIGTERM");
+            }
+            this.#launch = undefined;
+            if (this.#directory !== undefined) {
+                await rm(this.#directory, { recursive: true, force: true });
+                this.#directory = undefined;
+            }
+            this.#token = undefined;
+            this.#startPromise = undefined;
+        }
+        finally {
+            this.#closing = false;
+            this.#closePromise = undefined;
+        }
+    }
+    async #connect(socketPath, signal) {
+        const deadline = Date.now() + this.#options.startupTimeoutMs;
+        while (Date.now() < deadline) {
+            if (signal?.aborted === true)
+                return err(new HopperCancelledError());
+            if (this.#closing)
+                return err(new HopperProcessError(null));
+            try {
+                await access(socketPath);
+            }
+            catch {
+                if (!(await waitForDelay(50, signal)))
+                    return err(new HopperCancelledError());
+                continue;
+            }
+            const attempt = await connectOnce(socketPath);
+            if (attempt.ok) {
+                this.#socket = attempt.value;
+                this.#attachSocket(attempt.value);
+                return ok(undefined);
+            }
+            if (!(await waitForDelay(50, signal)))
+                return err(new HopperCancelledError());
+        }
+        return err(new HopperTimeoutError(this.#options.startupTimeoutMs));
+    }
+    async #request(method, params, options) {
+        const socket = this.#socket;
+        const token = this.#token;
+        if (socket === undefined || socket.destroyed || token === undefined) {
+            return err(new HopperProcessError(null));
+        }
+        if (options.signal?.aborted === true)
+            return err(new HopperCancelledError());
+        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,
+            });
+        });
+        socket.write(`${JSON.stringify({ id, token, method, params })}\n`, (cause) => {
+            if (cause !== undefined && cause !== null)
+                this.#settle(id, err(new HopperProcessError(null)));
+        });
+        const result = await response;
+        this.#logger[result.ok ? "debug" : "warn"]({
+            method,
+            durationMs: Math.round((performance.now() - startedAt) * 100) / 100,
+            status: result.ok ? "ok" : "error",
+            ...(result.ok ? {} : { errorTag: result.error._tag }),
+        }, "Hopper bridge request completed");
+        return result;
+    }
+    #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));
+        });
+    }
+    #attachLauncher(launch) {
+        launch.process.stderr?.on("data", (chunk) => {
+            this.#options.onDiagnostic?.({
+                type: "launcher-stderr",
+                bytes: chunk.byteLength,
+            });
+        });
+        launch.process.on("exit", (code) => {
+            this.#options.onDiagnostic?.({ type: "launcher-exit", code });
+            if (launch.ownsProcessLifetime && !this.#closing) {
+                this.#failAll(new HopperProcessError(code));
+            }
+        });
+    }
+    #onData(chunk) {
+        this.#buffer += chunk;
+        let newline = this.#buffer.indexOf("\n");
+        while (newline >= 0) {
+            const line = this.#buffer.slice(0, newline).trim();
+            this.#buffer = this.#buffer.slice(newline + 1);
+            if (Buffer.byteLength(line) > MAX_LINE_BYTES) {
+                this.#abortProtocol("Hopper response exceeded the maximum line size");
+                return;
+            }
+            if (line.length > 0)
+                this.#onLine(line);
+            newline = this.#buffer.indexOf("\n");
+        }
+        if (Buffer.byteLength(this.#buffer) > MAX_LINE_BYTES) {
+            this.#abortProtocol("Hopper response exceeded the maximum line size");
+        }
+    }
+    #onLine(line) {
+        const parsed = parseResponseLine(line);
+        if (!parsed.ok) {
+            this.#abortProtocol(parsed.error.message, parsed.error);
+            return;
+        }
+        if (!this.#pending.has(parsed.value.id)) {
+            if (parsed.value.id >= this.#nextId) {
+                this.#abortProtocol("Hopper returned an unknown response id");
+            }
+            return;
+        }
+        this.#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));
+    }
+}
+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 parseServerInfo = (value) => {
+    if (typeof value === "object" &&
+        value !== null &&
+        !Array.isArray(value) &&
+        value.name === "REA Hopper bridge" &&
+        typeof value.version === "string") {
+        return ok({ name: value.name, version: value.version });
+    }
+    return err(new HopperProtocolError("Hopper bridge health result is invalid"));
+};

package/dist/hopper/HopperProvider.js

@@ -0,0 +1,66 @@
+import { fileURLToPath } from "node:url";
+import { HopperApplicationLauncher } from "./BridgeLauncher.js";
+import { HopperClient } from "./HopperClient.js";
+const IDENTITY = {
+    id: "hopper",
+    name: "Hopper Disassembler",
+    version: null,
+};
+const OPERATIONS = [
+    "direct-analysis",
+    "decompilation",
+    "disassembly",
+    "cross-references",
+    "containing-procedure-resolution",
+    "procedure-references",
+    "analysis-metadata-mutation",
+];
+const CAPABILITIES = OPERATIONS.map((operation) => ({
+    operation,
+    version: 1,
+    available: true,
+    pagination: "none",
+    exhaustive: false,
+    effects: {
+        mutatesArtifact: operation === "analysis-metadata-mutation",
+        launchesProcess: true,
+        mayShowUi: true,
+        mayAccessNetwork: false,
+        mayWriteFilesystem: operation === "analysis-metadata-mutation",
+        requiresPrivileges: false,
+    },
+    limitations: ["Results depend on Hopper's completed static analysis."],
+}));
+/** Concrete analysis provider backed by REA's private Hopper bridge. */
+export class HopperProvider {
+    config;
+    logger;
+    constructor(config, logger) {
+        this.config = config;
+        this.logger = logger;
+    }
+    identity() {
+        return IDENTITY;
+    }
+    capabilities() {
+        return CAPABILITIES;
+    }
+    createClient(target) {
+        const client = new HopperClient({
+            launcher: new HopperApplicationLauncher({
+                launcherPath: this.config.hopperLauncherPath,
+                targetPath: target.path,
+                targetKind: target.kind,
+                loaderArgs: this.config.hopperLoaderArgs.length > 0
+                    ? this.config.hopperLoaderArgs
+                    : target.loaderArgs,
+                bridgeScriptPath: fileURLToPath(new URL("../../bridge/hopper_bridge.py", import.meta.url)),
+            }),
+            logger: this.logger.child({ layer: "bridge" }),
+        });
+        return {
+            execute: (operation, parameters, options) => client.callTool(operation, parameters, options),
+            close: () => client.close(),
+        };
+    }
+}

package/dist/hopper/protocol.js

@@ -0,0 +1,32 @@
+import { z } from "zod";
+import { HopperProtocolError, HopperRemoteError } from "../domain/errors.js";
+import { jsonValueSchema } from "../domain/jsonValue.js";
+import { err, ok } from "../domain/result.js";
+const responseSchema = z.union([
+    z.object({
+        id: z.number().int().nonnegative(),
+        result: jsonValueSchema,
+    }),
+    z.object({
+        id: z.number().int().nonnegative(),
+        error: z.object({ code: z.number().int(), message: z.string() }),
+    }),
+]);
+/** Parse one complete Hopper NDJSON response line. */
+export const parseResponseLine = (line) => {
+    let decoded;
+    try {
+        decoded = JSON.parse(line);
+    }
+    catch (cause) {
+        return err(new HopperProtocolError("Hopper returned malformed JSON", { cause }));
+    }
+    const parsed = responseSchema.safeParse(decoded);
+    return parsed.success
+        ? ok(parsed.data)
+        : err(new HopperProtocolError("Hopper returned a response outside the bridge contract", { cause: parsed.error }));
+};
+/** Project a parsed response into its result or expected remote failure. */
+export const responseResult = (response) => "error" in response
+    ? err(new HopperRemoteError(response.error.code, response.error.message))
+    : ok(response.result);

package/dist/identity.js

@@ -0,0 +1,14 @@
+/**
+ * Canonical public identity shared by packaging, setup, MCP, and skill install.
+ * Centralization prevents persistent client registrations from drifting from
+ * the npm package or executable exposed in package.json.
+ */
+export const PRODUCT_IDENTITY = {
+    displayName: "REA",
+    packageName: "rea-agents",
+    cliBinary: "rea",
+    mcpCommand: "npx -y rea-agents mcp",
+    mcpServerKey: "rea",
+    skillName: "rea-analysis",
+    configFileName: "rea.json",
+};

package/dist/logger.js

@@ -0,0 +1,27 @@
+import pino, {} from "pino";
+import { z } from "zod";
+const logLevelSchema = z
+    .enum(["trace", "debug", "info", "warn", "error", "fatal", "silent"])
+    .default("info");
+/** Parse the optional REA_LOG_LEVEL environment variable. */
+export const parseLogLevel = (value) => logLevelSchema.parse(value);
+/** Create a JSON logger whose destination cannot corrupt MCP stdout frames. */
+export const createLogger = (mode, level) => pino({
+    level,
+    base: { application: "rea", mode },
+    redact: {
+        paths: [
+            "token",
+            "*.token",
+            "params",
+            "*.params",
+            "arguments",
+            "*.arguments",
+            "environment",
+            "*.environment",
+        ],
+        censor: "[Redacted]",
+    },
+}, pino.destination({ dest: mode === "mcp" ? 2 : 1, sync: false }));
+/** Logger used by embedders that have not opted into process output. */
+export const silentLogger = pino({ level: "silent" });

package/dist/main.js

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+import { pathToFileURL } from "node:url";
+import { realpathSync } from "node:fs";
+import { serveStdio, } from "@modelcontextprotocol/server/stdio";
+import { parseConfig } from "./config.js";
+import { createBinarySession } from "./application/runtime.js";
+import { createServer } from "./server/createServer.js";
+import { createLogger } from "./logger.js";
+/**
+ * Start the long-lived MCP adapter and install idempotent shutdown handlers.
+ * The adapter owns its BinarySession for the process lifetime; EOF and process
+ * signals close bridge resources without assuming ownership of the Hopper app.
+ */
+export const run = async () => {
+    const config = parseConfig(process.env);
+    if (!config.ok) {
+        process.stderr.write(`${config.error._tag}: ${config.error.message}\n`);
+        return 1;
+    }
+    const logger = createLogger("mcp", config.value.logLevel);
+    const serverLogger = logger.child({ layer: "server" });
+    const session = createBinarySession(config.value, logger);
+    if (config.value.hopperTargetPath !== undefined) {
+        const opened = await session.open(config.value.hopperTargetPath, {
+            targetKind: config.value.hopperTargetKind,
+        });
+        if (!opened.ok) {
+            await session.close();
+            serverLogger.error({ errorTag: opened.error._tag }, "Initial target failed to open");
+            process.stderr.write(`${opened.error._tag}: ${opened.error.message}\n`);
+            return 1;
+        }
+    }
+    let handle;
+    try {
+        handle = serveStdio(() => createServer(session, session, logger, config.value.processExecutionPolicy), {
+            onerror: () => {
+                serverLogger.error("MCP stdio transport error");
+                process.stderr.write("MCP stdio transport error\n");
+            },
+        });
+    }
+    catch {
+        await session.close();
+        serverLogger.error("Failed to start MCP stdio transport");
+        process.stderr.write("Failed to start MCP stdio transport\n");
+        return 1;
+    }
+    let shutdownPromise;
+    const shutdown = () => {
+        shutdownPromise ??= (async () => {
+            await handle.close();
+            await session.close();
+        })();
+        return shutdownPromise;
+    };
+    const requestShutdown = () => {
+        shutdown().catch(() => {
+            process.exitCode = 1;
+            serverLogger.error("Failed to shut down cleanly");
+            process.stderr.write("Failed to shut down cleanly\n");
+        });
+    };
+    process.once("SIGINT", requestShutdown);
+    process.once("SIGTERM", requestShutdown);
+    process.stdin.once("end", requestShutdown);
+    process.stdin.once("close", requestShutdown);
+    return 0;
+};
+const entryPath = process.argv[1];
+if (entryPath !== undefined &&
+    pathToFileURL(realpathSync(entryPath)).href === import.meta.url) {
+    run()
+        .then((exitCode) => {
+        process.exitCode = exitCode;
+    })
+        .catch(() => {
+        process.stderr.write("Unexpected server startup failure\n");
+        process.exitCode = 1;
+    });
+}