Compare commits

..
Author SHA1 Message Date
morlutoandGitHub 1d1fe7b212 Merge pull request #88 from morluto/release-please--branches--main--components--rea-agents
chore(main): release rea-agents 1.0.0
2026-07-13 13:38:09 +08:00
github-actions[bot]andGitHub c614fe3f40 chore(main): release rea-agents 1.0.0 2026-07-13 05:37:01 +00:00
morlutoandGitHub c004220a26 Merge pull request #89 from morluto/feat/cli-upgrade
feat(cli): add self-upgrade command
2026-07-13 13:36:47 +08:00
morluto 8a24088c2b docs: list upgrade in CLI reference 2026-07-13 05:35:22 +00:00
morluto 0d77a9f135 feat(cli): add self-upgrade command 2026-07-13 05:30:39 +00:00
morlutoandGitHub 0d7d9e0e36 Merge pull request #87 from morluto/codex/rea-low-mid-batch
fix(contracts)!: return structured workflow failures
2026-07-13 13:14:08 +08:00
morluto ac8cc668fb fix(contracts): keep error schema internal 2026-07-13 05:12:43 +00:00
morluto dfd598f765 fix(native): classify pre-aborted analysis first 2026-07-13 05:03:47 +00:00
morluto 4c54ff6bca fix(contracts)!: return structured workflow failures
Replace prose-encoded partial failures in batch decompilation, call graphs, and named xref lookup with discriminated structured results.

BREAKING CHANGE: batch_decompile, get_call_graph, and find_xrefs_to_name now return structured discriminated output shapes.
2026-07-13 05:03:47 +00:00
morlutoandGitHub cba26666a2 Merge pull request #86 from morluto/release-please--branches--main--components--rea-agents
chore(main): release rea-agents 0.5.0
2026-07-13 11:56:13 +08:00
github-actions[bot]andGitHub a5edb3a2bc chore(main): release rea-agents 0.5.0 2026-07-13 03:52:52 +00:00
morlutoandGitHub 883db912da Merge pull request #85 from morluto/codex/rea-low-mid-batch
feat(analysis): harden agent workflows and evidence boundaries
2026-07-13 11:52:36 +08:00
morluto 7c36f36318 fix(analysis): accept valid final dossier pages 2026-07-13 03:38:15 +00:00
morluto c630f410b6 fix(cli): preserve function provider provenance 2026-07-13 03:34:57 +00:00
morluto 9526389f81 fix(process): keep network approval fail-closed 2026-07-13 03:30:17 +00:00
morluto 329fdf6fe8 refactor(cli): share direct analysis tool types 2026-07-13 03:26:32 +00:00
morluto d806480e41 docs: correct pull request tool inventory 2026-07-13 03:25:02 +00:00
morluto a7b84a9b4b test(docs): keep localized claims and tool counts aligned 2026-07-13 03:16:34 +00:00
morluto efc9bd270f docs: document CLI safety and provider evaluation 2026-07-13 03:16:02 +00:00
morluto 0d36976277 test(verification): strengthen conformance and real-Hopper checks 2026-07-13 03:15:46 +00:00
morluto bce3398dbe fix(process): default capture networking to loopback 2026-07-13 03:15:27 +00:00
morluto b1912b18e1 feat(cli): align terminal workflows with MCP 2026-07-13 03:15:01 +00:00
morluto 898d6b0192 fix(lifecycle): validate owned Hopper process identity 2026-07-13 03:14:36 +00:00
morluto f8e8ea35ff fix(bridge): harden bounded Hopper boundaries 2026-07-13 03:14:15 +00:00
42 changed files with 1836 additions and 274 deletions
+1 -1
View File
@@ -26,7 +26,7 @@
## Tool Contract Impact
<!-- If this PR adds, removes, or modifies MCP tools, list them here. -->
<!-- The current inventory is 42 tools (31 direct + 8 enhanced + 3 session). -->
<!-- The current inventory is 68 tools (33 direct + 10 enhanced + 5 native + 2 artifact + 18 session). -->
## Related Issues
+1 -1
View File
@@ -1,3 +1,3 @@
{
".": "0.4.0"
".": "1.0.0"
}
+59
View File
@@ -1,5 +1,64 @@
# Changelog
## [1.0.0](https://github.com/morluto/rea/compare/rea-agents-0.5.0...rea-agents-1.0.0) (2026-07-13)
### ⚠ BREAKING CHANGES
* **contracts:** batch_decompile, get_call_graph, and find_xrefs_to_name now return structured discriminated output shapes.
### Features
* **cli:** add self-upgrade command ([c004220](https://github.com/morluto/rea/commit/c004220a2699ac60a67a9c7edf1f96cad8a31d3e))
* **cli:** add self-upgrade command ([0d77a9f](https://github.com/morluto/rea/commit/0d77a9f1350056a7d2c43771d579e0461029f5b5))
### Bug Fixes
* **contracts:** keep error schema internal ([ac8cc66](https://github.com/morluto/rea/commit/ac8cc668fb6b9305d2dc9014f7a6006d96b18ba6))
* **contracts:** return structured workflow failures ([4c54ff6](https://github.com/morluto/rea/commit/4c54ff6bcaac02f39c6620a54ac29690a121f33d))
* **native:** classify pre-aborted analysis first ([dfd598f](https://github.com/morluto/rea/commit/dfd598f76505af978f2d11afffb5e1f362d3a769))
### Documentation
* list upgrade in CLI reference ([8a24088](https://github.com/morluto/rea/commit/8a24088c2bffd34050ea6f6f0e103f64a3f67a64))
## [0.5.0](https://github.com/morluto/rea/compare/rea-agents-0.4.0...rea-agents-0.5.0) (2026-07-13)
### Features
* **analysis:** harden agent workflows and evidence boundaries ([883db91](https://github.com/morluto/rea/commit/883db912da6e38e1078286997cc9048471e03896))
* **cli:** align terminal workflows with MCP ([b1912b1](https://github.com/morluto/rea/commit/b1912b18e1723c594a030b16acf01341f083455b))
### Bug Fixes
* **analysis:** accept valid final dossier pages ([7c36f36](https://github.com/morluto/rea/commit/7c36f3631862e67a0751967c84abc4f423f5475c))
* **bridge:** harden bounded Hopper boundaries ([f8e8ea3](https://github.com/morluto/rea/commit/f8e8ea35ff08ce5071acbccab188df808708b71c))
* **cli:** preserve function provider provenance ([c630f41](https://github.com/morluto/rea/commit/c630f410b6a81864bf90211a088c715bfe234722))
* **lifecycle:** validate owned Hopper process identity ([898d6b0](https://github.com/morluto/rea/commit/898d6b0192126030cedd7e5c2cb76f40568cda05))
* **process:** default capture networking to loopback ([bce3398](https://github.com/morluto/rea/commit/bce3398dbe3a3b20952f37573a656aa77b168977))
* **process:** keep network approval fail-closed ([9526389](https://github.com/morluto/rea/commit/9526389f815f0937fc01198ff3a8a850c6c1c81a))
### Code Refactoring
* **cli:** share direct analysis tool types ([329fdf6](https://github.com/morluto/rea/commit/329fdf6fe8f3a2bf9679b13a8ce5cb16cf946129))
### Documentation
* correct pull request tool inventory ([d806480](https://github.com/morluto/rea/commit/d806480e41bcb623448a258ddffeb75082fe1e1f))
* document CLI safety and provider evaluation ([efc9bd2](https://github.com/morluto/rea/commit/efc9bd270f58a5aaba15edb07cee135d2c54db83))
### Tests
* **docs:** keep localized claims and tool counts aligned ([a7b84a9](https://github.com/morluto/rea/commit/a7b84a9b4b7ea4336c0f327e13b2948a8d94fba9))
* **verification:** strengthen conformance and real-Hopper checks ([0d36976](https://github.com/morluto/rea/commit/0d369762770d2d92dd72c7dcb2f2f90a64b206ff))
## [0.4.0](https://github.com/morluto/rea/compare/rea-agents-0.3.0...rea-agents-0.4.0) (2026-07-12)
+33 -7
View File
@@ -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
```
+2 -1
View File
@@ -199,6 +199,7 @@ flowchart LR
```bash
npx -y rea-agents analyze /Applications/Notes.app
npx -y rea-agents compare /absolute/path/to/left-evidence.json /absolute/path/to/right-evidence.json
```
شغّل `npx -y rea-agents --help` لمعرفة خيارات فك الترجمة المباشر والخيارات الأخرى.
@@ -243,7 +244,7 @@ export HOPPER_LOADER_ARGS_JSON='["-l", "Mach-O", "--aarch68"]'
<details>
<summary><strong>هل يعمل REA على Linux أو Windows؟</strong></summary>
ليس حاليًا. يعتمد المحول الحالي على تطبيق Hopper لنظام macOS وواجهة Python الخاصة به.
نعم، يعمل REA على macOS 12+ وUbuntu 24.04+ وFedora 41+ وArch Linux ‏64 بت؛ Windows غير مدعوم حاليًا. يعتمد التحليل العميق على تطبيق Hopper وواجهة Python الخاصة به.
</details>
+18 -4
View File
@@ -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):
+59
View File
@@ -0,0 +1,59 @@
# Static-analysis provider evaluation
Status: research for issue #26; no provider implementation is approved by this note.
REA should add another analysis provider only after the provider-neutral capability
contracts, Evidence v2 metadata, ownership rules, and multi-fixture conformance
suite are complete. A provider is not a drop-in replacement for Hopper: every
capability must be mapped explicitly, with truthful `unavailable` results where
the engine cannot provide equivalent semantics.
## Shortlist
| Provider | License / automation surface | What it brings | REA fit and blockers |
| ------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Ghidra](https://github.com/NationalSecurityAgency/ghidra) | Apache-2.0 source license; `analyzeHeadless`, Java APIs, and PyGhidra | Broad static analysis, many processors and formats, scripting, and project/database workflows | Strong candidate for a full provider. Requires a Java/JDK runtime, isolated project/cache directories, process supervision, and a stable adapter for Ghidra's project-oriented model. |
| [Rizin](https://github.com/rizinorg/rizin) / [rz-pipe](https://github.com/rizinorg/rz-pipe) | Rizin repository contains LGPL-3.0 and GPL-3.0 components; `rizin`, `rz-bin`, and language bridges through `rzpipe` | Portable CLI analysis, disassembly/debugging, many architectures and file formats, JSON command output | Good candidate for a process-backed Linux provider and fast metadata fallback. License/component inventory must be preserved; command output needs version-pinned parsers and semantic conformance before evidence is trusted. |
| [LIEF](https://github.com/lief-project/LIEF) | Apache-2.0; C++, Python, and other bindings | Deterministic parsing and modification of ELF, PE, Mach-O, COFF, and related executable formats; headers, sections, symbols, relocations, and functions | Best near-term complement, not a decompiler replacement. It can cover format metadata and artifact evidence without a long-lived analysis process; function semantics, pseudocode, CFG, and cross-reference parity remain out of scope unless separately demonstrated. |
| [Binary Ninja](https://docs.binary.ninja/dev/index.html) | API/documentation components are MIT, while the analysis product is licensed by edition; commercial, Ultimate, or Headless license is required for headless automation | Python/Core/C++/Rust APIs, headless loading, IL layers, function analysis, plugins, and configurable analysis | Strong technical fit for a native provider, especially function dossiers. Commercial licensing, license-secret handling, native runtime packaging, and multithreaded lifecycle rules are material deployment blockers. |
## Recommended order
1. Use LIEF first for provider-neutral binary metadata where the current
contracts already describe headers, sections, symbols, and relocations.
2. Evaluate Rizin as a separate process provider for portable disassembly and
command-backed queries, with JSON-only parsing and fixture assertions.
3. Evaluate Ghidra or Binary Ninja for decompilation and richer function
semantics only after the conformance fixtures can compare evidence by
capability rather than by provider-specific output text.
## Required admission gate
Before implementation, an adapter proposal must provide:
- a capability matrix covering supported, unsupported, and degraded results;
- provider identity, version, target digest, authority, limitations, and
deterministic locations in every Evidence v2 record;
- bounded subprocess or library lifetime, cancellation, timeouts, and cleanup;
- sanitized diagnostics that do not expose license material, host paths, or
provider tracebacks;
- the same source-owned fixture corpus across architectures and formats;
- repeatable checks for function identity, addresses, strings, names, xrefs,
CFG, and pseudocode wherever those capabilities are claimed.
This keeps issue #26 a decision record rather than prematurely committing REA
to an engine whose semantics or redistribution terms have not been verified.
## Primary-source notes
- Ghidra documents headless batch mode and its Java/Python runtime requirements
in its [Getting Started guide](https://github.com/NationalSecurityAgency/ghidra/blob/master/GhidraDocs/GettingStarted.md).
- Rizin lists supported formats, architectures, tools, and `rzpipe` bridges in
its [repository README](https://github.com/rizinorg/rizin); `rz-pipe` documents
JSON command transport and pipe backends.
- LIEF's [format tutorial](https://lief.re/doc/stable/tutorials/01_play_with_formats.html)
and [Python API](https://lief.re/doc/latest/api/binary_abstraction/python.html)
document parsing and format-agnostic binary access.
- Binary Ninja documents its [headless automation model](https://docs.binary.ninja/dev/batch.html),
[edition licenses](https://docs.binary.ninja/about/license.html), and the
[MIT license for API/documentation components](https://docs.binary.ninja/about/open-source.html).
+2 -2
View File
@@ -1,12 +1,12 @@
{
"name": "rea-agents",
"version": "0.4.0",
"version": "1.0.0",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "rea-agents",
"version": "0.4.0",
"version": "1.0.0",
"license": "MIT",
"dependencies": {
"@babel/parser": "8.0.4",
+1 -1
View File
@@ -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": {
+22 -1
View File
@@ -3,7 +3,11 @@ import { readFile } from "node:fs/promises";
import { dirname, join, resolve } from "node:path";
import { promisify } from "node:util";
import { sha256 } from "./lib/conformance-fixtures.mjs";
import {
generateLargeFixture,
sha256,
sourceDigest,
} from "./lib/conformance-fixtures.mjs";
const exec = promisify(execFile);
const manifestPath = resolve(
@@ -16,6 +20,23 @@ const root = dirname(manifestPath);
for (const fixture of manifest.fixtures) {
const artifactPath = join(root, fixture.artifact);
const sources = [];
for (const source of fixture.sources ?? []) {
const content =
source.path === "generated/large.c"
? generateLargeFixture()
: await readFile(join(process.cwd(), "tests/conformance", source.path));
if (sha256(content) !== source.sha256)
throw new Error(
`${fixture.name}: source hash mismatch for ${source.path}`,
);
sources.push({ path: source.path, content });
}
if (
fixture.sourceSha256 !== undefined &&
sourceDigest(sources) !== fixture.sourceSha256
)
throw new Error(`${fixture.name}: source manifest digest mismatch`);
const artifact = await readFile(artifactPath);
if (sha256(artifact) !== fixture.artifactSha256)
throw new Error(`${fixture.name}: artifact hash mismatch`);
+117 -2
View File
@@ -119,10 +119,19 @@ try {
const expectedDoctorHealth = supportedSetupHost;
if (
!help.includes("setup") ||
!help.includes("upgrade") ||
!help.includes("inventory-artifact") ||
!help.includes("extract-artifact") ||
!help.includes("import-reference-source") ||
!help.includes("compare") ||
!llms.includes("decompile") ||
!llms.includes("function") ||
!llms.includes("search") ||
!llms.includes("inspect") ||
!llms.includes("xrefs") ||
!llms.includes("trace") ||
!llms.includes("capabilities") ||
!llms.includes("providers") ||
!llms.includes("inventory-artifact") ||
doctor.healthy !== expectedDoctorHealth ||
doctor.checks?.find(({ name }) => name === "hopper")?.ok !== true
@@ -157,6 +166,87 @@ try {
throw new Error(
`packaged Hopper-backed analyze CLI failed: ${JSON.stringify(overview)}`,
);
const inspected = json(
await run(
cli,
[
"inspect",
process.execPath,
"--detail",
"detailed",
"--limit",
"1",
"--json",
],
environment,
),
);
if (
inspected.operation !== "binary_overview" ||
inspected.normalized_result?.detail !== "detailed"
)
throw new Error("packaged inspect CLI failed");
const functionResult = json(
await run(
cli,
["function", process.execPath, "0x1000", "--json"],
environment,
),
);
if (
functionResult.operation !== "analyze_function" ||
functionResult.provider?.id !== "hopper" ||
functionResult.normalized_result?.procedure?.address !== "0x1000"
)
throw new Error(
`packaged function CLI failed: ${JSON.stringify(functionResult)}`,
);
const xrefs = json(
await run(
cli,
["xrefs", process.execPath, "0x1000", "--json"],
environment,
),
);
if (
xrefs.operation !== "xrefs" ||
JSON.stringify(xrefs.normalized_result) !== JSON.stringify(["0x1000"])
)
throw new Error(`packaged xrefs CLI failed: ${JSON.stringify(xrefs)}`);
const trace = json(
await run(
cli,
["trace", process.execPath, "fixture", "--json"],
environment,
),
);
if (trace.operation !== "trace_feature")
throw new Error(`packaged trace CLI failed: ${JSON.stringify(trace)}`);
const capabilities = json(
await run(cli, ["capabilities", "--json"], environment),
);
if (!Array.isArray(capabilities.capabilities))
throw new Error("packaged capabilities CLI failed");
const providers = json(await run(cli, ["providers", "--json"], environment));
if (
!Array.isArray(providers.providers) ||
providers.providers.some(({ id }) => typeof id !== "string")
)
throw new Error("packaged providers CLI failed");
const searchResult = json(
await run(
cli,
["search", process.execPath, "fixture", "--json"],
environment,
),
);
if (
searchResult.operation !== "search_strings" ||
searchResult.normalized_result?.items?.length !== 1
)
throw new Error(
`packaged search CLI failed: ${JSON.stringify(searchResult)}`,
);
const referenceImport = json(
await run(
cli,
@@ -201,14 +291,25 @@ try {
environment,
),
);
const comparedBundle = json(
await run(
cli,
["compare", sourceBundlePath, canonicalBundlePath, "--json"],
environment,
),
);
if (
importedBundle.imported !== 1 ||
importedBundle.total !== 1 ||
exportedBundle.records !== 1 ||
(await readFile(canonicalBundlePath, "utf8")) !==
serializeEvidenceBundle(sourceBundle)
serializeEvidenceBundle(sourceBundle) ||
comparedBundle.status !== "unchanged" ||
comparedBundle.summary?.records_unchanged !== 1
)
throw new Error("packaged CLI evidence bundle round trip failed");
throw new Error(
"packaged CLI evidence bundle comparison round trip failed",
);
await run(cli, ["mcp", "add"], environment);
const mcpRegistration = await readFile(npxLog, "utf8");
if (!mcpRegistration.includes("add-mcp npx -y rea-agents mcp --name rea"))
@@ -325,6 +426,20 @@ try {
json(text(current)).normalized_result !== "fixture"
)
throw new Error("packaged MCP bridge call failed");
const batch = await client.callTool(
{ name: "batch_decompile", arguments: { addresses: ["0x1000"] } },
mcpOptions,
);
const batchResult = json(text(batch)).normalized_result;
if (
batch.isError === true ||
batchResult?.total !== 1 ||
batchResult?.succeeded !== 1 ||
batchResult?.failed !== 0 ||
batchResult?.items?.[0]?.status !== "ok" ||
batchResult?.items?.[0]?.pseudocode !== "return 0;"
)
throw new Error("packaged MCP structured batch result failed");
const closed = await client.callTool(
{ name: "close_binary", arguments: {} },
mcpOptions,
+23 -2
View File
@@ -1,4 +1,6 @@
import { execFile } from "node:child_process";
import { createHash } from "node:crypto";
import { createReadStream } from "node:fs";
import { readdir, realpath } from "node:fs/promises";
import { promisify } from "node:util";
@@ -8,6 +10,7 @@ import { StdioClientTransport } from "@modelcontextprotocol/client/stdio";
import { TOOL_CONTRACTS } from "../dist/contracts/toolContracts.js";
import {
firstProcedureAddress,
requireDistinctTargetHashes,
requireAddressArray,
requireFunctionDossier,
requirePseudocode,
@@ -182,12 +185,18 @@ const verifyCurrentTarget = async (client, options) => {
boundedResult === null ||
typeof boundedResult !== "object" ||
Array.isArray(boundedResult) ||
Object.keys(boundedResult).length !== 1
boundedResult.total !== 1 ||
boundedResult.succeeded !== 1 ||
boundedResult.failed !== 0 ||
!Array.isArray(boundedResult.items) ||
boundedResult.items.length !== 1 ||
boundedResult.items[0]?.address !== firstAddress ||
boundedResult.items[0]?.status !== "ok"
) {
throw new Error("batch_decompile returned an invalid result");
}
const boundedPseudocode = requirePseudocode(
boundedResult[firstAddress],
boundedResult.items[0].pseudocode,
"batch_decompile",
);
const dossier = requireFunctionDossier(
@@ -253,6 +262,11 @@ const [targetA, targetB] = await Promise.all([
]);
if (targetA === targetB)
throw new Error("Real-Hopper verification requires two distinct targets");
const [targetHashA, targetHashB] = await Promise.all([
sha256File(targetA),
sha256File(targetB),
]);
requireDistinctTargetHashes(targetHashA, targetHashB);
const serverEnvironment = { ...process.env };
delete serverEnvironment.HOPPER_TARGET_PATH;
delete serverEnvironment.HOPPER_SECOND_TARGET_PATH;
@@ -377,6 +391,7 @@ try {
diagnosticCount,
dynamicSession: true,
targets: [targetA, targetB],
targetHashes: [targetHashA, targetHashB],
switched: true,
secondOverview: verifiedSecondOverview,
};
@@ -422,3 +437,9 @@ await new Promise((resolve, reject) => {
},
);
});
async function sha256File(path) {
const hash = createHash("sha256");
for await (const chunk of createReadStream(path)) hash.update(chunk);
return hash.digest("hex");
}
+10 -1
View File
@@ -316,6 +316,14 @@ export class BinarySession implements BinarySessionPort {
name: this.#providerIdentity.name,
version: this.#providerIdentity.version,
};
const providers = new Map<string, ProviderIdentity>();
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
? []
@@ -348,10 +356,11 @@ export class BinarySession implements BinarySessionPort {
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,
+44 -14
View File
@@ -13,6 +13,15 @@ const WORKFLOW_PROVIDER = {
version: "1",
} as const;
type DirectAnalysisTool =
| "binary_overview"
| "procedure_pseudo_code"
| "analyze_function"
| "search_strings"
| "search_procedures"
| "xrefs"
| "trace_feature";
/**
* Open one binary, execute one tool, and always release the bridge session.
* Unlike MCP mode, every CLI invocation is intentionally isolated and does not
@@ -20,7 +29,7 @@ const WORKFLOW_PROVIDER = {
*/
export const runDirectAnalysis = async (
path: string,
tool: "binary_overview" | "procedure_pseudo_code",
tool: DirectAnalysisTool,
arguments_: Readonly<Record<string, JsonValue>>,
logger: Logger = silentLogger,
): Promise<JsonValue> => runAnalysis(path, tool, arguments_, logger);
@@ -33,13 +42,24 @@ export const runProviderAnalysis = async (
logger: Logger = silentLogger,
): Promise<JsonValue> => runAnalysis(path, tool, arguments_, logger);
/** Describe configured providers without opening a target or launching Hopper. */
export const runSessionStatus = async (
logger: Logger = silentLogger,
): Promise<JsonValue> => {
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: string,
tool:
| NativeToolName
| ArtifactToolName
| "binary_overview"
| "procedure_pseudo_code",
tool: NativeToolName | ArtifactToolName | DirectAnalysisTool,
arguments_: Readonly<Record<string, JsonValue>>,
logger: Logger,
): Promise<JsonValue> => {
@@ -51,16 +71,26 @@ const runAnalysis = async (
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, {
operation: tool,
parameters: arguments_,
result: result.value,
confidence: "derived",
limitations: ["Derived by an REA composed workflow."],
})
? createEvidence(
opened.value,
tool === "analyze_function"
? session.providerIdentity(tool)
: WORKFLOW_PROVIDER,
{
operation: tool,
parameters: arguments_,
result: result.value,
confidence: "derived",
limitations: ["Derived by an REA composed workflow."],
},
)
: { error: result.error._tag, message: result.error.message };
}
const result = await session.execute(tool, arguments_);
+60 -40
View File
@@ -6,10 +6,13 @@ import type { EnhancedToolName } from "../contracts/enhancedInputs.js";
import { enhancedInputSchemas } from "../contracts/enhancedInputs.js";
import {
AnalysisInputError,
AnalysisCancelledError,
AnalysisOutputError,
projectAnalysisError,
type AnalysisError,
} from "../domain/errors.js";
import {
addressDistance,
parseDocuments,
parseFunctionDossier,
parseAddressedPage,
@@ -133,26 +136,40 @@ export class EnhancedTools {
addresses: readonly string[],
signal?: AbortSignal,
): EnhancedResult {
if (addresses.length === 0) return ok({ error: "No addresses provided" });
const entries = await Promise.all(
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}`,
] as const;
if (!result.ok)
return {
address,
status: "error" as const,
error: projectAnalysisError(result.error),
};
if (typeof result.value !== "string" || result.value.length === 0)
return {
address,
status: "error" as const,
error: projectAnalysisError(
new AnalysisOutputError(
"procedure_pseudo_code",
"provider returned empty pseudocode",
),
),
};
return { address, status: "ok" as const, 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(
@@ -189,7 +206,8 @@ export class EnhancedTools {
if (!result.ok) {
graph[level].push({
address: current.address,
error: result.error.message,
status: "error",
error: projectAnalysisError(result.error),
});
continue;
}
@@ -197,12 +215,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) {
@@ -225,21 +245,34 @@ export class EnhancedTools {
}
async #findXrefs(name: string, signal?: AbortSignal): EnhancedResult {
const resolved = await this.#call(
"address_name",
{ address: name },
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 (!resolved.ok) return resolved;
const address = resolveAddress(resolved.value);
if (address === undefined)
return ok({ error: `Could not resolve name: ${name}` });
const xrefs = await this.#call("xrefs", { address }, signal);
if (!xrefs.ok) return xrefs;
return ok(
Array.isArray(xrefs.value) ? { xrefs: xrefs.value } : xrefs.value,
);
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(
@@ -472,6 +505,7 @@ export class EnhancedTools {
arguments_: Readonly<Record<string, JsonValue>>,
signal?: AbortSignal,
): Promise<Result<JsonValue, AnalysisError>> {
if (signal?.aborted === true) return err(new AnalysisCancelledError(name));
const execution = await this.analysis.execute(
name,
arguments_,
@@ -489,17 +523,3 @@ const invalidInput = (name: EnhancedToolName, cause: Error): EnhancedResult =>
}),
),
);
const resolveAddress = (value: JsonValue): string | undefined => {
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: string, end: string): number =>
Math.max(0, Number.parseInt(end, 16) - Number.parseInt(start, 16));
+35 -1
View File
@@ -1,10 +1,15 @@
import type { AnalysisError } from "../domain/errors.js";
import {
EvidenceIntegrityError,
type AnalysisError,
} from "../domain/errors.js";
import type {
EvidenceFilePolicy,
EvidenceBundle,
} from "../domain/evidenceBundle.js";
import type { JsonValue } from "../domain/jsonValue.js";
import { jsonValueSchema } from "../domain/jsonValue.js";
import { err, ok, type Result } from "../domain/result.js";
import { compareBundles } from "../domain/bundleComparison.js";
import { EvidenceLedger } from "./EvidenceLedger.js";
import {
readEvidenceBundle,
@@ -40,6 +45,35 @@ export const exportEvidenceBundleCommand = async (
);
};
/** Compare two validated canonical Evidence v2 bundles without session state. */
export const compareEvidenceBundlesCommand = async (input: {
readonly leftPath: string;
readonly rightPath: string;
readonly offset: number;
readonly limit: number;
readonly policy: EvidenceFilePolicy;
}): Promise<Result<JsonValue, AnalysisError>> => {
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: unknown) {
return err(
new EvidenceIntegrityError("Evidence bundle comparison failed", {
cause,
}),
);
}
};
const createLedger = (): EvidenceLedger =>
new EvidenceLedger({ maxRecords: 10_000, maxBytes: 64 * 1024 * 1024 });
+32
View File
@@ -8,6 +8,10 @@ export interface OwnedProcessGroup {
readonly runId: string;
readonly leaderPid: number;
readonly processGroupId: number;
/** Expected launcher identity, checked only while the leader exists. */
readonly expectedCommand?: string;
/** Expected launcher parent, checked only while the leader exists. */
readonly expectedParentPid?: number;
}
interface ProcessGroupMember {
@@ -86,6 +90,25 @@ export const cleanupOwnedProcessGroup = async (
return { cleaned: false, reason: "process group could not be inspected" };
}
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: Readonly<Record<string, string>>;
try {
@@ -113,3 +136,12 @@ export const cleanupOwnedProcessGroup = async (
}
return { cleaned: true, signaled: true };
};
const commandMatches = (actual: string, expected: string): boolean => {
const normalizedActual = actual.trim();
const normalizedExpected = expected.trim();
return (
normalizedActual === normalizedExpected ||
normalizedActual.startsWith(`${normalizedExpected} `)
);
};
+17
View File
@@ -27,6 +27,23 @@ export const firstProcedureAddress = (input: unknown): string => {
return first.address;
};
/** Reject two target paths that resolve to the same binary content. */
export const requireDistinctTargetHashes = (
firstHash: unknown,
secondHash: unknown,
): void => {
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: unknown,
+197
View File
@@ -0,0 +1,197 @@
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";
/** Location of the global npm installation that owns the running CLI. */
export interface NpmInstallation {
readonly prefix: string;
}
/** npm filesystem queries used to identify the installation being updated. */
export interface NpmInstallationHost {
canonicalPath(path: string): Promise<string>;
globalRoot(): Promise<string>;
globalPrefix(): Promise<string>;
}
/** Output channel policy for the package manager subprocess. */
export type UpgradeOutput = "human" | "structured";
/** Effects required to inspect and update the installed CLI. */
export interface UpgradeHost {
latestVersion(): Promise<string | undefined>;
installation(): Promise<NpmInstallation | undefined>;
installLatest(
installation: NpmInstallation,
output: UpgradeOutput,
): Promise<boolean>;
}
/** Caller-visible outcome of checking and updating the REA CLI. */
export type UpgradeResult =
| {
readonly status: "current";
readonly currentVersion: string;
readonly latestVersion: string;
readonly installMethod: "npm";
}
| {
readonly status: "upgraded";
readonly previousVersion: string;
readonly latestVersion: string | null;
readonly versionCheck: "available" | "unavailable";
readonly installMethod: "npm";
readonly command: typeof UPGRADE_COMMAND;
}
| {
readonly status: "failed";
readonly currentVersion: string;
readonly latestVersion: string | null;
readonly reason: "unknown-install-method" | "install";
readonly remediation: string;
};
/** Check the npm registry and update the same global REA installation. */
export const runUpgrade = async (
currentVersion: string,
host: UpgradeHost = systemUpgradeHost(),
output: UpgradeOutput = "human",
): Promise<UpgradeResult> => {
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 = (): UpgradeHost => ({
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: NpmInstallationHost = {
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: string,
host: NpmInstallationHost,
): Promise<NpmInstallation | undefined> => {
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: string,
): NpmInstallation | undefined => {
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: string,
arguments_: readonly string[],
output: UpgradeOutput,
): Promise<boolean> =>
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));
});
+208 -91
View File
@@ -5,17 +5,17 @@ import { runDoctor } from "./application/Doctor.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, type Logger } 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.
@@ -49,6 +49,27 @@ export const createCli = (): ReturnType<typeof Cli.create> => {
},
});
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: ReturnType<typeof Cli.create>,
logger: Logger,
): void => {
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({
@@ -81,14 +102,47 @@ export const createCli = (): ReturnType<typeof Cli.create> => {
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 }) =>
options: overviewOptions,
run: ({ args, options }) =>
logCliCommand(logger, "analyze", () =>
runDirectAnalysis(args.path, "binary_overview", {}, logger),
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", {
@@ -107,11 +161,154 @@ export const createCli = (): ReturnType<typeof Cli.create> => {
),
),
});
registerNativeCommands(cli, logger);
registerArtifactCommands(cli, logger);
registerEvidenceCommands(cli, logger);
registerReferenceSourceCommand(cli, logger);
return cli;
};
const registerXrefsCommand = (
cli: ReturnType<typeof Cli.create>,
logger: Logger,
): void => {
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: ReturnType<typeof Cli.create>,
logger: Logger,
): void => {
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: ReturnType<typeof Cli.create>,
logger: Logger,
): void => {
for (const command of ["capabilities", "providers"] as const) {
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: ReturnType<typeof Cli.create>,
logger: Logger,
): void => {
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: ReturnType<typeof Cli.create>,
logger: Logger,
): void => {
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 = (
@@ -253,83 +450,3 @@ const registerNativeCommands = (
),
});
};
const registerEvidenceCommands = (
cli: ReturnType<typeof Cli.create>,
logger: Logger,
): void => {
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 <Value>(
logger: Logger,
command: string,
execute: () => Promise<Value>,
): Promise<Value> => {
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: unknown) {
logger.error(
{
command,
durationMs: Math.round((performance.now() - startedAt) * 100) / 100,
status: "error",
},
"CLI command failed",
);
throw cause;
}
};
+89
View File
@@ -0,0 +1,89 @@
import { Cli, z } from "incur";
import {
compareEvidenceBundlesCommand,
exportEvidenceBundleCommand,
importEvidenceBundleCommand,
} from "./application/EvidenceBundleCommands.js";
import { parseConfig } from "./config.js";
import { logCliCommand } from "./cliLogging.js";
import type { Logger } from "./logger.js";
/** Register filesystem-gated Evidence v2 commands. */
export const registerEvidenceCommands = (
cli: ReturnType<typeof Cli.create>,
logger: Logger,
): void => {
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 };
}),
});
};
+32
View File
@@ -0,0 +1,32 @@
import type { Logger } from "./logger.js";
/** Log one CLI command with duration and a stable success or failure status. */
export const logCliCommand = async <Value>(
logger: Logger,
command: string,
execute: () => Promise<Value>,
): Promise<Value> => {
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: unknown) {
logger.error(
{
command,
durationMs: Math.round((performance.now() - startedAt) * 100) / 100,
status: "error",
},
"CLI command failed",
);
throw cause;
}
};
+3 -3
View File
@@ -365,12 +365,12 @@ export const ENHANCED_TOOL_CONTRACTS = [
),
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.",
"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. Nodes preserve per-procedure errors; indirect calls may be missing and results are not a whole-program CFG.",
"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(
@@ -380,7 +380,7 @@ export const ENHANCED_TOOL_CONTRACTS = [
),
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.",
"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(
+57 -15
View File
@@ -1,4 +1,5 @@
import { z } from "zod";
import { ANALYSIS_ERROR_TAGS } from "../domain/errors.js";
import { evidenceSchema } from "../domain/evidence.js";
import {
processCaptureComparisonSchema,
@@ -87,12 +88,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();
@@ -175,9 +178,24 @@ const symbolDiscoveryOutput = (property: "classes" | "protocols") =>
[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);
@@ -240,10 +258,25 @@ export const enhancedOutputSchemas: Readonly<Record<string, z.ZodObject>> = {
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()),
]),
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(
@@ -259,9 +292,18 @@ export const enhancedOutputSchemas: Readonly<Record<string, z.ZodObject>> = {
}),
),
find_xrefs_to_name: resultOf(
z.union([
z.object({ xrefs: addressList }),
z.object({ error: z.string() }),
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(
+45 -26
View File
@@ -1,27 +1,34 @@
export type AnalysisErrorTag =
| "AnalysisProtocolError"
| "AnalysisInputError"
| "AnalysisOutputError"
| "AnalysisCapabilityUnavailableError"
| "AnalysisCancelledError"
| "AnalysisTimeoutError"
| "ProviderSelectionError"
| "ProviderAdapterError"
| "ArtifactOperationError"
| "ProcessCaptureError"
| "EvidenceIntegrityError"
| "EvidenceLimitError"
| "EvidenceFileError"
| "UnknownRegistryError"
| "HopperTimeoutError"
| "HopperCancelledError"
| "HopperProtocolError"
| "HopperRemoteError"
| "HopperProcessError"
| "HopperStartError"
| "ConfigurationError"
| "NoBinaryOpenError"
| "BinaryTargetError";
import type { JsonValue } from "./jsonValue.js";
/** 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",
] as const;
/** Stable tag for an expected analysis failure. */
export type AnalysisErrorTag = (typeof ANALYSIS_ERROR_TAGS)[number];
/** Base class for expected analysis, provider, and session failures. */
export abstract class AnalysisError extends Error {
@@ -216,6 +223,12 @@ export class HopperProtocolError extends HopperError {
readonly _tag = "HopperProtocolError";
}
export type HopperDiagnosticType =
| "remote"
| "authorization"
| "invalid_request"
| "bridge_exception";
/** Hopper's JSON-RPC endpoint returned an expected remote error response. */
export class HopperRemoteError extends HopperError {
readonly _tag = "HopperRemoteError";
@@ -223,6 +236,7 @@ export class HopperRemoteError extends HopperError {
constructor(
readonly code: number,
readonly safeMessage: string,
readonly diagnosticType: HopperDiagnosticType = "remote",
) {
super(`Hopper request failed (${String(code)}): ${safeMessage}`);
}
@@ -273,7 +287,8 @@ export class BinaryTargetError extends AnalysisError {
}
}
export interface AnalysisErrorProjection {
export interface AnalysisErrorProjection
extends Readonly<Record<string, JsonValue>> {
readonly tag: AnalysisErrorTag;
readonly message: string;
readonly details: Readonly<Record<string, string | number | null>>;
@@ -322,7 +337,11 @@ const safeDetails = (
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 {};
};
+29 -5
View File
@@ -24,6 +24,10 @@ export interface AddressedPage {
readonly hasMore: boolean;
}
/** Return the non-negative byte distance between hexadecimal addresses. */
export const addressDistance = (start: string, end: string): number =>
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() }),
@@ -37,11 +41,31 @@ const segmentSchema = z.object({
writable: z.boolean().nullable().default(null),
executable: z.boolean().nullable().default(null),
});
const addressedPageSchema = z.object({
items: z.array(z.object({ address: z.string(), value: z.string() })),
next_offset: z.number().int().min(0).nullable(),
has_more: z.boolean(),
});
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() })
.strict();
+18 -10
View File
@@ -141,22 +141,18 @@ export class HopperApplicationLauncher implements BridgeLauncher {
{ encoding: "utf8", mode: 0o600 },
);
} catch (cause: unknown) {
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,
}),
cleanupOwnedProcessGroup(
ownedProcessGroup(session, pid, this.options.launcherPath),
),
});
} catch (cause: unknown) {
return err(new HopperStartError({ cause }));
@@ -164,6 +160,18 @@ export class HopperApplicationLauncher implements BridgeLauncher {
}
}
const ownedProcessGroup = (
session: BridgeSession,
pid: number,
launcherPath: string,
) => ({
runId: session.runId,
leaderPid: pid,
processGroupId: pid,
expectedCommand: launcherPath,
expectedParentPid: process.pid,
});
const prepareHopperApplication = async (
launcherPath: string,
signal?: AbortSignal,
+19 -2
View File
@@ -11,7 +11,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"),
}),
}),
]);
@@ -46,5 +57,11 @@ export const responseResult = (
response: HopperResponse,
): Result<JsonValue, HopperRemoteError> =>
"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);
+2
View File
@@ -129,6 +129,8 @@ class NativeMacOSClient implements AnalysisClient {
parameters: Readonly<Record<string, JsonValue>>,
options?: { readonly signal?: AbortSignal },
) {
if (options?.signal?.aborted === true)
return err(new AnalysisCancelledError(operation));
if (operation === "health")
return ok(createAnalysisExecution(null, IDENTITY));
if (!isNativeOperation(operation))
+1
View File
@@ -79,6 +79,7 @@ describe("binary session", () => {
expect(provider.capabilities()[0]?.operation).toBe("address_name");
expect(session.status()).toMatchObject({
provider: { id: "fixture", name: "Fixture", version: "1" },
providers: [{ id: "fixture", name: "Fixture", version: "1" }],
capabilities: [
{
operation: "address_name",
+11
View File
@@ -73,6 +73,11 @@ describe("Hopper bridge truthfulness", () => {
expect(bridgeSource).toContain("MAX_SEARCH_PATTERN_LENGTH = 256");
expect(bridgeSource).toContain("MAX_SEARCH_VALUE_LENGTH = 4096");
expect(bridgeSource).toContain('"value_truncated"');
expect(bridgeSource).toContain("page_end = offset + limit");
expect(bridgeSource).toContain("if offset <= total < page_end:");
expect(bridgeSource).not.toContain(
"matching = [item for item in _search_inventory(document, kind)",
);
});
it("caches sorted search inventories and invalidates them after renames", () => {
@@ -80,4 +85,10 @@ describe("Hopper bridge truthfulness", () => {
expect(bridgeSource).toContain("tuple(sorted(values.items()");
expect(bridgeSource).toContain("_invalidate_search_inventory(document)");
});
it("classifies bridge exceptions without forwarding tracebacks", () => {
expect(bridgeSource).toContain("def _diagnostic_type(error):");
expect(bridgeSource).toContain('"type": _diagnostic_type(error)');
expect(bridgeSource).not.toContain("traceback.format_exc");
});
});
+166 -9
View File
@@ -3,10 +3,13 @@ import type { CallToolResult } from "@modelcontextprotocol/server";
import { afterEach, describe, expect, it } from "vitest";
import type { AnalysisOperationPort } from "../src/application/AnalysisProvider.js";
import { EnhancedTools } from "../src/application/EnhancedTools.js";
import { ENHANCED_TOOL_CONTRACTS } from "../src/contracts/toolContracts.js";
import { observed as ok } from "./fixtures/analysisExecution.js";
import { AnalysisOutputError } from "../src/domain/errors.js";
import { jsonValueSchema, type JsonValue } from "../src/domain/jsonValue.js";
import { err } from "../src/domain/result.js";
import { createServer } from "../src/server/createServer.js";
import { observed as ok } from "./fixtures/analysisExecution.js";
const PROCEDURES = {
"0x1": "_TtC7Fixture5Class",
@@ -38,6 +41,7 @@ const fixturePort = (): AnalysisOperationPort => ({
"0x10": "_OBJC_CLASS_$_Fixture",
"0x11": "_OBJC_CLASS_$_Fixture",
"0x12": "_OBJC_PROTOCOL_$_FixtureDelegate",
"0x13": "entry",
}),
),
);
@@ -62,9 +66,7 @@ const fixturePort = (): AnalysisOperationPort => ({
case "procedure_callers":
return Promise.resolve(ok(["0x9"]));
case "address_name":
return Promise.resolve(
ok({ address: "0x1", name: arguments_.address ?? "" }),
);
return Promise.resolve(ok(arguments_.address ?? null));
case "xrefs":
return Promise.resolve(ok(["0x20", "0x21"]));
case "resolve_containing_procedure":
@@ -216,16 +218,29 @@ describe("enhanced MCP tools", () => {
// Legacy behavior treats any `_OBJC_` label, including protocol labels, as a class.
expect(results[1]).toMatchObject({ count: 2 });
expect(results[2]).toMatchObject({ count: 1 });
expect(results[3]).toEqual({ "0x1": "pseudo:0x1", "0x2": "pseudo:0x2" });
expect(results[3]).toEqual({
items: [
{ address: "0x1", status: "ok", pseudocode: "pseudo:0x1" },
{ address: "0x2", status: "ok", pseudocode: "pseudo:0x2" },
],
total: 2,
succeeded: 2,
failed: 0,
});
expect(results[4]).toEqual({
"0": [{ address: "0x1", calls: ["0x2", "0x3"] }],
"0": [{ address: "0x1", status: "ok", calls: ["0x2", "0x3"] }],
"1": [
{ address: "0x2", calls: ["0x1"] },
{ address: "0x3", calls: [] },
{ address: "0x2", status: "ok", calls: ["0x1"] },
{ address: "0x3", status: "ok", calls: [] },
],
});
expect(results[5]).toMatchObject({ total: 6 });
expect(results[6]).toEqual({ xrefs: ["0x20", "0x21"] });
expect(results[6]).toEqual({
status: "resolved",
name: "entry",
address: "0x13",
xrefs: ["0x20", "0x21"],
});
expect(results[7]).toMatchObject({
document: "fixture",
segment_count: 1,
@@ -274,6 +289,84 @@ describe("enhanced MCP tools", () => {
expect(maximum).toBe(20);
});
it("returns ordered typed batch failures and zero counts for empty input", async () => {
const tools = new EnhancedTools({
execute: (_name, arguments_) =>
arguments_.procedure === "0x2"
? Promise.resolve(err(new AnalysisOutputError("decompile", "failed")))
: Promise.resolve(ok("pseudo")),
});
const result = await tools.execute("batch_decompile", {
addresses: ["0x1", "0x2"],
});
const empty = await tools.execute("batch_decompile", { addresses: [] });
expect(result).toEqual({
ok: true,
value: {
items: [
{ address: "0x1", status: "ok", pseudocode: "pseudo" },
{
address: "0x2",
status: "error",
error: {
tag: "AnalysisOutputError",
message: "Invalid analysis output for decompile: failed",
details: { operation: "decompile", reason: "failed" },
},
},
],
total: 2,
succeeded: 1,
failed: 1,
},
});
expect(empty).toEqual({
ok: true,
value: { items: [], total: 0, succeeded: 0, failed: 0 },
});
});
it("returns typed graph failures and stable unresolved-name results", async () => {
const tools = new EnhancedTools({
execute: (name) =>
name === "procedure_callees"
? Promise.resolve(err(new AnalysisOutputError(name, "failed")))
: Promise.resolve(ok(page({}))),
});
const graph = await tools.execute("get_call_graph", {
address: "0x1",
direction: "forward",
depth: 1,
});
const unresolved = await tools.execute("find_xrefs_to_name", {
name: "missing",
});
expect(graph).toMatchObject({
ok: true,
value: {
"0": [
{
address: "0x1",
status: "error",
error: { tag: "AnalysisOutputError" },
},
],
},
});
expect(unresolved).toEqual({
ok: true,
value: {
status: "unresolved",
name: "missing",
reason: "name_not_found",
},
});
});
it("follows procedure pagination for whole-binary workflows", async () => {
const offsets: number[] = [];
const client = await connect({
@@ -304,6 +397,38 @@ describe("enhanced MCP tools", () => {
expect(result).toMatchObject({ count: 2 });
});
it("does not start another page after cancellation", async () => {
const controller = new AbortController();
let calls = 0;
const analysis: AnalysisOperationPort = {
execute: () => {
calls += 1;
controller.abort();
return Promise.resolve(
ok({
items: [{ address: "0x1", value: "_TtC5First" }],
offset: 0,
limit: 500,
total: 2,
next_offset: 500,
has_more: true,
}),
);
},
};
const result = await new EnhancedTools(analysis).execute(
"swift_classes",
{},
controller.signal,
);
expect(calls).toBe(1);
expect(result.ok).toBe(false);
if (result.ok) throw new Error("expected cancellation");
expect(result.error._tag).toBe("AnalysisCancelledError");
});
it("follows name pagination for exhaustive Objective-C discovery", async () => {
const offsets: number[] = [];
const client = await connect({
@@ -534,4 +659,36 @@ describe("enhanced MCP tools", () => {
"AnalysisOutputError",
);
});
it("accepts a final dossier page whose total exceeds returned", async () => {
const malformedPort = fixturePort();
const client = await connect({
execute: async (name, arguments_, options) => {
const result = await malformedPort.execute(name, arguments_, options);
if (!result.ok || name !== "analyze_function") return result;
const dossier = result.value.result;
if (
typeof dossier !== "object" ||
dossier === null ||
Array.isArray(dossier)
)
return result;
return ok({
...dossier,
callers: {
items: [],
total: 1,
returned: 0,
truncated: false,
next_offset: null,
},
});
},
});
const result = await client.callTool({
name: "analyze_function",
arguments: { procedure: "0x1" },
});
expect(result.isError).not.toBe(true);
});
});
+59 -23
View File
@@ -6,6 +6,8 @@ import {
AnalysisInputError,
AnalysisOutputError,
AnalysisProtocolError,
AnalysisTimeoutError,
ArtifactOperationError,
BinaryTargetError,
ConfigurationError,
EvidenceFileError,
@@ -20,8 +22,10 @@ import {
NoBinaryOpenError,
ProviderAdapterError,
ProviderSelectionError,
UnknownRegistryError,
projectAnalysisError,
type AnalysisError,
type AnalysisErrorTag,
} from "../src/domain/errors.js";
import { ProcessCaptureError } from "../src/application/ProcessHarness.js";
@@ -34,35 +38,67 @@ describe("analysis error projection", () => {
it("exhaustively projects stable tags without causes or local paths", () => {
const secretCause = new Error("secret-token");
const errors: readonly AnalysisError[] = [
new AnalysisProtocolError("protocol"),
new AnalysisInputError("overview", { cause: secretCause }),
new AnalysisOutputError("overview", "invalid shape", {
const byTag = {
AnalysisProtocolError: new AnalysisProtocolError("protocol failed"),
AnalysisInputError: new AnalysisInputError("overview", {
cause: secretCause,
}),
new AnalysisCapabilityUnavailableError("fixture", "overview", "absent"),
new AnalysisCancelledError("overview"),
new ProviderSelectionError("overview"),
new ProviderAdapterError("fixture", "overview", { cause: secretCause }),
new ProcessCaptureError("capture refused", { cause: secretCause }),
new EvidenceIntegrityError("integrity", { cause: secretCause }),
new EvidenceLimitError("records", 10),
new EvidenceFileError("read", "outside-root", { cause: secretCause }),
new HopperTimeoutError(100),
new HopperCancelledError(),
new HopperProtocolError("wire", { cause: secretCause }),
new HopperRemoteError(7, "safe"),
new HopperProcessError(1),
new HopperStartError({ cause: secretCause }),
new ConfigurationError("configuration", { cause: secretCause }),
new NoBinaryOpenError(),
new BinaryTargetError("/secret/local/path", "invalid", {
AnalysisOutputError: new AnalysisOutputError(
"overview",
"invalid shape",
{
cause: secretCause,
},
),
AnalysisCapabilityUnavailableError:
new AnalysisCapabilityUnavailableError("fixture", "overview", "absent"),
AnalysisCancelledError: new AnalysisCancelledError("overview"),
AnalysisTimeoutError: new AnalysisTimeoutError("overview", 50),
ProviderSelectionError: new ProviderSelectionError("overview"),
ProviderAdapterError: new ProviderAdapterError("fixture", "overview", {
cause: secretCause,
}),
];
ArtifactOperationError: new ArtifactOperationError(
"inventory_artifact",
"integrity",
),
ProcessCaptureError: new ProcessCaptureError("capture failed", {
cause: secretCause,
}),
EvidenceIntegrityError: new EvidenceIntegrityError("integrity failed", {
cause: secretCause,
}),
EvidenceLimitError: new EvidenceLimitError("records", 10),
EvidenceFileError: new EvidenceFileError("read", "outside-root", {
cause: secretCause,
}),
UnknownRegistryError: new UnknownRegistryError("revision-conflict", {
cause: secretCause,
}),
HopperTimeoutError: new HopperTimeoutError(100),
HopperCancelledError: new HopperCancelledError(),
HopperProtocolError: new HopperProtocolError("wire failed", {
cause: secretCause,
}),
HopperRemoteError: new HopperRemoteError(7, "safe"),
HopperProcessError: new HopperProcessError(1),
HopperStartError: new HopperStartError({ cause: secretCause }),
ConfigurationError: new ConfigurationError("configuration failed", {
cause: secretCause,
}),
NoBinaryOpenError: new NoBinaryOpenError(),
BinaryTargetError: new BinaryTargetError(
"/secret/local/path",
"invalid",
{
cause: secretCause,
},
),
} satisfies Readonly<Record<AnalysisErrorTag, AnalysisError>>;
const errors = Object.values(byTag);
const projected = errors.map(projectAnalysisError);
expect(new Set(projected.map(({ tag }) => tag)).size).toBe(errors.length);
expect(projected).toHaveLength(20);
expect(projected).toHaveLength(23);
expect(JSON.stringify(projected)).not.toContain("secret-token");
expect(JSON.stringify(projected)).not.toContain("/secret/local/path");
expect(
+16
View File
@@ -15,6 +15,7 @@ import {
readEvidenceBundle,
writeEvidenceBundle,
} from "../src/application/EvidenceBundleFiles.js";
import { compareEvidenceBundlesCommand } from "../src/application/EvidenceBundleCommands.js";
import { createEvidence } from "../src/domain/evidence.js";
import {
createEvidenceBundle,
@@ -66,6 +67,21 @@ describe("evidence bundle filesystem adapter", () => {
ok: true,
value: evidenceBundle,
});
expect(
await compareEvidenceBundlesCommand({
leftPath: path,
rightPath: path,
offset: 0,
limit: 100,
policy: policy(directory),
}),
).toMatchObject({
ok: true,
value: {
status: "unchanged",
summary: { records_unchanged: 1 },
},
});
expect(
await writeEvidenceBundle(evidenceBundle, path, false, policy(directory)),
).toMatchObject({
+66 -2
View File
@@ -26,9 +26,69 @@ const enhancedFixtureResult = (method) => {
has_more: false,
};
case "list_strings":
return ["fixture"];
return {
items: [{ address: "0x1000", value: "fixture" }],
offset: 0,
limit: 500,
total: 1,
next_offset: null,
has_more: false,
};
case "procedure_pseudo_code":
return "return 0;";
case "analyze_function": {
const empty = () => ({
items: [],
total: 0,
returned: 0,
truncated: false,
next_offset: null,
});
return {
procedure: {
address: "0x1000",
name: "fixture",
signature: null,
locals: [],
},
pseudocode: {
text: "return 0;",
total_chars: 9,
returned_chars: 9,
truncated: false,
next_offset: null,
},
assembly: { ...empty(), items: ["ret"], total: 1, returned: 1 },
comments: empty(),
callers: empty(),
callees: empty(),
incoming_references: empty(),
outgoing_references: empty(),
referenced_strings: empty(),
referenced_names: empty(),
basic_blocks: {
...empty(),
items: [{ start: "0x1000", end: "0x1001", successors: [] }],
total: 1,
returned: 1,
},
instruction_scan: { scanned: 1, truncated: false },
};
}
case "search_strings":
case "search_procedures":
return {
items: [
{ address: "0x1000", value: "fixture", value_truncated: false },
],
offset: 0,
limit: 100,
total: 1,
next_offset: null,
has_more: false,
};
case "xrefs":
return ["0x1000"];
default:
return undefined;
}
@@ -79,7 +139,11 @@ const server = createServer((socket) => {
} else if (request.method === "remote_error") {
send({
id: request.id,
error: { code: -32001, message: "safe fake failure" },
error: {
code: -32001,
message: "safe fake failure",
type: "bridge_exception",
},
});
} else if (request.method === "current_document") {
send({ id: request.id, result: "fixture" });
+11
View File
@@ -131,6 +131,17 @@ describe("HopperClient", () => {
if (!result.ok) expect(result.error._tag).toBe(expectedTag);
});
it("preserves a sanitized bridge exception diagnostic", async () => {
const client = await startClient();
const result = await client.callTool("remote_error");
expect(result.ok).toBe(false);
if (!result.ok)
expect(result.error).toMatchObject({
_tag: "HopperRemoteError",
diagnosticType: "bridge_exception",
});
});
it("cancels and ignores late responses without corrupting the session", async () => {
const client = await startClient();
const controller = new AbortController();
+24
View File
@@ -2,6 +2,7 @@ import { describe, expect, it } from "vitest";
import {
parseDocuments,
parseAddressedPage,
parseListCount,
parseNames,
parseProcedures,
@@ -62,6 +63,29 @@ describe("Hopper boundary values", () => {
});
});
it.each([
{
items: [],
offset: 0,
limit: 100,
total: 1,
next_offset: null,
has_more: true,
},
{
items: [],
offset: 0,
limit: 100,
total: 0,
next_offset: 100,
has_more: false,
},
])("rejects contradictory page continuation metadata", (page) => {
const result = parseAddressedPage(page);
expect(result.ok).toBe(false);
if (!result.ok) expect(result.error._tag).toBe("HopperProtocolError");
});
it.each([
["procedures", () => parseProcedures(["not-a-map"])],
["names", () => parseNames([{ address: 1, name: "bad" }])],
+29
View File
@@ -137,6 +137,26 @@ describe("native macOS provider", () => {
}
});
it("classifies pre-aborted requests before operation or runner discovery", async () => {
const controller = new AbortController();
controller.abort();
const runner = new CountingRunner();
const client = new NativeMacOSProvider(runner, "linux").createClient(
machoTarget("/fixture"),
);
const result = await client.execute(
"list_architectures",
{},
{
signal: controller.signal,
},
);
expect(!result.ok && result.error._tag).toBe("AnalysisCancelledError");
expect(runner.calls).toBe(0);
});
it("parses thin and universal lipo fixtures", async () => {
expect(
parseLipoArchitectures(await fixture("lipo-thin.txt")),
@@ -169,6 +189,15 @@ class FailingRunner implements NativeCommandRunner {
}
}
class CountingRunner implements NativeCommandRunner {
calls = 0;
run(tool: string) {
this.calls += 1;
return Promise.resolve(err(new NativeCommandFailure(tool, "unavailable")));
}
}
const outputFor = async (
tool: string,
arguments_: readonly string[],
+36
View File
@@ -67,4 +67,40 @@ describe("owned process-group cleanup", () => {
signaled: false,
});
});
it("fails closed when the launcher command identity changes", async () => {
const { adapter, signalGroup } = host({
100: { REA_PROCESS_RUN_ID: "run-token" },
});
expect(
await cleanupOwnedProcessGroup(
{
...ownership,
expectedCommand: "/owned/hopper",
expectedParentPid: 1,
},
adapter,
),
).toEqual({
cleaned: false,
reason: "owned launcher command identity did not match",
});
expect(signalGroup).not.toHaveBeenCalled();
});
it("fails closed when the launcher parent identity changes", async () => {
const { adapter, signalGroup } = host({
100: { REA_PROCESS_RUN_ID: "run-token" },
});
expect(
await cleanupOwnedProcessGroup(
{ ...ownership, expectedCommand: "fixture", expectedParentPid: 999 },
adapter,
),
).toEqual({
cleaned: false,
reason: "owned launcher parent identity did not match",
});
expect(signalGroup).not.toHaveBeenCalled();
});
});
+38 -10
View File
@@ -19,6 +19,38 @@ const readmes = [
"README_ar.md",
] as const;
const expectedToolCounts = [
OFFICIAL_TOOL_CONTRACTS.length,
ENHANCED_TOOL_CONTRACTS.length,
NATIVE_TOOL_CONTRACTS.length,
ARTIFACT_TOOL_CONTRACTS.length,
SESSION_TOOL_CONTRACTS.length,
] as const;
const toolCountsFromReadme = (content: string, path: string): number[] => {
const lines = content.split(/\r?\n/u);
const headingIndex = lines.findIndex((line) => /^## .*68/u.test(line));
if (headingIndex === -1)
throw new Error(`Missing 68-tool heading in ${path}`);
const counts: number[] = [];
for (const line of lines.slice(headingIndex + 1)) {
if (line.startsWith("## ")) break;
if (!line.trim().startsWith("|") || /^\|\s*-/.test(line)) continue;
const cells = line.split("|").map((cell) => cell.trim());
const countCell = cells[2];
if (countCell === undefined)
throw new Error(`Malformed table row in ${path}`);
const count = Number(countCell);
if (!Number.isInteger(count)) {
if (counts.length === 0) continue;
throw new Error(`Non-numeric tool count in ${path}`);
}
counts.push(count);
}
return counts;
};
describe("localized README product facts", () => {
it.each(readmes)(
"keeps commands and requirements aligned in %s",
@@ -34,17 +66,13 @@ describe("localized README product facts", () => {
expect(content).toContain('"args": ["-y", "rea-agents", "mcp"]');
expect(content).toContain("Node.js 24");
expect(content).toContain("macOS 12");
expect(content).toContain("Ubuntu 24.04");
expect(content).toContain("Fedora 41");
expect(content).toContain("Arch Linux");
if (path === "README_ar.md")
expect(content).toContain("Windows غير مدعوم حاليًا");
expect(content).toContain(`MCP_tools-${String(TOOL_CONTRACTS.length)}`);
for (const count of [
OFFICIAL_TOOL_CONTRACTS.length,
ENHANCED_TOOL_CONTRACTS.length,
NATIVE_TOOL_CONTRACTS.length,
ARTIFACT_TOOL_CONTRACTS.length,
SESSION_TOOL_CONTRACTS.length,
])
expect(content).toMatch(
new RegExp(`\\|\\s*${String(count)}\\s*\\|`, "u"),
);
expect(toolCountsFromReadme(content, path)).toEqual(expectedToolCounts);
},
);
+8
View File
@@ -2,12 +2,20 @@ import { describe, expect, it } from "vitest";
import {
firstProcedureAddress,
requireDistinctTargetHashes,
requireAddressArray,
requireFunctionDossier,
requirePseudocode,
} from "../src/application/RealHopperAssertions.js";
describe("real Hopper semantic assertions", () => {
it("rejects two target paths containing the same binary", () => {
expect(() => requireDistinctTargetHashes("same", "same")).toThrow(
/distinct binaries/u,
);
expect(() => requireDistinctTargetHashes("", "other")).toThrow();
expect(() => requireDistinctTargetHashes("first", "second")).not.toThrow();
});
it("extracts only a real procedure address from a structured page", () => {
expect(
firstProcedureAddress({
+136
View File
@@ -0,0 +1,136 @@
import { describe, expect, it } from "vitest";
import {
detectNpmInstallation,
runUpgrade,
type UpgradeHost,
type UpgradeOutput,
type NpmInstallationHost,
} from "../src/application/Upgrade.js";
class FakeUpgradeHost implements UpgradeHost {
latest: string | undefined = "0.6.0";
installationResult: { readonly prefix: string } | undefined = {
prefix: "/fixture",
};
installSucceeds = true;
installs = 0;
output: UpgradeOutput | undefined;
latestVersion = (): Promise<string | undefined> =>
Promise.resolve(this.latest);
installation = (): Promise<{ readonly prefix: string } | undefined> =>
Promise.resolve(this.installationResult);
installLatest = (
_installation: { readonly prefix: string },
output: UpgradeOutput,
): Promise<boolean> => {
this.installs += 1;
this.output = output;
return Promise.resolve(this.installSucceeds);
};
}
describe("CLI upgrade", () => {
it("reports an already-current release without mutation", async () => {
const host = new FakeUpgradeHost();
expect(await runUpgrade("0.6.0", host)).toEqual({
status: "current",
currentVersion: "0.6.0",
latestVersion: "0.6.0",
installMethod: "npm",
});
expect(host.installs).toBe(0);
});
it("upgrades an outdated global npm installation", async () => {
const host = new FakeUpgradeHost();
expect(await runUpgrade("0.5.0", host)).toEqual({
status: "upgraded",
previousVersion: "0.5.0",
latestVersion: "0.6.0",
versionCheck: "available",
installMethod: "npm",
command: "npm install --global rea-agents@latest",
});
expect(host.installs).toBe(1);
});
it("continues with npm latest when the registry check is unavailable", async () => {
const host = new FakeUpgradeHost();
host.latest = undefined;
expect(await runUpgrade("0.5.0", host)).toMatchObject({
status: "upgraded",
latestVersion: null,
versionCheck: "unavailable",
});
expect(host.installs).toBe(1);
});
it("preserves stdout for an explicitly structured CLI response", async () => {
const host = new FakeUpgradeHost();
await runUpgrade("0.5.0", host, "structured");
expect(host.output).toBe("structured");
});
it("refuses to mutate an unrelated installation", async () => {
const host = new FakeUpgradeHost();
host.installationResult = undefined;
expect(await runUpgrade("0.5.0", host)).toMatchObject({
status: "failed",
reason: "unknown-install-method",
remediation:
"Update manually with: npm install --global rea-agents@latest",
});
expect(host.installs).toBe(0);
});
it("reports npm installation failure", async () => {
const host = new FakeUpgradeHost();
host.installSucceeds = false;
expect(await runUpgrade("0.5.0", host)).toMatchObject({
status: "failed",
reason: "install",
});
expect(host.installs).toBe(1);
});
});
describe("npm installation detection", () => {
const host = (root: string, prefix = "/usr/local"): NpmInstallationHost => ({
canonicalPath: (path) => Promise.resolve(path),
globalRoot: () => Promise.resolve(root),
globalPrefix: () => Promise.resolve(prefix),
});
it("returns the prefix for the global package that owns the running CLI", async () => {
await expect(
detectNpmInstallation(
"/usr/local/lib/node_modules/rea-agents",
host("/usr/local/lib/node_modules"),
),
).resolves.toEqual({ prefix: "/usr/local" });
});
it("infers the prefix used by the curl installer's custom npm layout", async () => {
await expect(
detectNpmInstallation(
"/home/user/.local/lib/node_modules/rea-agents",
host("/usr/local/lib/node_modules"),
),
).resolves.toEqual({ prefix: "/home/user/.local" });
});
it("rejects a source checkout when a different global copy exists", async () => {
await expect(
detectNpmInstallation("/work/rea", host("/usr/local/lib/node_modules")),
).resolves.toBeUndefined();
});
});