rea-agents 0.4.0 → 0.5.0

package/README.md

@@ -170,12 +170,12 @@ Uninstall preserves Hopper, Homebrew, Node.js, evidence, captures, external evid
 
 ### CLI or coding agent?
 
-| If you want to…                                           | Use                                            |
-| --------------------------------------------------------- | ---------------------------------------------- |
-| Ask an agent to investigate an app and build a feature    | Install the skill, then talk to your agent     |
-| Inspect or decompile one part of an app from the Terminal | `rea analyze` or `rea decompile`               |
-| Validate or canonicalize an Evidence v2 bundle            | `rea evidence-import` or `rea evidence-export` |
-| Import source as historical reference                     | `rea import-reference-source`                  |
+| If you want to…                                           | Use                                                            |
+| --------------------------------------------------------- | -------------------------------------------------------------- |
+| Ask an agent to investigate an app and build a feature    | Install the skill, then talk to your agent                     |
+| Inspect or decompile one part of an app from the Terminal | `rea analyze` or `rea decompile`                               |
+| Validate, canonicalize, or compare Evidence v2 bundles    | `rea evidence-import`, `rea evidence-export`, or `rea compare` |
+| Import source as historical reference                     | `rea import-reference-source`                                  |
 
 Filesystem evidence commands and MCP file tools are disabled until the operator approves absolute roots:
 
@@ -183,6 +183,7 @@ Filesystem evidence commands and MCP file tools are disabled until the operator
 export REA_EVIDENCE_ROOTS_JSON='["/absolute/path/to/evidence"]'
 rea evidence-import /absolute/path/to/evidence/bundle.json
 rea evidence-export /absolute/path/to/evidence/bundle.json /absolute/path/to/evidence/canonical.json
+rea compare /absolute/path/to/evidence/left.json /absolute/path/to/evidence/right.json
 ```
 
 Historical source import requires a separate allowlist and never treats source as current behavioral authority:
@@ -276,6 +277,8 @@ REA is growing into a toolkit for understanding software across static artifacts
 
 Roadmap items describe direction, not shipped support. New providers must produce the same evidence and safety metadata as existing capabilities before they become part of the public workflow.
 
+See the [static-analysis provider evaluation](docs/provider-evaluation.md) for the current research matrix and admission gate.
+
 ## Using REA with other coding agents
 
 Setup currently configures Claude Desktop and Cursor automatically. Any coding agent that supports local MCP servers can use REA with the configuration below.
@@ -320,9 +323,20 @@ The agent workflow above is the easiest way to use REA. For a one-off overview f
 
 ```bash
 npx -y rea-agents analyze /Applications/Notes.app
+npx -y rea-agents inspect /Applications/Notes.app
+npx -y rea-agents inspect /Applications/Notes.app --detail detailed --limit 20
+npx -y rea-agents search /Applications/Notes.app "offline"
+npx -y rea-agents function /Applications/Notes.app 0x1000
+npx -y rea-agents xrefs /Applications/Notes.app 0x1000
+npx -y rea-agents trace /Applications/Notes.app "offline"
+npx -y rea-agents compare /absolute/path/to/left-evidence.json /absolute/path/to/right-evidence.json
+npx -y rea-agents capabilities
+npx -y rea-agents providers
 ```
 
-Run `npx -y rea-agents --help` for direct decompilation and other options.
+Run `npx -y rea-agents --help` for direct decompilation, bounded search and
+other options. `analyze` and `inspect` share the same overview workflow;
+`function`, `xrefs`, and `trace` return the same Evidence v2 envelopes as MCP.
 
 Or install the `rea` command globally:
 

package/bridge/hopper_bridge.py

@@ -274,9 +274,15 @@ def _search_page(document, kind, params):
             raise ValueError("Invalid regex pattern") from error
         matches = lambda value: expression.search(value) is not None
 
-    matching = [item for item in _search_inventory(document, kind) if matches(item[1])]
-    selected = matching[offset:offset + limit]
-    total = len(matching)
+    selected = []
+    total = 0
+    page_end = offset + limit
+    for item in _search_inventory(document, kind):
+        if not matches(item[1]):
+            continue
+        if offset <= total < page_end:
+            selected.append(item)
+        total += 1
     next_offset = offset + len(selected)
     has_more = next_offset < total
     return {
@@ -654,7 +660,7 @@ def _serve_connection(connection):
             should_stop = request["method"] == "shutdown"
             response = {"id": request_id, "result": _json_safe(result)}
         except Exception as error:
-            response = {"id": request_id if isinstance(request_id, int) else 0, "error": {"code": -32000, "message": str(error)[:512]}}
+            response = {"id": request_id if isinstance(request_id, int) else 0, "error": {"code": -32000, "message": str(error)[:512], "type": _diagnostic_type(error)}}
         file.write((json.dumps(response, separators=(",", ":")) + "\n").encode("utf-8"))
         file.flush()
         if should_stop:
@@ -663,6 +669,14 @@ def _serve_connection(connection):
     connection.close()
 
 
+def _diagnostic_type(error):
+    if isinstance(error, PermissionError):
+        return "authorization"
+    if isinstance(error, (ValueError, TypeError, KeyError)):
+        return "invalid_request"
+    return "bridge_exception"
+
+
 def _run():
     """Own a permission-restricted, single-client Unix socket for this bridge."""
     if os.path.exists(REA_SOCKET):

package/dist/application/BinarySession.js

@@ -180,6 +180,15 @@ export class BinarySession {
             name: this.#providerIdentity.name,
             version: this.#providerIdentity.version,
         };
+        const providers = new Map();
+        if (this.#capabilities === undefined)
+            providers.set(provider.id, provider);
+        else
+            for (const descriptor of this.#capabilities.values())
+                providers.set(descriptor.provider.id, descriptor.provider);
+        const providerList = [...providers.values()]
+            .sort((left, right) => left.id.localeCompare(right.id))
+            .map(({ id, name, version }) => ({ id, name, version }));
         const capabilities = this.#capabilities === undefined
             ? []
             : [...this.#capabilities.values()]
@@ -209,10 +218,11 @@ export class BinarySession {
                 limitations: [...descriptor.limitations],
             }));
         return target === undefined
-            ? { open: false, provider, capabilities }
+            ? { open: false, provider, providers: providerList, capabilities }
             : {
                 open: true,
                 provider,
+                providers: providerList,
                 capabilities,
                 path: target.path,
                 sha256: target.sha256,

package/dist/application/DirectAnalysis.js

@@ -16,6 +16,19 @@ const WORKFLOW_PROVIDER = {
 export const runDirectAnalysis = async (path, tool, arguments_, logger = silentLogger) => runAnalysis(path, tool, arguments_, logger);
 /** Execute one provider-native semantic operation with atomic provenance. */
 export const runProviderAnalysis = async (path, tool, arguments_, logger = silentLogger) => runAnalysis(path, tool, arguments_, logger);
+/** Describe configured providers without opening a target or launching Hopper. */
+export const runSessionStatus = async (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 {
+        return session.status();
+    }
+    finally {
+        await session.close();
+    }
+};
 const runAnalysis = async (path, tool, arguments_, logger) => {
     const config = parseConfig(process.env);
     if (!config.ok)
@@ -25,10 +38,14 @@ const runAnalysis = async (path, tool, arguments_, logger) => {
         const opened = await session.open(path);
         if (!opened.ok)
             return { error: opened.error._tag, message: opened.error.message };
-        if (tool === "binary_overview") {
+        if (tool === "binary_overview" ||
+            tool === "analyze_function" ||
+            tool === "trace_feature") {
             const result = await new EnhancedTools(session).execute(tool, arguments_);
             return result.ok
-                ? createEvidence(opened.value, WORKFLOW_PROVIDER, {
+                ? createEvidence(opened.value, tool === "analyze_function"
+                    ? session.providerIdentity(tool)
+                    : WORKFLOW_PROVIDER, {
                     operation: tool,
                     parameters: arguments_,
                     result: result.value,

package/dist/application/EnhancedTools.js

@@ -1,5 +1,5 @@
 import { enhancedInputSchemas } from "../contracts/enhancedInputs.js";
-import { AnalysisInputError, AnalysisOutputError, } from "../domain/errors.js";
+import { AnalysisInputError, AnalysisCancelledError, AnalysisOutputError, } 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";
@@ -337,6 +337,8 @@ export class EnhancedTools {
         }
     }
     async #call(name, arguments_, signal) {
+        if (signal?.aborted === true)
+            return err(new AnalysisCancelledError(name));
         const execution = await this.analysis.execute(name, arguments_, signal === undefined ? {} : { signal });
         return execution.ok ? ok(execution.value.result) : execution;
     }

package/dist/application/EvidenceBundleCommands.js

@@ -1,4 +1,7 @@
+import { EvidenceIntegrityError, } from "../domain/errors.js";
+import { jsonValueSchema } from "../domain/jsonValue.js";
 import { err, ok } from "../domain/result.js";
+import { compareBundles } from "../domain/bundleComparison.js";
 import { EvidenceLedger } from "./EvidenceLedger.js";
 import { readEvidenceBundle, writeEvidenceBundle, } from "./EvidenceBundleFiles.js";
 /** Validate and merge one bundle using the same bounded ledger as MCP. */
@@ -19,6 +22,25 @@ export const exportEvidenceBundleCommand = async (sourcePath, outputPath, overwr
         return loaded;
     return projectWrite(loaded.value, await writeEvidenceBundle(loaded.value, outputPath, overwrite, policy));
 };
+/** Compare two validated canonical Evidence v2 bundles without session state. */
+export const compareEvidenceBundlesCommand = async (input) => {
+    const [left, right] = await Promise.all([
+        readEvidenceBundle(input.leftPath, input.policy),
+        readEvidenceBundle(input.rightPath, input.policy),
+    ]);
+    if (!left.ok)
+        return left;
+    if (!right.ok)
+        return right;
+    try {
+        return ok(jsonValueSchema.parse(compareBundles(left.value, right.value, [], input.offset, input.limit)));
+    }
+    catch (cause) {
+        return err(new EvidenceIntegrityError("Evidence bundle comparison failed", {
+            cause,
+        }));
+    }
+};
 const createLedger = () => new EvidenceLedger({ maxRecords: 10_000, maxBytes: 64 * 1024 * 1024 });
 const projectWrite = (bundle, written) => written.ok
     ? ok({

package/dist/application/ProcessOwnership.js

@@ -54,6 +54,21 @@ export const cleanupOwnedProcessGroup = async (ownership, host = systemHost) =>
     }
     if (members.length === 0)
         return { cleaned: true, signaled: false };
+    const leader = members.find((member) => member.pid === ownership.leaderPid);
+    if (leader !== undefined) {
+        if (ownership.expectedParentPid !== undefined &&
+            leader.parentPid !== ownership.expectedParentPid)
+            return {
+                cleaned: false,
+                reason: "owned launcher parent identity did not match",
+            };
+        if (ownership.expectedCommand !== undefined &&
+            !commandMatches(leader.command, ownership.expectedCommand))
+            return {
+                cleaned: false,
+                reason: "owned launcher command identity did not match",
+            };
+    }
     for (const member of members) {
         let environment;
         try {
@@ -82,3 +97,9 @@ export const cleanupOwnedProcessGroup = async (ownership, host = systemHost) =>
     }
     return { cleaned: true, signaled: true };
 };
+const commandMatches = (actual, expected) => {
+    const normalizedActual = actual.trim();
+    const normalizedExpected = expected.trim();
+    return (normalizedActual === normalizedExpected ||
+        normalizedActual.startsWith(`${normalizedExpected} `));
+};

package/dist/application/RealHopperAssertions.js

@@ -25,6 +25,17 @@ export const firstProcedureAddress = (input) => {
         throw new TypeError("Procedure page was empty");
     return first.address;
 };
+/** Reject two target paths that resolve to the same binary content. */
+export const requireDistinctTargetHashes = (firstHash, secondHash) => {
+    if (typeof firstHash !== "string" ||
+        typeof secondHash !== "string" ||
+        firstHash.length === 0 ||
+        secondHash.length === 0) {
+        throw new TypeError("Target hashes must be non-empty strings");
+    }
+    if (firstHash === secondHash)
+        throw new TypeError("Real-Hopper verification requires distinct binaries");
+};
 /** Reject empty and success-shaped embedded decompilation failures. */
 export const requirePseudocode = (input, operation) => {
     if (typeof input !== "string" || input.trim().length === 0)

package/dist/cli.js

@@ -1,14 +1,15 @@
 import { Cli, z } from "incur";
 import { fileURLToPath } from "node:url";
 import { runDoctor } from "./application/Doctor.js";
-import { runDirectAnalysis, runProviderAnalysis, } from "./application/DirectAnalysis.js";
+import { runDirectAnalysis, runProviderAnalysis, runSessionStatus, } from "./application/DirectAnalysis.js";
 import { runSetup } from "./application/Setup.js";
 import { runUninstall } from "./application/Uninstall.js";
 import { PRODUCT_IDENTITY } from "./identity.js";
 import { createLogger, parseLogLevel } from "./logger.js";
+import { logCliCommand } from "./cliLogging.js";
 import { parseConfig } from "./config.js";
-import { exportEvidenceBundleCommand, importEvidenceBundleCommand, } from "./application/EvidenceBundleCommands.js";
 import { importReferenceSource } from "./application/ReferenceSourceImport.js";
+import { registerEvidenceCommands } from "./cliEvidenceCommands.js";
 /**
  * Build the one-shot Incur CLI without starting Hopper at import time.
  * Analysis commands acquire and close their own sessions; bare `mcp` and
@@ -35,6 +36,23 @@ export const createCli = () => {
             ],
         },
     });
+    registerCoreCommands(cli, logger);
+    registerFunctionCommand(cli, logger);
+    registerSearchCommand(cli, logger);
+    registerXrefsCommand(cli, logger);
+    registerTraceCommand(cli, logger);
+    registerCapabilityCommands(cli, logger);
+    registerNativeCommands(cli, logger);
+    registerArtifactCommands(cli, logger);
+    registerEvidenceCommands(cli, logger);
+    registerReferenceSourceCommand(cli, logger);
+    return cli;
+};
+const registerCoreCommands = (cli, logger) => {
+    const overviewOptions = z.object({
+        detail: z.enum(["concise", "detailed"]).default("concise"),
+        limit: z.number().int().min(1).max(50).default(10),
+    });
     cli.command("setup", {
         description: "Install requirements and configure coding agents",
         options: z.object({
@@ -69,7 +87,16 @@ export const createCli = () => {
         args: z.object({
             path: z.string().describe("App, program, or Hopper database path"),
         }),
-        run: ({ args }) => logCliCommand(logger, "analyze", () => runDirectAnalysis(args.path, "binary_overview", {}, logger)),
+        options: overviewOptions,
+        run: ({ args, options }) => logCliCommand(logger, "analyze", () => runDirectAnalysis(args.path, "binary_overview", { detail: options.detail, limit: options.limit }, logger)),
+    });
+    cli.command("inspect", {
+        description: "Inspect an app overview with evidence",
+        args: z.object({
+            path: z.string().describe("App, program, or Hopper database path"),
+        }),
+        options: overviewOptions,
+        run: ({ args, options }) => logCliCommand(logger, "inspect", () => runDirectAnalysis(args.path, "binary_overview", { detail: options.detail, limit: options.limit }, logger)),
     });
     cli.command("decompile", {
         description: "Read one part of an app as code",
@@ -79,11 +106,101 @@ export const createCli = () => {
         }),
         run: ({ args }) => logCliCommand(logger, "decompile", () => runDirectAnalysis(args.path, "procedure_pseudo_code", { procedure: args.address }, logger)),
     });
-    registerNativeCommands(cli, logger);
-    registerArtifactCommands(cli, logger);
-    registerEvidenceCommands(cli, logger);
-    registerReferenceSourceCommand(cli, logger);
-    return cli;
+};
+const registerXrefsCommand = (cli, logger) => {
+    cli.command("xrefs", {
+        description: "List bounded references to an analyzed address",
+        args: z.object({
+            path: z.string().describe("App or program path"),
+            address: z.string().describe("Hexadecimal address"),
+        }),
+        run: ({ args }) => logCliCommand(logger, "xrefs", () => runDirectAnalysis(args.path, "xrefs", { address: args.address }, logger)),
+    });
+};
+const registerTraceCommand = (cli, logger) => {
+    cli.command("trace", {
+        description: "Trace a bounded literal feature through analyzed references",
+        args: z.object({
+            path: z.string().describe("App or program path"),
+            query: z.string().min(1).describe("Literal feature query"),
+        }),
+        options: z.object({
+            caseSensitive: z.boolean().default(false),
+            limit: z.number().int().min(1).max(100).default(20),
+            maxOperations: z.number().int().min(1).max(100).default(20),
+        }),
+        alias: {
+            caseSensitive: "case-sensitive",
+            maxOperations: "max-operations",
+        },
+        run: ({ args, options }) => logCliCommand(logger, "trace", () => runDirectAnalysis(args.path, "trace_feature", {
+            query: args.query,
+            case_sensitive: options.caseSensitive,
+            limit: options.limit,
+            max_operations: options.maxOperations,
+        }, logger)),
+    });
+};
+const registerCapabilityCommands = (cli, logger) => {
+    for (const command of ["capabilities", "providers"]) {
+        cli.command(command, {
+            description: command === "capabilities"
+                ? "List provider capabilities and side effects"
+                : "List configured analysis providers",
+            run: () => logCliCommand(logger, command, () => runSessionStatus(logger)),
+        });
+    }
+};
+const registerFunctionCommand = (cli, logger) => {
+    cli.command("function", {
+        description: "Analyze one bounded function with evidence",
+        args: z.object({
+            path: z.string().describe("App or program path"),
+            address: z.string().describe("Procedure name or address"),
+        }),
+        options: z.object({
+            includeAssembly: z.boolean().default(false),
+            limit: z.number().int().min(1).max(500).default(100),
+            maxPseudocodeChars: z.number().int().min(1).max(100_000).default(20_000),
+            maxInstructions: z.number().int().min(1).max(5_000).default(500),
+        }),
+        alias: {
+            includeAssembly: "include-assembly",
+            maxPseudocodeChars: "max-pseudocode-chars",
+            maxInstructions: "max-instructions",
+        },
+        run: ({ args, options }) => logCliCommand(logger, "function", () => runDirectAnalysis(args.path, "analyze_function", {
+            procedure: args.address,
+            include_assembly: options.includeAssembly,
+            limit: options.limit,
+            max_pseudocode_chars: options.maxPseudocodeChars,
+            max_instructions: options.maxInstructions,
+        }, logger)),
+    });
+};
+const registerSearchCommand = (cli, logger) => {
+    cli.command("search", {
+        description: "Search bounded analyzed strings or procedure names",
+        args: z.object({
+            path: z.string().describe("App or program path"),
+            pattern: z.string().min(1).describe("Literal text or regex pattern"),
+        }),
+        options: z.object({
+            kind: z.enum(["strings", "procedures"]).default("strings"),
+            mode: z.enum(["literal", "regex"]).default("literal"),
+            caseSensitive: z.boolean().default(false),
+            offset: z.number().int().min(0).default(0),
+            limit: z.number().int().min(1).max(100).default(100),
+        }),
+        alias: { caseSensitive: "case-sensitive" },
+        run: ({ args, options }) => logCliCommand(logger, "search", () => runDirectAnalysis(args.path, options.kind === "strings" ? "search_strings" : "search_procedures", {
+            pattern: args.pattern,
+            mode: options.mode,
+            case_sensitive: options.caseSensitive,
+            offset: options.offset,
+            limit: options.limit,
+        }, logger)),
+    });
 };
 const registerReferenceSourceCommand = (cli, logger) => {
     cli.command("import-reference-source", {
@@ -177,59 +294,3 @@ const registerNativeCommands = (cli, logger) => {
         run: ({ args }) => logCliCommand(logger, "demangle-swift", () => runProviderAnalysis(args.path, "demangle_swift", { symbols: args.symbols }, logger)),
     });
 };
-const registerEvidenceCommands = (cli, logger) => {
-    cli.command("evidence-import", {
-        description: "Validate and import a bounded local Evidence v2 bundle",
-        args: z.object({
-            path: z.string().describe("Evidence bundle JSON path"),
-        }),
-        run: ({ args }) => logCliCommand(logger, "evidence-import", async () => {
-            const config = parseConfig(process.env);
-            if (!config.ok)
-                return { error: config.error._tag, message: config.error.message };
-            const imported = await importEvidenceBundleCommand(args.path, config.value.evidenceFilePolicy);
-            return imported.ok
-                ? imported.value
-                : { error: imported.error._tag, message: imported.error.message };
-        }),
-    });
-    cli.command("evidence-export", {
-        description: "Validate and atomically export canonical Evidence v2 JSON",
-        args: z.object({
-            source: z.string().describe("Existing evidence bundle JSON path"),
-            output: z.string().describe("Canonical output JSON path"),
-        }),
-        options: z.object({
-            overwrite: z.boolean().default(false).describe("Replace output file"),
-        }),
-        run: ({ args, options }) => logCliCommand(logger, "evidence-export", async () => {
-            const config = parseConfig(process.env);
-            if (!config.ok)
-                return { error: config.error._tag, message: config.error.message };
-            const exported = await exportEvidenceBundleCommand(args.source, args.output, options.overwrite, config.value.evidenceFilePolicy);
-            return exported.ok
-                ? exported.value
-                : { error: exported.error._tag, message: exported.error.message };
-        }),
-    });
-};
-const logCliCommand = async (logger, command, execute) => {
-    const startedAt = performance.now();
-    try {
-        const value = await execute();
-        logger.info({
-            command,
-            durationMs: Math.round((performance.now() - startedAt) * 100) / 100,
-            status: "ok",
-        }, "CLI command completed");
-        return value;
-    }
-    catch (cause) {
-        logger.error({
-            command,
-            durationMs: Math.round((performance.now() - startedAt) * 100) / 100,
-            status: "error",
-        }, "CLI command failed");
-        throw cause;
-    }
-};

package/dist/cliEvidenceCommands.js

@@ -0,0 +1,68 @@
+import { Cli, z } from "incur";
+import { compareEvidenceBundlesCommand, exportEvidenceBundleCommand, importEvidenceBundleCommand, } from "./application/EvidenceBundleCommands.js";
+import { parseConfig } from "./config.js";
+import { logCliCommand } from "./cliLogging.js";
+/** Register filesystem-gated Evidence v2 commands. */
+export const registerEvidenceCommands = (cli, logger) => {
+    cli.command("evidence-import", {
+        description: "Validate and import a bounded local Evidence v2 bundle",
+        args: z.object({
+            path: z.string().describe("Evidence bundle JSON path"),
+        }),
+        run: ({ args }) => logCliCommand(logger, "evidence-import", async () => {
+            const config = parseConfig(process.env);
+            if (!config.ok)
+                return { error: config.error._tag, message: config.error.message };
+            const imported = await importEvidenceBundleCommand(args.path, config.value.evidenceFilePolicy);
+            return imported.ok
+                ? imported.value
+                : { error: imported.error._tag, message: imported.error.message };
+        }),
+    });
+    cli.command("evidence-export", {
+        description: "Validate and atomically export canonical Evidence v2 JSON",
+        args: z.object({
+            source: z.string().describe("Existing evidence bundle JSON path"),
+            output: z.string().describe("Canonical output JSON path"),
+        }),
+        options: z.object({
+            overwrite: z.boolean().default(false).describe("Replace output file"),
+        }),
+        run: ({ args, options }) => logCliCommand(logger, "evidence-export", async () => {
+            const config = parseConfig(process.env);
+            if (!config.ok)
+                return { error: config.error._tag, message: config.error.message };
+            const exported = await exportEvidenceBundleCommand(args.source, args.output, options.overwrite, config.value.evidenceFilePolicy);
+            return exported.ok
+                ? exported.value
+                : { error: exported.error._tag, message: exported.error.message };
+        }),
+    });
+    cli.command("compare", {
+        aliases: ["compare-bundles"],
+        description: "Compare two canonical Evidence v2 bundles",
+        args: z.object({
+            left: z.string().describe("Left Evidence bundle JSON path"),
+            right: z.string().describe("Right Evidence bundle JSON path"),
+        }),
+        options: z.object({
+            offset: z.number().int().min(0).default(0),
+            limit: z.number().int().min(1).max(500).default(100),
+        }),
+        run: ({ args, options }) => logCliCommand(logger, "compare", async () => {
+            const config = parseConfig(process.env);
+            if (!config.ok)
+                return { error: config.error._tag, message: config.error.message };
+            const compared = await compareEvidenceBundlesCommand({
+                leftPath: args.left,
+                rightPath: args.right,
+                offset: options.offset,
+                limit: options.limit,
+                policy: config.value.evidenceFilePolicy,
+            });
+            return compared.ok
+                ? compared.value
+                : { error: compared.error._tag, message: compared.error.message };
+        }),
+    });
+};

package/dist/cliLogging.js

@@ -0,0 +1,21 @@
+/** Log one CLI command with duration and a stable success or failure status. */
+export const logCliCommand = async (logger, command, execute) => {
+    const startedAt = performance.now();
+    try {
+        const value = await execute();
+        logger.info({
+            command,
+            durationMs: Math.round((performance.now() - startedAt) * 100) / 100,
+            status: "ok",
+        }, "CLI command completed");
+        return value;
+    }
+    catch (cause) {
+        logger.error({
+            command,
+            durationMs: Math.round((performance.now() - startedAt) * 100) / 100,
+            status: "error",
+        }, "CLI command failed");
+        throw cause;
+    }
+};

package/dist/contracts/toolOutputSchemas.js

@@ -69,12 +69,14 @@ const providerCapability = z.object({
     }),
     limitations: z.array(z.string()),
 });
+const providerIdentity = z.object({
+    id: z.string(),
+    name: z.string(),
+    version: z.string().nullable(),
+});
 const sessionProvider = z.object({
-    provider: z.object({
-        id: z.string(),
-        name: z.string(),
-        version: z.string().nullable(),
-    }),
+    provider: providerIdentity,
+    providers: z.array(providerIdentity),
     capabilities: z.array(providerCapability),
 });
 const nullableText = z.string().nullable();

package/dist/domain/errors.js

@@ -151,11 +151,13 @@ export class HopperProtocolError extends HopperError {
 export class HopperRemoteError extends HopperError {
     code;
     safeMessage;
+    diagnosticType;
     _tag = "HopperRemoteError";
-    constructor(code, safeMessage) {
+    constructor(code, safeMessage, diagnosticType = "remote") {
         super(`Hopper request failed (${String(code)}): ${safeMessage}`);
         this.code = code;
         this.safeMessage = safeMessage;
+        this.diagnosticType = diagnosticType;
     }
 }
 /** The owned Hopper bridge stopped before its client was closed. */
@@ -233,7 +235,11 @@ const safeDetails = (error) => {
     if (error instanceof HopperTimeoutError)
         return { timeoutMs: error.timeoutMs };
     if (error instanceof HopperRemoteError)
-        return { code: error.code, safeMessage: error.safeMessage };
+        return {
+            code: error.code,
+            safeMessage: error.safeMessage,
+            diagnosticType: error.diagnosticType,
+        };
     if (error instanceof HopperProcessError)
         return { exitCode: error.exitCode };
     return {};

package/dist/domain/hopperValues.js

@@ -12,10 +12,30 @@ const segmentSchema = z.object({
     writable: z.boolean().nullable().default(null),
     executable: z.boolean().nullable().default(null),
 });
-const addressedPageSchema = z.object({
+const addressedPageSchema = z
+    .object({
     items: z.array(z.object({ address: z.string(), value: z.string() })),
+    offset: z.number().int().min(0),
+    limit: z.number().int().min(1),
+    total: z.number().int().min(0),
     next_offset: z.number().int().min(0).nullable(),
     has_more: z.boolean(),
+})
+    .superRefine((value, context) => {
+    if (value.has_more && value.next_offset === null) {
+        context.addIssue({
+            code: "custom",
+            message: "a page with more results must provide next_offset",
+            path: ["next_offset"],
+        });
+    }
+    if (!value.has_more && value.next_offset !== null) {
+        context.addIssue({
+            code: "custom",
+            message: "a complete page must not provide next_offset",
+            path: ["next_offset"],
+        });
+    }
 });
 const unavailableSchema = z
     .object({ available: z.literal(false), reason: z.string() })

package/dist/hopper/BridgeLauncher.js

@@ -94,21 +94,13 @@ export class HopperApplicationLauncher {
                 await writeFileAtomic(join(session.directory, "ownership.json"), `${JSON.stringify(ownership)}\n`, { encoding: "utf8", mode: 0o600 });
             }
             catch (cause) {
-                await cleanupOwnedProcessGroup({
-                    runId: session.runId,
-                    leaderPid: pid,
-                    processGroupId: pid,
-                });
+                await cleanupOwnedProcessGroup(ownedProcessGroup(session, pid, this.options.launcherPath));
                 return err(new HopperStartError({ cause }));
             }
             return ok({
                 process: child,
                 ownsProcessLifetime: true,
-                cleanup: () => cleanupOwnedProcessGroup({
-                    runId: session.runId,
-                    leaderPid: pid,
-                    processGroupId: pid,
-                }),
+                cleanup: () => cleanupOwnedProcessGroup(ownedProcessGroup(session, pid, this.options.launcherPath)),
             });
         }
         catch (cause) {
@@ -116,6 +108,13 @@ export class HopperApplicationLauncher {
         }
     }
 }
+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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rea-agents",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Reverse engineer anything from your terminal or coding agent with one CLI and MCP server.",
   "license": "MIT",
   "repository": {