rea-agents 0.3.0 → 0.5.0

package/dist/hopper/BridgeLauncher.js

@@ -5,6 +5,8 @@ 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";
+import { cleanupOwnedProcessGroup, } from "../application/ProcessOwnership.js";
+import writeFileAtomic from "write-file-atomic";
 const execFileAsync = promisify(execFile);
 const HOPPER_BACKGROUND_STARTUP_MS = 5_000;
 /**
@@ -17,8 +19,9 @@ const HOPPER_BACKGROUND_STARTUP_MS = 5_000;
  * 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.
+ * REA owns only the short-lived launcher helper's run-token-authenticated
+ * process group. It does not claim ownership of the Hopper GUI process that
+ * macOS LaunchServices may create or reuse.
  */
 export class HopperApplicationLauncher {
     options;
@@ -30,6 +33,7 @@ export class HopperApplicationLauncher {
         const source = [
             `REA_SOCKET = ${JSON.stringify(session.socketPath)}`,
             `REA_TOKEN = ${JSON.stringify(session.token)}`,
+            `REA_RUN_ID = ${JSON.stringify(session.runId)}`,
             `exec(compile(open(${JSON.stringify(this.options.bridgeScriptPath)}, 'rb').read(), ${JSON.stringify(this.options.bridgeScriptPath)}, 'exec'))`,
             "",
         ].join("\n");
@@ -57,6 +61,8 @@ export class HopperApplicationLauncher {
                 return err(new HopperCancelledError());
             const child = spawn(this.options.launcherPath, args, {
                 stdio: ["ignore", "ignore", "pipe"],
+                detached: process.platform !== "win32",
+                env: { ...process.env, REA_PROCESS_RUN_ID: session.runId },
             });
             const started = await new Promise((resolve) => {
                 const onSpawn = () => {
@@ -72,13 +78,43 @@ export class HopperApplicationLauncher {
             });
             if (!started.ok)
                 return started;
-            return ok({ process: child, ownsProcessLifetime: false });
+            const pid = child.pid;
+            if (pid === undefined)
+                return err(new HopperStartError({ cause: new Error("missing launcher PID") }));
+            const ownership = {
+                schema_version: 1,
+                run_id: session.runId,
+                pid,
+                process_group_id: pid,
+                parent_pid: process.pid,
+                launcher: this.options.launcherPath,
+                created_at: new Date().toISOString(),
+            };
+            try {
+                await writeFileAtomic(join(session.directory, "ownership.json"), `${JSON.stringify(ownership)}\n`, { encoding: "utf8", mode: 0o600 });
+            }
+            catch (cause) {
+                await cleanupOwnedProcessGroup(ownedProcessGroup(session, pid, this.options.launcherPath));
+                return err(new HopperStartError({ cause }));
+            }
+            return ok({
+                process: child,
+                ownsProcessLifetime: true,
+                cleanup: () => cleanupOwnedProcessGroup(ownedProcessGroup(session, pid, this.options.launcherPath)),
+            });
         }
         catch (cause) {
             return err(new HopperStartError({ cause }));
         }
     }
 }
+const ownedProcessGroup = (session, pid, launcherPath) => ({
+    runId: session.runId,
+    leaderPid: pid,
+    processGroupId: pid,
+    expectedCommand: launcherPath,
+    expectedParentPid: process.pid,
+});
 const prepareHopperApplication = async (launcherPath, signal) => {
     const appBundle = hopperApplicationBundle(launcherPath);
     if (appBundle === undefined)

package/dist/hopper/HopperClient.js

@@ -1,4 +1,4 @@
-import { randomBytes } from "node:crypto";
+import { randomBytes, randomUUID } from "node:crypto";
 import { access, mkdtemp, rm } from "node:fs/promises";
 import { createConnection } from "node:net";
 import { tmpdir } from "node:os";
@@ -57,10 +57,12 @@ export class HopperClient {
         }
         const socketPath = join(this.#directory, "bridge.sock");
         this.#token = randomBytes(32).toString("hex");
+        const runId = randomUUID();
         const launched = await this.#options.launcher.launch({
             directory: this.#directory,
             socketPath,
             token: this.#token,
+            runId,
         }, signal === undefined ? {} : { signal });
         if (!launched.ok) {
             await this.close();
@@ -81,7 +83,7 @@ export class HopperClient {
             await this.close();
             return health;
         }
-        const parsed = parseServerInfo(health.value);
+        const parsed = parseServerInfo(health.value, runId);
         if (!parsed.ok)
             await this.close();
         return parsed;
@@ -109,7 +111,13 @@ export class HopperClient {
             socket?.destroy();
             this.#socket = undefined;
             if (this.#launch?.ownsProcessLifetime === true) {
-                this.#launch.process.kill("SIGTERM");
+                if (this.#launch.cleanup !== undefined) {
+                    const cleanup = await this.#launch.cleanup();
+                    if (!cleanup.cleaned)
+                        this.#logger.warn({ reason: cleanup.reason }, "Owned launcher cleanup failed closed");
+                }
+                else
+                    this.#launch.process.kill("SIGTERM");
             }
             this.#launch = undefined;
             if (this.#directory !== undefined) {
@@ -302,12 +310,13 @@ const connectOnce = async (socketPath) => new Promise((resolve) => {
         resolve(err(new HopperStartError({ cause })));
     });
 });
-const parseServerInfo = (value) => {
+const parseServerInfo = (value, expectedRunId) => {
     if (typeof value === "object" &&
         value !== null &&
         !Array.isArray(value) &&
         value.name === "REA Hopper bridge" &&
-        typeof value.version === "string") {
+        typeof value.version === "string" &&
+        value.run_id === expectedRunId) {
         return ok({ name: value.name, version: value.version });
     }
     return err(new HopperProtocolError("Hopper bridge health result is invalid"));

package/dist/hopper/HopperProvider.js

@@ -1,36 +1,54 @@
 import { fileURLToPath } from "node:url";
+import { createAnalysisExecution } from "../application/AnalysisProvider.js";
+import { AnalysisCapabilityUnavailableError } from "../domain/errors.js";
+import { err } from "../domain/result.js";
+import { ENHANCED_TOOL_CONTRACTS, OFFICIAL_TOOL_CONTRACTS, } from "../contracts/toolContracts.js";
 import { HopperApplicationLauncher } from "./BridgeLauncher.js";
 import { HopperClient } from "./HopperClient.js";
-const IDENTITY = {
+const IDENTITY = Object.freeze({
     id: "hopper",
     name: "Hopper Disassembler",
     version: null,
-};
-const OPERATIONS = [
-    "direct-analysis",
-    "decompilation",
-    "disassembly",
-    "cross-references",
-    "containing-procedure-resolution",
-    "procedure-references",
-    "analysis-metadata-mutation",
+});
+const MUTATING_OPERATIONS = new Set([
+    "set_address_name",
+    "set_addresses_names",
+    "set_bookmark",
+    "set_comment",
+    "set_inline_comment",
+    "unset_bookmark",
+]);
+const PROVIDER_TOOL_CONTRACTS = [
+    ...OFFICIAL_TOOL_CONTRACTS,
+    ...ENHANCED_TOOL_CONTRACTS.filter((contract) => contract.name === "analyze_function"),
 ];
-const CAPABILITIES = OPERATIONS.map((operation) => ({
-    operation,
-    version: 1,
+const CAPABILITIES = Object.freeze(PROVIDER_TOOL_CONTRACTS.map((contract) => Object.freeze({
+    provider: IDENTITY,
+    operation: contract.name,
+    inputContractVersion: 1,
+    outputContractVersion: 1,
     available: true,
-    pagination: "none",
+    reason: null,
+    pagination: "offset" in contract.inputSchema.shape ? "offset" : "none",
     exhaustive: false,
-    effects: {
-        mutatesArtifact: operation === "analysis-metadata-mutation",
+    effects: Object.freeze({
+        mutatesArtifact: MUTATING_OPERATIONS.has(contract.name),
         launchesProcess: true,
         mayShowUi: true,
         mayAccessNetwork: false,
-        mayWriteFilesystem: operation === "analysis-metadata-mutation",
-        requiresPrivileges: false,
-    },
-    limitations: ["Results depend on Hopper's completed static analysis."],
-}));
+        mayWriteFilesystem: MUTATING_OPERATIONS.has(contract.name),
+        changesPermissions: false,
+        requiresRoot: false,
+    }),
+    limits: Object.freeze({
+        maxResults: null,
+        maxPayloadBytes: null,
+        timeoutMs: null,
+    }),
+    limitations: Object.freeze([
+        "Results depend on Hopper's completed static analysis.",
+    ]),
+})));
 /** Concrete analysis provider backed by REA's private Hopper bridge. */
 export class HopperProvider {
     config;
@@ -46,6 +64,11 @@ export class HopperProvider {
         return CAPABILITIES;
     }
     createClient(target) {
+        if (target.kind !== "executable" && target.kind !== "database")
+            return {
+                execute: (operation) => Promise.resolve(err(new AnalysisCapabilityUnavailableError(IDENTITY.id, operation, `Hopper cannot open ${target.kind} targets directly. Inventory or extract the artifact first.`))),
+                close: () => Promise.resolve(),
+            };
         const client = new HopperClient({
             launcher: new HopperApplicationLauncher({
                 launcherPath: this.config.hopperLauncherPath,
@@ -59,7 +82,19 @@ export class HopperProvider {
             logger: this.logger.child({ layer: "bridge" }),
         });
         return {
-            execute: (operation, parameters, options) => client.callTool(operation, parameters, options),
+            execute: async (operation, parameters, options) => {
+                const result = await client.callTool(operation, parameters, options);
+                return result.ok
+                    ? {
+                        ok: true,
+                        value: createAnalysisExecution(result.value, IDENTITY, {
+                            limitations: [
+                                "Results depend on Hopper's completed static analysis.",
+                            ],
+                        }),
+                    }
+                    : result;
+            },
             close: () => client.close(),
         };
     }

package/dist/hopper/protocol.js

@@ -9,7 +9,18 @@ const responseSchema = z.union([
     }),
     z.object({
         id: z.number().int().nonnegative(),
-        error: z.object({ code: z.number().int(), message: z.string() }),
+        error: z.object({
+            code: z.number().int(),
+            message: z.string(),
+            type: z
+                .enum([
+                "remote",
+                "authorization",
+                "invalid_request",
+                "bridge_exception",
+            ])
+                .default("remote"),
+        }),
     }),
 ]);
 /** Parse one complete Hopper NDJSON response line. */
@@ -28,5 +39,5 @@ export const parseResponseLine = (line) => {
 };
 /** 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))
+    ? err(new HopperRemoteError(response.error.code, response.error.message, response.error.type))
     : ok(response.result);

package/dist/identity.js

@@ -10,5 +10,6 @@ export const PRODUCT_IDENTITY = {
     mcpCommand: "npx -y rea-agents mcp",
     mcpServerKey: "rea",
     skillName: "rea-analysis",
+    skillVersion: "10",
     configFileName: "rea.json",
 };

package/dist/main.js

@@ -33,7 +33,11 @@ export const run = async () => {
     }
     let handle;
     try {
-        handle = serveStdio(() => createServer(session, session, logger, config.value.processExecutionPolicy), {
+        handle = serveStdio(() => createServer(session, session, {
+            logger,
+            processPolicy: config.value.processExecutionPolicy,
+            evidenceFilePolicy: config.value.evidenceFilePolicy,
+        }), {
             onerror: () => {
                 serverLogger.error("MCP stdio transport error");
                 process.stderr.write("MCP stdio transport error\n");

package/dist/native/CommandRunner.js

@@ -0,0 +1,156 @@
+import { createHash, randomUUID } from "node:crypto";
+import { createReadStream } from "node:fs";
+import { realpath } from "node:fs/promises";
+import { spawn } from "node:child_process";
+import { err, ok } from "../domain/result.js";
+export class NativeCommandFailure extends Error {
+    tool;
+    reason;
+    exitCode;
+    constructor(tool, reason, exitCode = null, options) {
+        super(`Native command ${tool} failed: ${reason}`, options);
+        this.tool = tool;
+        this.reason = reason;
+        this.exitCode = exitCode;
+    }
+}
+/** Run allowlisted Xcode tools directly with bounded output and no shell. */
+export class XcrunCommandRunner {
+    #resolved = new Map();
+    run(tool, arguments_, options) {
+        if (!ALLOWED_TOOLS.has(tool))
+            return Promise.resolve(err(new NativeCommandFailure(tool, "unavailable")));
+        return this.#resolve(tool).then(async (resolved) => {
+            if (!resolved.ok)
+                return resolved;
+            const captured = await captureProcess(resolved.value.path, arguments_, tool, options);
+            return captured.ok
+                ? ok({
+                    ...captured.value,
+                    tool,
+                    executable: resolved.value.path,
+                    executableSha256: resolved.value.sha256,
+                    toolVersion: null,
+                    versionReason: "Tool exposes no uniform stable version flag; executable digest identifies it.",
+                    arguments: [...arguments_],
+                })
+                : captured;
+        });
+    }
+    #resolve(tool) {
+        const existing = this.#resolved.get(tool);
+        if (existing !== undefined)
+            return existing;
+        const pending = resolveTool(tool);
+        this.#resolved.set(tool, pending);
+        return pending;
+    }
+}
+const ALLOWED_TOOLS = new Set([
+    "codesign",
+    "dyld_info",
+    "dwarfdump",
+    "file",
+    "lipo",
+    "nm",
+    "otool",
+    "plutil",
+    "strings",
+    "swift-demangle",
+    "vtool",
+]);
+const resolveTool = async (tool) => {
+    const found = await captureProcess("/usr/bin/xcrun", ["--find", tool], "xcrun", { timeoutMs: 5_000, maxOutputBytes: 64 * 1024 });
+    if (!found.ok || found.value.exitCode !== 0)
+        return err(new NativeCommandFailure(tool, "unavailable"));
+    const candidate = found.value.stdout.trim();
+    if (!candidate.startsWith("/"))
+        return err(new NativeCommandFailure(tool, "unavailable"));
+    try {
+        const path = await realpath(candidate);
+        return ok({ path, sha256: await hashFile(path) });
+    }
+    catch (cause) {
+        return err(new NativeCommandFailure(tool, "io", null, { cause }));
+    }
+};
+const captureProcess = (executable, arguments_, tool, options) => new Promise((resolve) => {
+    if (options.signal?.aborted === true) {
+        resolve(err(new NativeCommandFailure(tool, "cancelled")));
+        return;
+    }
+    const runToken = randomUUID();
+    const child = spawn(executable, [...arguments_], {
+        shell: false,
+        stdio: ["ignore", "pipe", "pipe"],
+        env: {
+            PATH: "/usr/bin:/bin:/usr/sbin:/sbin",
+            LC_ALL: "C",
+            LANG: "C",
+            REA_NATIVE_RUN_TOKEN: runToken,
+        },
+    });
+    const stdout = [];
+    const stderr = [];
+    let stdoutBytes = 0;
+    let stderrBytes = 0;
+    let settled = false;
+    let reason;
+    const finish = (result) => {
+        if (settled)
+            return;
+        settled = true;
+        clearTimeout(timeout);
+        options.signal?.removeEventListener("abort", onAbort);
+        resolve(result);
+    };
+    const stop = (failure) => {
+        reason ??= failure;
+        child.kill("SIGKILL");
+    };
+    const onAbort = () => stop("cancelled");
+    options.signal?.addEventListener("abort", onAbort, { once: true });
+    const timeout = setTimeout(() => stop("timeout"), options.timeoutMs);
+    child.stdout.on("data", (chunk) => {
+        stdoutBytes += chunk.length;
+        if (stdoutBytes + stderrBytes > options.maxOutputBytes)
+            stop("output-limit");
+        else
+            stdout.push(chunk);
+    });
+    child.stderr.on("data", (chunk) => {
+        stderrBytes += chunk.length;
+        if (stdoutBytes + stderrBytes > options.maxOutputBytes)
+            stop("output-limit");
+        else
+            stderr.push(chunk);
+    });
+    child.once("error", (cause) => finish(err(new NativeCommandFailure(tool, "io", null, { cause }))));
+    child.once("close", (code, signal) => {
+        if (reason !== undefined) {
+            finish(err(new NativeCommandFailure(tool, reason, code)));
+            return;
+        }
+        if (code !== 0 && options.acceptNonZero !== true) {
+            finish(err(new NativeCommandFailure(tool, "nonzero-exit", code)));
+            return;
+        }
+        finish(ok({
+            stdout: Buffer.concat(stdout).toString("utf8"),
+            stderr: Buffer.concat(stderr).toString("utf8"),
+            stdoutBytes,
+            stderrBytes,
+            stdoutTruncated: false,
+            stderrTruncated: false,
+            exitCode: code,
+            signal,
+        }));
+    });
+});
+const hashFile = (path) => new Promise((resolve, reject) => {
+    const hash = createHash("sha256");
+    const stream = createReadStream(path);
+    stream.on("data", (chunk) => hash.update(chunk));
+    stream.once("error", reject);
+    stream.once("end", () => resolve(hash.digest("hex")));
+});