rea-agents 0.4.0 → 1.0.0

package/README.md

@@ -120,6 +120,17 @@ rea doctor
 rea analyze /Applications/Notes.app
 ```
 
+Update that global installation in place:
+
+```bash
+rea upgrade
+```
+
+REA checks npm for the latest release and verifies that the running package is
+the global installation it will replace. Source, local, and `npx` copies report
+the manual `npm install --global rea-agents@latest` command instead of updating
+an unrelated global package.
+
 Choose either the no-install commands or the global installation. You do not need both.
 
 ### Requirements
@@ -170,12 +181,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 +194,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 +288,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,15 +334,27 @@ 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:
 
 ```bash
 npm install --global rea-agents
 rea --help
+rea upgrade
 rea mcp
 ```
 

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,6 +1,6 @@
 import { enhancedInputSchemas } from "../contracts/enhancedInputs.js";
-import { AnalysisInputError, AnalysisOutputError, } from "../domain/errors.js";
-import { parseDocuments, parseFunctionDossier, parseAddressedPage, parseListCount, parseRelatedAddresses, parseSegments, } from "../domain/hopperValues.js";
+import { AnalysisInputError, AnalysisCancelledError, AnalysisOutputError, projectAnalysisError, } from "../domain/errors.js";
+import { addressDistance, 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";
 /**
@@ -89,20 +89,29 @@ export class EnhancedTools {
         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 items = 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}`,
-            ];
+            if (!result.ok)
+                return {
+                    address,
+                    status: "error",
+                    error: projectAnalysisError(result.error),
+                };
+            if (typeof result.value !== "string" || result.value.length === 0)
+                return {
+                    address,
+                    status: "error",
+                    error: projectAnalysisError(new AnalysisOutputError("procedure_pseudo_code", "provider returned empty pseudocode")),
+                };
+            return { address, status: "ok", pseudocode: result.value };
         }));
-        return ok(Object.fromEntries(entries));
+        const succeeded = items.filter(({ status }) => status === "ok").length;
+        return ok({
+            items,
+            total: items.length,
+            succeeded,
+            failed: items.length - succeeded,
+        });
     }
     async #callGraph(input, signal) {
         const relation = input.direction === "forward" ? "callees" : "callers";
@@ -124,7 +133,8 @@ export class EnhancedTools {
             if (!result.ok) {
                 graph[level].push({
                     address: current.address,
-                    error: result.error.message,
+                    status: "error",
+                    error: projectAnalysisError(result.error),
                 });
                 continue;
             }
@@ -132,12 +142,14 @@ export class EnhancedTools {
             if (!related.ok) {
                 graph[level].push({
                     address: current.address,
-                    error: related.error.message,
+                    status: "error",
+                    error: projectAnalysisError(related.error),
                 });
                 continue;
             }
             graph[level].push({
                 address: current.address,
+                status: "ok",
                 calls: [...related.value],
             });
             if (current.depth + 1 < input.depth) {
@@ -158,16 +170,24 @@ export class EnhancedTools {
             : 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);
+        const names = await this.#allAddressed("list_names", signal);
+        if (!names.ok)
+            return names;
+        const resolved = names.value.find((entry) => entry.name === name);
+        if (resolved === undefined)
+            return ok({ status: "unresolved", name, reason: "name_not_found" });
+        const xrefs = await this.#call("xrefs", { address: resolved.address }, signal);
         if (!xrefs.ok)
             return xrefs;
-        return ok(Array.isArray(xrefs.value) ? { xrefs: xrefs.value } : xrefs.value);
+        if (!Array.isArray(xrefs.value) ||
+            xrefs.value.some((xref) => typeof xref !== "string"))
+            return err(new AnalysisOutputError("xrefs", "provider returned an invalid address list"));
+        return ok({
+            status: "resolved",
+            name,
+            address: resolved.address,
+            xrefs: xrefs.value,
+        });
     }
     async #binaryOverview(input, signal) {
         const [segmentsResult, documentsResult, procedures, stringsResult] = await Promise.all([
@@ -337,6 +357,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;
     }
@@ -344,15 +366,3 @@ export class EnhancedTools {
 const invalidInput = (name, cause) => Promise.resolve(err(new AnalysisInputError(name, {
     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));

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/application/Upgrade.js

@@ -0,0 +1,106 @@
+import { execFile, spawn } from "node:child_process";
+import { realpath } from "node:fs/promises";
+import { basename, dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { promisify } from "node:util";
+import { z } from "zod";
+import { PRODUCT_IDENTITY } from "../identity.js";
+const execFileAsync = promisify(execFile);
+const registryResponseSchema = z.object({ version: z.string().min(1) });
+const UPGRADE_COMMAND = "npm install --global rea-agents@latest";
+/** Check the npm registry and update the same global REA installation. */
+export const runUpgrade = async (currentVersion, host = systemUpgradeHost(), output = "human") => {
+    const latestVersion = await host.latestVersion();
+    if (latestVersion === currentVersion)
+        return {
+            status: "current",
+            currentVersion,
+            latestVersion,
+            installMethod: "npm",
+        };
+    const installation = await host.installation();
+    if (installation === undefined)
+        return {
+            status: "failed",
+            currentVersion,
+            latestVersion: latestVersion ?? null,
+            reason: "unknown-install-method",
+            remediation: `Update manually with: ${UPGRADE_COMMAND}`,
+        };
+    if (!(await host.installLatest(installation, output)))
+        return {
+            status: "failed",
+            currentVersion,
+            latestVersion: latestVersion ?? null,
+            reason: "install",
+            remediation: `${UPGRADE_COMMAND} failed.`,
+        };
+    return {
+        status: "upgraded",
+        previousVersion: currentVersion,
+        latestVersion: latestVersion ?? null,
+        versionCheck: latestVersion === undefined ? "unavailable" : "available",
+        installMethod: "npm",
+        command: UPGRADE_COMMAND,
+    };
+};
+/** Create the npm registry and subprocess effects for a production upgrade. */
+export const systemUpgradeHost = () => ({
+    latestVersion: async () => {
+        try {
+            const response = await fetch(`https://registry.npmjs.org/${PRODUCT_IDENTITY.packageName}/latest`, { signal: AbortSignal.timeout(10_000) });
+            if (!response.ok)
+                return undefined;
+            const parsed = registryResponseSchema.safeParse(await response.json());
+            return parsed.success ? parsed.data.version : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    },
+    installation: () => detectNpmInstallation(fileURLToPath(new URL("../..", import.meta.url)), systemNpmInstallationHost),
+    installLatest: ({ prefix }, output) => runCommand("npm", [
+        "install",
+        "--global",
+        "--prefix",
+        prefix,
+        `${PRODUCT_IDENTITY.packageName}@latest`,
+    ], output),
+});
+const systemNpmInstallationHost = {
+    canonicalPath: realpath,
+    globalRoot: async () => (await execFileAsync("npm", ["root", "--global"])).stdout.trim(),
+    globalPrefix: async () => (await execFileAsync("npm", ["prefix", "--global"])).stdout.trim(),
+};
+/** Identify the npm prefix only when it owns the running package. */
+export const detectNpmInstallation = async (packageRoot, host) => {
+    try {
+        const canonicalPackageRoot = await host.canonicalPath(packageRoot);
+        const npmRoot = await host.globalRoot();
+        const globalPackageRoot = await host.canonicalPath(resolve(npmRoot, PRODUCT_IDENTITY.packageName));
+        if (canonicalPackageRoot === globalPackageRoot) {
+            const prefix = await host.globalPrefix();
+            return prefix.length === 0 ? undefined : { prefix };
+        }
+        return inferUnixGlobalPrefix(canonicalPackageRoot);
+    }
+    catch {
+        return inferUnixGlobalPrefix(packageRoot);
+    }
+};
+const inferUnixGlobalPrefix = (packageRoot) => {
+    const nodeModules = dirname(packageRoot);
+    const library = dirname(nodeModules);
+    if (basename(packageRoot) !== PRODUCT_IDENTITY.packageName ||
+        basename(nodeModules) !== "node_modules" ||
+        basename(library) !== "lib")
+        return undefined;
+    return { prefix: dirname(library) };
+};
+const runCommand = (command, arguments_, output) => new Promise((resolveResult) => {
+    const child = spawn(command, [...arguments_], {
+        stdio: output === "human" ? "inherit" : ["inherit", process.stderr, "inherit"],
+    });
+    child.once("error", () => resolveResult(false));
+    child.once("exit", (code) => resolveResult(code === 0));
+});

package/dist/cli.js

@@ -1,14 +1,16 @@
 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 { runUpgrade, systemUpgradeHost } from "./application/Upgrade.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 +37,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({
@@ -64,12 +83,25 @@ export const createCli = () => {
         alias: { purgeData: "purge-data" },
         run: ({ options }) => logCliCommand(logger, "uninstall", () => runUninstall(options.purgeData)),
     });
+    cli.command("upgrade", {
+        description: "Upgrade a global npm installation to the latest REA release",
+        run: ({ formatExplicit }) => logCliCommand(logger, "upgrade", () => runUpgrade(process.env.REA_PACKAGE_VERSION ?? "0.0.0-development", systemUpgradeHost(), formatExplicit ? "structured" : "human")),
+    });
     cli.command("analyze", {
         description: "Get an overview of an app",
         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 +111,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 +299,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/toolContracts.js

@@ -146,10 +146,10 @@ export const ENHANCED_TOOL_CONTRACTS = [
     enhanced("swift_classes", "Discover legacy-mangled Swift class procedures after exhaustively paging analyzed procedures. Returns at most 100 entries and scans at most 5,000 symbols; use analyze_swift_types for other Swift kinds.", enhancedInputSchemas.swift_classes),
     enhanced("get_objc_classes", "Discover and deduplicate Objective-C class labels after exhaustively paging names, optionally filtering by literal substring. Returns at most 100 classes; inspect matching metadata and references next.", enhancedInputSchemas.get_objc_classes),
     enhanced("get_objc_protocols", "Discover and deduplicate Objective-C and Swift protocol labels after exhaustively paging names. Returns at most 100 entries; use xrefs or analyze_function to connect a protocol to implementations.", enhancedInputSchemas.get_objc_protocols),
-    enhanced("batch_decompile", "Decompile up to 20 explicit procedure symbols or addresses concurrently. Per-item strings may contain errors or no-output markers, so validate each result; use analyze_function for a richer single-function dossier.", enhancedInputSchemas.batch_decompile),
-    enhanced("get_call_graph", "Traverse Hopper's caller or callee relationships from one symbol or address for at most five levels. Nodes preserve per-procedure errors; indirect calls may be missing and results are not a whole-program CFG.", enhancedInputSchemas.get_call_graph),
+    enhanced("batch_decompile", "Decompile up to 20 explicit procedure symbols or addresses concurrently. Returns ordered per-item ok/error variants and aggregate counts; use analyze_function for a richer single-function dossier.", enhancedInputSchemas.batch_decompile),
+    enhanced("get_call_graph", "Traverse Hopper's caller or callee relationships from one symbol or address for at most five levels. Every node has an ok/error status and failures use safe typed projections; indirect calls may be missing and results are not a whole-program CFG.", enhancedInputSchemas.get_call_graph),
     enhanced("analyze_swift_types", "Categorize exhaustively paged procedure names into Swift classes, structs, enums, protocols, extensions, and other symbols. Scans at most 5,000 names and returns at most 50 entries per category.", enhancedInputSchemas.analyze_swift_types),
-    enhanced("find_xrefs_to_name", "Resolve a name through Hopper and return analyzed references to its address. Use when starting from a selector or symbol; resolution failure is returned explicitly and xrefs remain untyped.", enhancedInputSchemas.find_xrefs_to_name),
+    enhanced("find_xrefs_to_name", "Resolve an exact name through Hopper's exhaustively paged name inventory and return a resolved or unresolved result. Unresolved names use the stable name_not_found reason; xrefs remain untyped.", enhancedInputSchemas.find_xrefs_to_name),
     enhanced("binary_overview", "Use immediately after opening a target to summarize document, exhaustive procedure/string counts, and a bounded segment sample. detail controls segment fields and limit controls only the returned segment sample.", enhancedInputSchemas.binary_overview),
     enhanced("analyze_function", "Preferred bounded analysis for one procedure symbol or address. Returns identity, pseudocode, optional assembly, comments, calls, incoming references, and blocks; unsupported outgoing references and CFG edges carry explicit unavailable metadata.", enhancedInputSchemas.analyze_function),
     enhanced("trace_feature", "Trace a bounded literal feature query through matching strings and procedures, xrefs, and truthful containing-procedure resolution. Returns the operation budget, truncation, and residual unknowns; unknown_registry_approved: true records them durably without inferring reference kinds.", enhancedInputSchemas.trace_feature),

package/dist/contracts/toolOutputSchemas.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { ANALYSIS_ERROR_TAGS } from "../domain/errors.js";
 import { evidenceSchema } from "../domain/evidence.js";
 import { processCaptureComparisonSchema, processCaptureSchema, } from "../domain/processCapture.js";
 import { evidenceBundleSchema } from "../domain/evidenceBundle.js";
@@ -69,12 +70,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();
@@ -147,9 +150,24 @@ const symbolDiscoveryOutput = (property) => resultOf(z.object({
     count: z.number().int().min(0),
     [property]: z.array(addressedEntry),
 }));
-const graphNode = z.union([
-    z.object({ address: z.string(), calls: z.array(z.string()) }),
-    z.object({ address: z.string(), error: z.string() }),
+const analysisErrorProjectionSchema = z
+    .object({
+    tag: z.enum(ANALYSIS_ERROR_TAGS),
+    message: z.string(),
+    details: z.record(z.string(), z.union([z.string(), z.number(), z.null()])),
+})
+    .strict();
+const graphNode = z.discriminatedUnion("status", [
+    z.object({
+        address: z.string(),
+        status: z.literal("ok"),
+        calls: z.array(z.string()),
+    }),
+    z.object({
+        address: z.string(),
+        status: z.literal("error"),
+        error: analysisErrorProjectionSchema,
+    }),
 ]);
 const functionDossierOutput = resultOf(functionDossierSchema);
 /** Exact structured-content schemas for the direct Hopper operations. */
@@ -205,10 +223,23 @@ export const enhancedOutputSchemas = {
     swift_classes: symbolDiscoveryOutput("classes"),
     get_objc_classes: symbolDiscoveryOutput("classes"),
     get_objc_protocols: symbolDiscoveryOutput("protocols"),
-    batch_decompile: resultOf(z.union([
-        z.object({ error: z.literal("No addresses provided") }),
-        z.record(z.string(), z.string()),
-    ])),
+    batch_decompile: resultOf(z.object({
+        items: z.array(z.discriminatedUnion("status", [
+            z.object({
+                address: z.string(),
+                status: z.literal("ok"),
+                pseudocode: z.string().min(1),
+            }),
+            z.object({
+                address: z.string(),
+                status: z.literal("error"),
+                error: analysisErrorProjectionSchema,
+            }),
+        ])),
+        total: z.number().int().min(0),
+        succeeded: z.number().int().min(0),
+        failed: z.number().int().min(0),
+    })),
     get_call_graph: resultOf(z.record(z.string(), z.array(graphNode))),
     analyze_swift_types: resultOf(z.object({
         total: z.number().int().min(0),
@@ -217,9 +248,18 @@ export const enhancedOutputSchemas = {
             items: z.array(addressedEntry),
         })),
     })),
-    find_xrefs_to_name: resultOf(z.union([
-        z.object({ xrefs: addressList }),
-        z.object({ error: z.string() }),
+    find_xrefs_to_name: resultOf(z.discriminatedUnion("status", [
+        z.object({
+            status: z.literal("resolved"),
+            name: z.string(),
+            address: z.string(),
+            xrefs: addressList,
+        }),
+        z.object({
+            status: z.literal("unresolved"),
+            name: z.string(),
+            reason: z.literal("name_not_found"),
+        }),
     ])),
     binary_overview: resultOf(z.object({
         document: z.string(),

package/dist/domain/errors.js

@@ -1,3 +1,29 @@
+/** Stable tags exposed by safe analysis-error projections. */
+export const ANALYSIS_ERROR_TAGS = [
+    "AnalysisProtocolError",
+    "AnalysisInputError",
+    "AnalysisOutputError",
+    "AnalysisCapabilityUnavailableError",
+    "AnalysisCancelledError",
+    "AnalysisTimeoutError",
+    "ProviderSelectionError",
+    "ProviderAdapterError",
+    "ArtifactOperationError",
+    "ProcessCaptureError",
+    "EvidenceIntegrityError",
+    "EvidenceLimitError",
+    "EvidenceFileError",
+    "UnknownRegistryError",
+    "HopperTimeoutError",
+    "HopperCancelledError",
+    "HopperProtocolError",
+    "HopperRemoteError",
+    "HopperProcessError",
+    "HopperStartError",
+    "ConfigurationError",
+    "NoBinaryOpenError",
+    "BinaryTargetError",
+];
 /** Base class for expected analysis, provider, and session failures. */
 export class AnalysisError extends Error {
 }
@@ -151,11 +177,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 +261,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

@@ -1,6 +1,8 @@
 import { z } from "zod";
 import { AnalysisOutputError, HopperProtocolError } from "./errors.js";
 import { err, ok } from "./result.js";
+/** Return the non-negative byte distance between hexadecimal addresses. */
+export const addressDistance = (start, end) => Math.max(0, Number.parseInt(end, 16) - Number.parseInt(start, 16));
 const procedureMapSchema = z.record(z.string(), z.string());
 const addressedNamesSchema = z.array(z.object({ address: z.string(), name: z.string() }));
 const addressedNameMapSchema = z.record(z.string(), z.string());
@@ -12,10 +14,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/dist/native/NativeMacOSProvider.js

@@ -81,6 +81,8 @@ class NativeMacOSClient {
         this.runner = runner;
     }
     async execute(operation, parameters, options) {
+        if (options?.signal?.aborted === true)
+            return err(new AnalysisCancelledError(operation));
         if (operation === "health")
             return ok(createAnalysisExecution(null, IDENTITY));
         if (!isNativeOperation(operation))

package/package.json

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