Compare commits
76
Commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
960b4df056 | ||
|
|
a83dbb2fb3 | ||
|
|
71f03a7224 | ||
|
|
7b6f7becd2 | ||
|
|
1f8ad7bc68 | ||
|
|
7f46bb1824 | ||
|
|
dae2b9cc4e | ||
|
|
48053d1032 | ||
|
|
f0d8cdafa8 | ||
|
|
97f6a0f3fd | ||
|
|
92a1c33625 | ||
|
|
8ccdb33dd2 | ||
|
|
788f4057ae | ||
|
|
f07acde513 | ||
|
|
f47ee1abb4 | ||
|
|
935721df10 | ||
|
|
3c42403b78 | ||
|
|
a8161f0e55 | ||
|
|
513d9b1555 | ||
|
|
7f2348619a | ||
|
|
ede91ff1f0 | ||
|
|
f3b3fb07de | ||
|
|
ab4193c1f4 | ||
|
|
c824db1ab7 | ||
|
|
17d7dbc461 | ||
|
|
2a45d8de7d | ||
|
|
ba098f24e5 | ||
|
|
1712e6d821 | ||
|
|
3e1e8cd3f8 | ||
|
|
59d465971e | ||
|
|
281e41f766 | ||
|
|
0f96bf365c | ||
|
|
969519c00f | ||
|
|
222ce83967 | ||
|
|
7929bf1688 | ||
|
|
8ab40974d3 | ||
|
|
91fb87d17e | ||
|
|
54153ed62c | ||
|
|
f942558573 | ||
|
|
1fb22b4c21 | ||
|
|
1a75f8dc23 | ||
|
|
18624df572 | ||
|
|
0ef1b91cf3 | ||
|
|
64f64fec30 | ||
|
|
4602efd27c | ||
|
|
94e6600faf | ||
|
|
4d228b4d8c | ||
|
|
a5e355a3d5 | ||
|
|
fdeeb27f23 | ||
|
|
d5d2e56d04 | ||
|
|
d7a07535b0 | ||
|
|
6c03f83b1b | ||
|
|
4e0127d620 | ||
|
|
6fa6f9b6d9 | ||
|
|
3f336fefb1 | ||
|
|
4ee30e4145 | ||
|
|
645668b70d | ||
|
|
ba3151891e | ||
|
|
c4cd0330e0 | ||
|
|
1caa0d6e54 | ||
|
|
17c8b4c2f1 | ||
|
|
58c749e831 | ||
|
|
8ec9bb1bfe | ||
|
|
7157ab0b70 | ||
|
|
fecddc0549 | ||
|
|
6d37efe8fa | ||
|
|
90bb1610f5 | ||
|
|
1a0931b630 | ||
|
|
40bf55b74c | ||
|
|
b2f7561bdd | ||
|
|
f2c4edd2bf | ||
|
|
4716fa2ece | ||
|
|
521139d4a5 | ||
|
|
5184816199 | ||
|
|
9522adf19a | ||
|
|
7a43420029 |
+54
-15
@@ -88,7 +88,7 @@ jobs:
|
||||
strategy:
|
||||
fail-fast: false
|
||||
matrix:
|
||||
shard: [1/2, 2/2]
|
||||
shard: [1/4, 2/4, 3/4, 4/4]
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
- uses: actions/setup-node@v4
|
||||
@@ -160,13 +160,47 @@ jobs:
|
||||
path: .vitest-reports
|
||||
pattern: vitest-report-*
|
||||
merge-multiple: true
|
||||
- if: needs.changes.outputs.code == 'true' && success()
|
||||
run: npm run test:ci:merge
|
||||
- name: Merge coverage, JUnit, and timing reports
|
||||
if: needs.changes.outputs.code == 'true' && success()
|
||||
run: >-
|
||||
npm run test:ci:merge --
|
||||
--coverage.reportsDirectory=coverage
|
||||
--coverage.reporter=text
|
||||
--coverage.reporter=json-summary
|
||||
--coverage.reporter=lcov
|
||||
--reporter=default
|
||||
--reporter=junit
|
||||
--reporter=json
|
||||
--outputFile.junit=test-results.xml
|
||||
--outputFile.json=test-results.json
|
||||
- name: Summarize slowest test files
|
||||
if: needs.changes.outputs.code == 'true' && success()
|
||||
shell: bash
|
||||
run: |
|
||||
node <<'NODE' >> "${GITHUB_STEP_SUMMARY}"
|
||||
const report = JSON.parse(require("node:fs").readFileSync("test-results.json", "utf8"));
|
||||
const files = (report.testResults ?? [])
|
||||
.map((result) => ({
|
||||
name: result.name,
|
||||
duration: Math.max(0, (result.endTime ?? result.startTime) - result.startTime),
|
||||
}))
|
||||
.sort((left, right) => right.duration - left.duration)
|
||||
.slice(0, 20);
|
||||
console.log("## Slowest deterministic test files\n");
|
||||
console.log("| File | Duration (ms) |");
|
||||
console.log("| --- | ---: |");
|
||||
for (const file of files) {
|
||||
console.log(`| \`${file.name}\` | ${file.duration} |`);
|
||||
}
|
||||
NODE
|
||||
- uses: actions/upload-artifact@v4
|
||||
if: needs.changes.outputs.code == 'true' && always()
|
||||
with:
|
||||
name: test-results
|
||||
path: test-results.xml
|
||||
path: |
|
||||
test-results.xml
|
||||
test-results.json
|
||||
coverage/
|
||||
if-no-files-found: error
|
||||
retention-days: 30
|
||||
|
||||
@@ -258,17 +292,22 @@ jobs:
|
||||
- name: Run curated Windows P0 tests
|
||||
run: >-
|
||||
npx vitest run --coverage.enabled=false
|
||||
tests/binaryTarget.test.ts
|
||||
tests/windowsCapabilities.test.ts
|
||||
tests/ghidraWindowsFixture.test.ts
|
||||
tests/ghidraInstallation.test.ts
|
||||
tests/ghidraProvider.test.ts
|
||||
tests/ghidraTransport.test.ts
|
||||
tests/ghidraTargetSnapshot.test.ts
|
||||
tests/ghidraClient.test.ts
|
||||
tests/ghidraLauncher.test.ts
|
||||
tests/processOwnership.test.ts
|
||||
tests/realGhidraWindowsWorkflow.test.ts
|
||||
tests/composition/analysis-sessions/binaryTarget.test.ts
|
||||
tests/conformance/providers/ghidra/windowsCapabilities.test.ts
|
||||
tests/conformance/providers/ghidra/ghidraWindowsFixture.test.ts
|
||||
tests/boundary/providers/ghidra/ghidraInstallation.test.ts
|
||||
tests/boundary/providers/ghidra/ghidraProvider.test.ts
|
||||
tests/boundary/providers/ghidra/ghidraTransport.test.ts
|
||||
tests/boundary/providers/ghidra/ghidraTargetSnapshot.test.ts
|
||||
tests/boundary/providers/ghidra/ghidraClient.test.ts
|
||||
tests/boundary/providers/ghidra/ghidraLauncher.test.ts
|
||||
tests/boundary/process/processOwnership.test.ts
|
||||
tests/boundary/process/processOwnershipPart2.test.ts
|
||||
tests/boundary/process/processOwnershipPart3.test.ts
|
||||
tests/boundary/process/processOwnershipValidation.test.ts
|
||||
tests/boundary/process/processOwnershipValidationPart2.test.ts
|
||||
tests/boundary/process/processOwnershipValidationPart3.test.ts
|
||||
tests/conformance/providers/ghidra/realGhidraWindowsWorkflow.test.ts
|
||||
- run: npm run verify:package:windows
|
||||
- uses: actions/upload-artifact@v4
|
||||
if: always()
|
||||
|
||||
+77
-3
@@ -18,10 +18,84 @@
|
||||
},
|
||||
"overrides": [
|
||||
{
|
||||
"files": ["tests/**/*.ts"],
|
||||
"files": ["tests/**/*.ts", "src/**/*.test.ts"],
|
||||
"rules": {
|
||||
"max-lines-per-function": "off",
|
||||
"max-lines": "off"
|
||||
"max-lines": [
|
||||
"error",
|
||||
{ "max": 500, "skipBlankLines": true, "skipComments": true }
|
||||
],
|
||||
"max-lines-per-function": [
|
||||
"error",
|
||||
{ "max": 150, "skipBlankLines": true, "skipComments": true }
|
||||
]
|
||||
}
|
||||
},
|
||||
{
|
||||
"files": ["src/domain/**/*.test.ts"],
|
||||
"rules": {
|
||||
"no-restricted-imports": [
|
||||
"error",
|
||||
{
|
||||
"patterns": [
|
||||
{
|
||||
"group": [
|
||||
"**/application/**",
|
||||
"**/server/**",
|
||||
"**/process/**",
|
||||
"**/browser/**",
|
||||
"**/ghidra/**",
|
||||
"**/hopper/**",
|
||||
"**/replay/**",
|
||||
"**/cli.*",
|
||||
"**/main.*"
|
||||
],
|
||||
"message": "Domain tests may import only their owning domain and inward dependencies."
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
},
|
||||
{
|
||||
"files": ["src/application/**/*.test.ts"],
|
||||
"rules": {
|
||||
"no-restricted-imports": [
|
||||
"error",
|
||||
{
|
||||
"patterns": [
|
||||
{
|
||||
"group": ["**/server/**", "**/cli.*", "**/main.*"],
|
||||
"message": "Service tests must use application ports rather than CLI or MCP entrypoints."
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
},
|
||||
{
|
||||
"files": ["tests/composition/**/*.test.ts"],
|
||||
"rules": {
|
||||
"no-restricted-imports": [
|
||||
"error",
|
||||
{
|
||||
"patterns": [
|
||||
{
|
||||
"group": [
|
||||
"**/server/**",
|
||||
"**/cli.*",
|
||||
"**/main.*",
|
||||
"node:child_process",
|
||||
"node:net",
|
||||
"node:http",
|
||||
"node:https",
|
||||
"ws",
|
||||
"playwright"
|
||||
],
|
||||
"message": "Composition tests may wire provider-neutral sessions but must not invoke CLI, MCP, process, network, or browser boundaries."
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
],
|
||||
|
||||
@@ -1,3 +1,3 @@
|
||||
{
|
||||
".": "2.5.1"
|
||||
".": "3.0.0"
|
||||
}
|
||||
|
||||
+118
@@ -1,5 +1,123 @@
|
||||
# Changelog
|
||||
|
||||
## [3.0.0](https://github.com/morluto/rea/compare/rea-agents-2.7.0...rea-agents-3.0.0) (2026-08-01)
|
||||
|
||||
|
||||
### ⚠ BREAKING CHANGES
|
||||
|
||||
* export_evidence_bundle now requires a filesystem path and no longer returns an inline bundle.
|
||||
|
||||
### Features
|
||||
|
||||
* make evidence bundles canonical MCP resources ([1712e6d](https://github.com/morluto/rea/commit/1712e6d821965ce5edc3880fe4ebab2e3cc02fd4))
|
||||
|
||||
|
||||
### Bug Fixes
|
||||
|
||||
* address MCP resource review feedback ([f3b3fb0](https://github.com/morluto/rea/commit/f3b3fb07ded3d1ad72c0a4f24ca3147ef9722c5d))
|
||||
* align aggregate tools with session capabilities ([ede91ff](https://github.com/morluto/rea/commit/ede91ff1f04563001f695ec3869daeb3c826154a))
|
||||
* **ci:** align Vitest project worker budgets ([f47ee1a](https://github.com/morluto/rea/commit/f47ee1abb4fc8dbd5da3fa13c5870d6580b28bfa))
|
||||
* **ci:** allow documented public type aliases ([97f6a0f](https://github.com/morluto/rea/commit/97f6a0f3fd2ebf8fa884d7f7ba6e1c66ecfe80e0))
|
||||
* **ci:** make coverage report merging composable ([788f405](https://github.com/morluto/rea/commit/788f4057aee65dfae441249d2c9789bb996912a7))
|
||||
* **ci:** stabilize Vitest project routing and shards ([f07acde](https://github.com/morluto/rea/commit/f07acde513d4c74d027b66e143cf5072246b412b))
|
||||
* **errors:** preserve actionable analysis diagnostics ([0f96bf3](https://github.com/morluto/rea/commit/0f96bf365c330a7eb121a173bfa140cc2b652764))
|
||||
* **mcp:** clarify routing and advertise input examples ([969519c](https://github.com/morluto/rea/commit/969519c00f31b5bc0f23dcffe8867e091461fda6))
|
||||
* **mcp:** clarify target routing and caller diagnostics ([3e1e8cd](https://github.com/morluto/rea/commit/3e1e8cd3f829e6d3ac8b3c63d979f9db84dec826))
|
||||
* **test:** bound boundary worker pressure ([935721d](https://github.com/morluto/rea/commit/935721df10d25d23621dbc2be90d334644e0858c))
|
||||
* **test:** honor boundary ownership and public aliases ([92a1c33](https://github.com/morluto/rea/commit/92a1c33625ff88d81581554687e7708dd3c91e2d))
|
||||
* **test:** retain subprocess coverage and cleanup ([7f46bb1](https://github.com/morluto/rea/commit/7f46bb18241bf3815e5e01816277d0cafe8f923b))
|
||||
* **test:** retain subprocess coverage and cleanup ([dae2b9c](https://github.com/morluto/rea/commit/dae2b9cc4e8753827702ada6e51f2ee01811cfed))
|
||||
* **test:** stabilize boundary timing ([f0d8cda](https://github.com/morluto/rea/commit/f0d8cdafa86bafdc6ad5d8c2d23a97ef583b53d5))
|
||||
* **verify:** follow dynamic Hopper tool availability ([281e41f](https://github.com/morluto/rea/commit/281e41f7660066addcc7a204128fb1f49bf7a674))
|
||||
|
||||
|
||||
### Code Refactoring
|
||||
|
||||
* preserve provider-neutral runtime seams ([a8161f0](https://github.com/morluto/rea/commit/a8161f0e5540f3261a08015dfe56a4254980c064))
|
||||
|
||||
|
||||
### Documentation
|
||||
|
||||
* document resource snapshot workflow ([2a45d8d](https://github.com/morluto/rea/commit/2a45d8de7d52d0a234672d03c7dae794859f8ced))
|
||||
* refresh generated SDK metadata ([c824db1](https://github.com/morluto/rea/commit/c824db1ab7aed2886e9050c1b7fe2136b77e3698))
|
||||
* refresh managed completion manifest ([59d4659](https://github.com/morluto/rea/commit/59d465971ea86f933e9037fa32ac2787d935d076))
|
||||
|
||||
|
||||
### Tests
|
||||
|
||||
* **contracts:** cover validation branches ([8ccdb33](https://github.com/morluto/rea/commit/8ccdb33dd25922e039140bcd1e3cbf3d5acee837))
|
||||
* derive MCP SDK identity expectations ([ab4193c](https://github.com/morluto/rea/commit/ab4193c1f48020ff6baa42cb75e033110ee72b36))
|
||||
* **eval:** cover navigation and address tool routing ([ba098f2](https://github.com/morluto/rea/commit/ba098f24e59efbd567ae8438f65e31af0f0b8050))
|
||||
* overhaul deterministic suite architecture ([48053d1](https://github.com/morluto/rea/commit/48053d1032324cce6e2fe782ecba43d1b91a1bba))
|
||||
* overhaul deterministic suite architecture ([513d9b1](https://github.com/morluto/rea/commit/513d9b15558f9174a8e2c0ab00e31cbc05dbaba7))
|
||||
* **package:** verify npx upgrade on published releases ([7b6f7be](https://github.com/morluto/rea/commit/7b6f7becd257170cebf80f4f9f9c385b0000f074))
|
||||
* **package:** verify npx upgrade on published releases ([1f8ad7b](https://github.com/morluto/rea/commit/1f8ad7bc68f50d396715116467f19524da7e05e6))
|
||||
|
||||
|
||||
### Continuous Integration
|
||||
|
||||
* document deterministic suite ownership ([3c42403](https://github.com/morluto/rea/commit/3c42403b78b53e7b5358c2bca9bc156ef2c32efd))
|
||||
|
||||
## [2.7.0](https://github.com/morluto/rea/compare/rea-agents-2.6.0...rea-agents-2.7.0) (2026-07-28)
|
||||
|
||||
|
||||
### Features
|
||||
|
||||
* **bytecode:** add JVM and Python bytecode providers ([1a75f8d](https://github.com/morluto/rea/commit/1a75f8dc236d8269a5fa07e042471ac79e79d728))
|
||||
* **bytecode:** add JVM and Python bytecode providers ([4e0127d](https://github.com/morluto/rea/commit/4e0127d620377e5dc7e09444f9db0977e3d47ed1)), closes [#367](https://github.com/morluto/rea/issues/367)
|
||||
* **conformance:** add portable conformance export package format ([91fb87d](https://github.com/morluto/rea/commit/91fb87d17e7885439762667c96167af79a2e044e))
|
||||
* **conformance:** add portable conformance export package format ([4ee30e4](https://github.com/morluto/rea/commit/4ee30e4145db9b496158cd980af05e22010856a7))
|
||||
* **metadata:** add deeper ObjC/Swift metadata and database save/licensing ([4602efd](https://github.com/morluto/rea/commit/4602efd27cbf8701c2dc15542042bc9d9ef76e7f))
|
||||
* **metadata:** add deeper ObjC/Swift metadata and database save/licensing ([d7a0753](https://github.com/morluto/rea/commit/d7a07535b0fb61ee8f9ae648bb673dda23290653)), closes [#353](https://github.com/morluto/rea/issues/353)
|
||||
* **mobile:** add Android APK/AAB/DEX and iOS IPA static investigation providers ([18624df](https://github.com/morluto/rea/commit/18624df5724a2c4d14a4e8e178660456424b2344))
|
||||
* **mobile:** add Android APK/AAB/DEX and iOS IPA static investigation providers ([fdeeb27](https://github.com/morluto/rea/commit/fdeeb27f23041c19b5857fe7873106f0cd9c6244)), closes [#366](https://github.com/morluto/rea/issues/366)
|
||||
* **package:** add MSIX/MSI/AppX package, resource, and signature analysis ([0ef1b91](https://github.com/morluto/rea/commit/0ef1b91cf31f6ca53991ee5ca60b4a22f430c01e))
|
||||
* **package:** add MSIX/MSI/AppX package, resource, and signature analysis ([6c03f83](https://github.com/morluto/rea/commit/6c03f83b1bd55095d136aeb3700733383365ecc4)), closes [#363](https://github.com/morluto/rea/issues/363)
|
||||
* **pe:** add broader PE/COFF/PDB static inspection ([f942558](https://github.com/morluto/rea/commit/f9425585736a89165390178f245b0f0f5d6cdacf))
|
||||
* **pe:** add broader PE/COFF/PDB static inspection ([94e6600](https://github.com/morluto/rea/commit/94e6600faf89436e4e2689fda8050792307b268d)), closes [#362](https://github.com/morluto/rea/issues/362)
|
||||
* **process:** replace procfs sampling with event-backed process-tree capture ([a5e355a](https://github.com/morluto/rea/commit/a5e355a3d52b19e89535449cd923c35e56ccc60d))
|
||||
* **process:** replace procfs sampling with event-backed process-tree capture ([d5d2e56](https://github.com/morluto/rea/commit/d5d2e56d0461cb0debba540bc658a9938ac30599)), closes [#332](https://github.com/morluto/rea/issues/332)
|
||||
* **protocol:** add custom TCP/UDP/IPC/XPC and auth-flow capture ([1fb22b4](https://github.com/morluto/rea/commit/1fb22b4c21e3a5581f3928003cc32ddc1cc9530b))
|
||||
* **protocol:** add custom TCP/UDP/IPC/XPC and auth-flow capture ([6fa6f9b](https://github.com/morluto/rea/commit/6fa6f9b6d9595a480a590766dadcfebb8e7111b5)), closes [#365](https://github.com/morluto/rea/issues/365)
|
||||
* **protocol:** add gRPC/Protobuf and JSON-RPC/MessagePack capture ([54153ed](https://github.com/morluto/rea/commit/54153ed62cb4f55d1efd4794490c2481ab34e212))
|
||||
* **protocol:** add gRPC/Protobuf and JSON-RPC/MessagePack capture ([3f336fe](https://github.com/morluto/rea/commit/3f336fefb132971bc6bb37b2b59aa01a5e3be5ca)), closes [#364](https://github.com/morluto/rea/issues/364)
|
||||
|
||||
|
||||
### Bug Fixes
|
||||
|
||||
* **catalog:** digest provider projections ([645668b](https://github.com/morluto/rea/commit/645668b70dfdff74582d4ac26cda417947231764))
|
||||
* **catalog:** digest provider projections ([c4cd033](https://github.com/morluto/rea/commit/c4cd0330e00eeb8e272abbf6ecc6ce961e72f317))
|
||||
|
||||
## [2.6.0](https://github.com/morluto/rea/compare/rea-agents-2.5.1...rea-agents-2.6.0) (2026-07-26)
|
||||
|
||||
|
||||
### Features
|
||||
|
||||
* complete evidence-backed roadmap workflows ([1a0931b](https://github.com/morluto/rea/commit/1a0931b630587701d495d1634fbafe3638ad5516))
|
||||
* **hopper:** report bridge progress diagnostics ([7a43420](https://github.com/morluto/rea/commit/7a434200297df85c62c02bb103cf870d14f202f7))
|
||||
* **native:** inspect API boundaries with evidence ([521139d](https://github.com/morluto/rea/commit/521139d4a57a8ab2e25bb262d2a1fd09fd06be92))
|
||||
|
||||
|
||||
### Bug Fixes
|
||||
|
||||
* **setup:** refresh stale local npx bootstrap ([6d37efe](https://github.com/morluto/rea/commit/6d37efe8fa1fb9b09c8eaa3a1ed6b6f63188ae22))
|
||||
* **setup:** refresh stale local npx bootstrap ([90bb161](https://github.com/morluto/rea/commit/90bb1610f56448846adf85b31d9ae96be12dfb4a))
|
||||
|
||||
|
||||
### Performance Improvements
|
||||
|
||||
* **mcp:** reduce cold-start work ([8ec9bb1](https://github.com/morluto/rea/commit/8ec9bb1bfea8bc57441bec72f3fcfbe93cf5d4f4))
|
||||
* **mcp:** reduce cold-start work ([fecddc0](https://github.com/morluto/rea/commit/fecddc0549a31e99a5ea72cbda84e448b1a961d5))
|
||||
|
||||
|
||||
### Tests
|
||||
|
||||
* add critical provider workflow coverage ([4716fa2](https://github.com/morluto/rea/commit/4716fa2ece954f5e53bdda9d1f33afad57d2e151))
|
||||
* **hopper:** remove brittle diagnostic source assertion ([40bf55b](https://github.com/morluto/rea/commit/40bf55b74ca6b2c90b3243a29018cb75879ba081))
|
||||
* **investigation:** prove multi-version fixture closure ([5184816](https://github.com/morluto/rea/commit/5184816199895ceff6a489810e12fba0c2c41eb7))
|
||||
* **mcp:** stabilize lazy-loading verification ([7157ab0](https://github.com/morluto/rea/commit/7157ab0b70833cc8237271e8625ccb7965c318c3))
|
||||
* **package:** prove artifact cleanup and identity ([9522adf](https://github.com/morluto/rea/commit/9522adf19ac915247e2c74b18d3ef5cab95befc5))
|
||||
|
||||
## [2.5.1](https://github.com/morluto/rea/compare/rea-agents-2.5.0...rea-agents-2.5.1) (2026-07-25)
|
||||
|
||||
|
||||
|
||||
+7
-9
@@ -38,15 +38,13 @@ provider and replay execution remains uncached, but their deterministic build
|
||||
prerequisite uses Turbo. CI uploads the rendered TypeDoc site as an `api-docs`
|
||||
artifact; the generated HTML is not committed.
|
||||
|
||||
Local `npm test` runs without coverage, retries, or verbose output. Use `npm run
|
||||
test:fast` for pure and subprocess groups, `npm run test:integration` for serial
|
||||
filesystem/process/CLI cases. `npm run test:changed` runs changed and related
|
||||
non-serial tests once; `npm run test:watch` keeps that selection live. Pure tests
|
||||
use Vitest threads, while subprocess tests stay in isolated forks. CI splits the
|
||||
complete suite across two native Vitest
|
||||
shards, then merges their coverage and JUnit reports. `npm run test:ci` runs the
|
||||
equivalent unsharded gate locally. Coverage thresholds remain in
|
||||
`vitest.config.ts`.
|
||||
Local `npm test` runs every deterministic Vitest project without coverage,
|
||||
retries, or verbose output. Focused boundary, acceptance, changed-test, and
|
||||
watch commands are documented in [docs/testing.md](docs/testing.md), together
|
||||
with the path-based behavioral-depth rules. Changed-test selection follows the
|
||||
import graph and is feedback, not the release gate. CI splits the complete suite
|
||||
across four native Vitest shards, then merges coverage, JUnit, and JSON timing
|
||||
reports. Coverage thresholds remain in `vitest.config.ts`.
|
||||
|
||||
CI installs dependencies once for all static checks, cancels superseded PR
|
||||
runs, and skips package, Windows, and full test lanes for documentation-only
|
||||
|
||||
@@ -103,6 +103,13 @@ detected agents, then asks which capabilities to set up: agent integration
|
||||
Nothing is preselected. Choosing agent integration opens a second empty
|
||||
checklist for the specific detected agents that should receive a registration.
|
||||
|
||||
If bare `npx` finds a project-local REA package, its dispatcher restarts setup
|
||||
through `rea-agents@latest` before planning any changes. This prevents an older
|
||||
local dependency from silently writing stale integration state. An already
|
||||
published older release cannot contain that dispatcher protection; run
|
||||
`npx -y rea-agents@latest setup` once to repair registrations created by one.
|
||||
Intentional rollbacks remain available through an exact package request.
|
||||
|
||||
REA keeps the journey inline so its history remains in the terminal. Selecting
|
||||
a capability does not select every detected target or authorize a change.
|
||||
Before anything changes, REA validates existing configuration, prints exact
|
||||
@@ -374,7 +381,7 @@ REA handles the app analysis in steps 1–5. The agent performs step 6 with its
|
||||
| Tool family | Count | Examples |
|
||||
| ------------------------- | ----: | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| Native inspection | 36 | procedures, pseudocode, assembly, strings, names, segments, callers, callees, xrefs, annotations, bounded byte reads, file-offset translation |
|
||||
| Investigation workflows | 12 | `binary_overview`, `analyze_function`, `batch_decompile`, `trace_feature`, exact string-to-code lookup, bounded call paths, call graphs, Swift and Objective-C discovery |
|
||||
| Investigation workflows | 13 | `binary_overview`, `analyze_function`, `inspect_native_api`, `batch_decompile`, `trace_feature`, exact string-to-code lookup, bounded call paths, call graphs, Swift and Objective-C discovery |
|
||||
| Native macOS utilities | 5 | Mach-O metadata, code signatures, plists, architectures, Swift demangling; Hopper-free and provenance-bearing |
|
||||
| Artifact graph | 3 | bounded provider-neutral inspection, deterministic directory/ZIP/APK/IPA/MSIX/AppX/ASAR inventory, and explicitly selected extraction into an absent owned tree |
|
||||
| Managed PE/CLI | 8 | PE/CLI identity, metadata members, CIL hashes, P/Invoke/native-boundary declarations and verification, application-graph projection, decompiler reconstruction import, token remapping, runtime-correlation plans, and version comparison |
|
||||
@@ -382,7 +389,7 @@ REA handles the app analysis in steps 1–5. The agent performs step 6 with its
|
||||
| Electron analysis | 4 | passive root-confined observation, bounded static application mapping, and evidence-backed static/runtime reconciliation |
|
||||
| JavaScript runtime | 2 | approved attach-only Node/Electron Inspector target discovery plus bounded script and execution-context observation without evaluation or instrumentation |
|
||||
| Application workflows | 12 | bounded cross-layer traces, unique-only version matching, historical-source to bundle mapping, static export return-shape comparison, approved Linux-isolated extracted-module replay, managed-runtime characterization, reconstruction coverage closure, deterministic obligation ledgers, and end-to-end readiness conformance |
|
||||
| Workspace and observation | 19 | target lifecycle, Evidence v2 bundles, direct finite replay-machine evaluation, process/artifact/function comparison, evidence-linked residual-unknown lifecycle |
|
||||
| Workspace and observation | 22 | target lifecycle, Evidence v2 bundle snapshots, aggregate navigation/address context, direct finite replay-machine evaluation, process/artifact/function comparison, evidence-linked residual-unknown lifecycle |
|
||||
|
||||
The public interface describes what the agent is trying to learn. Providers decide how to answer. macOS utilities handle common semantic inspection without launching Hopper; Hopper handles deeper native analysis; the process harness implements controlled behavioral capture.
|
||||
|
||||
@@ -530,7 +537,7 @@ Setup detects Claude Code, Claude Desktop, Codex, Cursor, Gemini CLI, Windsurf,
|
||||
"mcpServers": {
|
||||
"rea": {
|
||||
"command": "npx",
|
||||
"args": ["-y", "rea-agents@2.5.1", "mcp"]
|
||||
"args": ["-y", "rea-agents@3.0.0", "mcp"]
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -787,7 +794,10 @@ Any agent that can run a local MCP server can use the manual configuration. Setu
|
||||
|
||||
## Development
|
||||
|
||||
See [CONTRIBUTING.md](CONTRIBUTING.md) for setup, architecture, tests, and release instructions. PR CI publishes generated API documentation as the `api-docs` workflow artifact.
|
||||
See [CONTRIBUTING.md](CONTRIBUTING.md) for setup, architecture, and release
|
||||
instructions, and [docs/testing.md](docs/testing.md) for the behavioral test
|
||||
depths, focused developer commands, coverage floors, and CI evidence. PR CI
|
||||
publishes generated API documentation as the `api-docs` workflow artifact.
|
||||
|
||||
`npm run verify:agent` runs brandless native, JavaScript-application, managed,
|
||||
and browser prompts through a real local Codex CLI. Its JSON report measures
|
||||
|
||||
+3
-3
@@ -162,7 +162,7 @@ rea uninstall --purge-data
|
||||
| عائلة الأدوات | العدد | أمثلة |
|
||||
| --------------------- | ----: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| فحص الملفات التنفيذية | 36 | الدوال، والشيفرة شبه المصدرية، والتعليمات، والسلاسل، والأسماء، والمراجع، والتعليقات |
|
||||
| التحليل المركب | 12 | النظرة العامة، وفك الترجمة الدفعي، ومخططات الاستدعاء، والمراجع، واكتشاف الأنواع |
|
||||
| التحليل المركب | 13 | النظرة العامة، و`inspect_native_api`، وفك الترجمة الدفعي، ومخططات الاستدعاء، والمراجع، واكتشاف الأنواع |
|
||||
| أدوات macOS الأصلية | 5 | بيانات Mach-O والتوقيعات وملفات plist والمعماريات وفك رموز Swift دون تشغيل Hopper |
|
||||
| رسم القطع الأثرية | 3 | جرد حتمي للدلائل وZIP/APK/IPA وASAR واستخراج معاملاتي محدد صراحة |
|
||||
| Managed PE/CLI | 8 | هوية PE/CLI، أعضاء البيانات الوصفية، بصمات CIL، تصريحات P/Invoke/الحدود الأصلية والتحقق منها، إسقاط رسم التطبيق، استيراد إعادة البناء من فك الترجمة، إعادة ربط الرموز، خطط ترابط وقت التشغيل ومقارنة الإصدارات |
|
||||
@@ -170,7 +170,7 @@ rea uninstall --purge-data
|
||||
| تحليل Electron | 4 | مراقبة سلبية ضمن جذور canonical، ورسم ثابت ومحدود للتطبيق، ومطابقة ثابتة/وقت تشغيل قائمة على Evidence |
|
||||
| وقت تشغيل JavaScript | 2 | اكتشاف أهداف Node/Electron Inspector المعتمدة للاتصال فقط، ومراقبة محدودة للبرامج النصية وسياقات التنفيذ دون تقييم أو تجهيز |
|
||||
| سير عمل التطبيقات | 12 | تتبع محدود ومقارنة إصدارات فريدة ومقارنة ثابتة لأشكال قيم إرجاع الصادرات وإعادة تشغيل وحدات معزولة ومعتمدة على Linux وتوصيف وقت التشغيل المُدار وإغلاق تغطية إعادة البناء ودفاتر التزامات حتمية والتحقق الشامل من جاهزية إعادة البناء |
|
||||
| جلسة الملف التنفيذي | 19 | فتح الأهداف وحزم الأدلة وتشغيل آلة إعادة محدودة ومقارنة العمليات والقطع والدوال وسجل المجهولات المتبقية |
|
||||
| جلسة الملف التنفيذي | 22 | فتح الأهداف وحزم الأدلة وتشغيل آلة إعادة محدودة ومقارنة العمليات والقطع والدوال وسجل المجهولات المتبقية |
|
||||
|
||||
## استخدام REA مع وكلاء برمجة آخرين
|
||||
|
||||
@@ -183,7 +183,7 @@ rea uninstall --purge-data
|
||||
"mcpServers": {
|
||||
"rea": {
|
||||
"command": "npx",
|
||||
"args": ["-y", "rea-agents@2.5.1", "mcp"]
|
||||
"args": ["-y", "rea-agents@3.0.0", "mcp"]
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
+3
-3
@@ -152,7 +152,7 @@ REA は手順 1〜5 のバイナリ解析を処理し、手順 6 はエージェ
|
||||
| ツール群 | 数 | 例 |
|
||||
| ---------------------- | --: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| バイナリ調査 | 36 | プロシージャ、疑似コード、アセンブリ、文字列、名前、セグメント、callers、callees、xrefs、注釈 |
|
||||
| 合成解析 | 12 | `binary_overview`, `analyze_function`, `batch_decompile`, `get_call_graph`, `find_xrefs_to_name`, Swift / ObjC 検出 |
|
||||
| 合成解析 | 13 | `binary_overview`, `analyze_function`, `inspect_native_api`, `batch_decompile`, `get_call_graph`, `find_xrefs_to_name`, Swift / ObjC 検出 |
|
||||
| macOS ネイティブ | 5 | Mach-O メタデータ、署名、plist、アーキテクチャ、Swift デマングル。Hopper 起動不要 |
|
||||
| アーティファクトグラフ | 3 | ディレクトリ、ZIP/APK/IPA、ASAR の決定的一覧と明示選択されたトランザクション抽出 |
|
||||
| Managed PE/CLI | 8 | PE/CLI 識別、メタデータメンバー、CIL ハッシュ、P/Invoke/ネイティブ境界宣言と検証、アプリケーショングラフ投影、逆コンパイル再構成インポート、構造的 token 再マッピング、ランタイム相関計画、バージョン比較 |
|
||||
@@ -160,7 +160,7 @@ REA は手順 1〜5 のバイナリ解析を処理し、手順 6 はエージェ
|
||||
| Electron 解析 | 4 | canonical ファイルルート内の受動観察、有界な静的アプリマッピング、Evidence に基づく静的/実行時の照合 |
|
||||
| JavaScript ランタイム | 2 | 承認済みのアタッチ専用 Node/Electron Inspector ターゲット検出と、評価や計装を行わない有界なスクリプト/実行コンテキスト観察 |
|
||||
| アプリケーション | 12 | 有界なクロスレイヤー追跡、一意限定のバージョン比較、静的なエクスポート戻り値形状比較、承認済み Linux 隔離 extracted-module replay、マネージドランタイム特性評価、再構築カバレッジ閉包、決定論的な義務台帳、エンドツーエンドの準備適合性検証 |
|
||||
| バイナリセッション | 19 | `open_binary`、`binary_session`、証拠バンドル、有限リプレイ状態機械、プロセス/成果物/関数比較、残余未知レジストリ |
|
||||
| バイナリセッション | 22 | `open_binary`、`binary_session`、証拠バンドル、有限リプレイ状態機械、プロセス/成果物/関数比較、残余未知レジストリ |
|
||||
|
||||
## 他のコーディングエージェントで使う
|
||||
|
||||
@@ -173,7 +173,7 @@ Setup は Claude Code、Claude Desktop、Codex、Cursor、Gemini CLI、Windsurf
|
||||
"mcpServers": {
|
||||
"rea": {
|
||||
"command": "npx",
|
||||
"args": ["-y", "rea-agents@2.5.1", "mcp"]
|
||||
"args": ["-y", "rea-agents@3.0.0", "mcp"]
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
+3
-3
@@ -152,7 +152,7 @@ REA는 1–5단계의 바이너리 분석을 처리합니다. 6단계는 에이
|
||||
| 도구 그룹 | 수 | 예시 |
|
||||
| ------------------- | --: | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| 바이너리 검사 | 36 | 프로시저, 의사 코드, 어셈블리, 문자열, 이름, 세그먼트, callers, callees, xrefs, 주석 |
|
||||
| 합성 분석 | 12 | `binary_overview`, `analyze_function`, `batch_decompile`, `get_call_graph`, `find_xrefs_to_name`, Swift 및 ObjC 탐색 |
|
||||
| 합성 분석 | 13 | `binary_overview`, `analyze_function`, `inspect_native_api`, `batch_decompile`, `get_call_graph`, `find_xrefs_to_name`, Swift 및 ObjC 탐색 |
|
||||
| macOS 네이티브 도구 | 5 | Mach-O 메타데이터, 코드 서명, plist, 아키텍처, Swift 디맹글링. Hopper 실행 불필요 |
|
||||
| 아티팩트 그래프 | 3 | 디렉터리, ZIP/APK/IPA, ASAR 결정적 인벤토리와 명시적으로 선택한 트랜잭션 추출 |
|
||||
| Managed PE/CLI | 8 | PE/CLI ID, 메타데이터 멤버, CIL 해시, P/Invoke/네이티브 경계 선언 및 검증, 애플리케이션 그래프 투영, 디컴파일 재구성 가져오기, 구조적 token 재매핑, 런타임 상관 계획, 버전 비교 |
|
||||
@@ -160,7 +160,7 @@ REA는 1–5단계의 바이너리 분석을 처리합니다. 6단계는 에이
|
||||
| Electron 분석 | 4 | canonical 파일 루트 내 수동 관찰, 제한된 정적 앱 매핑, Evidence 기반 정적/런타임 조정 |
|
||||
| JavaScript 런타임 | 2 | 승인된 연결 전용 Node/Electron Inspector 대상 탐색과 평가·계측 없는 제한된 스크립트 및 실행 컨텍스트 관찰 |
|
||||
| 애플리케이션 | 12 | 제한된 교차 계층 추적, 고유 일치 버전 비교, 정적 export 반환 형태 비교, 승인된 Linux 격리 extracted-module replay, 관리형 런타임 특성화, 재구성 커버리지 폐쇄, 결정론적 의무 원장, 엔드투엔드 준비 적합성 검증 |
|
||||
| 바이너리 세션 | 19 | `open_binary`, `binary_session`, 증거 번들, 유한 replay 상태 머신, 프로세스·아티팩트·함수 비교, 잔여 미지수 레지스트리 |
|
||||
| 바이너리 세션 | 22 | `open_binary`, `binary_session`, 증거 번들, 유한 replay 상태 머신, 프로세스·아티팩트·함수 비교, 잔여 미지수 레지스트리 |
|
||||
|
||||
## 다른 코딩 에이전트에서 사용하기
|
||||
|
||||
@@ -173,7 +173,7 @@ Setup은 Claude Code, Claude Desktop, Codex, Cursor, Gemini CLI, Windsurf, Devin
|
||||
"mcpServers": {
|
||||
"rea": {
|
||||
"command": "npx",
|
||||
"args": ["-y", "rea-agents@2.5.1", "mcp"]
|
||||
"args": ["-y", "rea-agents@3.0.0", "mcp"]
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
+3
-3
@@ -152,7 +152,7 @@ REA 负责第 1–5 步中的二进制分析。第 6 步由智能体使用其常
|
||||
| 工具类别 | 数量 | 示例 |
|
||||
| ----------------- | ---: | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| 二进制检查 | 36 | 过程、伪代码、汇编、字符串、名称、段、调用者、被调用者、交叉引用、注释 |
|
||||
| 组合分析 | 12 | `binary_overview`, `analyze_function`, `batch_decompile`, `get_call_graph`, `find_xrefs_to_name`、Swift 与 ObjC 发现 |
|
||||
| 组合分析 | 13 | `binary_overview`, `analyze_function`, `inspect_native_api`, `batch_decompile`, `get_call_graph`, `find_xrefs_to_name`、Swift 与 ObjC 发现 |
|
||||
| macOS 原生工具 | 5 | Mach-O 元数据、代码签名、plist、架构与 Swift 符号还原,无需启动 Hopper |
|
||||
| 制品图谱 | 3 | 确定性目录、ZIP/APK/IPA 与 ASAR 清单,以及显式选择的事务式提取 |
|
||||
| Managed PE/CLI | 8 | PE/CLI 身份、元数据成员、CIL 哈希、P/Invoke/原生边界声明与验证、应用图谱投影、反编译重建导入、结构化 token 重映射、运行时关联计划与跨版本比较 |
|
||||
@@ -160,7 +160,7 @@ REA 负责第 1–5 步中的二进制分析。第 6 步由智能体使用其常
|
||||
| Electron 分析 | 4 | 限定 canonical 文件根的被动观察、有界静态应用映射,以及基于 Evidence 的静态/运行时对账 |
|
||||
| JavaScript 运行时 | 2 | 经批准的只附加 Node/Electron Inspector 目标发现,以及不执行求值或插桩的有界脚本和执行上下文观察 |
|
||||
| 应用工作流 | 12 | 有界跨层追踪、唯一匹配跨版本图比较、静态导出返回形状比较、经批准的 Linux 隔离 extracted-module replay、托管运行时表征、重建覆盖闭合、确定性义务账本和端到端就绪性一致性验证 |
|
||||
| 二进制会话 | 19 | `open_binary`、`binary_session`、证据包、有限重放状态机、进程、制品与函数比较、残余未知项注册表 |
|
||||
| 二进制会话 | 22 | `open_binary`、`binary_session`、证据包、有限重放状态机、进程、制品与函数比较、残余未知项注册表 |
|
||||
|
||||
## 与其他编程智能体一起使用
|
||||
|
||||
@@ -173,7 +173,7 @@ Setup 会检测 Claude Code、Claude Desktop、Codex、Cursor、Gemini CLI、Win
|
||||
"mcpServers": {
|
||||
"rea": {
|
||||
"command": "npx",
|
||||
"args": ["-y", "rea-agents@2.5.1", "mcp"]
|
||||
"args": ["-y", "rea-agents@3.0.0", "mcp"]
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
@@ -55,6 +55,7 @@ import ghidra.program.model.block.CodeBlockIterator;
|
||||
import ghidra.program.model.block.CodeBlockReference;
|
||||
import ghidra.program.model.block.CodeBlockReferenceIterator;
|
||||
import ghidra.program.model.data.StringDataInstance;
|
||||
import ghidra.program.model.data.DataType;
|
||||
import ghidra.program.model.listing.CommentType;
|
||||
import ghidra.program.model.listing.Data;
|
||||
import ghidra.program.model.listing.DataIterator;
|
||||
@@ -70,15 +71,25 @@ import ghidra.program.model.symbol.ReferenceIterator;
|
||||
import ghidra.program.model.symbol.SourceType;
|
||||
import ghidra.program.model.symbol.Symbol;
|
||||
import ghidra.program.model.symbol.SymbolIterator;
|
||||
import ghidra.program.model.pcode.FunctionPrototype;
|
||||
import ghidra.program.model.pcode.HighFunction;
|
||||
import ghidra.program.model.pcode.HighSymbol;
|
||||
import ghidra.program.model.pcode.JumpTable;
|
||||
|
||||
public final class ReaGhidraBridge extends HeadlessScript {
|
||||
private static final int BRIDGE_VERSION = 5;
|
||||
private static final int BRIDGE_VERSION = 6;
|
||||
private static final int MAX_DESCRIPTOR_BYTES = 16 * 1024;
|
||||
private static final int MAX_REQUEST_CHARACTERS = 256 * 1024;
|
||||
private static final int MAX_RESPONSE_BYTES = 1024 * 1024;
|
||||
private static final int RESPONSE_ENVELOPE_RESERVE_BYTES = 32 * 1024;
|
||||
private static final int MAX_NATIVE_API_RESPONSE_BYTES = 192 * 1024;
|
||||
private static final int MAX_INVENTORY_ITEMS = 1_000_000;
|
||||
private static final int MAX_FUNCTION_ITEMS = 100_000;
|
||||
private static final int MAX_FUNCTION_INSTRUCTIONS = 100_000;
|
||||
private static final int MAX_NATIVE_API_PARAMETERS = 64;
|
||||
private static final int MAX_NATIVE_API_JUMP_TABLES = 4;
|
||||
private static final int MAX_NATIVE_API_LOAD_TABLES = 4;
|
||||
private static final int MAX_NATIVE_API_MAPPINGS = 32;
|
||||
private static final int DECOMPILE_TIMEOUT_SECONDS = 30;
|
||||
private static final int DECOMPILE_PAYLOAD_MBYTES = 8;
|
||||
private static final int MAX_LIST_VALUE_CODE_POINTS = 1_024;
|
||||
@@ -377,7 +388,9 @@ public final class ReaGhidraBridge extends HeadlessScript {
|
||||
private JsonElement procedurePseudocode(JsonObject params) throws Exception {
|
||||
requireKeys(params, Set.of("document", "procedure"));
|
||||
requireDocument(params);
|
||||
String value = decompile(resolveProcedure(requireString(params, "procedure")));
|
||||
String value = decompiledText(
|
||||
decompile(resolveProcedure(requireString(params, "procedure")))
|
||||
);
|
||||
return value == null ? JsonNull.INSTANCE : GSON.toJsonTree(value);
|
||||
}
|
||||
|
||||
@@ -576,7 +589,8 @@ public final class ReaGhidraBridge extends HeadlessScript {
|
||||
);
|
||||
JsonObject offsets = requireCollectionOffsets(params);
|
||||
InstructionScan scan = scanInstructions(function, maximumInstructions);
|
||||
String pseudocode = decompile(function);
|
||||
DecompileResults decompilation = decompile(function);
|
||||
String pseudocode = decompiledText(decompilation);
|
||||
if (pseudocode == null) {
|
||||
pseudocode = "";
|
||||
}
|
||||
@@ -662,6 +676,19 @@ public final class ReaGhidraBridge extends HeadlessScript {
|
||||
instructionScan.addProperty("scanned", scan.instructions.size());
|
||||
instructionScan.addProperty("truncated", scan.truncated);
|
||||
result.add("instruction_scan", instructionScan);
|
||||
int nativeApiBudget = Math.min(
|
||||
MAX_NATIVE_API_RESPONSE_BYTES,
|
||||
Math.max(
|
||||
0,
|
||||
MAX_RESPONSE_BYTES -
|
||||
encodedUtf8Length(result) -
|
||||
RESPONSE_ENVELOPE_RESERVE_BYTES
|
||||
)
|
||||
);
|
||||
result.add(
|
||||
"native_api",
|
||||
nativeApiBoundary(function, decompilation, nativeApiBudget)
|
||||
);
|
||||
JsonArray limitations = new JsonArray();
|
||||
limitations.add(
|
||||
"Unresolved computed or indirect flows without target addresses are not represented as reference edges."
|
||||
@@ -971,7 +998,446 @@ public final class ReaGhidraBridge extends HeadlessScript {
|
||||
return matches.get(0);
|
||||
}
|
||||
|
||||
private String decompile(Function function) {
|
||||
private JsonObject nativeApiBoundary(
|
||||
Function function,
|
||||
DecompileResults decompilation,
|
||||
int maximumBytes
|
||||
) throws Exception {
|
||||
if (decompilation == null || decompilation.getHighFunction() == null) {
|
||||
return unavailableNativeApiBoundary(
|
||||
"Ghidra has no HighFunction model for an external or bodyless procedure"
|
||||
);
|
||||
}
|
||||
|
||||
HighFunction highFunction = decompilation.getHighFunction();
|
||||
FunctionPrototype prototype = highFunction.getFunctionPrototype();
|
||||
String signatureSource = function
|
||||
.getSignatureSource()
|
||||
.name()
|
||||
.toLowerCase(Locale.ROOT);
|
||||
JsonObject result = new JsonObject();
|
||||
result.addProperty("available", true);
|
||||
result.addProperty("provenance", "ghidra-high-function");
|
||||
result.addProperty("signature_source", signatureSource);
|
||||
String callingConvention = prototype.getModelName();
|
||||
result.addProperty(
|
||||
"calling_convention",
|
||||
callingConvention == null || callingConvention.isBlank()
|
||||
? "unknown"
|
||||
: callingConvention
|
||||
);
|
||||
result.add(
|
||||
"return_type",
|
||||
inferredBoundaryType(
|
||||
"return",
|
||||
null,
|
||||
null,
|
||||
prototype.getReturnType(),
|
||||
prototype.getReturnStorage().toString(),
|
||||
false,
|
||||
signatureSource
|
||||
)
|
||||
);
|
||||
|
||||
JsonArray parameters = new JsonArray();
|
||||
result.add("parameters", parameters);
|
||||
result.addProperty("parameters_truncated", false);
|
||||
|
||||
JsonArray jumpTables = new JsonArray();
|
||||
result.add("jump_tables", jumpTables);
|
||||
result.addProperty("jump_tables_truncated", false);
|
||||
|
||||
JsonObject pseudocode = new JsonObject();
|
||||
pseudocode.addProperty("classification", "decompiler-generated-non-source");
|
||||
pseudocode.addProperty("compilable", false);
|
||||
result.add("pseudocode", pseudocode);
|
||||
|
||||
JsonArray artifacts = new JsonArray();
|
||||
artifacts.add("recovered-signature");
|
||||
artifacts.add("register-and-stack-variables");
|
||||
artifacts.add("compiler-generated-control-flow");
|
||||
artifacts.add("pointer-arithmetic");
|
||||
artifacts.add("pseudocode");
|
||||
result.add("decompiler_artifacts", artifacts);
|
||||
|
||||
JsonArray limitations = new JsonArray();
|
||||
limitations.add(
|
||||
"Types and calling conventions are Ghidra decompiler observations, not source declarations."
|
||||
);
|
||||
limitations.add(
|
||||
"Register variables, compiler-generated blocks, and pointer arithmetic remain decompiler artifacts."
|
||||
);
|
||||
limitations.add(
|
||||
"Pseudocode is neither original source nor guaranteed to compile."
|
||||
);
|
||||
result.add("limitations", limitations);
|
||||
if (encodedUtf8Length(result) > maximumBytes) {
|
||||
return unavailableNativeApiBoundary(
|
||||
"The remaining Ghidra response budget cannot contain a structured native API boundary"
|
||||
);
|
||||
}
|
||||
|
||||
int parameterCount = Math.min(
|
||||
prototype.getNumParams(),
|
||||
MAX_NATIVE_API_PARAMETERS
|
||||
);
|
||||
for (int index = 0; index < parameterCount; index += 1) {
|
||||
HighSymbol parameter = prototype.getParam(index);
|
||||
if (parameter == null) {
|
||||
continue;
|
||||
}
|
||||
parameters.add(
|
||||
inferredBoundaryType(
|
||||
"parameter",
|
||||
index,
|
||||
parameter.getName(),
|
||||
parameter.getDataType(),
|
||||
parameter.getStorage().toString(),
|
||||
parameter.isTypeLocked(),
|
||||
signatureSource
|
||||
)
|
||||
);
|
||||
if (encodedUtf8Length(result) > maximumBytes) {
|
||||
parameters.remove(parameters.size() - 1);
|
||||
break;
|
||||
}
|
||||
}
|
||||
result.addProperty(
|
||||
"parameters_truncated",
|
||||
prototype.getNumParams() > parameters.size()
|
||||
);
|
||||
|
||||
JumpTable[] recoveredJumpTables = highFunction.getJumpTables();
|
||||
int jumpTableCount = Math.min(
|
||||
recoveredJumpTables.length,
|
||||
MAX_NATIVE_API_JUMP_TABLES
|
||||
);
|
||||
for (int index = 0; index < jumpTableCount; index += 1) {
|
||||
jumpTables.add(inferredJumpTable(recoveredJumpTables[index]));
|
||||
if (encodedUtf8Length(result) > maximumBytes) {
|
||||
jumpTables.remove(jumpTables.size() - 1);
|
||||
break;
|
||||
}
|
||||
}
|
||||
result.addProperty(
|
||||
"jump_tables_truncated",
|
||||
recoveredJumpTables.length > jumpTables.size()
|
||||
);
|
||||
return result;
|
||||
}
|
||||
|
||||
private static JsonObject unavailableNativeApiBoundary(String reason) {
|
||||
JsonObject unavailable = new JsonObject();
|
||||
unavailable.addProperty("available", false);
|
||||
unavailable.addProperty("reason", reason);
|
||||
JsonArray unknowns = new JsonArray();
|
||||
unknowns.add("Return and parameter boundary types are unavailable.");
|
||||
unknowns.add("Jump-table mappings are unavailable.");
|
||||
unavailable.add("residual_unknowns", unknowns);
|
||||
return unavailable;
|
||||
}
|
||||
|
||||
private static int encodedUtf8Length(JsonElement value) {
|
||||
return GSON.toJson(value).getBytes(StandardCharsets.UTF_8).length;
|
||||
}
|
||||
|
||||
private static JsonObject inferredBoundaryType(
|
||||
String role,
|
||||
Integer ordinal,
|
||||
String name,
|
||||
DataType dataType,
|
||||
String storage,
|
||||
boolean typeLocked,
|
||||
String signatureSource
|
||||
) {
|
||||
JsonObject result = new JsonObject();
|
||||
result.addProperty("role", role);
|
||||
if (ordinal == null) {
|
||||
result.add("ordinal", JsonNull.INSTANCE);
|
||||
}
|
||||
else {
|
||||
result.addProperty("ordinal", ordinal);
|
||||
}
|
||||
if (name == null || name.isBlank()) {
|
||||
result.add("name", JsonNull.INSTANCE);
|
||||
}
|
||||
else {
|
||||
result.addProperty("name", name);
|
||||
}
|
||||
result.addProperty("data_type", dataType.getDisplayName());
|
||||
int dataTypeLength = dataType.getLength();
|
||||
if (dataTypeLength < 0) {
|
||||
result.add("size_bytes", JsonNull.INSTANCE);
|
||||
}
|
||||
else {
|
||||
result.addProperty("size_bytes", dataTypeLength);
|
||||
}
|
||||
if (storage.isBlank()) {
|
||||
result.add("storage", JsonNull.INSTANCE);
|
||||
}
|
||||
else {
|
||||
result.addProperty("storage", storage);
|
||||
}
|
||||
result.addProperty(
|
||||
"confidence",
|
||||
inferenceConfidence(signatureSource, typeLocked)
|
||||
);
|
||||
|
||||
JsonArray evidence = new JsonArray();
|
||||
evidence.add(
|
||||
inferenceEvidence(
|
||||
"signature-source",
|
||||
"ghidra-function-manager",
|
||||
"Function signature source is " + signatureSource + "."
|
||||
)
|
||||
);
|
||||
evidence.add(
|
||||
inferenceEvidence(
|
||||
"decompiler-type",
|
||||
"ghidra-high-function",
|
||||
"HighFunction recovered data type " + dataType.getDisplayName() + "."
|
||||
)
|
||||
);
|
||||
if (typeLocked) {
|
||||
evidence.add(
|
||||
inferenceEvidence(
|
||||
"type-lock",
|
||||
"ghidra-high-symbol",
|
||||
"The decompiler marks this parameter type as locked."
|
||||
)
|
||||
);
|
||||
}
|
||||
result.add("evidence", evidence);
|
||||
|
||||
JsonArray artifacts = new JsonArray();
|
||||
artifacts.add("recovered-signature");
|
||||
if (!storage.isBlank()) {
|
||||
artifacts.add("register-or-stack-storage");
|
||||
}
|
||||
if (name != null && (name.startsWith("param_") || name.startsWith("unaff_"))) {
|
||||
artifacts.add("compiler-generated-variable");
|
||||
}
|
||||
result.add("decompiler_artifacts", artifacts);
|
||||
return result;
|
||||
}
|
||||
|
||||
private JsonObject inferredJumpTable(JumpTable jumpTable) throws Exception {
|
||||
JsonObject result = new JsonObject();
|
||||
result.addProperty(
|
||||
"dispatch_address",
|
||||
canonicalAddress(jumpTable.getSwitchAddress())
|
||||
);
|
||||
JumpTable.LoadTable[] loadTables = jumpTable.getLoadTables();
|
||||
List<Address> referencedDataAddresses = loadTables.length == 0
|
||||
? dispatchPathDataReferences(jumpTable)
|
||||
: List.of();
|
||||
JsonArray dataSources = new JsonArray();
|
||||
int loadTableCount = Math.min(
|
||||
loadTables.length,
|
||||
MAX_NATIVE_API_LOAD_TABLES
|
||||
);
|
||||
for (int index = 0; index < loadTableCount; index += 1) {
|
||||
JumpTable.LoadTable loadTable = loadTables[index];
|
||||
JsonObject source = new JsonObject();
|
||||
source.addProperty("address", canonicalAddress(loadTable.getAddress()));
|
||||
source.addProperty("provenance", "ghidra-decompiler-load-table");
|
||||
source.addProperty("entry_size_bytes", loadTable.getSize());
|
||||
source.addProperty("entry_count", loadTable.getNum());
|
||||
source.addProperty("confidence", "high");
|
||||
JsonArray evidence = new JsonArray();
|
||||
evidence.add(
|
||||
inferenceEvidence(
|
||||
"jump-table",
|
||||
"ghidra-high-function",
|
||||
"Decompiler load table starts at " +
|
||||
canonicalAddress(loadTable.getAddress()) +
|
||||
"."
|
||||
)
|
||||
);
|
||||
source.add("evidence", evidence);
|
||||
dataSources.add(source);
|
||||
}
|
||||
int referencedDataCount = Math.min(
|
||||
referencedDataAddresses.size(),
|
||||
MAX_NATIVE_API_LOAD_TABLES - loadTableCount
|
||||
);
|
||||
for (int index = 0; index < referencedDataCount; index += 1) {
|
||||
Address address = referencedDataAddresses.get(index);
|
||||
JsonObject source = new JsonObject();
|
||||
source.addProperty("address", canonicalAddress(address));
|
||||
source.addProperty(
|
||||
"provenance",
|
||||
"ghidra-dispatch-block-data-reference"
|
||||
);
|
||||
source.add("entry_size_bytes", JsonNull.INSTANCE);
|
||||
source.add("entry_count", JsonNull.INSTANCE);
|
||||
source.addProperty("confidence", "medium");
|
||||
JsonArray evidence = new JsonArray();
|
||||
evidence.add(
|
||||
inferenceEvidence(
|
||||
"jump-table",
|
||||
"ghidra-reference-manager",
|
||||
"The dispatch block or an immediate predecessor contains a typed data reference to " +
|
||||
canonicalAddress(address) +
|
||||
"."
|
||||
)
|
||||
);
|
||||
source.add("evidence", evidence);
|
||||
dataSources.add(source);
|
||||
}
|
||||
result.add("data_sources", dataSources);
|
||||
result.addProperty(
|
||||
"data_sources_truncated",
|
||||
loadTables.length > loadTableCount ||
|
||||
referencedDataAddresses.size() > referencedDataCount
|
||||
);
|
||||
|
||||
Address[] targets = jumpTable.getCases();
|
||||
Integer[] labels = jumpTable.getLabelValues();
|
||||
JsonArray mappings = new JsonArray();
|
||||
int mappingCount = Math.min(targets.length, MAX_NATIVE_API_MAPPINGS);
|
||||
for (int index = 0; index < mappingCount; index += 1) {
|
||||
JsonObject mapping = new JsonObject();
|
||||
if (labels == null || index >= labels.length || labels[index] == null) {
|
||||
mapping.add("case_value", JsonNull.INSTANCE);
|
||||
}
|
||||
else {
|
||||
mapping.addProperty("case_value", labels[index]);
|
||||
}
|
||||
String targetAddress = canonicalAddress(targets[index]);
|
||||
mapping.addProperty("target_address", targetAddress);
|
||||
JsonArray dataAddresses = new JsonArray();
|
||||
for (int sourceIndex = 0; sourceIndex < loadTableCount; sourceIndex += 1) {
|
||||
dataAddresses.add(
|
||||
canonicalAddress(loadTables[sourceIndex].getAddress())
|
||||
);
|
||||
}
|
||||
mapping.add("data_addresses", dataAddresses);
|
||||
mapping.addProperty("confidence", "medium");
|
||||
JsonArray evidence = new JsonArray();
|
||||
evidence.add(
|
||||
inferenceEvidence(
|
||||
"jump-table",
|
||||
"ghidra-high-function",
|
||||
"Recovered target " +
|
||||
targetAddress +
|
||||
" from dispatch " +
|
||||
canonicalAddress(jumpTable.getSwitchAddress()) +
|
||||
"."
|
||||
)
|
||||
);
|
||||
mapping.add("evidence", evidence);
|
||||
mappings.add(mapping);
|
||||
}
|
||||
result.add("mappings", mappings);
|
||||
result.addProperty("mappings_truncated", targets.length > mappingCount);
|
||||
|
||||
JsonArray limitations = new JsonArray();
|
||||
if (loadTables.length == 0 && referencedDataAddresses.isEmpty()) {
|
||||
limitations.add(
|
||||
"Ghidra recovered targets but exposed no backing load-table or dispatch-block data address."
|
||||
);
|
||||
}
|
||||
if (loadTables.length == 0 && !referencedDataAddresses.isEmpty()) {
|
||||
limitations.add(
|
||||
"Load-table metadata was absent; table-level candidate ownership is inferred from typed data references in the dispatch block and its immediate control-flow predecessors, but candidates are not assigned to individual mappings."
|
||||
);
|
||||
}
|
||||
if (labels == null || labels.length != targets.length) {
|
||||
limitations.add(
|
||||
"Case labels were unavailable or incomplete; null labels are preserved."
|
||||
);
|
||||
}
|
||||
if (
|
||||
loadTables.length > loadTableCount ||
|
||||
referencedDataAddresses.size() > referencedDataCount ||
|
||||
targets.length > mappingCount
|
||||
) {
|
||||
limitations.add(
|
||||
"Native API jump-table observations reached REA's bounded output limits."
|
||||
);
|
||||
}
|
||||
result.add("limitations", limitations);
|
||||
return result;
|
||||
}
|
||||
|
||||
private List<Address> dispatchPathDataReferences(JumpTable jumpTable)
|
||||
throws Exception {
|
||||
BasicBlockModel model = new BasicBlockModel(currentProgram, false);
|
||||
CodeBlock dispatchBlock = model.getFirstCodeBlockContaining(
|
||||
jumpTable.getSwitchAddress(),
|
||||
monitor
|
||||
);
|
||||
if (dispatchBlock == null) {
|
||||
return List.of();
|
||||
}
|
||||
List<CodeBlock> blocks = new ArrayList<>();
|
||||
blocks.add(dispatchBlock);
|
||||
CodeBlockReferenceIterator sources = dispatchBlock.getSources(monitor);
|
||||
while (sources.hasNext()) {
|
||||
monitor.checkCancelled();
|
||||
CodeBlock sourceBlock = sources.next().getSourceBlock();
|
||||
if (sourceBlock != null) {
|
||||
blocks.add(sourceBlock);
|
||||
}
|
||||
}
|
||||
Set<Address> addresses = new HashSet<>();
|
||||
for (CodeBlock block : blocks) {
|
||||
InstructionIterator instructions = currentProgram
|
||||
.getListing()
|
||||
.getInstructions(block, true);
|
||||
while (instructions.hasNext()) {
|
||||
monitor.checkCancelled();
|
||||
Instruction instruction = instructions.next();
|
||||
for (
|
||||
Reference reference : currentProgram
|
||||
.getReferenceManager()
|
||||
.getReferencesFrom(instruction.getAddress())
|
||||
) {
|
||||
if (
|
||||
reference.getReferenceType().isData() &&
|
||||
currentProgram
|
||||
.getMemory()
|
||||
.getLoadedAndInitializedAddressSet()
|
||||
.contains(reference.getToAddress())
|
||||
) {
|
||||
addresses.add(reference.getToAddress());
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
List<Address> ordered = new ArrayList<>(addresses);
|
||||
ordered.sort(Address::compareTo);
|
||||
return List.copyOf(ordered);
|
||||
}
|
||||
|
||||
private static JsonObject inferenceEvidence(
|
||||
String kind,
|
||||
String source,
|
||||
String detail
|
||||
) {
|
||||
JsonObject evidence = new JsonObject();
|
||||
evidence.addProperty("kind", kind);
|
||||
evidence.addProperty("source", source);
|
||||
evidence.addProperty("detail", detail);
|
||||
return evidence;
|
||||
}
|
||||
|
||||
private static String inferenceConfidence(
|
||||
String signatureSource,
|
||||
boolean typeLocked
|
||||
) {
|
||||
if (
|
||||
typeLocked ||
|
||||
signatureSource.equals("user_defined") ||
|
||||
signatureSource.equals("imported")
|
||||
) {
|
||||
return "high";
|
||||
}
|
||||
return signatureSource.equals("analysis") ? "medium" : "low";
|
||||
}
|
||||
|
||||
private DecompileResults decompile(Function function) {
|
||||
if (function.isExternal() || function.getBody().isEmpty()) {
|
||||
return null;
|
||||
}
|
||||
@@ -995,6 +1461,13 @@ public final class ReaGhidraBridge extends HeadlessScript {
|
||||
"Ghidra decompilation failed: " + boundedMessage(results.getErrorMessage())
|
||||
);
|
||||
}
|
||||
return results;
|
||||
}
|
||||
|
||||
private static String decompiledText(DecompileResults results) {
|
||||
if (results == null) {
|
||||
return null;
|
||||
}
|
||||
DecompiledFunction value = results.getDecompiledFunction();
|
||||
return value == null ? null : value.getC();
|
||||
}
|
||||
|
||||
+54
-4
@@ -1046,29 +1046,65 @@ def _serve_connection(connection):
|
||||
if not line or len(line) > MAX_LINE_BYTES:
|
||||
break
|
||||
request_id = None
|
||||
authenticated = False
|
||||
should_stop = False
|
||||
try:
|
||||
request = json.loads(line.decode("utf-8"))
|
||||
if set(request) != {"id", "token", "method", "params"}:
|
||||
raise ValueError("Invalid bridge request shape")
|
||||
request_id = request["id"]
|
||||
if isinstance(request_id, bool) or not isinstance(request_id, int) or request_id < 0:
|
||||
raise ValueError("Invalid bridge request id")
|
||||
if not isinstance(request["token"], str) or not hmac.compare_digest(request["token"], REA_TOKEN):
|
||||
raise PermissionError("Invalid bridge capability")
|
||||
authenticated = True
|
||||
_write_message(file, {"id": request_id, "event": {
|
||||
"type": "progress",
|
||||
"phase": "hopper_bridge",
|
||||
"completed": 0,
|
||||
"total": 1,
|
||||
"message": "Hopper bridge started request",
|
||||
}})
|
||||
result = _dispatch(request["method"], request["params"])
|
||||
should_stop = request["method"] == "shutdown_document" or (
|
||||
request["method"] == "shutdown" and not result.get("cleanup_required", False)
|
||||
)
|
||||
response = {"id": request_id, "result": _json_safe(result)}
|
||||
safe_result = _json_safe(result)
|
||||
_write_message(file, {"id": request_id, "event": {
|
||||
"type": "progress",
|
||||
"phase": "hopper_bridge",
|
||||
"completed": 1,
|
||||
"total": 1,
|
||||
"message": "Hopper bridge completed request",
|
||||
"terminal": True,
|
||||
}})
|
||||
response = {"id": request_id, "result": safe_result}
|
||||
except Exception as error:
|
||||
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()
|
||||
diagnostic = _safe_diagnostic(error)
|
||||
if authenticated:
|
||||
_write_message(file, {"id": request_id, "event": {
|
||||
"type": "diagnostic",
|
||||
"error": diagnostic,
|
||||
}})
|
||||
response_id = request_id if (
|
||||
isinstance(request_id, int)
|
||||
and not isinstance(request_id, bool)
|
||||
and request_id >= 0
|
||||
) else 0
|
||||
response = {"id": response_id, "error": diagnostic}
|
||||
_write_message(file, response)
|
||||
if should_stop:
|
||||
break
|
||||
file.close()
|
||||
connection.close()
|
||||
|
||||
|
||||
def _write_message(file, message):
|
||||
"""Write and flush one compact bridge message."""
|
||||
file.write((json.dumps(message, separators=(",", ":")) + "\n").encode("utf-8"))
|
||||
file.flush()
|
||||
|
||||
|
||||
def _diagnostic_type(error):
|
||||
if isinstance(error, CapabilityUnavailableError):
|
||||
return "capability_unavailable"
|
||||
@@ -1079,6 +1115,20 @@ def _diagnostic_type(error):
|
||||
return "bridge_exception"
|
||||
|
||||
|
||||
def _safe_diagnostic(error):
|
||||
"""Project one exception without retaining provider or credential text."""
|
||||
diagnostic_type = _diagnostic_type(error)
|
||||
if diagnostic_type == "capability_unavailable":
|
||||
message = str(error)[:512]
|
||||
elif diagnostic_type == "authorization":
|
||||
message = "Invalid bridge capability"
|
||||
elif diagnostic_type == "invalid_request":
|
||||
message = "Invalid Hopper bridge request"
|
||||
else:
|
||||
message = "%s: Hopper bridge operation failed" % type(error).__name__[:128]
|
||||
return {"code": -32000, "message": message, "type": diagnostic_type}
|
||||
|
||||
|
||||
def _run():
|
||||
"""Own a permission-restricted, single-client Unix socket for this bridge."""
|
||||
if os.path.exists(REA_SOCKET):
|
||||
|
||||
@@ -15,6 +15,24 @@ current package-runner invocation. REA still prints its own setup plan and asks
|
||||
for separate approval before changing agent configuration or installing a
|
||||
product-owned component.
|
||||
|
||||
When bare `npx` resolves `rea-agents` from the current project's
|
||||
`node_modules`, the selected dispatcher restarts setup through
|
||||
`rea-agents@latest` before REA plans or writes configuration. This protects
|
||||
current and future releases from silently persisting stale integration state.
|
||||
Code in an already-published older release cannot acquire that check
|
||||
retroactively; invoke `npx -y rea-agents@latest setup` once to repair any
|
||||
registration it created.
|
||||
|
||||
For an intentional rollback, make the package request explicit:
|
||||
|
||||
```bash
|
||||
npm exec --yes --package=rea-agents@2.4.0 -- rea setup
|
||||
```
|
||||
|
||||
Setup continues to pin persistent MCP registrations to the exact version that
|
||||
performed setup. Running current setup later migrates unversioned or older
|
||||
managed registrations through the normal reviewed setup transaction.
|
||||
|
||||
REA supports Node.js 22.19+ and 24.11+ (including newer releases). It uses the npm already paired with that runtime and never upgrades Node.js, npm, or Homebrew.
|
||||
|
||||
Running `npm install rea-agents` without `--global` installs the executable only
|
||||
@@ -145,6 +163,26 @@ host mount and the rest of `/tmp` remain unchanged; this fallback never invokes
|
||||
`sudo`. `rea doctor --provider hopper --detail full --json` reports the selected
|
||||
strategy and both host and effective mount facts.
|
||||
|
||||
### Hopper in CI
|
||||
|
||||
REA's unattended Linux path is validated against Hopper's offered demo mode.
|
||||
A paid license is not required for that path, and REA does not read, install, or
|
||||
automate license credentials. Licensed Hopper installations remain supported,
|
||||
but license activation is an operator-owned prerequisite rather than part of
|
||||
REA setup.
|
||||
|
||||
macOS requires Hopper's first-run UI to be completed in the same user session
|
||||
that will run REA: choose the demo mode or activate an existing license before
|
||||
starting an unattended job. Ephemeral macOS runners therefore need a
|
||||
pre-provisioned user session or a deliberate interactive bootstrap step.
|
||||
|
||||
When Hopper cannot start in CI, run
|
||||
`rea doctor --provider hopper --detail full --json` in the failing runner.
|
||||
Structured failures distinguish private-display dependencies, an unsupported
|
||||
demo dialog or build, process-ownership conflicts, and an early lifecycle exit.
|
||||
Apply the reported remediation rather than exposing the runner's desktop,
|
||||
copying license secrets into logs, or killing unrelated Hopper processes.
|
||||
|
||||
## Ghidra
|
||||
|
||||
REA's Ghidra provider is bring-your-own and supports Linux x64 with the exact
|
||||
|
||||
+21
-5
@@ -60,8 +60,10 @@ shutdown rules still apply; REA never kills a process it cannot prove it owns.
|
||||
|
||||
## Evidence resources
|
||||
|
||||
Evidence remains inline for compatibility and successful Evidence-producing
|
||||
tools also return `resource_link` content. Session resources are connection-local:
|
||||
Evidence-producing tools return compact summaries plus `resource_link` content.
|
||||
Every link is accompanied by an ordinary instruction to copy its opaque URI
|
||||
unchanged and call MCP `resources/read` (Codex: `read_mcp_resource`). Session
|
||||
resources are connection-local:
|
||||
|
||||
- `rea://evidence/{evidenceId}` returns the complete immutable Evidence v2 record.
|
||||
- `rea://evidence/{evidenceId}/section/{section}` returns a bounded result section.
|
||||
@@ -69,9 +71,10 @@ tools also return `resource_link` content. Session resources are connection-loca
|
||||
`protocol`, `nodes`, `occurrences`, and `edges` when present.
|
||||
- `rea://unknown/{unknownId}` returns the current residual-unknown head and its
|
||||
immutable revision history.
|
||||
- `rea://unknowns/active` returns current unresolved heads.
|
||||
- `rea://snapshot/{snapshotDigest}` returns the current immutable analysis
|
||||
snapshot when its canonical content digest matches.
|
||||
- `rea://evidence-bundle/{bundleDigest}` returns immutable canonical bytes
|
||||
retained by `snapshot_evidence_bundle`.
|
||||
- `rea://snapshot/current` returns the mutable native analysis cache as an
|
||||
`available` or `unavailable` state.
|
||||
- `rea://artifact/{manifestId}/{collection}` returns a canonical artifact
|
||||
`nodes`, `occurrences`, or `edges` page with Evidence provenance.
|
||||
- `rea://function/{targetSha256}/{address}` returns a retained function dossier
|
||||
@@ -84,11 +87,24 @@ workspace `resource_link` blocks. Workspace resources preserve revision and
|
||||
`previous_revision_digest` commitments; persistent workspace files remain
|
||||
subject to configured read/write roots.
|
||||
|
||||
`export_evidence_bundle` is file-only and requires `path`; existing files
|
||||
require `overwrite: true`. Use `snapshot_evidence_bundle` and then
|
||||
`resources/read` when the complete bundle is needed within the current session.
|
||||
|
||||
An Evidence URI is discoverability, not authorization. It cannot authorize file
|
||||
access, extraction, mounting, execution, or networking. IDs disappear when the
|
||||
session ends unless the existing Evidence bundle or workspace persistence flow
|
||||
explicitly retains them.
|
||||
|
||||
## Aggregate native context
|
||||
|
||||
`get_navigation_context` combines the selected document, current address, and
|
||||
current/containing procedure. A cursor outside a procedure is represented as
|
||||
`procedure: null`. `inspect_address_context` requires an explicit address and
|
||||
returns bounded name, procedure, comment, inline-comment, and bookmark facets;
|
||||
unsupported facets are local `unavailable` outcomes. The scalar getters remain
|
||||
available while the aggregate contracts are evaluated.
|
||||
|
||||
## Permission policy
|
||||
|
||||
All local side effects use one scope vocabulary: capability, canonical roots,
|
||||
|
||||
@@ -20,6 +20,10 @@ also requires the agent to keep observations, inferences, and unknowns
|
||||
distinct. Requested prompt arguments and completion choices are rendered as
|
||||
untrusted selection data, not instructions or authorization.
|
||||
|
||||
For target paths in `compare_application_versions`, the rendered workflow
|
||||
opens each target before calling `inventory_artifact`; artifact inventory and
|
||||
inspection operate on the active target and do not accept a path themselves.
|
||||
|
||||
Use standard MCP discovery and retrieval:
|
||||
|
||||
```json
|
||||
|
||||
+20
-14
@@ -2,16 +2,16 @@
|
||||
"catalog_schema_version": 1,
|
||||
"package": {
|
||||
"name": "rea-agents",
|
||||
"version": "2.5.1",
|
||||
"version": "3.0.0",
|
||||
"sdk": {
|
||||
"server": "2.0.0-beta.4",
|
||||
"client": "2.0.0-beta.4",
|
||||
"core": "2.0.0-beta.4"
|
||||
"server": "2.0.0",
|
||||
"client": "2.0.0",
|
||||
"core": "2.0.0"
|
||||
},
|
||||
"skill_version": "23"
|
||||
},
|
||||
"tools": {
|
||||
"total": 110,
|
||||
"total": 114,
|
||||
"families": [
|
||||
{
|
||||
"id": "direct",
|
||||
@@ -59,7 +59,7 @@
|
||||
{
|
||||
"id": "enhanced",
|
||||
"surface": "enhanced",
|
||||
"count": 12,
|
||||
"count": 13,
|
||||
"tools": [
|
||||
"analyze_function",
|
||||
"analyze_swift_types",
|
||||
@@ -70,6 +70,7 @@
|
||||
"get_call_graph",
|
||||
"get_objc_classes",
|
||||
"get_objc_protocols",
|
||||
"inspect_native_api",
|
||||
"swift_classes",
|
||||
"trace_call_path",
|
||||
"trace_feature"
|
||||
@@ -166,7 +167,7 @@
|
||||
{
|
||||
"id": "session",
|
||||
"surface": "session",
|
||||
"count": 19,
|
||||
"count": 22,
|
||||
"tools": [
|
||||
"binary_session",
|
||||
"build_call_path",
|
||||
@@ -179,11 +180,14 @@
|
||||
"correlate_static_and_runtime",
|
||||
"export_evidence_bundle",
|
||||
"find_changed_behavior",
|
||||
"get_navigation_context",
|
||||
"import_evidence_bundle",
|
||||
"inspect_address_context",
|
||||
"list_unknowns",
|
||||
"open_binary",
|
||||
"record_unknown",
|
||||
"run_replay_machine",
|
||||
"snapshot_evidence_bundle",
|
||||
"update_unknown",
|
||||
"verify_reconstruction",
|
||||
"verify_unknown_resolution"
|
||||
@@ -581,7 +585,7 @@
|
||||
}
|
||||
],
|
||||
"cli": {
|
||||
"primary_count": 66,
|
||||
"primary_count": 67,
|
||||
"commands": [
|
||||
"analyze",
|
||||
"analyze-javascript-application",
|
||||
@@ -619,6 +623,7 @@
|
||||
"inspect-managed-artifact",
|
||||
"inspect-managed-members",
|
||||
"inspect-managed-native-boundaries",
|
||||
"inspect-native-api",
|
||||
"inspect-plist",
|
||||
"inspect-signature",
|
||||
"inspect-web-page",
|
||||
@@ -659,17 +664,18 @@
|
||||
},
|
||||
"runtime_catalog": {
|
||||
"counts": {
|
||||
"cli_commands": 66,
|
||||
"mcp_tools": 110,
|
||||
"cli_commands": 67,
|
||||
"mcp_tools": 114,
|
||||
"mcp_prompts": 6,
|
||||
"mcp_resources": 2,
|
||||
"mcp_resource_templates": 11
|
||||
},
|
||||
"digests": {
|
||||
"tools_sha256": "9a033ddd40fcb8273365cc895bbf75d943bf1c5c8c2ee1eb9c4b3494064aaf58",
|
||||
"prompts_sha256": "f6da3ad38a1000c11364d1710f122ac4990551f04efd8c53ffb2e819b5cf5707",
|
||||
"resources_sha256": "339a984ea8cd8be5f234adf24395bf0295258d990492005cf6fe1f293d12cd46",
|
||||
"combined_sha256": "e8cac51f2f17a5b9a088c3ff773473c4897823401481fc0875a28fe7daf8eee0"
|
||||
"tools_sha256": "58bc4f72c5f8de4328728ead9f3a28ec5548484b7b9cf2ed85cf0edcc689a63c",
|
||||
"prompts_sha256": "3886a3bf55a448def79e3eb429e6a56eb2ba075423c5cb1e5747642b389ef8fe",
|
||||
"resources_sha256": "e0e872276ebf6f88e916ef24930a99eed27ce4c93e494e60820e9bd8cc8497c3",
|
||||
"combined_sha256": "e83a177f5eca63bbad17886a61f5a1a376d44afe862c51c56e5d38339f7d41f8",
|
||||
"providers_sha256": "918ccd6b8ae442cd5844dcfde55086f458176241c8d166c1e9dd0f242ccd2bb0"
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
@@ -0,0 +1,73 @@
|
||||
# Test architecture migration ledger
|
||||
|
||||
This ledger records how the flat test suite was classified during the
|
||||
coordinated architecture cutover. It is an evidence index, not a declaration
|
||||
that every test became independent merely because its path changed.
|
||||
|
||||
## Classification batches
|
||||
|
||||
The following mappings are grounded in the current moved paths. They describe
|
||||
ownership only; decomposition and evidence replacement must be recorded in the
|
||||
per-suite table below.
|
||||
|
||||
| Previous path | Current path | Classification |
|
||||
| --------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | ----------------------------------- |
|
||||
| `tests/applicationWorkflowCli.test.ts` | `tests/acceptance/applications/applicationWorkflowCli.test.ts` | Acceptance application workflow |
|
||||
| `tests/setupLifecycle.test.ts` | `tests/acceptance/setup/setupLifecycle.test.ts` | Acceptance setup workflow |
|
||||
| `tests/cdpBrowserProvider.test.ts` | `tests/boundary/browser/cdpBrowserProvider*.test.ts` | Browser boundary |
|
||||
| `tests/ghidraClient.test.ts` | `tests/boundary/providers/ghidra/ghidraClient.test.ts` | Ghidra provider boundary |
|
||||
| `tests/processOwnership.test.ts` | `tests/boundary/process/processOwnership*.test.ts` | Process boundary |
|
||||
| `tests/binarySession.test.ts` | `tests/composition/analysis-sessions/binarySession.*.test.ts` | Analysis-session composition |
|
||||
| `tests/javascriptSemanticAnalysis.test.ts` | `tests/composition/javascript-applications/javascriptSemanticAnalysis.*.test.ts` | JavaScript-application composition |
|
||||
| `tests/config.test.ts` | `tests/composition/setup-lifecycle/config.test.ts` | Setup-lifecycle composition |
|
||||
| `tests/composition/analysis-sessions/runtime.test.ts` | `tests/acceptance/applications/runtime.test.ts` | Compiled MCP acceptance workflow |
|
||||
| `tests/composition/runtime-observation/webCaptureDiff.test.ts` | `tests/boundary/browser/webCaptureDiff.test.ts` | Browser boundary |
|
||||
| `tests/conformanceFixtures.test.ts` | `tests/conformance/providers/conformanceFixtures.test.ts` | Provider conformance |
|
||||
| `tests/codexAgentEval.test.ts` | `tests/evaluation/model-evals/codexAgentEval.test.ts` | Deterministic model-evaluator logic |
|
||||
| `tests/composition/analysis-sessions/{boundedCartesianProjection,symbolAnalysis,jsonShape}.test.ts` | `src/domain/{boundedCartesianProjection,symbolAnalysis,jsonShape}.test.ts` | Colocated pure-domain behavior |
|
||||
|
||||
The same directory mapping applies to the other files moved in each batch:
|
||||
`tests/acceptance/{analysis,applications,investigations,setup}`,
|
||||
`tests/boundary/{browser,cli,filesystem,mcp,process,providers}`,
|
||||
`tests/composition/{analysis-sessions,evidence-investigations,javascript-applications,process-capture,runtime-observation,setup-lifecycle}`,
|
||||
`tests/conformance`, and `tests/evaluation`. Git rename detection remains the
|
||||
canonical source for the complete old-to-new path list.
|
||||
|
||||
## Per-suite evidence record
|
||||
|
||||
Add a row when a legacy suite is materially decomposed, consolidated, replaced,
|
||||
or removed. “Replacement evidence” must identify executable behavior, a
|
||||
generated artifact comparison, a protocol probe, or an explicit verifier; a new
|
||||
path alone is not replacement evidence.
|
||||
|
||||
| Legacy suite or claim | Disposition | Replacement evidence | Validation | Remaining gap |
|
||||
| ----------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
|
||||
| Flat path classification | Moved | Vitest configuration contract proves every deterministic test belongs to exactly one project | Configuration contract test | Record any exceptions discovered during cutover |
|
||||
| Direct session construction outside owner tests | Consolidated | `composeBinarySession` and `composeBinarySessionFromProvider` are the shared production/test seams | Repository search plus session-composition and acceptance tests | None |
|
||||
| Repeated temporary-directory setup | Consolidated | `createTestTempDirectory` delegates every test-owned root to the typed workspace fixture with HOME/XDG projection and awaited cleanup | Repository search plus filesystem, process, runtime suites, and the Vitest topology hygiene contract | None; direct `mkdtemp` remains only in the workspace fixture and package-canary source text |
|
||||
| Repeated CLI/MCP connection helpers | Consolidated | Typed CLI and MCP fixtures under `tests/support`; CLI output, dispatcher, and server tests use them | Acceptance startup, typed failure, lifecycle, and teardown tests | Provider-specific protocol harnesses remain local |
|
||||
| Implementation-shaped assertions | Replaced | Recording adapters, executable bridge/protocol probes, generated-artifact comparisons, and supported configuration contracts | Focused boundary/conformance tests and repository search | None identified in the final audit |
|
||||
| Module mocks and spies | Replaced | Recording adapters and caller-visible outcomes | Repository search plus focused reload, Ghidra, and enhanced-tool tests | None |
|
||||
| `processCapture.test.ts` | Consolidated | Ten lifecycle, observation, reactive, replay, terminal, validation, and trace suites | 42 focused boundary tests | None |
|
||||
| `cdpBrowserProvider.test.ts` | Consolidated | Five discovery, document/script, network, lifecycle, and sensitive-data suites | 36 focused browser-boundary tests | None |
|
||||
| `javascriptSemanticAnalysis.test.ts` | Consolidated | Six structure, call, dataflow, runtime, native-binding, and rejection suites | 29 focused composition tests | None |
|
||||
| `binarySession.test.ts` | Consolidated | Nine provider binding, lifecycle, cache, Evidence, permissions, and shutdown suites | Focused composition tests and shared composition-seam test | None |
|
||||
| MCP mega-suites | Consolidated | Tool/resource-family suites plus catalog-wide identity and lifecycle coverage | Focused MCP tests and complete deterministic run | None |
|
||||
| Provider client mega-suites | Consolidated | Capability-named protocol, timeout, ownership, error, and cleanup suites | 85 focused provider tests | Real systems remain in `verify:*` lanes |
|
||||
| Pure domain proofs | Moved | Colocated bounded projection, symbol classification, and JSON-shape tests | Domain Vitest project | Continue moving only tests with no external boundary dependency |
|
||||
|
||||
Use these dispositions consistently:
|
||||
|
||||
- **Moved**: the same material claim now has depth-appropriate ownership.
|
||||
- **Replaced**: stronger executable evidence supersedes the old assertion.
|
||||
- **Consolidated**: one retained test proves a claim previously duplicated.
|
||||
- **Intentionally removed**: the claim was not public or independent; the row
|
||||
must still name the retained evidence or explain why none is warranted.
|
||||
- **In progress**: classification exists but the replacement audit is not
|
||||
complete. No final-cutover row may retain this disposition.
|
||||
|
||||
The exact old-to-new inventory is mechanically enforced by the project
|
||||
classification contract and retained in Git rename metadata. Real-system lanes,
|
||||
coverage, repeated-run stability, and benchmark timing are release evidence;
|
||||
they are reported separately because they depend on the execution host and
|
||||
installed external systems.
|
||||
@@ -0,0 +1,94 @@
|
||||
# Testing REA
|
||||
|
||||
REA's test suite follows one rule: use the lowest behavioral depth that can
|
||||
prove a claim. Tests are grouped into native Vitest projects so ownership,
|
||||
allowed dependencies, and runtime cost are visible from their paths.
|
||||
|
||||
## Behavioral depths
|
||||
|
||||
| Depth | Location | What it proves |
|
||||
| ----------- | ---------------------- | ----------------------------------------------------------------------------------------------------- |
|
||||
| Module | `src/**/*.test.ts` | One domain, service, or adapter through its narrow public surface |
|
||||
| Composition | `tests/composition/**` | Provider-neutral session and registry wiring; filesystem access is limited to fixture materialization |
|
||||
| Boundary | `tests/boundary/**` | Exactly one production filesystem, process, network, browser, CLI, MCP, or provider boundary |
|
||||
| Acceptance | `tests/acceptance/**` | A complete compiled CLI or MCP workflow |
|
||||
| Conformance | `tests/conformance/**` | Shared provider contracts, parameterized by declared capabilities and explicit opt-outs |
|
||||
| Evaluation | `tests/evaluation/**` | Deterministic evaluator parsing, scoring, and report generation |
|
||||
|
||||
Colocated domain tests may import only their owning domain and inward
|
||||
dependencies. They do not construct sessions or servers and do not start
|
||||
subprocesses or network listeners. Colocated application tests exercise one
|
||||
service through explicit ports and recording adapters, never a CLI or MCP
|
||||
entrypoint. Composition tests may assemble provider-neutral sessions and
|
||||
registries but do not cross production filesystem, process, socket, or browser boundaries.
|
||||
Boundary tests cross one production boundary. Only acceptance tests assemble
|
||||
the complete runtime or invoke the compiled product surface.
|
||||
|
||||
`tests/process-global/**` is reserved for cases with a demonstrated dependency
|
||||
on process-global state. Those tests run without file parallelism. Reusable,
|
||||
test-scoped fixtures live under `tests/support/**`; immutable source artifacts
|
||||
remain under `tests/fixtures/**`.
|
||||
The process-global Vitest configuration contract rejects new direct temporary-root
|
||||
creation outside the workspace seam and its narrowly documented boundary/package
|
||||
exceptions.
|
||||
|
||||
Real Hopper, Ghidra, browser, package, managed-code, and controlled-replay
|
||||
claims belong to their explicit `npm run verify:*` lanes. They are not inferred
|
||||
from mocks or folded into the deterministic local gate. Real model trials are
|
||||
manual; Vitest covers only deterministic evaluator logic.
|
||||
|
||||
## Developer commands
|
||||
|
||||
`npm test` runs every deterministic project once. The narrower feedback loops
|
||||
are:
|
||||
|
||||
| Command | Scope |
|
||||
| ------------------------- | -------------------------------------------------------------------------------------------------------- |
|
||||
| `npm run test:fast` | Domain, service, adapter, composition, boundary, and conformance projects |
|
||||
| `npm run test:boundary` | Boundary and process-global projects |
|
||||
| `npm run test:acceptance` | Complete CLI and MCP acceptance workflows |
|
||||
| `npm run test:changed` | Changed tests in non-serial projects via Vitest's import graph |
|
||||
| `npm run test:watch` | Changed domain, service, adapter, composition, boundary, conformance, and evaluation tests in watch mode |
|
||||
| `npm run test:watch:all` | Changed tests from every deterministic project in watch mode |
|
||||
| `npm run check:changed` | Cached static checks followed by changed tests |
|
||||
| `npm run check:pr` | Static, generated-document, and complete deterministic PR gate |
|
||||
|
||||
Changed-test selection is a fast feedback aid, not release evidence. It can
|
||||
miss behavior connected through runtime registration, generated data, shell
|
||||
entrypoints, or other relationships that are absent from the import graph.
|
||||
Use `npm run check:pr` before handing off a contribution.
|
||||
|
||||
Vitest and Node persistent compile caches are deliberately not enabled by
|
||||
default. To evaluate repeated local runs, opt in for both cold and warm
|
||||
measurements with an isolated cache:
|
||||
|
||||
```bash
|
||||
NODE_COMPILE_CACHE=.cache/node-compile npm test
|
||||
```
|
||||
|
||||
Do not report the warm result as a cold-suite improvement, and do not enable
|
||||
the cache in coverage or benchmark CI without first showing that its
|
||||
instrumentation remains equivalent.
|
||||
|
||||
## Coverage and timing
|
||||
|
||||
CI owns coverage. The aggregate floors are 65% statements, 60% branches, 60%
|
||||
functions, and 68% lines. `src/domain/**` must reach 80% statements, 75%
|
||||
branches, 75% functions, and 80% lines. `src/contracts/**` must reach 85%
|
||||
statements, 80% branches, 80% functions, and 85% lines. Thresholds are
|
||||
glob-specific rather than per-file and are never updated automatically.
|
||||
Coverage does not replace named boundary, acceptance, or real-provider scenario
|
||||
matrices.
|
||||
|
||||
CI runs four native Vitest shards without retries. Each shard emits a blob
|
||||
report; the merge job produces aggregate coverage plus JUnit and JSON timing
|
||||
reports, uploads them together, and writes the slowest files to the workflow
|
||||
summary. Static checks, documentation, build, package verification, and
|
||||
real-system lanes remain separate jobs so one kind of evidence cannot stand in
|
||||
for another.
|
||||
|
||||
The PR acceptance target is a median `npm run check:pr` wall time below three
|
||||
minutes across three warm-build runs on the benchmark host. Keep Vitest caches
|
||||
cold unless separately identified. The final cutover also requires three
|
||||
consecutive deterministic passes without retries, `npm run verify:package`, and
|
||||
the applicable real-system lanes.
|
||||
@@ -12,7 +12,7 @@ harm_rank,location,trigger,current_copy,user_risk,proposed_replacement,implement
|
||||
11,src/domain/errors.ts:ArtifactOperationError,Artifact inventory or extraction fails,"Artifact {operation} failed: {reason} at {logicalPath} (declared_sha256=...)",Exposes paths hashes and internal reason,"Reason-specific plain message with safe recovery step.",implemented,focused assertions passed; full `npm run check` passed
|
||||
12,src/domain/errors.ts:EvidenceFileError,Evidence file operation fails,"Evidence bundle {operation} failed: {reason}",Internal reason token gives weak recovery,"Reason-specific plain message with safe recovery step.",implemented,focused assertions passed; full `npm run check` passed
|
||||
13,src/domain/errors.ts:EvidenceIntegrityError,Evidence validation fails,Raw constructor message,May expose validation internals and lacks recovery,"Evidence is invalid or has changed. Recreate or re-import it, then try again.",implemented,focused assertions passed; full `npm run check` passed
|
||||
14,src/domain/errors.ts:UnknownRegistryError,Evidence-state mutation fails,"Residual unknown registry mutation failed: {reason}",Exposes internal subsystem and state token,"Evidence state changed before the update completed. Refresh the current state and try again.",implemented,focused assertions passed; full `npm run check` passed
|
||||
14,src/domain/errors.ts:UnknownRegistryError,Evidence-state mutation fails,"Residual unknown registry mutation failed: {reason}",Exposes internal subsystem and state token,"Missing IDs identify the session and retry; concurrent revision conflicts refresh current state.",implemented,focused assertions passed; full `npm run check` passed
|
||||
15,src/domain/errors.ts:ProcessCaptureError,Process capture fails,Raw constructor message,May expose process and cleanup internals,"Process capture could not complete. Check command access and limits, then try again.",implemented,focused assertions passed; full `npm run check` passed
|
||||
16,src/domain/errors.ts:AnalysisTimeoutError,Analysis deadline expires,"Analysis operation timed out after {timeoutMs}ms: {operation}",Exposes internal deadline and operation; weak recovery,"Analysis took too long. Try a smaller request, then run `rea doctor` if it continues.",implemented,focused assertions passed; full `npm run check` passed
|
||||
17,src/domain/errors.ts:HopperTimeoutError,Provider deadline expires,"Hopper did not respond within {timeoutMs}ms",Exposes provider and internal deadline,"Analysis took too long. Try a smaller request, then run `rea doctor` if it continues.",implemented,focused assertions passed; full `npm run check` passed
|
||||
|
||||
|
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"schema_version": 1,
|
||||
"manifest_id": "ecm_ee8e5f2f4ea090052051d2994cbff148d9c796e1bc28b2fdc145aa5fa48cd248",
|
||||
"manifest_id": "ecm_c1609d2cc959477e200df1a368ade5e3d68ad6fd4041009b78a5778a3b76e9bc",
|
||||
"verifier": {
|
||||
"id": "rea-managed-conformance",
|
||||
"version": "1"
|
||||
@@ -14,7 +14,7 @@
|
||||
"skill_digests": [
|
||||
{
|
||||
"skill_id": "reverse-engineer-anything",
|
||||
"sha256": "6a910f067c946d545f5eb711eacbdf804839dbfb6b3b7b6ea91769be37ae47ce"
|
||||
"sha256": "1398947e9119a5a9af08514413d8cfdd8dcdc9373ebab1ba6eb525126db5ffff"
|
||||
}
|
||||
],
|
||||
"claims": [
|
||||
|
||||
@@ -5,6 +5,10 @@
|
||||
"ignoreDependencies": [],
|
||||
"ignoreBinaries": ["ps"],
|
||||
"ignoreExportsUsedInFile": true,
|
||||
"ignoreIssues": {
|
||||
"src/domain/mobileApplicationInvestigation.ts": ["types"],
|
||||
"src/domain/objcSwiftMetadata.ts": ["types"]
|
||||
},
|
||||
"rules": {
|
||||
"files": "error",
|
||||
"dependencies": "error",
|
||||
|
||||
Generated
+15
-15
@@ -1,12 +1,12 @@
|
||||
{
|
||||
"name": "rea-agents",
|
||||
"version": "2.5.1",
|
||||
"version": "3.0.0",
|
||||
"lockfileVersion": 3,
|
||||
"requires": true,
|
||||
"packages": {
|
||||
"": {
|
||||
"name": "rea-agents",
|
||||
"version": "2.5.1",
|
||||
"version": "3.0.0",
|
||||
"license": "MIT",
|
||||
"dependencies": {
|
||||
"@babel/parser": "8.0.4",
|
||||
@@ -15,8 +15,8 @@
|
||||
"@electron/asar": "4.2.0",
|
||||
"@jridgewell/trace-mapping": "0.3.31",
|
||||
"@lydell/node-pty": "1.1.0",
|
||||
"@modelcontextprotocol/client": "2.0.0-beta.4",
|
||||
"@modelcontextprotocol/server": "2.0.0-beta.4",
|
||||
"@modelcontextprotocol/client": "2.0.0",
|
||||
"@modelcontextprotocol/server": "2.0.0",
|
||||
"@xterm/addon-serialize": "0.14.0",
|
||||
"@xterm/headless": "6.0.0",
|
||||
"@zip.js/zip.js": "2.8.26",
|
||||
@@ -369,12 +369,12 @@
|
||||
]
|
||||
},
|
||||
"node_modules/@modelcontextprotocol/client": {
|
||||
"version": "2.0.0-beta.4",
|
||||
"resolved": "https://registry.npmjs.org/@modelcontextprotocol/client/-/client-2.0.0-beta.4.tgz",
|
||||
"integrity": "sha512-VNHA/UXDk7mCpVl+jOg5B4WMRRD2OEl+it360Lhi6HiCbrIB2f6pZ0cqSDKXQVUtZvqnhdQHzZAM9h8EKWhq/A==",
|
||||
"version": "2.0.0",
|
||||
"resolved": "https://registry.npmjs.org/@modelcontextprotocol/client/-/client-2.0.0.tgz",
|
||||
"integrity": "sha512-8f1OghQ2rjzIOfqgUCP+8GiUWqRs89njoWLNqAe8kWmDePv3s1fZXseej+QXemssEuuOvLLmLO/kqM3IQHtISw==",
|
||||
"license": "MIT",
|
||||
"dependencies": {
|
||||
"@modelcontextprotocol/core": "2.0.0-beta.4",
|
||||
"@modelcontextprotocol/core": "2.0.0",
|
||||
"cross-spawn": "^7.0.5",
|
||||
"eventsource": "^3.0.2",
|
||||
"eventsource-parser": "^3.0.0",
|
||||
@@ -387,9 +387,9 @@
|
||||
}
|
||||
},
|
||||
"node_modules/@modelcontextprotocol/core": {
|
||||
"version": "2.0.0-beta.4",
|
||||
"resolved": "https://registry.npmjs.org/@modelcontextprotocol/core/-/core-2.0.0-beta.4.tgz",
|
||||
"integrity": "sha512-nsMXd4wQBKzmph6r+WOhum+mXjDYljTAqwY/XUg3hLtvNOQ8+JVqBSJOVCMJvx9lXhTpTOPrGZ3BuNiaNPjSvg==",
|
||||
"version": "2.0.0",
|
||||
"resolved": "https://registry.npmjs.org/@modelcontextprotocol/core/-/core-2.0.0.tgz",
|
||||
"integrity": "sha512-pJCEwGG7Lfr/+PQp9ZTwKXNeO5wzbfKL7H3MYpCorM4oFBoQrdjnBgEoqG+RjhsvS1FKrDbKux+M1HhlnGWqcA==",
|
||||
"license": "MIT",
|
||||
"dependencies": {
|
||||
"zod": "^4.2.0"
|
||||
@@ -399,12 +399,12 @@
|
||||
}
|
||||
},
|
||||
"node_modules/@modelcontextprotocol/server": {
|
||||
"version": "2.0.0-beta.4",
|
||||
"resolved": "https://registry.npmjs.org/@modelcontextprotocol/server/-/server-2.0.0-beta.4.tgz",
|
||||
"integrity": "sha512-pjMZcNEt1dOq0aJCcY3b7w1Ayh+qmQN2xlfTELcGV9yiAjEGIczBPBLWWW0k0zzo5T8kiv15jtKPsWeHGxLvLg==",
|
||||
"version": "2.0.0",
|
||||
"resolved": "https://registry.npmjs.org/@modelcontextprotocol/server/-/server-2.0.0.tgz",
|
||||
"integrity": "sha512-YhHWdHfpFMQfd0prsEnxKeS3Qz3ytIGmsS0sth4KDjnacIT7hxk6hXHkJ9KysxlkvTM+WZAtQbbcUhdoP4Hvtw==",
|
||||
"license": "MIT",
|
||||
"dependencies": {
|
||||
"@modelcontextprotocol/core": "2.0.0-beta.4",
|
||||
"@modelcontextprotocol/core": "2.0.0",
|
||||
"zod": "^4.2.0"
|
||||
},
|
||||
"engines": {
|
||||
|
||||
+21
-10
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "rea-agents",
|
||||
"version": "2.5.1",
|
||||
"version": "3.0.0",
|
||||
"description": "Reverse engineer anything from your terminal or agent with one CLI and MCP server.",
|
||||
"license": "MIT",
|
||||
"repository": {
|
||||
@@ -43,6 +43,7 @@
|
||||
"bridge/hopper_bridge.py",
|
||||
"bridge/ghidra/ReaGhidraBridge.java",
|
||||
"scripts/rea.mjs",
|
||||
"scripts/package-runner-bootstrap.mjs",
|
||||
"scripts/hopper-demo-x11.py",
|
||||
"scripts/prepack.mjs",
|
||||
"scripts/prepare.mjs",
|
||||
@@ -54,12 +55,16 @@
|
||||
"deps:check": "node scripts/check-dependency-install.mjs",
|
||||
"metadata:generate": "node scripts/generate-package-metadata.mjs",
|
||||
"metadata:check": "node scripts/generate-package-metadata.mjs --check",
|
||||
"mcp-catalog:generate": "npm run build:cached && node scripts/generate-mcp-tool-catalog.mjs",
|
||||
"mcp-catalog:check": "node scripts/generate-mcp-tool-catalog.mjs --check",
|
||||
"prebuild": "npm run deps:check && npm run metadata:check",
|
||||
"build": "tsc -p tsconfig.build.json",
|
||||
"precheck": "npm run deps:check",
|
||||
"check": "turbo run typecheck lint format:check knip metadata:check",
|
||||
"precheck:fast": "npm run deps:check",
|
||||
"check:fast": "turbo run typecheck lint",
|
||||
"precheck:changed": "npm run deps:check",
|
||||
"check:changed": "turbo run typecheck lint && npm run test:changed",
|
||||
"precheck:test": "npm run deps:check",
|
||||
"check:test": "turbo run typecheck lint format:check knip metadata:check test:run",
|
||||
"precheck:pr": "npm run deps:check",
|
||||
@@ -80,22 +85,28 @@
|
||||
"test": "vitest run",
|
||||
"test:run": "vitest run",
|
||||
"pretest:fast": "npm run build:cached",
|
||||
"test:fast": "vitest run --project parallel --project subprocess",
|
||||
"test:fast": "vitest run --project domain --project services --project adapters --project composition --project boundary --project conformance",
|
||||
"pretest:boundary": "npm run build:cached",
|
||||
"test:boundary": "vitest run --project boundary --project process-global",
|
||||
"pretest:acceptance": "npm run build:cached",
|
||||
"test:acceptance": "vitest run --project acceptance",
|
||||
"pretest:changed": "npm run build:cached",
|
||||
"test:changed": "vitest run --project parallel --project subprocess --changed",
|
||||
"test:changed": "vitest run --project domain --project services --project adapters --project composition --project boundary --project conformance --project evaluation --changed",
|
||||
"pretest:integration": "npm run build:cached",
|
||||
"test:integration": "vitest run --project serial-integration",
|
||||
"test:integration": "vitest run --project boundary --project process-global --project acceptance",
|
||||
"pretest:coverage": "npm run build:cached",
|
||||
"test:coverage": "vitest run --coverage.enabled --coverage.provider=v8",
|
||||
"test:ci": "npm run test:coverage -- --reporter=default --reporter=junit --outputFile.junit=test-results.xml",
|
||||
"pretest:ci:shard": "npm run build:cached",
|
||||
"test:ci:shard": "npm run test:ci:shard:run",
|
||||
"test:ci:shard:run": "vitest run --coverage.enabled --coverage.provider=v8 --coverage.thresholds.lines=0 --coverage.thresholds.functions=0 --coverage.thresholds.branches=0 --coverage.thresholds.statements=0 --reporter=default --reporter=blob",
|
||||
"test:ci:merge": "vitest --merge-reports --coverage.enabled --coverage.provider=v8 --reporter=default --reporter=junit --outputFile.junit=test-results.xml",
|
||||
"test:ci:merge": "vitest --merge-reports --coverage.enabled --coverage.provider=v8",
|
||||
"pretest:verbose": "npm run build:cached",
|
||||
"test:verbose": "vitest run --reporter=verbose",
|
||||
"pretest:watch": "npm run build:cached",
|
||||
"test:watch": "vitest --project parallel --project subprocess --changed",
|
||||
"test:watch": "vitest --project domain --project services --project adapters --project composition --project boundary --project conformance --project evaluation --changed",
|
||||
"pretest:watch:all": "npm run build:cached",
|
||||
"test:watch:all": "vitest --changed",
|
||||
"typecheck": "tsc --noEmit",
|
||||
"verify:test-temp-hygiene": "npm run build:cached && node scripts/verify-test-temp-hygiene.mjs",
|
||||
"verify:hopper": "npm run verify:fixtures && npm run build:cached && node scripts/verify-real-hopper.mjs",
|
||||
@@ -123,9 +134,9 @@
|
||||
"evidence:check": "npm run build:cached && node scripts/generate-completion-ledger.mjs --check",
|
||||
"docs:api": "typedoc",
|
||||
"docs:api:cached": "turbo run docs:api",
|
||||
"docs:generate": "npm run metadata:generate && npm run build:cached && node scripts/generate-skill-metadata.mjs && node scripts/generate-product-catalog.mjs && node scripts/generate-completion-ledger.mjs && npm run docs:api:cached && node scripts/generate-error-schema.mjs",
|
||||
"docs:generate": "npm run metadata:generate && npm run build:cached && node scripts/generate-mcp-tool-catalog.mjs && node scripts/generate-skill-metadata.mjs && node scripts/generate-product-catalog.mjs && node scripts/generate-completion-ledger.mjs && npm run docs:api:cached && node scripts/generate-error-schema.mjs",
|
||||
"docs:check": "turbo run docs:check:built",
|
||||
"docs:check:built": "node scripts/generate-package-metadata.mjs --check && node scripts/generate-skill-metadata.mjs --check && node scripts/generate-product-catalog.mjs --check && node scripts/generate-completion-ledger.mjs --check && node scripts/check-doc-facts.mjs && node scripts/generate-error-schema.mjs --check",
|
||||
"docs:check:built": "node scripts/generate-package-metadata.mjs --check && node scripts/generate-mcp-tool-catalog.mjs --check && node scripts/generate-skill-metadata.mjs --check && node scripts/generate-product-catalog.mjs --check && node scripts/generate-completion-ledger.mjs --check && node scripts/check-doc-facts.mjs && node scripts/generate-error-schema.mjs --check",
|
||||
"docs:error-schema": "npm run build:cached && node scripts/generate-error-schema.mjs",
|
||||
"prepack": "node scripts/prepack.mjs",
|
||||
"prepare": "node scripts/prepare.mjs"
|
||||
@@ -144,8 +155,8 @@
|
||||
"@electron/asar": "4.2.0",
|
||||
"@jridgewell/trace-mapping": "0.3.31",
|
||||
"@lydell/node-pty": "1.1.0",
|
||||
"@modelcontextprotocol/client": "2.0.0-beta.4",
|
||||
"@modelcontextprotocol/server": "2.0.0-beta.4",
|
||||
"@modelcontextprotocol/client": "2.0.0",
|
||||
"@modelcontextprotocol/server": "2.0.0",
|
||||
"@xterm/addon-serialize": "0.14.0",
|
||||
"@xterm/headless": "6.0.0",
|
||||
"@zip.js/zip.js": "2.8.26",
|
||||
|
||||
@@ -0,0 +1,153 @@
|
||||
import { dirname, join } from "node:path";
|
||||
import { fileURLToPath } from "node:url";
|
||||
import { format } from "prettier";
|
||||
|
||||
import { TOOL_CONTRACTS } from "../dist/contracts/toolContracts.js";
|
||||
import { MANAGED_WORKFLOW_TOOL_CONTRACTS } from "../dist/contracts/managedWorkflowToolContracts.js";
|
||||
import { ArtifactProvider } from "../dist/artifacts/ArtifactProvider.js";
|
||||
import { ManagedStaticProvider } from "../dist/dotnet/ManagedStaticProvider.js";
|
||||
import { NativeMacOSProvider } from "../dist/native/NativeMacOSProvider.js";
|
||||
import { toolRegistrationOptions } from "../dist/server/toolRegistrationOptions.js";
|
||||
import { ensureGeneratedFile } from "./lib/generated-file.mjs";
|
||||
|
||||
const arguments_ = new Set(process.argv.slice(2));
|
||||
for (const argument of arguments_)
|
||||
if (argument !== "--check")
|
||||
throw new Error(`Unknown MCP tool catalog option: ${argument}`);
|
||||
|
||||
const root = join(dirname(fileURLToPath(import.meta.url)), "..");
|
||||
const sessionToolNames = new Set([
|
||||
...TOOL_CONTRACTS.filter(({ kind }) => kind === "session").map(
|
||||
({ name }) => name,
|
||||
),
|
||||
...MANAGED_WORKFLOW_TOOL_CONTRACTS.map(({ name }) => name),
|
||||
]);
|
||||
const catalog = TOOL_CONTRACTS.map((contract) => {
|
||||
const options = toolRegistrationOptions(contract);
|
||||
return {
|
||||
name: contract.name,
|
||||
analysisOperation: [
|
||||
"official-proxy",
|
||||
"enhanced",
|
||||
"native-provider",
|
||||
"artifact-provider",
|
||||
"managed-provider",
|
||||
].includes(contract.kind)
|
||||
? contract.name
|
||||
: null,
|
||||
title: options.title,
|
||||
description: options.description,
|
||||
kind: contract.kind,
|
||||
requiresSession: sessionToolNames.has(contract.name),
|
||||
inputSchema: options.inputSchema["~standard"].jsonSchema.input({
|
||||
target: "draft-2020-12",
|
||||
}),
|
||||
outputSchema: options.outputSchema["~standard"].jsonSchema.output({
|
||||
target: "draft-2020-12",
|
||||
}),
|
||||
annotations: options.annotations,
|
||||
effects: contract.effects,
|
||||
};
|
||||
});
|
||||
const auxiliaryProviders = [
|
||||
new ArtifactProvider(false, false),
|
||||
new NativeMacOSProvider(),
|
||||
new ManagedStaticProvider(),
|
||||
].map((provider) => ({
|
||||
identity: provider.identity(),
|
||||
capabilities: provider.capabilities(),
|
||||
}));
|
||||
const payloadJson = JSON.stringify({ catalog, auxiliaryProviders });
|
||||
const source = await format(
|
||||
`import type { ToolAnnotations } from "@modelcontextprotocol/server";
|
||||
import type {
|
||||
CapabilityDescriptor,
|
||||
ProviderIdentity,
|
||||
} from "./application/AnalysisProvider.js";
|
||||
import type { ToolKind } from "./contracts/toolContractTypes.js";
|
||||
import type { ToolEffects } from "./contracts/toolEffects.js";
|
||||
|
||||
interface GeneratedTool {
|
||||
readonly name: string;
|
||||
readonly analysisOperation: CapabilityDescriptor["operation"] | null;
|
||||
readonly title: string;
|
||||
readonly description: string;
|
||||
readonly kind: ToolKind;
|
||||
readonly requiresSession: boolean;
|
||||
readonly inputSchema: Readonly<Record<string, unknown>>;
|
||||
readonly outputSchema: Readonly<Record<string, unknown>>;
|
||||
readonly annotations: ToolAnnotations;
|
||||
readonly effects: ToolEffects;
|
||||
}
|
||||
|
||||
interface GeneratedProvider {
|
||||
readonly identity: ProviderIdentity;
|
||||
readonly capabilities: readonly CapabilityDescriptor[];
|
||||
}
|
||||
|
||||
interface GeneratedPayload {
|
||||
readonly catalog: readonly GeneratedTool[];
|
||||
readonly auxiliaryProviders: readonly GeneratedProvider[];
|
||||
}
|
||||
|
||||
const GENERATED_PAYLOAD_JSON = ${JSON.stringify(payloadJson)};
|
||||
const generatedPayload: unknown = JSON.parse(GENERATED_PAYLOAD_JSON);
|
||||
if (!isGeneratedPayload(generatedPayload))
|
||||
throw new TypeError("Generated MCP catalog payload is invalid");
|
||||
|
||||
/** Generated from TOOL_CONTRACTS; do not edit. */
|
||||
export const GENERATED_MCP_TOOL_CATALOG = generatedPayload.catalog;
|
||||
|
||||
/** Generated lightweight metadata for lazily loaded auxiliary providers. */
|
||||
export const GENERATED_AUXILIARY_PROVIDERS = generatedPayload.auxiliaryProviders;
|
||||
|
||||
function isGeneratedPayload(value: unknown): value is GeneratedPayload {
|
||||
return (
|
||||
isRecord(value) &&
|
||||
Array.isArray(value.catalog) &&
|
||||
value.catalog.every(isGeneratedTool) &&
|
||||
Array.isArray(value.auxiliaryProviders) &&
|
||||
value.auxiliaryProviders.every(isGeneratedProvider)
|
||||
);
|
||||
}
|
||||
|
||||
function isGeneratedTool(value: unknown): value is GeneratedTool {
|
||||
return (
|
||||
isRecord(value) &&
|
||||
typeof value.name === "string" &&
|
||||
(typeof value.analysisOperation === "string" ||
|
||||
value.analysisOperation === null) &&
|
||||
typeof value.title === "string" &&
|
||||
typeof value.description === "string" &&
|
||||
typeof value.kind === "string" &&
|
||||
typeof value.requiresSession === "boolean" &&
|
||||
isRecord(value.inputSchema) &&
|
||||
isRecord(value.outputSchema) &&
|
||||
isRecord(value.annotations) &&
|
||||
isRecord(value.effects)
|
||||
);
|
||||
}
|
||||
|
||||
function isGeneratedProvider(value: unknown): value is GeneratedProvider {
|
||||
return (
|
||||
isRecord(value) &&
|
||||
isRecord(value.identity) &&
|
||||
Array.isArray(value.capabilities)
|
||||
);
|
||||
}
|
||||
|
||||
function isRecord(
|
||||
value: unknown,
|
||||
): value is Readonly<Record<string, unknown>> {
|
||||
return typeof value === "object" && value !== null && !Array.isArray(value);
|
||||
}
|
||||
`,
|
||||
{ parser: "typescript" },
|
||||
);
|
||||
|
||||
await ensureGeneratedFile({
|
||||
path: join(root, "src/generatedMcpToolCatalog.ts"),
|
||||
source,
|
||||
check: arguments_.has("--check"),
|
||||
generateCommand: "npm run mcp-catalog:generate",
|
||||
});
|
||||
@@ -1,6 +1,9 @@
|
||||
import { createHash } from "node:crypto";
|
||||
import { join } from "node:path";
|
||||
import { pathToFileURL } from "node:url";
|
||||
|
||||
import canonicalize from "canonicalize";
|
||||
|
||||
const load = (root, path) => import(pathToFileURL(join(root, path)).href);
|
||||
|
||||
/** Sort tool/provider names alphabetically. */
|
||||
@@ -9,6 +12,14 @@ export const names = (contracts) =>
|
||||
.map(({ name }) => name)
|
||||
.sort((left, right) => left.localeCompare(right));
|
||||
|
||||
/** Return the stable digest for a generated catalog projection. */
|
||||
export const digest = (value) => {
|
||||
const encoded = canonicalize(value);
|
||||
if (encoded === undefined)
|
||||
throw new TypeError("Catalog projection is not canonical JSON");
|
||||
return createHash("sha256").update(encoded).digest("hex");
|
||||
};
|
||||
|
||||
/** Throw when two name lists diverge. */
|
||||
export const assertSameNames = (label, actual, expected) => {
|
||||
const actualSet = new Set(actual);
|
||||
|
||||
@@ -0,0 +1,62 @@
|
||||
interface McpStartupPolicy {
|
||||
readonly initializeBudgetMs: number;
|
||||
readonly toolsListBudgetMs: number;
|
||||
readonly firstCatalogBudgetMs: number;
|
||||
readonly doctorDeadlineMs: number;
|
||||
}
|
||||
|
||||
interface McpProcessOptions {
|
||||
readonly command: string;
|
||||
readonly args: readonly string[];
|
||||
readonly environment: Readonly<Record<string, string | undefined>>;
|
||||
readonly policy: McpStartupPolicy;
|
||||
}
|
||||
|
||||
interface McpModuleProfileOptions extends McpProcessOptions {
|
||||
readonly packageName: string;
|
||||
}
|
||||
|
||||
interface RssMeasurement {
|
||||
readonly supported: boolean;
|
||||
readonly method: string | null;
|
||||
readonly peak_bytes: number | null;
|
||||
}
|
||||
|
||||
/** Measure the first usable MCP catalog through a child-process boundary. */
|
||||
export function measureMcpStartup(options: McpProcessOptions): Promise<{
|
||||
readonly process_started_to_initialized_ms: number;
|
||||
readonly initialized_to_tools_list_ms: number;
|
||||
readonly process_started_to_tools_list_ms: number;
|
||||
readonly listed_tool_count: number;
|
||||
readonly rss: RssMeasurement;
|
||||
}>;
|
||||
|
||||
/** Profile ESM file loading in a separate diagnostic MCP child. */
|
||||
export function profileMcpModuleLoading(
|
||||
options: McpModuleProfileOptions,
|
||||
): Promise<{
|
||||
readonly supported: true;
|
||||
readonly method: "node-debug-esm";
|
||||
readonly unique_file_modules: number;
|
||||
readonly unique_package_modules: number;
|
||||
readonly unique_dependency_modules: number;
|
||||
readonly debug_lines: number;
|
||||
readonly truncated: boolean;
|
||||
}>;
|
||||
|
||||
/** Parse Linux procfs VmRSS text into bytes. */
|
||||
export function parseLinuxVmRssBytes(status: string): number | null;
|
||||
|
||||
/** Collect unique file-backed ESM module URLs from Node diagnostics. */
|
||||
export function createEsmModuleProfileCollector(packageName?: string): {
|
||||
append(chunk: string): void;
|
||||
result(): {
|
||||
readonly supported: true;
|
||||
readonly method: "node-debug-esm";
|
||||
readonly unique_file_modules: number;
|
||||
readonly unique_package_modules: number;
|
||||
readonly unique_dependency_modules: number;
|
||||
readonly debug_lines: number;
|
||||
readonly truncated: boolean;
|
||||
};
|
||||
};
|
||||
@@ -0,0 +1,217 @@
|
||||
import { readFileSync } from "node:fs";
|
||||
import { performance } from "node:perf_hooks";
|
||||
|
||||
import { Client } from "@modelcontextprotocol/client";
|
||||
import { StdioClientTransport } from "@modelcontextprotocol/client/stdio";
|
||||
|
||||
const RSS_SAMPLE_INTERVAL_MS = 10;
|
||||
const MAXIMUM_PROFILE_BUFFER_BYTES = 2 * 1_024 * 1_024;
|
||||
const MAXIMUM_PROFILE_MODULES = 10_000;
|
||||
|
||||
/**
|
||||
* Measure the first usable MCP catalog through the installed process boundary.
|
||||
*/
|
||||
export async function measureMcpStartup({
|
||||
command,
|
||||
args,
|
||||
environment,
|
||||
policy,
|
||||
}) {
|
||||
const transport = new StdioClientTransport({
|
||||
command,
|
||||
args,
|
||||
env: environment,
|
||||
stderr: "pipe",
|
||||
});
|
||||
let stderr = "";
|
||||
transport.stderr?.on("data", (chunk) => {
|
||||
stderr = boundedAppend(stderr, chunk.toString());
|
||||
});
|
||||
const rss = createLinuxRssSampler(() => transport.pid);
|
||||
const client = new Client({
|
||||
name: "package-startup-probe",
|
||||
version: "1.0.0",
|
||||
});
|
||||
const startedAt = performance.now();
|
||||
rss.start();
|
||||
try {
|
||||
await client.connect(transport, { timeout: policy.initializeBudgetMs });
|
||||
const initializedAt = performance.now();
|
||||
const tools = await client.listTools(undefined, {
|
||||
timeout: policy.toolsListBudgetMs,
|
||||
});
|
||||
const listedAt = performance.now();
|
||||
rss.stop();
|
||||
const measurement = {
|
||||
process_started_to_initialized_ms: elapsed(startedAt, initializedAt),
|
||||
initialized_to_tools_list_ms: elapsed(initializedAt, listedAt),
|
||||
process_started_to_tools_list_ms: elapsed(startedAt, listedAt),
|
||||
listed_tool_count: tools.tools.length,
|
||||
rss: rss.result(),
|
||||
};
|
||||
assertStartupBudgets(measurement, policy);
|
||||
return measurement;
|
||||
} catch (cause) {
|
||||
throw new Error(`packaged MCP startup probe failed: ${stderr}`, { cause });
|
||||
} finally {
|
||||
rss.stop();
|
||||
await Promise.allSettled([client.close(), transport.close()]);
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Profile ESM file loading in a separate diagnostic child.
|
||||
*/
|
||||
export async function profileMcpModuleLoading({
|
||||
command,
|
||||
args,
|
||||
environment,
|
||||
policy,
|
||||
packageName,
|
||||
}) {
|
||||
const profile = createEsmModuleProfileCollector(packageName);
|
||||
const transport = new StdioClientTransport({
|
||||
command,
|
||||
args,
|
||||
env: { ...environment, NODE_DEBUG: "esm" },
|
||||
stderr: "pipe",
|
||||
});
|
||||
transport.stderr?.on("data", (chunk) => profile.append(chunk.toString()));
|
||||
const client = new Client({
|
||||
name: "package-module-profile",
|
||||
version: "1.0.0",
|
||||
});
|
||||
try {
|
||||
await client.connect(transport, {
|
||||
timeout: policy.doctorDeadlineMs,
|
||||
});
|
||||
await client.listTools(undefined, {
|
||||
timeout: policy.toolsListBudgetMs,
|
||||
});
|
||||
return profile.result();
|
||||
} finally {
|
||||
await Promise.allSettled([client.close(), transport.close()]);
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Parse Linux procfs VmRSS text into bytes.
|
||||
*/
|
||||
export const parseLinuxVmRssBytes = (status) => {
|
||||
const match = /^VmRSS:\s+(\d+)\s+kB$/mu.exec(status);
|
||||
return match === null ? null : Number(match[1]) * 1_024;
|
||||
};
|
||||
|
||||
/**
|
||||
* Collect unique file-backed ESM module URLs from Node's diagnostic stream.
|
||||
*/
|
||||
export const createEsmModuleProfileCollector = (packageName = "rea-agents") => {
|
||||
const modules = new Set();
|
||||
let buffer = "";
|
||||
let debugLines = 0;
|
||||
let truncated = false;
|
||||
const consume = (line) => {
|
||||
if (line.startsWith("ESM ")) debugLines += 1;
|
||||
for (const match of line.matchAll(/file:\/\/\/[^\s'",}\])]+/gu)) {
|
||||
if (modules.size >= MAXIMUM_PROFILE_MODULES) {
|
||||
truncated = true;
|
||||
break;
|
||||
}
|
||||
modules.add(match[0]);
|
||||
}
|
||||
};
|
||||
return {
|
||||
append(chunk) {
|
||||
buffer += chunk;
|
||||
if (Buffer.byteLength(buffer) > MAXIMUM_PROFILE_BUFFER_BYTES) {
|
||||
buffer = buffer.slice(-MAXIMUM_PROFILE_BUFFER_BYTES);
|
||||
truncated = true;
|
||||
}
|
||||
const lines = buffer.split("\n");
|
||||
buffer = lines.pop() ?? "";
|
||||
for (const line of lines) consume(line);
|
||||
},
|
||||
result() {
|
||||
if (buffer.length > 0) consume(buffer);
|
||||
const values = [...modules];
|
||||
const packageSegment = `/node_modules/${packageName}/`;
|
||||
return {
|
||||
supported: true,
|
||||
method: "node-debug-esm",
|
||||
unique_file_modules: values.length,
|
||||
unique_package_modules: values.filter((value) =>
|
||||
value.includes(packageSegment),
|
||||
).length,
|
||||
unique_dependency_modules: values.filter(
|
||||
(value) =>
|
||||
value.includes("/node_modules/") && !value.includes(packageSegment),
|
||||
).length,
|
||||
debug_lines: debugLines,
|
||||
truncated,
|
||||
};
|
||||
},
|
||||
};
|
||||
};
|
||||
|
||||
const createLinuxRssSampler = (pid) => {
|
||||
if (process.platform !== "linux")
|
||||
return {
|
||||
start() {},
|
||||
stop() {},
|
||||
result: () => ({
|
||||
supported: false,
|
||||
method: null,
|
||||
peak_bytes: null,
|
||||
}),
|
||||
};
|
||||
let peakBytes = null;
|
||||
let timer;
|
||||
const sample = () => {
|
||||
const currentPid = pid();
|
||||
if (currentPid === null) return;
|
||||
try {
|
||||
const current = parseLinuxVmRssBytes(
|
||||
readFileSync(`/proc/${String(currentPid)}/status`, "utf8"),
|
||||
);
|
||||
if (current !== null && (peakBytes === null || current > peakBytes))
|
||||
peakBytes = current;
|
||||
} catch {
|
||||
// The short-lived child may exit between resolving its PID and reading.
|
||||
}
|
||||
};
|
||||
return {
|
||||
start() {
|
||||
sample();
|
||||
timer = setInterval(sample, RSS_SAMPLE_INTERVAL_MS);
|
||||
timer.unref();
|
||||
},
|
||||
stop() {
|
||||
if (timer !== undefined) clearInterval(timer);
|
||||
sample();
|
||||
},
|
||||
result: () => ({
|
||||
supported: true,
|
||||
method: "linux-proc-status-vmrss-sampled",
|
||||
peak_bytes: peakBytes,
|
||||
}),
|
||||
};
|
||||
};
|
||||
|
||||
const assertStartupBudgets = (measurement, policy) => {
|
||||
if (measurement.process_started_to_initialized_ms > policy.initializeBudgetMs)
|
||||
throw new Error("packaged MCP exceeded the initialize regression budget");
|
||||
if (measurement.initialized_to_tools_list_ms > policy.toolsListBudgetMs)
|
||||
throw new Error("packaged MCP exceeded the tools/list regression budget");
|
||||
if (
|
||||
measurement.process_started_to_tools_list_ms > policy.firstCatalogBudgetMs
|
||||
)
|
||||
throw new Error(
|
||||
"packaged MCP exceeded the first-catalog regression budget",
|
||||
);
|
||||
};
|
||||
|
||||
const elapsed = (startedAt, completedAt) =>
|
||||
Math.round((completedAt - startedAt) * 100) / 100;
|
||||
|
||||
const boundedAppend = (current, chunk) =>
|
||||
`${current}${chunk}`.slice(-64 * 1_024);
|
||||
@@ -46,6 +46,9 @@ export interface ProductCatalog {
|
||||
}
|
||||
|
||||
export function createProductCatalog(root: string): Promise<ProductCatalog>;
|
||||
export function providerCatalogDigest(
|
||||
providers: ProductCatalog["providers"],
|
||||
): string;
|
||||
export function createCliInventory(cli: unknown): {
|
||||
readonly primary: readonly string[];
|
||||
readonly aliases: readonly {
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
import { format } from "prettier";
|
||||
|
||||
import { assertSameNames, loadSources } from "./catalog-core.mjs";
|
||||
import { assertSameNames, digest, loadSources } from "./catalog-core.mjs";
|
||||
import {
|
||||
createCliInventory,
|
||||
cliCommandDescriptionIssues,
|
||||
@@ -15,6 +15,9 @@ export {
|
||||
cliCommandOptionNames,
|
||||
};
|
||||
|
||||
/** Return the stable digest for the source-derived provider projection. */
|
||||
export const providerCatalogDigest = (providers) => digest(providers);
|
||||
|
||||
/** Project current runtime contracts into deterministic, machine-readable facts. */
|
||||
export const createProductCatalog = async (root) => {
|
||||
const sources = await loadSources(root);
|
||||
@@ -25,6 +28,7 @@ export const createProductCatalog = async (root) => {
|
||||
sources.catalogIdentity.CLI_COMMAND_NAMES,
|
||||
);
|
||||
const tools = toolFamilyCatalog(sources);
|
||||
const providers = providerCatalog(sources);
|
||||
const metadata = sources.packageMetadata.PACKAGE_METADATA;
|
||||
return {
|
||||
catalog_schema_version: 1,
|
||||
@@ -39,7 +43,7 @@ export const createProductCatalog = async (root) => {
|
||||
skill_version: metadata.skillVersion,
|
||||
},
|
||||
tools,
|
||||
providers: providerCatalog(sources),
|
||||
providers,
|
||||
setup_clients: sources.supportedClients.SUPPORTED_CLIENT_DEFINITIONS.map(
|
||||
({ name, displayName, format }) => ({
|
||||
id: name,
|
||||
@@ -56,7 +60,10 @@ export const createProductCatalog = async (root) => {
|
||||
},
|
||||
runtime_catalog: {
|
||||
counts: sources.catalogIdentity.CATALOG_IDENTITY.counts,
|
||||
digests: sources.catalogIdentity.CATALOG_IDENTITY.digests,
|
||||
digests: {
|
||||
...sources.catalogIdentity.CATALOG_IDENTITY.digests,
|
||||
providers_sha256: providerCatalogDigest(providers),
|
||||
},
|
||||
},
|
||||
};
|
||||
};
|
||||
|
||||
@@ -1,5 +1,68 @@
|
||||
import { requireFunctionDossierOracle } from "../../dist/application/RealHopperAssertions.js";
|
||||
|
||||
/** Require truthful tri-state permissions from real Hopper memory regions. */
|
||||
export const requireTruthfulMemoryRegions = (segments) => {
|
||||
if (!Array.isArray(segments) || segments.length === 0) {
|
||||
throw new Error("list_segments returned no real memory regions");
|
||||
}
|
||||
const regions = segments.flatMap((segment) => [
|
||||
segment,
|
||||
...(Array.isArray(segment.sections) ? segment.sections : []),
|
||||
]);
|
||||
for (const region of regions) {
|
||||
for (const permission of ["readable", "writable", "executable"]) {
|
||||
if (![true, false, null].includes(region?.[permission])) {
|
||||
throw new Error(`list_segments omitted tri-state ${permission}`);
|
||||
}
|
||||
}
|
||||
if (
|
||||
region.provenance !== "hopper-public-python-api" ||
|
||||
region.permissions?.available !== false ||
|
||||
typeof region.permissions.reason !== "string"
|
||||
) {
|
||||
throw new Error("list_segments omitted permission provenance");
|
||||
}
|
||||
}
|
||||
};
|
||||
|
||||
/** Require correlated start and terminal progress from the real bridge. */
|
||||
export function requireBridgeProgress(updates) {
|
||||
const messages = updates.map(({ message }) => message);
|
||||
if (
|
||||
!messages.some(
|
||||
(message) =>
|
||||
message === "Hopper bridge started request" ||
|
||||
message.includes("started on Hopper's serial bridge"),
|
||||
) ||
|
||||
!messages.some(
|
||||
(message) =>
|
||||
message === "Hopper bridge completed request" ||
|
||||
message.includes("Hopper bridge completed request"),
|
||||
)
|
||||
)
|
||||
throw new Error(
|
||||
`The MCP client did not observe correlated Hopper bridge progress: ${JSON.stringify(updates)}`,
|
||||
);
|
||||
}
|
||||
|
||||
/** Require one sanitized invalid-request diagnostic from the real bridge. */
|
||||
export function requireBridgeDiagnostic(chunks) {
|
||||
const diagnostics = chunks
|
||||
.join("")
|
||||
.split("\n")
|
||||
.filter((line) => line.trim().length > 0)
|
||||
.map((line) => JSON.parse(line));
|
||||
if (
|
||||
!diagnostics.some(
|
||||
(diagnostic) =>
|
||||
diagnostic.type === "bridge-diagnostic" &&
|
||||
diagnostic.category === "invalid_request" &&
|
||||
diagnostic.message === "Invalid Hopper bridge request",
|
||||
)
|
||||
)
|
||||
throw new Error("The MCP runtime omitted the correlated Hopper diagnostic");
|
||||
}
|
||||
|
||||
/** Verify named positive semantics from the source-owned C fixture. */
|
||||
export async function verifyRealHopperFixture({
|
||||
client,
|
||||
|
||||
@@ -0,0 +1,19 @@
|
||||
export interface PackageRunnerSetupInput {
|
||||
readonly args: readonly string[];
|
||||
readonly environment: Readonly<Record<string, string | undefined>>;
|
||||
readonly packageRoot: string;
|
||||
readonly packageName: string;
|
||||
}
|
||||
|
||||
export interface PackageRunnerSetupPlan {
|
||||
readonly command: "npm";
|
||||
readonly args: readonly string[];
|
||||
}
|
||||
|
||||
export function packageRunnerSetupPlan(
|
||||
input: PackageRunnerSetupInput,
|
||||
): PackageRunnerSetupPlan | undefined;
|
||||
|
||||
export function runPackageRunnerSetupBootstrap(
|
||||
input: PackageRunnerSetupInput,
|
||||
): Promise<number | undefined>;
|
||||
@@ -0,0 +1,72 @@
|
||||
import { spawn } from "node:child_process";
|
||||
import { resolve } from "node:path";
|
||||
|
||||
const BOOTSTRAP_MARKER = "REA_PACKAGE_RUNNER_BOOTSTRAPPED";
|
||||
|
||||
/**
|
||||
* Plan a current-release setup bootstrap when bare npx selected a project-local
|
||||
* package. Explicit `npm exec --package=<name>@<version>` rollbacks bypass it.
|
||||
*/
|
||||
export function packageRunnerSetupPlan(input) {
|
||||
if (input.args[0] !== "setup") return undefined;
|
||||
if (input.environment[BOOTSTRAP_MARKER] === "1") return undefined;
|
||||
if (input.environment.npm_lifecycle_event !== "npx") return undefined;
|
||||
|
||||
const localPrefix = input.environment.npm_config_local_prefix;
|
||||
if (localPrefix === undefined || localPrefix.length === 0) return undefined;
|
||||
if (
|
||||
!isPackageBelowLocalPrefix(
|
||||
input.packageRoot,
|
||||
localPrefix,
|
||||
input.packageName,
|
||||
)
|
||||
)
|
||||
return undefined;
|
||||
|
||||
const requestedPackage = input.environment.npm_config_package;
|
||||
if (
|
||||
requestedPackage !== undefined &&
|
||||
isExactPackageVersion(requestedPackage, input.packageName)
|
||||
)
|
||||
return undefined;
|
||||
|
||||
return {
|
||||
command: "npm",
|
||||
args: [
|
||||
"exec",
|
||||
"--yes",
|
||||
`--package=${input.packageName}@latest`,
|
||||
"--",
|
||||
"rea",
|
||||
...input.args,
|
||||
],
|
||||
};
|
||||
}
|
||||
|
||||
/** Execute a planned package-runner bootstrap and return its exit status. */
|
||||
export async function runPackageRunnerSetupBootstrap(input) {
|
||||
const plan = packageRunnerSetupPlan(input);
|
||||
if (plan === undefined) return undefined;
|
||||
|
||||
return await new Promise((resolveExitCode) => {
|
||||
const child = spawn(plan.command, plan.args, {
|
||||
stdio: "inherit",
|
||||
env: { ...input.environment, [BOOTSTRAP_MARKER]: "1" },
|
||||
});
|
||||
child.once("error", () => resolveExitCode(1));
|
||||
child.once("exit", (code) => resolveExitCode(code ?? 1));
|
||||
});
|
||||
}
|
||||
|
||||
function isPackageBelowLocalPrefix(packageRoot, localPrefix, packageName) {
|
||||
const expectedRoot = resolve(localPrefix, "node_modules", packageName);
|
||||
return resolve(packageRoot) === expectedRoot;
|
||||
}
|
||||
|
||||
function isExactPackageVersion(packageSpecifier, packageName) {
|
||||
const version = packageSpecifier.slice(`${packageName}@`.length);
|
||||
return (
|
||||
packageSpecifier.startsWith(`${packageName}@`) &&
|
||||
/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/u.test(version)
|
||||
);
|
||||
}
|
||||
+11
-1
@@ -4,6 +4,8 @@ import { access } from "node:fs/promises";
|
||||
import { dirname, resolve } from "node:path";
|
||||
import { fileURLToPath } from "node:url";
|
||||
|
||||
import { runPackageRunnerSetupBootstrap } from "./package-runner-bootstrap.mjs";
|
||||
|
||||
// Route production MCP before importing Incur. Incur owns registration helpers
|
||||
// such as `mcp add`, while only dist/main.js may serve the stdio tool catalog.
|
||||
const args = process.argv.slice(2);
|
||||
@@ -15,13 +17,21 @@ const isMcpMode =
|
||||
args.length === 1 && (args[0] === "--mcp" || args[0] === "mcp");
|
||||
const isMcpDoctorMode = args[0] === "mcp" && args[1] === "doctor";
|
||||
const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
|
||||
const bootstrapExitCode = await runPackageRunnerSetupBootstrap({
|
||||
args,
|
||||
environment: process.env,
|
||||
packageRoot,
|
||||
packageName: packageJson.name,
|
||||
});
|
||||
const runtimeFiles = isMcpMode
|
||||
? ["dist/main.js"]
|
||||
: isMcpDoctorMode
|
||||
? ["dist/main.js", "dist/mcpDoctor.js"]
|
||||
: ["dist/cli.js", "dist/cliOutput.js"];
|
||||
|
||||
if (!(await compiledRuntimeExists(runtimeFiles))) {
|
||||
if (bootstrapExitCode !== undefined) {
|
||||
process.exitCode = bootstrapExitCode;
|
||||
} else if (!(await compiledRuntimeExists(runtimeFiles))) {
|
||||
process.stderr.write(
|
||||
`REA's compiled runtime is missing. Run \`npm ci\` in ${packageRoot} to install dependencies and build REA, then restart it. If this is an installed package, reinstall rea-agents.\n`,
|
||||
);
|
||||
|
||||
@@ -8,6 +8,7 @@ import { fileURLToPath } from "node:url";
|
||||
import { createPackage } from "@electron/asar";
|
||||
|
||||
import { evaluateCodexEvents } from "../dist/evaluation/CodexAgentEval.js";
|
||||
import { MCP_STARTUP_POLICY } from "../dist/mcpStartupPolicy.js";
|
||||
import { completeVerifierRun, createVerifierRun } from "./lib/verifier-run.mjs";
|
||||
|
||||
const repositoryRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
|
||||
@@ -33,7 +34,16 @@ try {
|
||||
skillDestination,
|
||||
{ recursive: true },
|
||||
);
|
||||
const targets = await createTargets(fixtureRoot);
|
||||
const requestedScenarioIds = new Set(
|
||||
(process.env.REA_AGENT_EVAL_SCENARIOS ?? "")
|
||||
.split(",")
|
||||
.map((value) => value.trim())
|
||||
.filter((value) => value.length > 0),
|
||||
);
|
||||
const targets = await createTargets(
|
||||
fixtureRoot,
|
||||
requestedScenarioIds.size === 0 || requestedScenarioIds.has("managed"),
|
||||
);
|
||||
const allScenarios = [
|
||||
{
|
||||
id: "native",
|
||||
@@ -93,13 +103,23 @@ try {
|
||||
prompt:
|
||||
"A user-owned page is already open at http://127.0.0.1:3000 through the approved local debugging endpoint http://127.0.0.1:9222. Inspect what is available without navigating or executing page code, and report any authority or availability limits.",
|
||||
},
|
||||
{
|
||||
id: "navigation-context",
|
||||
expectedFirstTool: "get_navigation_context",
|
||||
requiresEvidence: false,
|
||||
requiredAnswerTermGroups: [["unavailable", "could not", "session"]],
|
||||
prompt:
|
||||
"Report the selected document, current address, and containing procedure from the current native-analysis session in one coherent request. If no native session is available, report that limitation plainly.",
|
||||
},
|
||||
{
|
||||
id: "address-context",
|
||||
expectedFirstTool: "inspect_address_context",
|
||||
requiresEvidence: false,
|
||||
requiredAnswerTermGroups: [["unavailable", "could not", "session"]],
|
||||
prompt:
|
||||
"Inspect explicit address 0x401000 in the current native-analysis session. Report its analyzed name, containing procedure, regular comment, inline comment, and matching bookmarks. If no native session is available, report that limitation plainly.",
|
||||
},
|
||||
];
|
||||
const requestedScenarioIds = new Set(
|
||||
(process.env.REA_AGENT_EVAL_SCENARIOS ?? "")
|
||||
.split(",")
|
||||
.map((value) => value.trim())
|
||||
.filter((value) => value.length > 0),
|
||||
);
|
||||
const scenarios =
|
||||
requestedScenarioIds.size === 0
|
||||
? allScenarios
|
||||
@@ -233,7 +253,7 @@ try {
|
||||
await rm(evaluationRoot, { recursive: true, force: true });
|
||||
}
|
||||
|
||||
async function createTargets(root) {
|
||||
async function createTargets(root, includeManaged) {
|
||||
const javascript = join(root, "desktop-app");
|
||||
await mkdir(join(javascript, "renderer"), { recursive: true });
|
||||
await Promise.all([
|
||||
@@ -274,33 +294,35 @@ async function createTargets(root) {
|
||||
),
|
||||
]);
|
||||
|
||||
const managedProject = join(root, "managed-project");
|
||||
const managedOutput = join(root, "managed-output");
|
||||
await mkdir(managedProject, { recursive: true });
|
||||
await Promise.all([
|
||||
writeFile(
|
||||
join(managedProject, "AgentEval.csproj"),
|
||||
'<Project Sdk="Microsoft.NET.Sdk"><PropertyGroup><OutputType>Exe</OutputType><TargetFramework>net8.0</TargetFramework><ImplicitUsings>enable</ImplicitUsings><Nullable>enable</Nullable></PropertyGroup></Project>\n',
|
||||
),
|
||||
writeFile(
|
||||
join(managedProject, "Program.cs"),
|
||||
'namespace AgentEval; public sealed record Profile(string Id); public static class Program { public static void Main() => Console.WriteLine(new Profile("fixture")); }\n',
|
||||
),
|
||||
]);
|
||||
await runProcess(
|
||||
"dotnet",
|
||||
[
|
||||
"build",
|
||||
join(managedProject, "AgentEval.csproj"),
|
||||
"--configuration",
|
||||
"Release",
|
||||
"--output",
|
||||
managedOutput,
|
||||
"--nologo",
|
||||
],
|
||||
root,
|
||||
120_000,
|
||||
);
|
||||
if (includeManaged) {
|
||||
const managedProject = join(root, "managed-project");
|
||||
await mkdir(managedProject, { recursive: true });
|
||||
await Promise.all([
|
||||
writeFile(
|
||||
join(managedProject, "AgentEval.csproj"),
|
||||
'<Project Sdk="Microsoft.NET.Sdk"><PropertyGroup><OutputType>Exe</OutputType><TargetFramework>net8.0</TargetFramework><ImplicitUsings>enable</ImplicitUsings><Nullable>enable</Nullable></PropertyGroup></Project>\n',
|
||||
),
|
||||
writeFile(
|
||||
join(managedProject, "Program.cs"),
|
||||
'namespace AgentEval; public sealed record Profile(string Id); public static class Program { public static void Main() => Console.WriteLine(new Profile("fixture")); }\n',
|
||||
),
|
||||
]);
|
||||
await runProcess(
|
||||
"dotnet",
|
||||
[
|
||||
"build",
|
||||
join(managedProject, "AgentEval.csproj"),
|
||||
"--configuration",
|
||||
"Release",
|
||||
"--output",
|
||||
managedOutput,
|
||||
"--nologo",
|
||||
],
|
||||
root,
|
||||
120_000,
|
||||
);
|
||||
}
|
||||
return {
|
||||
native: "/bin/true",
|
||||
javascript: javascriptAsar,
|
||||
@@ -346,7 +368,7 @@ async function runCodex(prompt, investigationRoot) {
|
||||
"-c",
|
||||
`mcp_servers.rea.args=${JSON.stringify([join(repositoryRoot, "scripts/rea.mjs"), "mcp"])}`,
|
||||
"-c",
|
||||
"mcp_servers.rea.startup_timeout_sec=30",
|
||||
`mcp_servers.rea.startup_timeout_sec=${String(MCP_STARTUP_POLICY.codexStartupTimeoutSeconds)}`,
|
||||
"-c",
|
||||
mcpEnvironmentOverride,
|
||||
...(optionalModel === undefined ? [] : ["--model", optionalModel]),
|
||||
|
||||
@@ -1,4 +1,5 @@
|
||||
import { mkdir, writeFile } from "node:fs/promises";
|
||||
import { mkdir, readFile, writeFile } from "node:fs/promises";
|
||||
import { isDeepStrictEqual } from "node:util";
|
||||
import { join } from "node:path";
|
||||
import { TextReader, Uint8ArrayWriter, ZipWriter } from "@zip.js/zip.js";
|
||||
|
||||
@@ -21,12 +22,30 @@ export async function verifyPackageArtifactAndElectron({
|
||||
environment,
|
||||
),
|
||||
);
|
||||
const repeatedArtifactInventory = json(
|
||||
await run(
|
||||
cli,
|
||||
["inventory-artifact", artifactArchive, "--limit", "500", "--json"],
|
||||
environment,
|
||||
),
|
||||
);
|
||||
if (
|
||||
artifactInventory.operation !== "inventory_artifact" ||
|
||||
artifactInventory.provider?.id !== "rea-artifact-graph" ||
|
||||
artifactInventory.normalized_result?.manifest?.root_format !== "zip"
|
||||
artifactInventory.normalized_result?.manifest?.root_format !== "zip" ||
|
||||
!sameArtifactIdentity(
|
||||
artifactInventory.normalized_result,
|
||||
repeatedArtifactInventory.normalized_result,
|
||||
)
|
||||
)
|
||||
throw new Error("packaged artifact inventory CLI failed");
|
||||
await verifyPackagedArtifactExtraction({
|
||||
artifactArchive,
|
||||
artifactInventory,
|
||||
cli,
|
||||
environment,
|
||||
workspace,
|
||||
});
|
||||
const applicationRoot = join(workspace, "electron-app");
|
||||
await mkdir(applicationRoot);
|
||||
await writeFile(
|
||||
@@ -73,6 +92,51 @@ export async function verifyPackageArtifactAndElectron({
|
||||
return { artifactArchive };
|
||||
}
|
||||
|
||||
const sameArtifactIdentity = (left, right) =>
|
||||
isDeepStrictEqual(left?.manifest, right?.manifest) &&
|
||||
isDeepStrictEqual(left?.nodes?.items, right?.nodes?.items) &&
|
||||
isDeepStrictEqual(left?.occurrences?.items, right?.occurrences?.items) &&
|
||||
isDeepStrictEqual(left?.edges?.items, right?.edges?.items);
|
||||
|
||||
const verifyPackagedArtifactExtraction = async ({
|
||||
artifactArchive,
|
||||
artifactInventory,
|
||||
cli,
|
||||
environment,
|
||||
workspace,
|
||||
}) => {
|
||||
const occurrence =
|
||||
artifactInventory.normalized_result?.occurrences?.items?.find(
|
||||
({ logical_path: path }) => path === "app/main.js",
|
||||
);
|
||||
if (occurrence?.occurrence_id === undefined)
|
||||
throw new Error("packaged artifact inventory omitted the selected member");
|
||||
const outputRoot = join(workspace, "artifact-extraction");
|
||||
const extraction = json(
|
||||
await run(
|
||||
cli,
|
||||
[
|
||||
"extract-artifact",
|
||||
artifactArchive,
|
||||
outputRoot,
|
||||
"--occurrence-ids",
|
||||
occurrence.occurrence_id,
|
||||
"--json",
|
||||
],
|
||||
environment,
|
||||
),
|
||||
);
|
||||
if (
|
||||
extraction.operation !== "extract_artifact" ||
|
||||
extraction.provider?.id !== "rea-artifact-graph" ||
|
||||
extraction.normalized_result?.containment_verified !== true ||
|
||||
extraction.normalized_result?.artifacts?.items?.[0]?.relative_path !==
|
||||
"app/main.js" ||
|
||||
(await readFile(join(outputRoot, "app/main.js"), "utf8")) !== "main();"
|
||||
)
|
||||
throw new Error("packaged artifact extraction CLI failed");
|
||||
};
|
||||
|
||||
const assertRoutedApplicationAnalysis = (analysis) => {
|
||||
if (
|
||||
analysis.operation !== "analyze_javascript_application" ||
|
||||
|
||||
@@ -5,6 +5,7 @@ import { promisify } from "node:util";
|
||||
|
||||
import { Client } from "@modelcontextprotocol/client";
|
||||
import { StdioClientTransport } from "@modelcontextprotocol/client/stdio";
|
||||
import { MCP_STARTUP_POLICY } from "../dist/mcpStartupPolicy.js";
|
||||
import * as prompts from "./verify-package-prompts.mjs";
|
||||
import {
|
||||
json,
|
||||
@@ -180,7 +181,7 @@ export async function verifyPackageMcp({
|
||||
(
|
||||
await execute(cli, ["mcp", "doctor", "--json"], {
|
||||
env: environment,
|
||||
timeout: 30_000,
|
||||
timeout: MCP_STARTUP_POLICY.doctorDeadlineMs,
|
||||
})
|
||||
).stdout,
|
||||
);
|
||||
|
||||
@@ -4,6 +4,7 @@ import { join } from "node:path";
|
||||
|
||||
import { TOOL_CONTRACTS } from "../dist/contracts/toolContracts.js";
|
||||
import { PRODUCT_IDENTITY } from "../dist/identity.js";
|
||||
import { MCP_STARTUP_POLICY } from "../dist/mcpStartupPolicy.js";
|
||||
import * as prompts from "./verify-package-prompts.mjs";
|
||||
import { verifyPackagedInvestigation } from "./verify-package-investigation.mjs";
|
||||
import { verifyPackageArtifactAndElectron } from "./verify-package-artifact.mjs";
|
||||
@@ -19,6 +20,10 @@ import { verifyPackageSetup } from "./verify-package-setup.mjs";
|
||||
import { verifyManaged } from "./verify-package-managed.mjs";
|
||||
import { verifyUnknownProvider } from "./verify-package-unknown-provider.mjs";
|
||||
import { completeVerifierRun, createVerifierRun } from "./lib/verifier-run.mjs";
|
||||
import {
|
||||
measureMcpStartup,
|
||||
profileMcpModuleLoading,
|
||||
} from "./lib/mcp-startup-probe.mjs";
|
||||
|
||||
const root = process.cwd();
|
||||
const verifierRun = createVerifierRun();
|
||||
@@ -26,6 +31,8 @@ const workspace = await mkdtemp(join(tmpdir(), "rea-package-"));
|
||||
const evidenceRoot = join(workspace, "evidence");
|
||||
const referenceRoot = join(workspace, "reference-source");
|
||||
let tarball;
|
||||
let mcpStartup;
|
||||
let mcpModuleLoading;
|
||||
|
||||
try {
|
||||
({ tarball } = await verifyPackagePack({ root, workspace }));
|
||||
@@ -42,6 +49,25 @@ try {
|
||||
workspace,
|
||||
environment: environmentData.environment,
|
||||
});
|
||||
mcpStartup = await measureMcpStartup({
|
||||
command: cli,
|
||||
args: ["mcp"],
|
||||
environment: {
|
||||
...environmentData.environment,
|
||||
REA_INVESTIGATION_INPUT_ROOTS_JSON: JSON.stringify([]),
|
||||
},
|
||||
policy: MCP_STARTUP_POLICY,
|
||||
});
|
||||
mcpModuleLoading = await profileMcpModuleLoading({
|
||||
command: cli,
|
||||
args: ["mcp"],
|
||||
environment: {
|
||||
...environmentData.environment,
|
||||
REA_INVESTIGATION_INPUT_ROOTS_JSON: JSON.stringify([]),
|
||||
},
|
||||
policy: MCP_STARTUP_POLICY,
|
||||
packageName: PRODUCT_IDENTITY.packageName,
|
||||
});
|
||||
const { supportedSetupHost } = await verifyPackageDiscovery({
|
||||
cli,
|
||||
environment: environmentData.environment,
|
||||
@@ -102,7 +128,7 @@ try {
|
||||
investigationReplay,
|
||||
});
|
||||
process.stdout.write(
|
||||
`${JSON.stringify({ verifier_run: await completeVerifierRun(verifierRun), cli: true, analysisCli: true, artifactCli: true, managedCli: true, managedReconstructionCli: true, managedNativeVerificationCli: true, managedRuntimePlanCli: true, managedApplicationGraphCli: true, evidenceCli: true, incurMcpCommand: PRODUCT_IDENTITY.mcpCommand, lifecycleScriptsRequired: false, doctor: "platform-appropriate", setup: supportedSetupHost ? "planned-then-idempotent" : "unsupported-host-rejected", setupPlanReadOnly: supportedSetupHost, existingHopperPreserved: supportedSetupHost, clients: supportedSetupHost ? 3 : 0, backupReadback: supportedSetupHost, failureRecovery: supportedSetupHost, configSymlinkLifecycle: supportedSetupHost, skill: supportedSetupHost, skillReferences: supportedSetupHost, mcpTools: TOOL_CONTRACTS.length, mcpPrompts: prompts.names.length, promptCompletion: true, promptCompletionLifecycle: true, evidenceMcp: true, targetFree: true, targetLifecycle: true, boundedRegexBridge: true })}\n`,
|
||||
`${JSON.stringify({ verifier_run: await completeVerifierRun(verifierRun), cli: true, analysisCli: true, artifactCli: true, managedCli: true, managedReconstructionCli: true, managedNativeVerificationCli: true, managedRuntimePlanCli: true, managedApplicationGraphCli: true, evidenceCli: true, incurMcpCommand: PRODUCT_IDENTITY.mcpCommand, lifecycleScriptsRequired: false, doctor: "platform-appropriate", setup: supportedSetupHost ? "planned-then-idempotent" : "unsupported-host-rejected", setupPlanReadOnly: supportedSetupHost, existingHopperPreserved: supportedSetupHost, clients: supportedSetupHost ? 3 : 0, backupReadback: supportedSetupHost, failureRecovery: supportedSetupHost, configSymlinkLifecycle: supportedSetupHost, skill: supportedSetupHost, skillReferences: supportedSetupHost, mcpTools: TOOL_CONTRACTS.length, mcpPrompts: prompts.names.length, promptCompletion: true, promptCompletionLifecycle: true, evidenceMcp: true, targetFree: true, targetLifecycle: true, boundedRegexBridge: true, mcpStartup, mcpModuleLoading })}\n`,
|
||||
);
|
||||
} finally {
|
||||
if (tarball) await rm(join(root, tarball), { force: true });
|
||||
|
||||
@@ -1,13 +1,18 @@
|
||||
import { Client } from "@modelcontextprotocol/client";
|
||||
import { StdioClientTransport } from "@modelcontextprotocol/client/stdio";
|
||||
import { mkdtemp, rm } from "node:fs/promises";
|
||||
import { execFile } from "node:child_process";
|
||||
import { mkdtemp, readFile, rm } from "node:fs/promises";
|
||||
import { tmpdir } from "node:os";
|
||||
import { join } from "node:path";
|
||||
import { delimiter, join } from "node:path";
|
||||
import { promisify } from "node:util";
|
||||
|
||||
import { lt, rcompare } from "semver";
|
||||
|
||||
import { CATALOG_IDENTITY } from "../dist/catalogIdentity.js";
|
||||
import { completeVerifierRun, createVerifierRun } from "./lib/verifier-run.mjs";
|
||||
|
||||
const verifierRun = createVerifierRun();
|
||||
const execFileAsync = promisify(execFile);
|
||||
const version = process.argv[2];
|
||||
if (!/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/u.test(version ?? ""))
|
||||
throw new Error("Usage: node scripts/verify-published-package.mjs <version>");
|
||||
@@ -39,6 +44,7 @@ transport.stderr?.on("data", (chunk) => {
|
||||
});
|
||||
|
||||
let publishedToolCount = 0;
|
||||
let upgrade;
|
||||
|
||||
try {
|
||||
await client.connect(transport);
|
||||
@@ -65,8 +71,11 @@ try {
|
||||
});
|
||||
if (status.isError === true)
|
||||
throw new Error("Published target-free MCP session check failed");
|
||||
upgrade = await verifyPublishedUpgrade({ version, canaryRoot });
|
||||
} catch (cause) {
|
||||
throw new Error(`Published MCP canary failed: ${stderr}`, { cause });
|
||||
throw new Error(`Published package verification failed: ${stderr}`, {
|
||||
cause,
|
||||
});
|
||||
} finally {
|
||||
try {
|
||||
await client.close();
|
||||
@@ -77,5 +86,96 @@ try {
|
||||
}
|
||||
|
||||
process.stdout.write(
|
||||
`${JSON.stringify({ verifier_run: await completeVerifierRun(verifierRun), package: "rea-agents", version, mcpTools: publishedToolCount, canonicalMcpTools: CATALOG_IDENTITY.counts.mcp_tools })}\n`,
|
||||
`${JSON.stringify({ verifier_run: await completeVerifierRun(verifierRun), package: "rea-agents", version, mcpTools: publishedToolCount, canonicalMcpTools: CATALOG_IDENTITY.counts.mcp_tools, upgrade })}\n`,
|
||||
);
|
||||
|
||||
async function verifyPublishedUpgrade({ version: targetVersion, canaryRoot }) {
|
||||
const previousVersion = await findPreviousPublishedVersion(targetVersion);
|
||||
const prefix = join(canaryRoot, "upgrade-prefix");
|
||||
const home = join(canaryRoot, "upgrade-home");
|
||||
const environment = {
|
||||
...process.env,
|
||||
HOME: home,
|
||||
npm_config_cache: join(canaryRoot, "upgrade-cache"),
|
||||
npm_config_prefix: prefix,
|
||||
PATH: `${join(prefix, "bin")}${delimiter}${process.env.PATH ?? ""}`,
|
||||
};
|
||||
|
||||
await execFileAsync(
|
||||
"npm",
|
||||
[
|
||||
"install",
|
||||
"--global",
|
||||
"--ignore-scripts",
|
||||
"--prefix",
|
||||
prefix,
|
||||
`rea-agents@${previousVersion}`,
|
||||
],
|
||||
{ cwd: canaryRoot, env: environment, maxBuffer: 16 * 1024 * 1024 },
|
||||
);
|
||||
|
||||
const { stdout } = await execFileAsync(
|
||||
"npx",
|
||||
["rea-agents", "upgrade", "--json"],
|
||||
{ cwd: canaryRoot, env: environment, maxBuffer: 16 * 1024 * 1024 },
|
||||
);
|
||||
const result = JSON.parse(stdout);
|
||||
if (
|
||||
result.status !== "upgraded" ||
|
||||
result.previousVersion !== previousVersion ||
|
||||
result.latestVersion !== targetVersion
|
||||
)
|
||||
throw new Error(
|
||||
`npx rea-agents upgrade did not upgrade ${previousVersion} to ${targetVersion}: ${stdout}`,
|
||||
);
|
||||
|
||||
const npmRoot = (
|
||||
await execFileAsync("npm", ["root", "--global"], {
|
||||
cwd: canaryRoot,
|
||||
env: environment,
|
||||
})
|
||||
).stdout.trim();
|
||||
const installed = JSON.parse(
|
||||
await readFile(join(npmRoot, "rea-agents", "package.json"), "utf8"),
|
||||
);
|
||||
if (installed.version !== targetVersion)
|
||||
throw new Error(
|
||||
`npx rea-agents upgrade installed ${installed.version}, expected ${targetVersion}`,
|
||||
);
|
||||
|
||||
const help = (
|
||||
await execFileAsync(join(prefix, "bin", "rea-agents"), ["--help"], {
|
||||
cwd: canaryRoot,
|
||||
env: environment,
|
||||
})
|
||||
).stdout;
|
||||
if (!help.includes("setup"))
|
||||
throw new Error("the upgraded rea-agents executable did not start");
|
||||
|
||||
return {
|
||||
status: result.status,
|
||||
previousVersion,
|
||||
latestVersion: result.latestVersion,
|
||||
installedVersion: installed.version,
|
||||
};
|
||||
}
|
||||
|
||||
async function findPreviousPublishedVersion(targetVersion) {
|
||||
const { stdout } = await execFileAsync(
|
||||
"npm",
|
||||
["view", "rea-agents", "versions", "--json"],
|
||||
{ maxBuffer: 16 * 1024 * 1024 },
|
||||
);
|
||||
const versions = JSON.parse(stdout);
|
||||
const previous = versions
|
||||
.filter(
|
||||
(candidate) =>
|
||||
typeof candidate === "string" && lt(candidate, targetVersion),
|
||||
)
|
||||
.sort(rcompare)[0];
|
||||
if (previous === undefined)
|
||||
throw new Error(
|
||||
`No published rea-agents version precedes ${targetVersion}`,
|
||||
);
|
||||
return previous;
|
||||
}
|
||||
|
||||
@@ -55,9 +55,11 @@ export function assertDossier(
|
||||
expectedString = null,
|
||||
requireAssembly = false,
|
||||
requireMultiBlock = false,
|
||||
requireJumpTable = false,
|
||||
},
|
||||
) {
|
||||
assertDossierProcedure(dossier, address);
|
||||
assertNativeApiBoundary(dossier.native_api, requireJumpTable);
|
||||
assertDossierReferences(dossier);
|
||||
assertDossierCallees(dossier, expectedCallees);
|
||||
assertDossierStrings(dossier, expectedString);
|
||||
@@ -65,6 +67,78 @@ export function assertDossier(
|
||||
assertDossierMultiBlock(dossier, requireMultiBlock);
|
||||
}
|
||||
|
||||
export function assertDenseSwitchDossier(dossier, address) {
|
||||
assertDossier(dossier, {
|
||||
address,
|
||||
requireAssembly: true,
|
||||
requireMultiBlock: true,
|
||||
});
|
||||
const truncated = dossier.native_api.jump_tables.find(
|
||||
({ mappings_truncated: mappingsTruncated }) => mappingsTruncated,
|
||||
);
|
||||
if (
|
||||
truncated === undefined ||
|
||||
truncated.mappings.length !== 32 ||
|
||||
truncated.mappings.some(
|
||||
({ target_address: target, evidence }) =>
|
||||
!/^0x[0-9a-f]+$/u.test(target) ||
|
||||
!evidence.some(({ kind }) => kind === "jump-table"),
|
||||
)
|
||||
)
|
||||
throw new Error(
|
||||
`Ghidra dense jump-table truncation drifted: ${JSON.stringify(dossier.native_api.jump_tables)}`,
|
||||
);
|
||||
}
|
||||
|
||||
function assertNativeApiBoundary(observed, requireJumpTable) {
|
||||
if (
|
||||
observed?.available !== true ||
|
||||
observed.provenance !== "ghidra-high-function" ||
|
||||
observed.parameters_truncated !== false ||
|
||||
observed.jump_tables_truncated !== false ||
|
||||
!["low", "medium", "high"].includes(observed.return_type?.confidence) ||
|
||||
!observed.return_type?.evidence?.some(
|
||||
({ source }) => source === "ghidra-high-function",
|
||||
) ||
|
||||
observed.pseudocode?.classification !== "decompiler-generated-non-source" ||
|
||||
observed.pseudocode.compilable !== false ||
|
||||
!observed.decompiler_artifacts?.includes("pointer-arithmetic")
|
||||
)
|
||||
throw new Error(
|
||||
`Ghidra native API boundary drifted: ${JSON.stringify(observed)}`,
|
||||
);
|
||||
if (!requireJumpTable) return;
|
||||
if (
|
||||
observed.jump_tables.length === 0 ||
|
||||
!observed.jump_tables.some(
|
||||
({
|
||||
data_sources: sources,
|
||||
data_sources_truncated: sourcesTruncated,
|
||||
mappings,
|
||||
mappings_truncated: mappingsTruncated,
|
||||
}) =>
|
||||
!sourcesTruncated &&
|
||||
!mappingsTruncated &&
|
||||
sources.length > 0 &&
|
||||
sources.every(
|
||||
({ address, evidence }) =>
|
||||
/^0x[0-9a-f]+$/u.test(address) &&
|
||||
evidence.some(({ kind }) => kind === "jump-table"),
|
||||
) &&
|
||||
mappings.length > 0 &&
|
||||
mappings.every(
|
||||
({ target_address: target, data_addresses: addresses, evidence }) =>
|
||||
/^0x[0-9a-f]+$/u.test(target) &&
|
||||
addresses.every((address) => /^0x[0-9a-f]+$/u.test(address)) &&
|
||||
evidence.some(({ kind }) => kind === "jump-table"),
|
||||
),
|
||||
)
|
||||
)
|
||||
throw new Error(
|
||||
`Ghidra jump-table evidence drifted: ${JSON.stringify(observed.jump_tables)}`,
|
||||
);
|
||||
}
|
||||
|
||||
function assertDossierProcedure(dossier, address) {
|
||||
if (
|
||||
dossier.procedure.address !== address ||
|
||||
@@ -144,6 +218,14 @@ export function dossierSummary(dossier) {
|
||||
outgoing_references: dossier.outgoing_references.returned,
|
||||
referenced_strings: dossier.referenced_strings.returned,
|
||||
basic_blocks: dossier.basic_blocks.returned,
|
||||
native_parameters:
|
||||
dossier.native_api.available === true
|
||||
? dossier.native_api.parameters.length
|
||||
: null,
|
||||
jump_tables:
|
||||
dossier.native_api.available === true
|
||||
? dossier.native_api.jump_tables.length
|
||||
: null,
|
||||
};
|
||||
}
|
||||
|
||||
@@ -189,12 +271,15 @@ export async function assertCleanup(coordinates) {
|
||||
}
|
||||
|
||||
export function assertDebugFixture(observed) {
|
||||
const expectedDocument = `target-${observed.target.sha256.slice(0, 12)}.bin`;
|
||||
if (
|
||||
!Array.isArray(observed.documents) ||
|
||||
observed.documents.length !== 1 ||
|
||||
!observed.documents[0].includes("debug")
|
||||
observed.documents[0] !== expectedDocument
|
||||
)
|
||||
throw new Error("Ghidra did not expose exactly one debug Program identity");
|
||||
throw new Error(
|
||||
`Ghidra did not expose the digest-bound debug Program identity ${expectedDocument}: ${JSON.stringify(observed.documents)}`,
|
||||
);
|
||||
const entry = findValue(observed.procedures, "rea_ghidra_inventory_entry");
|
||||
const leaf = findValue(observed.procedures, "rea_ghidra_inventory_leaf");
|
||||
const external = observed.procedures.find(
|
||||
|
||||
@@ -2,8 +2,13 @@ import {
|
||||
parseGhidraFunctionInput,
|
||||
parseGhidraFunctionResult,
|
||||
} from "../dist/ghidra/GhidraFunctionValues.js";
|
||||
import {
|
||||
parseGhidraInventoryInput,
|
||||
parseGhidraInventoryResult,
|
||||
} from "../dist/ghidra/GhidraInventoryValues.js";
|
||||
|
||||
import {
|
||||
assertDenseSwitchDossier,
|
||||
assertDossier,
|
||||
assertLocalProcedureInfo,
|
||||
assertProviderText,
|
||||
@@ -27,6 +32,20 @@ async function functionCall(client, operation, parameters) {
|
||||
return parsed.value;
|
||||
}
|
||||
|
||||
async function inventoryCall(client, operation, parameters) {
|
||||
const input = parseGhidraInventoryInput(operation, parameters);
|
||||
if (!input.ok) throw input.error;
|
||||
const called = await client.callTool(operation, input.value);
|
||||
if (!called.ok)
|
||||
throw new Error(
|
||||
`Ghidra ${operation} failed for ${JSON.stringify(input.value)}: ${called.error.message}`,
|
||||
{ cause: called.error },
|
||||
);
|
||||
const parsed = parseGhidraInventoryResult(operation, called.value);
|
||||
if (!parsed.ok) throw parsed.error;
|
||||
return parsed.value;
|
||||
}
|
||||
|
||||
export async function verifyDebugFunctionOperations(
|
||||
client,
|
||||
{ procedures, strings, entry },
|
||||
@@ -37,6 +56,14 @@ export async function verifyDebugFunctionOperations(
|
||||
procedures,
|
||||
"rea_ghidra_inventory_indirect",
|
||||
);
|
||||
const switchProcedure = requireProcedure(
|
||||
procedures,
|
||||
"rea_ghidra_inventory_switch",
|
||||
);
|
||||
const denseSwitchProcedure = requireProcedure(
|
||||
procedures,
|
||||
"rea_ghidra_inventory_dense_switch",
|
||||
);
|
||||
const main = requireProcedure(procedures, "main");
|
||||
const entryString = strings.find(
|
||||
(item) => item.value === "REA_GHIDRA_INVENTORY_ENTRY",
|
||||
@@ -88,6 +115,15 @@ export async function verifyDebugFunctionOperations(
|
||||
);
|
||||
const branchDossier = await analyzeBranchDossier(client, branch);
|
||||
const indirectDossier = await analyzeIndirectDossier(client, indirect);
|
||||
const switchDossier = await analyzeSwitchDossier(client, switchProcedure);
|
||||
const denseSwitchDossier = await functionCall(client, "analyze_function", {
|
||||
procedure: denseSwitchProcedure.address,
|
||||
include_assembly: true,
|
||||
limit: 500,
|
||||
max_pseudocode_chars: 100_000,
|
||||
max_instructions: 5_000,
|
||||
});
|
||||
assertDenseSwitchDossier(denseSwitchDossier, denseSwitchProcedure.address);
|
||||
assertIndirectDossier(indirectDossier, leaf.address);
|
||||
|
||||
const { cancellation, timeout } = await verifyRequestCancellationAndTimeout(
|
||||
@@ -100,6 +136,8 @@ export async function verifyDebugFunctionOperations(
|
||||
entry: dossierSummary(entryDossier),
|
||||
branch: dossierSummary(branchDossier),
|
||||
indirect: dossierSummary(indirectDossier),
|
||||
switch: dossierSummary(switchDossier),
|
||||
dense_switch: dossierSummary(denseSwitchDossier),
|
||||
instruction_window: {
|
||||
returned: instructionWindow.instructions.returned,
|
||||
truncated: instructionWindow.instructions.truncated,
|
||||
@@ -164,7 +202,7 @@ async function resolveXrefOwners(client, entryXrefs) {
|
||||
for (const address of entryXrefs) {
|
||||
try {
|
||||
xrefOwners.push(
|
||||
await functionCall(client, "resolve_containing_procedure", {
|
||||
await inventoryCall(client, "resolve_containing_procedure", {
|
||||
document: null,
|
||||
address,
|
||||
}),
|
||||
@@ -222,6 +260,23 @@ async function analyzeEntryDossier(client, entry, branch, indirect) {
|
||||
return entryDossier;
|
||||
}
|
||||
|
||||
async function analyzeSwitchDossier(client, switchProcedure) {
|
||||
const dossier = await functionCall(client, "analyze_function", {
|
||||
procedure: switchProcedure.address,
|
||||
include_assembly: true,
|
||||
limit: 500,
|
||||
max_pseudocode_chars: 100_000,
|
||||
max_instructions: 5_000,
|
||||
});
|
||||
assertDossier(dossier, {
|
||||
address: switchProcedure.address,
|
||||
requireAssembly: true,
|
||||
requireMultiBlock: true,
|
||||
requireJumpTable: true,
|
||||
});
|
||||
return dossier;
|
||||
}
|
||||
|
||||
async function analyzeBranchDossier(client, branch) {
|
||||
const branchDossier = await functionCall(client, "analyze_function", {
|
||||
procedure: branch.address,
|
||||
@@ -310,7 +365,7 @@ export async function verifyStrippedFunctionOperations(client, entryString) {
|
||||
});
|
||||
if (stringXrefs.length === 0)
|
||||
throw new Error("Ghidra stripped string xref probe is unavailable");
|
||||
const containing = await functionCall(
|
||||
const containing = await inventoryCall(
|
||||
client,
|
||||
"resolve_containing_procedure",
|
||||
{
|
||||
@@ -339,7 +394,7 @@ export async function verifyStrippedFunctionOperations(client, entryString) {
|
||||
expectedString: "REA_GHIDRA_INVENTORY_ENTRY",
|
||||
requireAssembly: true,
|
||||
});
|
||||
if (symbolTail(dossier.procedure.name) === "rea_ghidra_inventory_entry")
|
||||
if (matchesSymbol(dossier.procedure.name, "rea_ghidra_inventory_entry"))
|
||||
throw new Error("Ghidra stripped dossier invented a source symbol");
|
||||
return dossierSummary(dossier);
|
||||
}
|
||||
@@ -424,7 +479,7 @@ export async function verifyCrossFormatOperations({
|
||||
|
||||
async function findCrossStringOwner(client, messageXrefs) {
|
||||
for (const address of messageXrefs) {
|
||||
const candidate = await functionCall(
|
||||
const candidate = await inventoryCall(
|
||||
client,
|
||||
"resolve_containing_procedure",
|
||||
{
|
||||
|
||||
@@ -126,25 +126,28 @@ try {
|
||||
format: "elf",
|
||||
architecture: "x86_64",
|
||||
});
|
||||
assertDebugFixture(debug);
|
||||
const nativeApiCli = await verifyNativeApiCli(debugPath);
|
||||
const stripped = await verifyTarget(strippedPath, "stripped", {
|
||||
format: "elf",
|
||||
architecture: "x86_64",
|
||||
});
|
||||
assertStrippedFixture(stripped);
|
||||
const arm64Elf = await verifyTarget(arm64ElfPath, "cross-arm64-elf", {
|
||||
format: "elf",
|
||||
architecture: "arm64",
|
||||
});
|
||||
assertCrossFixture(arm64Elf);
|
||||
const pe = await verifyTarget(pePath, "cross-x86_64-pe", {
|
||||
format: "pe",
|
||||
architecture: "x86_64",
|
||||
});
|
||||
assertCrossFixture(pe);
|
||||
const machObject = await verifyTarget(machObjectPath, "cross-x86_64-mach-o", {
|
||||
format: "mach-o",
|
||||
architecture: "x86_64",
|
||||
});
|
||||
assertDebugFixture(debug);
|
||||
assertStrippedFixture(stripped);
|
||||
for (const fixture of [arm64Elf, pe, machObject]) assertCrossFixture(fixture);
|
||||
assertCrossFixture(machObject);
|
||||
await assertMalformedFixture(malformedPath);
|
||||
|
||||
const customPath = process.env.GHIDRA_TARGET_PATH;
|
||||
@@ -164,6 +167,7 @@ try {
|
||||
summary(machObject),
|
||||
],
|
||||
malformed_target: "rejected-before-provider-start",
|
||||
native_api_cli: nativeApiCli,
|
||||
custom_target: custom === null ? null : summary(custom),
|
||||
cleanup: "complete",
|
||||
})}\n`,
|
||||
@@ -172,6 +176,52 @@ try {
|
||||
await rm(fixtureRoot, { recursive: true, force: true });
|
||||
}
|
||||
|
||||
async function verifyNativeApiCli(targetPath) {
|
||||
const { stdout } = await exec(
|
||||
process.execPath,
|
||||
[
|
||||
"scripts/rea.mjs",
|
||||
"inspect-native-api",
|
||||
targetPath,
|
||||
"rea_ghidra_inventory_dense_switch",
|
||||
"--provider",
|
||||
"ghidra",
|
||||
"--json",
|
||||
],
|
||||
{
|
||||
cwd: process.cwd(),
|
||||
env: process.env,
|
||||
maxBuffer: 2 * 1024 * 1024,
|
||||
},
|
||||
);
|
||||
const evidence = JSON.parse(stdout);
|
||||
const boundary = evidence.normalized_result?.boundary;
|
||||
const truncated = boundary?.jump_tables?.find(
|
||||
({ mappings_truncated: mappingsTruncated }) => mappingsTruncated === true,
|
||||
);
|
||||
const omittedQuestion =
|
||||
"Which additional data sources or targets were omitted";
|
||||
if (
|
||||
evidence.operation !== "inspect_native_api" ||
|
||||
evidence.provider?.id !== "rea-workflow" ||
|
||||
evidence.analysis_profile?.provider?.id !== "rea-workflow" ||
|
||||
boundary?.available !== true ||
|
||||
truncated?.mappings?.length !== 32 ||
|
||||
!evidence.normalized_result?.residual_unknowns?.some((question) =>
|
||||
question.includes(omittedQuestion),
|
||||
)
|
||||
)
|
||||
throw new Error(
|
||||
`The shipped inspect-native-api CLI did not preserve dense jump-table truncation: ${stdout}`,
|
||||
);
|
||||
return {
|
||||
operation: evidence.operation,
|
||||
provider: evidence.provider,
|
||||
mappings_returned: truncated.mappings.length,
|
||||
residual_unknowns: evidence.normalized_result.residual_unknowns.length,
|
||||
};
|
||||
}
|
||||
|
||||
async function verifyTarget(targetPath, variant, expectedTarget = null) {
|
||||
const parsedTarget = await parseBinaryTarget(targetPath);
|
||||
if (!parsedTarget.ok) throw parsedTarget.error;
|
||||
|
||||
@@ -5,7 +5,6 @@ import { promisify } from "node:util";
|
||||
import { Client } from "@modelcontextprotocol/client";
|
||||
import { StdioClientTransport } from "@modelcontextprotocol/client/stdio";
|
||||
|
||||
import { TOOL_CONTRACTS } from "../dist/contracts/toolContracts.js";
|
||||
import {
|
||||
firstProcedureAddress,
|
||||
requireAddressArray,
|
||||
@@ -16,8 +15,11 @@ import { HOPPER_PROVIDER_IDENTITY } from "../dist/hopper/HopperProvider.js";
|
||||
import { REA_WORKFLOW_PROVIDER } from "../dist/application/InvestigationProviders.js";
|
||||
import { loadRealHopperFixtureTargets } from "./lib/real-hopper-fixture.mjs";
|
||||
import {
|
||||
requireBridgeDiagnostic,
|
||||
requireBridgeProgress,
|
||||
requireCurrentDocument,
|
||||
requireSafeDiagnostics,
|
||||
requireTruthfulMemoryRegions,
|
||||
verifyRealHopperFixture,
|
||||
} from "./lib/real-hopper-semantic.mjs";
|
||||
import {
|
||||
@@ -99,30 +101,6 @@ const requireOverview = (value, operation) => {
|
||||
return value;
|
||||
};
|
||||
|
||||
const requireTruthfulMemoryRegions = (segments) => {
|
||||
if (!Array.isArray(segments) || segments.length === 0) {
|
||||
throw new Error("list_segments returned no real memory regions");
|
||||
}
|
||||
const regions = segments.flatMap((segment) => [
|
||||
segment,
|
||||
...(Array.isArray(segment.sections) ? segment.sections : []),
|
||||
]);
|
||||
for (const region of regions) {
|
||||
for (const permission of ["readable", "writable", "executable"]) {
|
||||
if (![true, false, null].includes(region?.[permission])) {
|
||||
throw new Error(`list_segments omitted tri-state ${permission}`);
|
||||
}
|
||||
}
|
||||
if (
|
||||
region.provenance !== "hopper-public-python-api" ||
|
||||
region.permissions?.available !== false ||
|
||||
typeof region.permissions.reason !== "string"
|
||||
) {
|
||||
throw new Error("list_segments omitted permission provenance");
|
||||
}
|
||||
}
|
||||
};
|
||||
|
||||
const verifyRelationships = async (client, options, procedure) => {
|
||||
const related = {};
|
||||
for (const operation of ["procedure_callers", "procedure_callees"]) {
|
||||
@@ -303,16 +281,11 @@ let summary;
|
||||
|
||||
try {
|
||||
await client.connect(transport);
|
||||
const listed = await client.listTools();
|
||||
const expectedNames = TOOL_CONTRACTS.map(({ name }) => name).sort();
|
||||
const actualNames = listed.tools.map(({ name }) => name).sort();
|
||||
if (JSON.stringify(actualNames) !== JSON.stringify(expectedNames)) {
|
||||
throw new Error(
|
||||
"The real server tool inventory did not match its contracts",
|
||||
);
|
||||
}
|
||||
|
||||
const options = { timeout };
|
||||
const progressUpdates = [];
|
||||
const options = {
|
||||
timeout,
|
||||
onprogress: (update) => progressUpdates.push(update),
|
||||
};
|
||||
const fullSessionStatus = () =>
|
||||
client.callTool(
|
||||
{ name: "binary_session", arguments: { detail: "full" } },
|
||||
@@ -320,6 +293,21 @@ try {
|
||||
);
|
||||
const initialSession = await fullSessionStatus();
|
||||
const initialStatus = requireMcpResult(initialSession, "binary_session");
|
||||
const listed = await client.listTools();
|
||||
const availableTools = initialStatus.tool_availability;
|
||||
if (!Array.isArray(availableTools))
|
||||
throw new Error("The real session omitted tool availability");
|
||||
const expectedNames = availableTools
|
||||
.filter(({ available }) => available === true)
|
||||
.map(({ name }) => name)
|
||||
.sort();
|
||||
const actualNames = listed.tools.map(({ name }) => name).sort();
|
||||
if (JSON.stringify(actualNames) !== JSON.stringify(expectedNames)) {
|
||||
throw new Error(
|
||||
"The real server tool inventory diverged from session availability",
|
||||
);
|
||||
}
|
||||
|
||||
if (initialStatus.open !== false)
|
||||
throw new Error("The verifier did not start without a target");
|
||||
requireHopperSelection(initialStatus, {
|
||||
@@ -343,6 +331,16 @@ try {
|
||||
{ name: "list_documents", arguments: {} },
|
||||
options,
|
||||
);
|
||||
requireBridgeProgress(progressUpdates);
|
||||
const rejectedProcedure = await client.callTool(
|
||||
{
|
||||
name: "procedure_info",
|
||||
arguments: { procedure: "__rea_missing_procedure__" },
|
||||
},
|
||||
options,
|
||||
);
|
||||
if (rejectedProcedure.isError !== true)
|
||||
throw new Error("The real Hopper bridge accepted an unknown procedure");
|
||||
const overview = await client.callTool(
|
||||
{ name: "binary_overview", arguments: {} },
|
||||
options,
|
||||
@@ -435,6 +433,7 @@ try {
|
||||
);
|
||||
}
|
||||
const diagnosticCount = requireSafeDiagnostics(stderrChunks);
|
||||
requireBridgeDiagnostic(stderrChunks);
|
||||
|
||||
const closed = await client.callTool(
|
||||
{ name: "close_binary", arguments: {} },
|
||||
@@ -460,6 +459,7 @@ try {
|
||||
bundledMcpRunning,
|
||||
stderrBytes,
|
||||
diagnosticCount,
|
||||
bridgeProgressUpdates: progressUpdates.length,
|
||||
dynamicSession: true,
|
||||
providerBinding,
|
||||
targets: [targetA, targetB, largeTarget],
|
||||
|
||||
@@ -3,8 +3,8 @@ name: reverse-engineer-anything
|
||||
description: Reverse engineer native, managed, Electron/JavaScript, packaged, and browser applications with REA. Use shipped-artifact or approved runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.
|
||||
metadata:
|
||||
version: "23"
|
||||
tool_count: 110
|
||||
catalog_digest: "e8cac51f2f17a5b9a088c3ff773473c4897823401481fc0875a28fe7daf8eee0"
|
||||
tool_count: 114
|
||||
catalog_digest: "e83a177f5eca63bbad17886a61f5a1a376d44afe862c51c56e5d38339f7d41f8"
|
||||
---
|
||||
|
||||
# REA
|
||||
@@ -23,7 +23,8 @@ Choose the first tool from the target the user supplied. Do not call
|
||||
- ASAR or extracted JavaScript/Electron tree:
|
||||
`analyze_javascript_application`.
|
||||
- Archive, application package, ZIP/APK/IPA/MSIX/AppX, or DMG:
|
||||
`inventory_artifact`.
|
||||
`open_binary` with the supplied local path, then `inspect_artifact` or
|
||||
`inventory_artifact` (both operate on the active target and accept no path).
|
||||
- Managed PE/CLI assembly: `inspect_managed_artifact`.
|
||||
- User-owned browser page already open: `list_browser_targets`.
|
||||
- User-owned Electron runtime already open: `list_electron_targets`.
|
||||
@@ -34,6 +35,12 @@ If the app is missing, ask which app to inspect. Resolve a human-readable app
|
||||
name to one clear installed artifact when possible; ask only when matches are
|
||||
ambiguous. Never choose an example app on the user's behalf.
|
||||
|
||||
In a target-free session, use `open_binary` to bind any archive/package or
|
||||
native target whose analysis tool operates on the active target. Do not call a
|
||||
tool hidden from `tools/list`; inspect `binary_session` with
|
||||
`detail: "capabilities"` for the exact remediation when a desired capability
|
||||
is unavailable.
|
||||
|
||||
## Work summary-first
|
||||
|
||||
Start with the default summary projection. Do not repeat an identical tool call.
|
||||
|
||||
@@ -0,0 +1,212 @@
|
||||
import type {
|
||||
AnalysisExecution,
|
||||
AnalysisOperation,
|
||||
AnalysisOperationPort,
|
||||
} from "./AnalysisProvider.js";
|
||||
import { AnalysisOutputError, type AnalysisError } from "../domain/errors.js";
|
||||
import type { JsonValue } from "../domain/jsonValue.js";
|
||||
import { err, ok, type Result } from "../domain/result.js";
|
||||
|
||||
type Facet =
|
||||
| { readonly state: "available"; readonly value: JsonValue }
|
||||
| {
|
||||
readonly state: "unavailable";
|
||||
readonly reason: string;
|
||||
readonly remediation: string;
|
||||
};
|
||||
|
||||
const parameters = (
|
||||
document: string | undefined,
|
||||
address?: string,
|
||||
): Readonly<Record<string, JsonValue>> => ({
|
||||
...(document === undefined ? {} : { document }),
|
||||
...(address === undefined ? {} : { address }),
|
||||
});
|
||||
|
||||
const executionOptions = (
|
||||
signal: AbortSignal | undefined,
|
||||
): { readonly signal?: AbortSignal } =>
|
||||
signal === undefined ? {} : { signal };
|
||||
|
||||
/** Compose the provider's volatile selection state into one coherent query. */
|
||||
export const getNavigationContext = async (
|
||||
analysis: AnalysisOperationPort,
|
||||
input: { readonly document?: string | undefined },
|
||||
signal?: AbortSignal,
|
||||
): Promise<Result<JsonValue, AnalysisError>> => {
|
||||
const document =
|
||||
input.document ??
|
||||
(await analysis.execute("current_document", {}, executionOptions(signal)));
|
||||
if (typeof document !== "string" && !document.ok) return document;
|
||||
const documentName =
|
||||
typeof document === "string" ? document : document.value.result;
|
||||
const documentArgs =
|
||||
typeof documentName === "string" ? parameters(documentName) : {};
|
||||
const address = await analysis.execute(
|
||||
"current_address",
|
||||
documentArgs,
|
||||
executionOptions(signal),
|
||||
);
|
||||
if (!address.ok) return address;
|
||||
if (typeof address.value.result !== "string")
|
||||
return ok({
|
||||
document: documentName,
|
||||
address: address.value.result,
|
||||
procedure: null,
|
||||
});
|
||||
const procedure = await analysis.execute(
|
||||
"resolve_containing_procedure",
|
||||
parameters(
|
||||
typeof documentName === "string" ? documentName : undefined,
|
||||
address.value.result,
|
||||
),
|
||||
executionOptions(signal),
|
||||
);
|
||||
if (!procedure.ok) {
|
||||
if (!isMissingCurrentProcedure(procedure.error)) return procedure;
|
||||
return ok({
|
||||
document: documentName,
|
||||
address: address.value.result,
|
||||
procedure: null,
|
||||
});
|
||||
}
|
||||
return ok({
|
||||
document: documentName,
|
||||
address: address.value.result,
|
||||
procedure: containingProcedureName(procedure.value.result),
|
||||
});
|
||||
};
|
||||
|
||||
/** Inspect bounded provider-neutral facets at one explicit reproducible address. */
|
||||
export const inspectAddressContext = async (
|
||||
analysis: AnalysisOperationPort,
|
||||
input: { readonly address: string; readonly document?: string | undefined },
|
||||
signal?: AbortSignal,
|
||||
): Promise<Result<JsonValue, AnalysisError>> => {
|
||||
const document = await resolveDocument(analysis, input.document, signal);
|
||||
if (!document.ok) return document;
|
||||
const args = parameters(document.value, input.address);
|
||||
const operations = [
|
||||
"address_name",
|
||||
"resolve_containing_procedure",
|
||||
"comment",
|
||||
"inline_comment",
|
||||
"list_bookmarks",
|
||||
] as const satisfies readonly AnalysisOperation[];
|
||||
const results = await Promise.all(
|
||||
operations.map((operation) =>
|
||||
analysis.execute(
|
||||
operation,
|
||||
operation === "list_bookmarks" ? parameters(document.value) : args,
|
||||
executionOptions(signal),
|
||||
),
|
||||
),
|
||||
);
|
||||
for (const result of results) {
|
||||
if (!result.ok && isRequestLevelFailure(result.error)) return result;
|
||||
}
|
||||
const name = facet(results[0], operations[0]);
|
||||
const procedure = facet(results[1], operations[1]);
|
||||
const comment = facet(results[2], operations[2]);
|
||||
const inlineComment = facet(results[3], operations[3]);
|
||||
const bookmarks = facet(results[4], operations[4]);
|
||||
return ok({
|
||||
address: input.address,
|
||||
document: document.value,
|
||||
name,
|
||||
procedure,
|
||||
comment,
|
||||
inline_comment: inlineComment,
|
||||
bookmarks:
|
||||
bookmarks.state === "available"
|
||||
? {
|
||||
state: "available",
|
||||
value: matchingBookmarks(
|
||||
bookmarks.value,
|
||||
resolvedAddress(results[1], input.address),
|
||||
),
|
||||
}
|
||||
: bookmarks,
|
||||
});
|
||||
};
|
||||
|
||||
const resolveDocument = async (
|
||||
analysis: AnalysisOperationPort,
|
||||
document: string | undefined,
|
||||
signal: AbortSignal | undefined,
|
||||
): Promise<Result<string, AnalysisError>> => {
|
||||
if (document !== undefined) return ok(document);
|
||||
const current = await analysis.execute(
|
||||
"current_document",
|
||||
{},
|
||||
executionOptions(signal),
|
||||
);
|
||||
if (!current.ok) return current;
|
||||
return typeof current.value.result === "string"
|
||||
? ok(current.value.result)
|
||||
: err(
|
||||
new AnalysisOutputError(
|
||||
"current_document",
|
||||
"expected a document identity string",
|
||||
),
|
||||
);
|
||||
};
|
||||
|
||||
const facet = (
|
||||
result: Result<AnalysisExecution, AnalysisError> | undefined,
|
||||
operation: AnalysisOperation,
|
||||
): Facet =>
|
||||
result?.ok === true
|
||||
? { state: "available", value: result.value.result }
|
||||
: {
|
||||
state: "unavailable",
|
||||
reason: result?.error.message ?? `${operation} returned no result`,
|
||||
remediation: `Call ${operation} directly to inspect provider availability and diagnostics.`,
|
||||
};
|
||||
|
||||
const isMissingCurrentProcedure = (error: AnalysisError): boolean =>
|
||||
/(?:no procedure exists|not in a procedure)/iu.test(error.message);
|
||||
|
||||
const isRequestLevelFailure = (error: AnalysisError): boolean =>
|
||||
error._tag === "AnalysisCancelledError" ||
|
||||
error._tag === "AnalysisTimeoutError" ||
|
||||
error._tag === "NoBinaryOpenError" ||
|
||||
error._tag === "PermissionRequiredError";
|
||||
|
||||
const containingProcedureName = (value: JsonValue): string | null => {
|
||||
if (typeof value !== "object" || value === null || Array.isArray(value))
|
||||
return null;
|
||||
if (value.found !== true) return null;
|
||||
const procedure = value.procedure;
|
||||
if (
|
||||
typeof procedure !== "object" ||
|
||||
procedure === null ||
|
||||
Array.isArray(procedure)
|
||||
)
|
||||
return null;
|
||||
return typeof procedure.name === "string" ? procedure.name : null;
|
||||
};
|
||||
|
||||
const resolvedAddress = (
|
||||
result: Result<AnalysisExecution, AnalysisError> | undefined,
|
||||
fallback: string,
|
||||
): string => {
|
||||
if (result?.ok !== true) return fallback;
|
||||
const value = result.value.result;
|
||||
if (typeof value !== "object" || value === null || Array.isArray(value))
|
||||
return fallback;
|
||||
return typeof value.query_address === "string"
|
||||
? value.query_address
|
||||
: fallback;
|
||||
};
|
||||
|
||||
const matchingBookmarks = (value: JsonValue, address: string): JsonValue => {
|
||||
if (!Array.isArray(value)) return [];
|
||||
return value.filter(
|
||||
(bookmark) =>
|
||||
typeof bookmark === "object" &&
|
||||
bookmark !== null &&
|
||||
!Array.isArray(bookmark) &&
|
||||
bookmark.address === address,
|
||||
);
|
||||
};
|
||||
@@ -26,7 +26,7 @@ import type {
|
||||
AnalysisOperation,
|
||||
CapabilityDescriptor,
|
||||
} from "./AnalysisProvider.js";
|
||||
import { OFFICIAL_TOOL_CONTRACTS } from "../contracts/toolContracts.js";
|
||||
import { GENERATED_MCP_TOOL_CATALOG } from "../generatedMcpToolCatalog.js";
|
||||
|
||||
const STATEFUL_OPERATIONS: ReadonlySet<AnalysisOperation> = new Set([
|
||||
"health",
|
||||
@@ -47,13 +47,15 @@ const CURSOR_DEFAULT_OPERATIONS: ReadonlySet<AnalysisOperation> = new Set([
|
||||
"xrefs",
|
||||
]);
|
||||
|
||||
const DOCUMENT_SCOPED_OPERATIONS: ReadonlySet<AnalysisOperation> = new Set(
|
||||
OFFICIAL_TOOL_CONTRACTS.map(({ name }) => name).filter(
|
||||
(name) =>
|
||||
name !== "current_document" &&
|
||||
name !== "list_documents" &&
|
||||
name !== "set_current_document",
|
||||
),
|
||||
const DOCUMENT_SCOPED_OPERATIONS: ReadonlySet<string> = new Set(
|
||||
GENERATED_MCP_TOOL_CATALOG.filter(({ kind }) => kind === "official-proxy")
|
||||
.map(({ name }) => name)
|
||||
.filter(
|
||||
(name) =>
|
||||
name !== "current_document" &&
|
||||
name !== "list_documents" &&
|
||||
name !== "set_current_document",
|
||||
),
|
||||
);
|
||||
|
||||
/** Whether an operation is immutable and independent of provider UI state. */
|
||||
|
||||
@@ -49,7 +49,7 @@ export const scanCanonicalArtifactInventory = async (
|
||||
(!integrity.approved || !integrity.enabled)
|
||||
)
|
||||
throw new ArtifactReaderFailure(
|
||||
"unavailable",
|
||||
"policy",
|
||||
"Integrity continuation requires explicit approval and operator policy",
|
||||
);
|
||||
const metadata = await lstat(path);
|
||||
|
||||
@@ -24,8 +24,7 @@ import type {
|
||||
ProviderIdentity,
|
||||
} from "./AnalysisProvider.js";
|
||||
import type { AnalysisOperation } from "./AnalysisProvider.js";
|
||||
import { enhancedToolNameSchema } from "../contracts/enhancedInputs.js";
|
||||
import { OFFICIAL_TOOL_CONTRACTS } from "../contracts/toolContracts.js";
|
||||
import { GENERATED_MCP_TOOL_CATALOG } from "../generatedMcpToolCatalog.js";
|
||||
import type { BinarySessionPort } from "./BinarySessionPort.js";
|
||||
import {
|
||||
SessionProviderRouter,
|
||||
@@ -41,7 +40,14 @@ import { prepareSessionExecution } from "./BinarySessionExecution.js";
|
||||
import { closeAnalysisClient } from "./AnalysisClientCleanup.js";
|
||||
export type { BinarySessionPort } from "./BinarySessionPort.js";
|
||||
const OFFICIAL_OPERATIONS: ReadonlySet<string> = new Set(
|
||||
OFFICIAL_TOOL_CONTRACTS.map(({ name }) => name),
|
||||
GENERATED_MCP_TOOL_CATALOG.filter(
|
||||
({ kind }) => kind === "official-proxy",
|
||||
).map(({ name }) => name),
|
||||
);
|
||||
const ENHANCED_OPERATIONS: ReadonlySet<string> = new Set(
|
||||
GENERATED_MCP_TOOL_CATALOG.filter(({ kind }) => kind === "enhanced").map(
|
||||
({ name }) => name,
|
||||
),
|
||||
);
|
||||
|
||||
/**
|
||||
@@ -100,7 +106,7 @@ export class BinarySession
|
||||
if (operation !== undefined) {
|
||||
const exact = route.capabilities?.get(operation)?.provider;
|
||||
if (exact !== undefined) selected = exact;
|
||||
else if (enhancedToolNameSchema.safeParse(operation).success) {
|
||||
else if (ENHANCED_OPERATIONS.has(operation)) {
|
||||
const providers = new Map<string, ProviderIdentity>();
|
||||
for (const descriptor of route.capabilities?.values() ?? [])
|
||||
if (
|
||||
@@ -183,6 +189,7 @@ export class BinarySession
|
||||
const imported = this.importAnalysisSnapshot(options.snapshot);
|
||||
if (!imported.ok) return imported;
|
||||
}
|
||||
this.resetSnapshotInvalidation();
|
||||
return ok(target);
|
||||
}
|
||||
await this.#drainCalls();
|
||||
|
||||
@@ -0,0 +1,35 @@
|
||||
import { describe, expect, it } from "vitest";
|
||||
|
||||
import type {
|
||||
AnalysisClient,
|
||||
AnalysisProvider,
|
||||
ProviderIdentity,
|
||||
} from "./AnalysisProvider.js";
|
||||
import { AnalysisProviderRegistry } from "./AnalysisProviderRegistry.js";
|
||||
import { composeBinarySession } from "./BinarySessionComposition.js";
|
||||
|
||||
const auxiliaryProvider = (identity: ProviderIdentity): AnalysisProvider => ({
|
||||
identity: () => identity,
|
||||
capabilities: () => [],
|
||||
createClient: (): AnalysisClient => {
|
||||
throw new Error("The composition check must not create provider clients");
|
||||
},
|
||||
});
|
||||
|
||||
describe("composeBinarySession", () => {
|
||||
it("exposes the complete configured provider set without starting clients", () => {
|
||||
const session = composeBinarySession(new AnalysisProviderRegistry([]), [
|
||||
auxiliaryProvider({
|
||||
id: "test-auxiliary",
|
||||
name: "Test auxiliary provider",
|
||||
version: "1.0.0",
|
||||
}),
|
||||
]);
|
||||
|
||||
expect(session.providerIdentity()).toEqual({
|
||||
id: "composite:test-auxiliary",
|
||||
name: "REA composite analysis provider",
|
||||
version: null,
|
||||
});
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,62 @@
|
||||
import type {
|
||||
AnalysisClientFactory,
|
||||
AnalysisProfileResolution,
|
||||
AnalysisProfileResolutionOptions,
|
||||
AnalysisProvider,
|
||||
} from "./AnalysisProvider.js";
|
||||
import { AnalysisProviderRegistry } from "./AnalysisProviderRegistry.js";
|
||||
import { BinarySession } from "./BinarySession.js";
|
||||
import { SessionProviderRouter } from "./SessionProviderRouter.js";
|
||||
import type { BinaryTarget } from "../domain/binaryTarget.js";
|
||||
import type { AnalysisError } from "../domain/errors.js";
|
||||
import type { Result } from "../domain/result.js";
|
||||
|
||||
type BinarySessionOptions = {
|
||||
readonly resolveAnalysisProfile?: (
|
||||
target: BinaryTarget,
|
||||
options?: AnalysisProfileResolutionOptions,
|
||||
) => Promise<Result<AnalysisProfileResolution, AnalysisError>>;
|
||||
};
|
||||
|
||||
type BinarySessionOptionsOrResolver =
|
||||
| BinarySessionOptions
|
||||
| BinarySessionOptions["resolveAnalysisProfile"];
|
||||
|
||||
const normalizeBinarySessionOptions = (
|
||||
optionsOrResolver?: BinarySessionOptionsOrResolver,
|
||||
): BinarySessionOptions =>
|
||||
typeof optionsOrResolver === "function"
|
||||
? { resolveAnalysisProfile: optionsOrResolver }
|
||||
: (optionsOrResolver ?? {});
|
||||
|
||||
/**
|
||||
* Compose one provider-neutral session from deep-provider selection and
|
||||
* disjoint auxiliary operation families.
|
||||
*/
|
||||
export const composeBinarySession = (
|
||||
registry: AnalysisProviderRegistry | SessionProviderRouter,
|
||||
auxiliaryProviders: readonly AnalysisProvider[] = [],
|
||||
): BinarySession =>
|
||||
new BinarySession(
|
||||
registry instanceof SessionProviderRouter
|
||||
? registry
|
||||
: SessionProviderRouter.selectable(registry, auxiliaryProviders),
|
||||
);
|
||||
|
||||
/**
|
||||
* Compose a session through the same internal seam for focused adapter tests.
|
||||
* The constructor remains private to this composition module, so callers test
|
||||
* provider behavior without coupling to BinarySession construction.
|
||||
*/
|
||||
export const composeBinarySessionFromFactory = (
|
||||
provider: AnalysisProvider | AnalysisClientFactory | SessionProviderRouter,
|
||||
optionsOrResolver?: BinarySessionOptionsOrResolver,
|
||||
): BinarySession =>
|
||||
new BinarySession(provider, normalizeBinarySessionOptions(optionsOrResolver));
|
||||
|
||||
/** Compose a focused session from any provider-shaped test seam. */
|
||||
export const composeBinarySessionFromProvider = (
|
||||
provider: AnalysisProvider | AnalysisClientFactory | SessionProviderRouter,
|
||||
optionsOrResolver?: BinarySessionOptionsOrResolver,
|
||||
): BinarySession =>
|
||||
new BinarySession(provider, normalizeBinarySessionOptions(optionsOrResolver));
|
||||
@@ -27,6 +27,16 @@ import type {
|
||||
ProviderIdentity,
|
||||
} from "./AnalysisProvider.js";
|
||||
|
||||
/** Compact identity and summary for one retained immutable Evidence bundle. */
|
||||
export interface EvidenceBundleSnapshot {
|
||||
readonly bundleDigest: string;
|
||||
readonly bundleVersion: 2;
|
||||
readonly bytes: number;
|
||||
readonly records: number;
|
||||
readonly unknowns: number;
|
||||
readonly uri: string;
|
||||
}
|
||||
|
||||
/** Target lifecycle used by CLI and MCP without exposing a concrete provider. */
|
||||
export interface BinarySessionPort extends AnalysisOperationPort {
|
||||
open(
|
||||
@@ -49,6 +59,8 @@ export interface BinarySessionPort extends AnalysisOperationPort {
|
||||
hasEvidence(evidenceId: string): boolean;
|
||||
evidenceById(evidenceId: string): Evidence | undefined;
|
||||
exportEvidenceBundle(): EvidenceBundle;
|
||||
snapshotEvidenceBundle(): Result<EvidenceBundleSnapshot, EvidenceLimitError>;
|
||||
retainedEvidenceBundle(digest: string): string | undefined;
|
||||
importEvidenceBundle(
|
||||
bundle: unknown,
|
||||
): Result<number, EvidenceIntegrityError | EvidenceLimitError>;
|
||||
@@ -101,4 +113,5 @@ export interface BinarySessionPort extends AnalysisOperationPort {
|
||||
): AnalysisProfileCommitment | undefined;
|
||||
openCompatibility(): Readonly<Record<string, JsonValue>>;
|
||||
onAvailabilityChanged?(listener: () => void | Promise<void>): () => void;
|
||||
onAnalysisSnapshotChanged?(listener: () => void | Promise<void>): () => void;
|
||||
}
|
||||
|
||||
@@ -3,11 +3,14 @@ import type { AnalysisSnapshot } from "../domain/analysisSnapshot.js";
|
||||
import type { BinaryTarget } from "../domain/binaryTarget.js";
|
||||
import { createEvidence, type Evidence } from "../domain/evidence.js";
|
||||
import type { EvidenceBundle } from "../domain/evidenceBundle.js";
|
||||
import { evidenceBundleForTarget } from "../domain/evidenceBundle.js";
|
||||
import {
|
||||
evidenceBundleForTarget,
|
||||
serializeEvidenceBundle,
|
||||
} from "../domain/evidenceBundle.js";
|
||||
import {
|
||||
EvidenceIntegrityError,
|
||||
EvidenceLimitError,
|
||||
type AnalysisError,
|
||||
type EvidenceLimitError,
|
||||
type UnknownRegistryError,
|
||||
} from "../domain/errors.js";
|
||||
import {
|
||||
@@ -24,7 +27,8 @@ import type {
|
||||
UnknownStatus,
|
||||
UpdateUnknownInput,
|
||||
} from "../domain/residualUnknown.js";
|
||||
import { err, type Result } from "../domain/result.js";
|
||||
import { err, ok, type Result } from "../domain/result.js";
|
||||
import type { EvidenceBundleSnapshot } from "./BinarySessionPort.js";
|
||||
import type {
|
||||
AnalysisExecution,
|
||||
AnalysisOperation,
|
||||
@@ -44,17 +48,28 @@ export interface ActiveAnalysisBinding {
|
||||
|
||||
/** Owns session evidence, snapshots, workspaces, and residual unknowns. */
|
||||
export abstract class BinarySessionRecords {
|
||||
static readonly MAX_RETAINED_BUNDLES = 16;
|
||||
static readonly MAX_RETAINED_BUNDLE_BYTES = 64 * 1024 * 1024;
|
||||
readonly #evidence = new EvidenceLedger({
|
||||
maxRecords: 10_000,
|
||||
maxBytes: 64 * 1024 * 1024,
|
||||
});
|
||||
readonly #snapshot = new AnalysisSnapshotCache();
|
||||
readonly #retainedBundles = new Map<string, string>();
|
||||
#retainedBundleBytes = 0;
|
||||
readonly #investigationWorkspaces = new Map<string, InvestigationWorkspace>();
|
||||
readonly #coverageWorkspaces = new Map<
|
||||
string,
|
||||
ReconstructionCoverageWorkspace
|
||||
>();
|
||||
#snapshotInvalidated = false;
|
||||
readonly #snapshotListeners = new Set<() => void | Promise<void>>();
|
||||
|
||||
/** Observe changes to the mutable current analysis snapshot resource. */
|
||||
onAnalysisSnapshotChanged(listener: () => void | Promise<void>): () => void {
|
||||
this.#snapshotListeners.add(listener);
|
||||
return () => this.#snapshotListeners.delete(listener);
|
||||
}
|
||||
|
||||
recordEvidence(
|
||||
evidence: Evidence,
|
||||
@@ -62,7 +77,9 @@ export abstract class BinarySessionRecords {
|
||||
"added" | "duplicate",
|
||||
EvidenceIntegrityError | EvidenceLimitError
|
||||
> {
|
||||
return this.#evidence.record(evidence);
|
||||
const recorded = this.#evidence.record(evidence);
|
||||
if (recorded.ok && recorded.value === "added") this.#emitSnapshotChanged();
|
||||
return recorded;
|
||||
}
|
||||
|
||||
hasEvidence(evidenceId: string): boolean {
|
||||
@@ -77,10 +94,55 @@ export abstract class BinarySessionRecords {
|
||||
return this.#evidence.export();
|
||||
}
|
||||
|
||||
snapshotEvidenceBundle(): Result<EvidenceBundleSnapshot, EvidenceLimitError> {
|
||||
const bundle = this.#evidence.export();
|
||||
const encoded = serializeEvidenceBundle(bundle);
|
||||
const digest = createHash("sha256").update(encoded).digest("hex");
|
||||
const existing = this.#retainedBundles.get(digest);
|
||||
if (existing === undefined) {
|
||||
if (
|
||||
this.#retainedBundles.size >= BinarySessionRecords.MAX_RETAINED_BUNDLES
|
||||
)
|
||||
return err(
|
||||
new EvidenceLimitError(
|
||||
"records",
|
||||
BinarySessionRecords.MAX_RETAINED_BUNDLES,
|
||||
),
|
||||
);
|
||||
const bytes = Buffer.byteLength(encoded);
|
||||
if (
|
||||
this.#retainedBundleBytes + bytes >
|
||||
BinarySessionRecords.MAX_RETAINED_BUNDLE_BYTES
|
||||
)
|
||||
return err(
|
||||
new EvidenceLimitError(
|
||||
"bytes",
|
||||
BinarySessionRecords.MAX_RETAINED_BUNDLE_BYTES,
|
||||
),
|
||||
);
|
||||
this.#retainedBundles.set(digest, encoded);
|
||||
this.#retainedBundleBytes += bytes;
|
||||
}
|
||||
return ok({
|
||||
bundleDigest: digest,
|
||||
bundleVersion: 2,
|
||||
bytes: Buffer.byteLength(existing ?? encoded),
|
||||
records: bundle.records.length,
|
||||
unknowns: bundle.unknowns.length,
|
||||
uri: `rea://evidence-bundle/${digest}`,
|
||||
});
|
||||
}
|
||||
|
||||
retainedEvidenceBundle(digest: string): string | undefined {
|
||||
return this.#retainedBundles.get(digest);
|
||||
}
|
||||
|
||||
importEvidenceBundle(
|
||||
bundle: unknown,
|
||||
): Result<number, EvidenceIntegrityError | EvidenceLimitError> {
|
||||
return this.#evidence.import(bundle);
|
||||
const imported = this.#evidence.import(bundle);
|
||||
if (imported.ok && imported.value > 0) this.#emitSnapshotChanged();
|
||||
return imported;
|
||||
}
|
||||
|
||||
protected abstract activeAnalysisBinding(): ActiveAnalysisBinding | undefined;
|
||||
@@ -120,13 +182,15 @@ export abstract class BinarySessionRecords {
|
||||
"Analysis snapshot profile_mismatch: the active target has no concrete analysis profile",
|
||||
),
|
||||
);
|
||||
return this.#snapshot.import(
|
||||
const imported = this.#snapshot.import(
|
||||
snapshot,
|
||||
active === undefined
|
||||
? undefined
|
||||
: { target: active.target, profile: active.profile },
|
||||
(bundle) => this.#evidence.import(bundle),
|
||||
);
|
||||
if (imported.ok) this.#emitSnapshotChanged();
|
||||
return imported;
|
||||
}
|
||||
|
||||
protected matchesSnapshot(
|
||||
@@ -141,6 +205,7 @@ export abstract class BinarySessionRecords {
|
||||
profile: AnalysisProfileCommitment,
|
||||
): void {
|
||||
this.#snapshot.select(target, profile);
|
||||
this.#emitSnapshotChanged();
|
||||
}
|
||||
|
||||
protected lookupSnapshot(
|
||||
@@ -158,25 +223,37 @@ export abstract class BinarySessionRecords {
|
||||
input: Parameters<AnalysisSnapshotCache["record"]>[0],
|
||||
): void {
|
||||
this.#snapshot.record(input);
|
||||
this.#emitSnapshotChanged();
|
||||
}
|
||||
|
||||
protected invalidateSnapshot(): void {
|
||||
this.#snapshot.clear();
|
||||
this.#snapshotInvalidated = true;
|
||||
this.#emitSnapshotChanged();
|
||||
}
|
||||
|
||||
protected resetSnapshotInvalidation(): void {
|
||||
if (!this.#snapshotInvalidated) return;
|
||||
this.#snapshotInvalidated = false;
|
||||
this.#emitSnapshotChanged();
|
||||
}
|
||||
|
||||
protected clearSnapshot(): void {
|
||||
this.#snapshot.clear();
|
||||
this.#emitSnapshotChanged();
|
||||
}
|
||||
|
||||
protected clearSessionRecords(): void {
|
||||
this.#evidence.clear();
|
||||
this.#snapshot.clear();
|
||||
this.#snapshotInvalidated = false;
|
||||
this.#retainedBundles.clear();
|
||||
this.#retainedBundleBytes = 0;
|
||||
this.#emitSnapshotChanged();
|
||||
}
|
||||
|
||||
#emitSnapshotChanged(): void {
|
||||
for (const listener of this.#snapshotListeners) void listener();
|
||||
}
|
||||
|
||||
retainInvestigationWorkspace(
|
||||
@@ -231,21 +308,25 @@ export abstract class BinarySessionRecords {
|
||||
input: RecordUnknownInput,
|
||||
): Result<ResidualUnknown, AnalysisError> {
|
||||
const target = this.activeAnalysisBinding()?.target;
|
||||
return this.#evidence.recordUnknown(
|
||||
const recorded = this.#evidence.recordUnknown(
|
||||
input,
|
||||
unknownMutationEvidence(target, input),
|
||||
);
|
||||
if (recorded.ok) this.#emitSnapshotChanged();
|
||||
return recorded;
|
||||
}
|
||||
|
||||
recordEvidenceWithUnknown(
|
||||
evidence: Evidence,
|
||||
input: RecordUnknownInput,
|
||||
): Result<ResidualUnknown | null, AnalysisError> {
|
||||
return this.#evidence.recordWithUnknown(
|
||||
const recorded = this.#evidence.recordWithUnknown(
|
||||
evidence,
|
||||
input,
|
||||
unknownMutationEvidence(undefined, input),
|
||||
);
|
||||
if (recorded.ok) this.#emitSnapshotChanged();
|
||||
return recorded;
|
||||
}
|
||||
|
||||
updateUnknown(
|
||||
@@ -267,7 +348,9 @@ export abstract class BinarySessionRecords {
|
||||
"Registry mutation evidence records analyst intent, not proof of the answer.",
|
||||
],
|
||||
});
|
||||
return this.#evidence.updateUnknown(input, evidence);
|
||||
const updated = this.#evidence.updateUnknown(input, evidence);
|
||||
if (updated.ok) this.#emitSnapshotChanged();
|
||||
return updated;
|
||||
}
|
||||
|
||||
listUnknowns(
|
||||
@@ -307,3 +390,4 @@ const sortedWorkspaces = <
|
||||
left.revision - right.revision,
|
||||
)
|
||||
.map((workspace) => structuredClone(workspace));
|
||||
import { createHash } from "node:crypto";
|
||||
|
||||
@@ -1,8 +1,9 @@
|
||||
import { z } from "zod";
|
||||
|
||||
import { TOOL_CONTRACTS } from "../contracts/toolContracts.js";
|
||||
import type { ClientFeatureAvailability } from "../contracts/toolOutputSchemaPrimitives.js";
|
||||
import type { ToolKind } from "../contracts/toolContractTypes.js";
|
||||
import type { JsonValue } from "../domain/jsonValue.js";
|
||||
import { GENERATED_MCP_TOOL_CATALOG } from "../generatedMcpToolCatalog.js";
|
||||
|
||||
const statusSchema = z.object({
|
||||
open: z.boolean(),
|
||||
@@ -28,7 +29,6 @@ type ToolAvailabilityReason =
|
||||
| "unsupported_host"
|
||||
| "policy_disabled";
|
||||
|
||||
type ToolKind = (typeof TOOL_CONTRACTS)[number]["kind"];
|
||||
type ProviderDescriptor = {
|
||||
readonly available: boolean;
|
||||
readonly reason: string | null;
|
||||
@@ -102,6 +102,7 @@ const ENHANCED_REQUIREMENTS: Readonly<Record<string, readonly string[]>> = {
|
||||
"list_strings",
|
||||
],
|
||||
analyze_function: ["analyze_function"],
|
||||
inspect_native_api: ["analyze_function"],
|
||||
trace_feature: [
|
||||
"list_strings",
|
||||
"list_procedures",
|
||||
@@ -110,6 +111,16 @@ const ENHANCED_REQUIREMENTS: Readonly<Record<string, readonly string[]>> = {
|
||||
],
|
||||
};
|
||||
|
||||
const SESSION_COMPOSITION_REQUIREMENTS: Readonly<
|
||||
Record<string, readonly string[]>
|
||||
> = {
|
||||
get_navigation_context: [
|
||||
"current_document",
|
||||
"current_address",
|
||||
"resolve_containing_procedure",
|
||||
],
|
||||
};
|
||||
|
||||
/** Build stable per-operation availability for discovery and tool visibility. */
|
||||
export const buildCapabilityInventory = (
|
||||
sessionStatus: JsonValue,
|
||||
@@ -127,7 +138,7 @@ export const buildCapabilityInventory = (
|
||||
},
|
||||
]),
|
||||
);
|
||||
return TOOL_CONTRACTS.map((contract) => {
|
||||
return GENERATED_MCP_TOOL_CATALOG.map((contract) => {
|
||||
const availability = availabilityFor({
|
||||
name: contract.name,
|
||||
kind: contract.kind,
|
||||
@@ -184,6 +195,9 @@ const clientRequirementsFor = (
|
||||
};
|
||||
|
||||
const availabilityFor = (context: AvailabilityContext): Availability => {
|
||||
const sessionComposition = SESSION_COMPOSITION_REQUIREMENTS[context.name];
|
||||
if (sessionComposition !== undefined)
|
||||
return composedAvailabilityFor(sessionComposition, context.descriptors);
|
||||
const javascriptApplication = javascriptApplicationAvailability(context);
|
||||
if (javascriptApplication !== null) return javascriptApplication;
|
||||
const policyDecision = policyAvailability(context);
|
||||
@@ -365,6 +379,13 @@ const composedAvailability = (
|
||||
reason: "provider_missing",
|
||||
remediation: "No provider composition is declared for this operation.",
|
||||
};
|
||||
return composedAvailabilityFor(requirements, descriptors);
|
||||
};
|
||||
|
||||
const composedAvailabilityFor = (
|
||||
requirements: readonly string[],
|
||||
descriptors: ReadonlyMap<string, ProviderDescriptor>,
|
||||
): Availability => {
|
||||
const missing = requirements.find((operation) => !descriptors.has(operation));
|
||||
if (missing !== undefined)
|
||||
return {
|
||||
|
||||
@@ -5,6 +5,7 @@ import { parse as parseToml } from "smol-toml";
|
||||
import { z } from "zod";
|
||||
|
||||
import { PRODUCT_IDENTITY } from "../identity.js";
|
||||
import { MCP_STARTUP_POLICY } from "../mcpStartupPolicy.js";
|
||||
import { supportedClients } from "./SupportedClients.js";
|
||||
|
||||
export interface ClientRegistrationStatus {
|
||||
@@ -80,7 +81,11 @@ const registrationAligned = (
|
||||
currentCommandPath: string,
|
||||
): boolean => {
|
||||
const command = [registration.command, ...registration.args];
|
||||
if (client === "codex" && registration.startup_timeout_sec !== 30)
|
||||
if (
|
||||
client === "codex" &&
|
||||
registration.startup_timeout_sec !==
|
||||
MCP_STARTUP_POLICY.codexStartupTimeoutSeconds
|
||||
)
|
||||
return false;
|
||||
if (
|
||||
command.length === 4 &&
|
||||
|
||||
@@ -52,6 +52,7 @@ type DirectAnalysisTool =
|
||||
| "procedure_pseudo_code"
|
||||
| "read_function_instructions"
|
||||
| "analyze_function"
|
||||
| "inspect_native_api"
|
||||
| "search_strings"
|
||||
| "search_procedures"
|
||||
| "xrefs"
|
||||
@@ -341,6 +342,7 @@ const executeAnalysisTool = async (input: {
|
||||
if (
|
||||
tool === "binary_overview" ||
|
||||
tool === "analyze_function" ||
|
||||
tool === "inspect_native_api" ||
|
||||
tool === "trace_feature"
|
||||
) {
|
||||
const result = await new EnhancedTools(session).execute(
|
||||
@@ -438,7 +440,7 @@ const replayProviderFor = (
|
||||
| ManagedToolName
|
||||
| DirectAnalysisTool,
|
||||
) =>
|
||||
tool === "binary_overview" || tool === "trace_feature"
|
||||
isWorkflowEvidenceTool(tool)
|
||||
? REA_WORKFLOW_PROVIDER
|
||||
: session.providerIdentity(tool);
|
||||
|
||||
@@ -450,12 +452,22 @@ const analysisProfileForEvidence = (
|
||||
| ManagedToolName
|
||||
| DirectAnalysisTool,
|
||||
): AnalysisProfileCommitment | undefined => {
|
||||
if (tool !== "binary_overview" && tool !== "trace_feature")
|
||||
return session.analysisProfile(tool);
|
||||
if (!isWorkflowEvidenceTool(tool)) return session.analysisProfile(tool);
|
||||
const upstream = session.analysisProfile();
|
||||
return upstream === undefined ? undefined : workflowAnalysisProfile(upstream);
|
||||
};
|
||||
|
||||
const isWorkflowEvidenceTool = (
|
||||
tool:
|
||||
| NativeToolName
|
||||
| ArtifactToolName
|
||||
| ManagedToolName
|
||||
| DirectAnalysisTool,
|
||||
): boolean =>
|
||||
tool === "binary_overview" ||
|
||||
tool === "inspect_native_api" ||
|
||||
tool === "trace_feature";
|
||||
|
||||
const fileExists = async (path: string): Promise<boolean> => {
|
||||
try {
|
||||
await access(path);
|
||||
|
||||
@@ -1,3 +1,5 @@
|
||||
import type { z } from "zod";
|
||||
|
||||
import type {
|
||||
AnalysisOperation,
|
||||
AnalysisOperationPort,
|
||||
@@ -12,6 +14,7 @@ import {
|
||||
} from "../domain/errors.js";
|
||||
import {
|
||||
addressDistance,
|
||||
functionDossierSchema,
|
||||
parseDocuments,
|
||||
parseFunctionDossier,
|
||||
parseListCount,
|
||||
@@ -25,7 +28,7 @@ import {
|
||||
discoverObjcProtocols,
|
||||
discoverSwiftClasses,
|
||||
} from "../domain/symbolAnalysis.js";
|
||||
import type { JsonValue } from "../domain/jsonValue.js";
|
||||
import { jsonValueSchema, type JsonValue } from "../domain/jsonValue.js";
|
||||
|
||||
import {
|
||||
invalidEnhancedInput,
|
||||
@@ -35,6 +38,7 @@ import {
|
||||
import { readAllAddressed } from "./EnhancedToolPagination.js";
|
||||
import { traceCallPath } from "./CallPathTracing.js";
|
||||
import { traceLiteralFeature } from "./EnhancedLiteralTracing.js";
|
||||
import { projectNativeApiInspection } from "./NativeApiInspection.js";
|
||||
export type { ValidatedEnhancedCall } from "./EnhancedToolTypes.js";
|
||||
|
||||
/**
|
||||
@@ -57,6 +61,8 @@ export class EnhancedTools {
|
||||
name === "trace_call_path"
|
||||
)
|
||||
return this.#executeTracing(name, input, signal);
|
||||
if (name === "analyze_function" || name === "inspect_native_api")
|
||||
return this.#executeFunctionAnalysis(name, input, signal);
|
||||
switch (name) {
|
||||
case "swift_classes": {
|
||||
const parsed = enhancedInputSchemas.swift_classes.safeParse(input);
|
||||
@@ -98,12 +104,6 @@ export class EnhancedTools {
|
||||
? this.executeValidated({ name, input: parsed.data }, signal)
|
||||
: invalidEnhancedInput(name, parsed.error);
|
||||
}
|
||||
case "analyze_function": {
|
||||
const parsed = enhancedInputSchemas.analyze_function.safeParse(input);
|
||||
return parsed.success
|
||||
? this.executeValidated({ name, input: parsed.data }, signal)
|
||||
: invalidEnhancedInput(name, parsed.error);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
@@ -131,6 +131,8 @@ export class EnhancedTools {
|
||||
return this.#binaryOverview(call.input, signal);
|
||||
case "analyze_function":
|
||||
return this.#analyzeFunction(call.input, signal);
|
||||
case "inspect_native_api":
|
||||
return this.#inspectNativeApi(call.input, signal);
|
||||
case "trace_feature":
|
||||
return traceLiteralFeature(
|
||||
(name, arguments_, operationSignal) =>
|
||||
@@ -181,6 +183,30 @@ export class EnhancedTools {
|
||||
);
|
||||
}
|
||||
|
||||
#executeFunctionAnalysis(
|
||||
name: "analyze_function" | "inspect_native_api",
|
||||
input: unknown,
|
||||
signal?: AbortSignal,
|
||||
): EnhancedResult {
|
||||
const parsed = enhancedInputSchemas[name].safeParse(input);
|
||||
if (!parsed.success) return invalidEnhancedInput(name, parsed.error);
|
||||
if (name === "analyze_function")
|
||||
return this.executeValidated(
|
||||
{
|
||||
name,
|
||||
input: enhancedInputSchemas.analyze_function.parse(parsed.data),
|
||||
},
|
||||
signal,
|
||||
);
|
||||
return this.executeValidated(
|
||||
{
|
||||
name,
|
||||
input: enhancedInputSchemas.inspect_native_api.parse(parsed.data),
|
||||
},
|
||||
signal,
|
||||
);
|
||||
}
|
||||
|
||||
async #analyzeFunction(
|
||||
input: Readonly<Record<string, JsonValue>>,
|
||||
signal?: AbortSignal,
|
||||
@@ -189,6 +215,24 @@ export class EnhancedTools {
|
||||
return result.ok ? parseFunctionDossier(result.value) : result;
|
||||
}
|
||||
|
||||
async #inspectNativeApi(
|
||||
input: z.output<typeof enhancedInputSchemas.inspect_native_api>,
|
||||
signal?: AbortSignal,
|
||||
): EnhancedResult {
|
||||
const analysisInput = enhancedInputSchemas.analyze_function.parse({
|
||||
procedure: input.procedure,
|
||||
include_assembly: true,
|
||||
max_pseudocode_chars: input.max_pseudocode_chars,
|
||||
max_instructions: input.max_instructions,
|
||||
});
|
||||
const result = await this.#call("analyze_function", analysisInput, signal);
|
||||
if (!result.ok) return result;
|
||||
const parsed = parseFunctionDossier(result.value);
|
||||
if (!parsed.ok) return parsed;
|
||||
const dossier = functionDossierSchema.parse(parsed.value);
|
||||
return ok(jsonValueSchema.parse(projectNativeApiInspection(dossier)));
|
||||
}
|
||||
|
||||
async #swiftClasses(pattern: string, signal?: AbortSignal): EnhancedResult {
|
||||
const procedures = await this.#allAddressed("list_procedures", signal);
|
||||
return procedures.ok
|
||||
|
||||
@@ -0,0 +1,113 @@
|
||||
import type { AnalysisProfileCommitment } from "../domain/analysisProfile.js";
|
||||
import type { BinaryTarget } from "../domain/binaryTarget.js";
|
||||
import type {
|
||||
AnalysisClient,
|
||||
AnalysisClientContext,
|
||||
AnalysisProvider,
|
||||
CapabilityDescriptor,
|
||||
ProviderIdentity,
|
||||
ProviderRequestActivitySnapshot,
|
||||
ProviderRuntimeLineageSnapshot,
|
||||
} from "./AnalysisProvider.js";
|
||||
|
||||
type LoadAnalysisProvider = () => Promise<AnalysisProvider>;
|
||||
|
||||
/**
|
||||
* Preserve synchronous provider discovery while loading implementation modules
|
||||
* only when a target-bound client first executes.
|
||||
*/
|
||||
export class LazyAnalysisProvider implements AnalysisProvider {
|
||||
readonly #providerIdentity: ProviderIdentity;
|
||||
readonly #capabilityDescriptors: readonly CapabilityDescriptor[];
|
||||
readonly #loadProvider: LoadAnalysisProvider;
|
||||
#provider: Promise<AnalysisProvider> | undefined;
|
||||
|
||||
constructor(options: {
|
||||
readonly identity: ProviderIdentity;
|
||||
readonly capabilities: readonly CapabilityDescriptor[];
|
||||
readonly load: LoadAnalysisProvider;
|
||||
}) {
|
||||
this.#providerIdentity = options.identity;
|
||||
this.#capabilityDescriptors = options.capabilities;
|
||||
this.#loadProvider = options.load;
|
||||
}
|
||||
|
||||
/** Return generated provider identity without loading its implementation. */
|
||||
identity(): ProviderIdentity {
|
||||
return this.#providerIdentity;
|
||||
}
|
||||
|
||||
/** Return generated capability metadata without loading its implementation. */
|
||||
capabilities(): readonly CapabilityDescriptor[] {
|
||||
return this.#capabilityDescriptors;
|
||||
}
|
||||
|
||||
/** Create a client whose implementation is loaded on first execution. */
|
||||
createClient(
|
||||
target: BinaryTarget,
|
||||
profile?: AnalysisProfileCommitment,
|
||||
context?: AnalysisClientContext,
|
||||
): AnalysisClient {
|
||||
return new LazyAnalysisClient(async () => {
|
||||
const provider = await this.#load();
|
||||
return provider.createClient(target, profile, context);
|
||||
});
|
||||
}
|
||||
|
||||
async #load(): Promise<AnalysisProvider> {
|
||||
this.#provider ??= this.#loadProvider().catch((cause: unknown) => {
|
||||
this.#provider = undefined;
|
||||
throw cause;
|
||||
});
|
||||
return this.#provider;
|
||||
}
|
||||
}
|
||||
|
||||
class LazyAnalysisClient implements AnalysisClient {
|
||||
readonly #loadClient: () => Promise<AnalysisClient>;
|
||||
#client: AnalysisClient | undefined;
|
||||
#loading: Promise<AnalysisClient> | undefined;
|
||||
#closed = false;
|
||||
|
||||
constructor(loadClient: () => Promise<AnalysisClient>) {
|
||||
this.#loadClient = loadClient;
|
||||
}
|
||||
|
||||
execute: AnalysisClient["execute"] = async (
|
||||
operation,
|
||||
parameters,
|
||||
options,
|
||||
) => {
|
||||
const client = await this.#load();
|
||||
return client.execute(operation, parameters, options);
|
||||
};
|
||||
|
||||
runtimeLineageSnapshots(): readonly ProviderRuntimeLineageSnapshot[] {
|
||||
return this.#client?.runtimeLineageSnapshots?.() ?? [];
|
||||
}
|
||||
|
||||
requestActivitySnapshots(): readonly ProviderRequestActivitySnapshot[] {
|
||||
return this.#client?.requestActivitySnapshots?.() ?? [];
|
||||
}
|
||||
|
||||
async close(): Promise<void> {
|
||||
this.#closed = true;
|
||||
if (this.#loading === undefined) return;
|
||||
const client = await this.#loading;
|
||||
await client.close();
|
||||
}
|
||||
|
||||
async #load(): Promise<AnalysisClient> {
|
||||
if (this.#closed) throw new Error("Lazy analysis client is closed");
|
||||
this.#loading ??= this.#loadClient()
|
||||
.then((client) => {
|
||||
this.#client = client;
|
||||
return client;
|
||||
})
|
||||
.catch((cause: unknown) => {
|
||||
this.#loading = undefined;
|
||||
throw cause;
|
||||
});
|
||||
return this.#loading;
|
||||
}
|
||||
}
|
||||
@@ -500,12 +500,12 @@ export const startLoopbackReplay = async (
|
||||
async close() {
|
||||
closePromise ??= (async () => {
|
||||
recorder.stopMachineAdmission();
|
||||
await recorder.drainMachine();
|
||||
for (const client of websocket.clients) client.terminate();
|
||||
await new Promise<void>((resolveClose) =>
|
||||
websocket.close(() => resolveClose()),
|
||||
);
|
||||
await closeReplayServer(server);
|
||||
await recorder.drainMachine();
|
||||
})();
|
||||
await closePromise;
|
||||
},
|
||||
|
||||
@@ -0,0 +1,113 @@
|
||||
import type { FunctionDossier } from "../domain/hopperValues.js";
|
||||
import {
|
||||
nativeApiInspectionResultSchema,
|
||||
type NativeApiBoundary,
|
||||
type NativeApiInspectionResult,
|
||||
} from "../domain/nativeApiBoundary.js";
|
||||
|
||||
const unavailableBoundary = (): NativeApiBoundary => ({
|
||||
available: false,
|
||||
reason:
|
||||
"The selected provider did not expose a structured native API boundary model.",
|
||||
residual_unknowns: [
|
||||
"What are the function's return and parameter boundary types?",
|
||||
"Does this function dispatch through a jump table with recoverable data addresses?",
|
||||
],
|
||||
});
|
||||
|
||||
/** Project one analyzed-function dossier into inspectable native API substeps. */
|
||||
export const projectNativeApiInspection = (
|
||||
dossier: FunctionDossier,
|
||||
): NativeApiInspectionResult => {
|
||||
const boundary = dossier.native_api ?? unavailableBoundary();
|
||||
const unsupportedBranches = boundary.available
|
||||
? []
|
||||
: ["structured-boundary-types", "jump-table-data-mapping"];
|
||||
const residualUnknowns = boundary.available
|
||||
? availableResidualUnknowns(boundary)
|
||||
: boundary.residual_unknowns;
|
||||
return nativeApiInspectionResultSchema.parse({
|
||||
schema_version: 1,
|
||||
procedure: {
|
||||
address: dossier.procedure.address,
|
||||
name: dossier.procedure.name,
|
||||
},
|
||||
boundary,
|
||||
substeps: [
|
||||
{
|
||||
operation: "analyze_function",
|
||||
status: "completed",
|
||||
observations: [
|
||||
"provider function dossier",
|
||||
"provider pseudocode classification",
|
||||
"provider control-flow observations",
|
||||
],
|
||||
},
|
||||
{
|
||||
operation: "project_native_api_boundary",
|
||||
status: boundary.available ? "completed" : "unsupported",
|
||||
observations: boundary.available
|
||||
? [
|
||||
"return and parameter boundary types",
|
||||
"confidence and inference evidence",
|
||||
"jump-table dispatch, data, and target addresses",
|
||||
]
|
||||
: [boundary.reason],
|
||||
},
|
||||
{
|
||||
operation: "preserve_residual_unknowns",
|
||||
status: "completed",
|
||||
observations:
|
||||
residualUnknowns.length === 0
|
||||
? ["no additional structured-boundary unknowns"]
|
||||
: residualUnknowns,
|
||||
},
|
||||
],
|
||||
unsupported_branches: unsupportedBranches,
|
||||
residual_unknowns: residualUnknowns,
|
||||
});
|
||||
};
|
||||
|
||||
const availableResidualUnknowns = (
|
||||
boundary: Extract<NativeApiBoundary, { readonly available: true }>,
|
||||
): readonly string[] => {
|
||||
const unknowns: string[] = [];
|
||||
if (boundary.parameters_truncated)
|
||||
unknowns.push(
|
||||
"Which additional parameters were omitted by the native API boundary limit?",
|
||||
);
|
||||
if (boundary.jump_tables_truncated)
|
||||
unknowns.push(
|
||||
"Which additional jump tables were omitted by the native API boundary limit?",
|
||||
);
|
||||
for (const table of boundary.jump_tables) {
|
||||
if (table.data_sources_truncated || table.mappings_truncated)
|
||||
unknowns.push(
|
||||
`Which additional data sources or targets were omitted for the jump table dispatched at ${table.dispatch_address}?`,
|
||||
);
|
||||
if (table.data_sources.length === 0)
|
||||
unknowns.push(
|
||||
`What backing data address produced the jump table dispatched at ${table.dispatch_address}?`,
|
||||
);
|
||||
if (
|
||||
table.data_sources.some(
|
||||
({ entry_count: count, entry_size_bytes: size }) =>
|
||||
count === null || size === null,
|
||||
)
|
||||
)
|
||||
unknowns.push(
|
||||
`What are the exact entry size and count for candidate jump-table data dispatched at ${table.dispatch_address}?`,
|
||||
);
|
||||
if (table.mappings.some(({ case_value: value }) => value === null))
|
||||
unknowns.push(
|
||||
`Which source-level case values correspond to every target dispatched at ${table.dispatch_address}?`,
|
||||
);
|
||||
}
|
||||
for (const value of [boundary.return_type, ...boundary.parameters]) {
|
||||
if (value.confidence === "low")
|
||||
unknowns.push(
|
||||
`Can the inferred ${value.role} type ${value.data_type} be confirmed with imported metadata or an ABI probe?`,
|
||||
);
|
||||
}
|
||||
return [...new Set(unknowns)];
|
||||
};
|
||||
@@ -49,8 +49,8 @@ export interface SessionProviderRoute {
|
||||
): AnalysisClient;
|
||||
}
|
||||
|
||||
interface LegacyProviderRuntime {
|
||||
readonly kind: "legacy";
|
||||
interface SingleProviderRuntime {
|
||||
readonly kind: "single";
|
||||
readonly provider: AnalysisProvider | AnalysisClientFactory;
|
||||
readonly identity: ProviderIdentity;
|
||||
readonly capabilities: ReadonlyMap<string, CapabilityDescriptor> | undefined;
|
||||
@@ -71,7 +71,7 @@ interface SelectableProviderRuntime {
|
||||
/** Resolve either the compatibility single-provider seam or a selectable set. */
|
||||
export class SessionProviderRouter {
|
||||
private constructor(
|
||||
private readonly runtime: LegacyProviderRuntime | SelectableProviderRuntime,
|
||||
private readonly runtime: SingleProviderRuntime | SelectableProviderRuntime,
|
||||
) {}
|
||||
|
||||
/** Preserve the existing provider/factory seam used by focused embedders. */
|
||||
@@ -104,7 +104,7 @@ export class SessionProviderRouter {
|
||||
provider.resolveAnalysisProfile?.(target, resolutionOptions) ??
|
||||
Promise.resolve(ok({ profile: null, compatibility: {} })));
|
||||
return new SessionProviderRouter({
|
||||
kind: "legacy",
|
||||
kind: "single",
|
||||
provider,
|
||||
identity,
|
||||
capabilities,
|
||||
@@ -148,7 +148,7 @@ export class SessionProviderRouter {
|
||||
|
||||
/** Provider identities exposed through the flat 1.x compatibility field. */
|
||||
providerIdentities(route: SessionProviderRoute): readonly ProviderIdentity[] {
|
||||
if (this.runtime.kind === "legacy") {
|
||||
if (this.runtime.kind === "single") {
|
||||
if (route.capabilities === undefined) return [route.identity];
|
||||
return uniqueProviderIdentities(
|
||||
[...route.capabilities.values()].map(({ provider }) => provider),
|
||||
@@ -177,7 +177,7 @@ export class SessionProviderRouter {
|
||||
binding: null,
|
||||
selection: undefined,
|
||||
createClient: (target, context) =>
|
||||
createLegacyClient(runtime, target, undefined, context),
|
||||
createSingleProviderClient(runtime, target, undefined, context),
|
||||
};
|
||||
}
|
||||
|
||||
@@ -231,7 +231,7 @@ export class SessionProviderRouter {
|
||||
binding: null,
|
||||
selection: undefined,
|
||||
createClient: (openedTarget, context) =>
|
||||
createLegacyClient(
|
||||
createSingleProviderClient(
|
||||
runtime,
|
||||
openedTarget,
|
||||
normalized.value.profile ?? undefined,
|
||||
@@ -244,7 +244,7 @@ export class SessionProviderRouter {
|
||||
candidateStatuses(
|
||||
route: SessionProviderRoute,
|
||||
): readonly AnalysisProviderCandidateStatus[] {
|
||||
if (this.runtime.kind === "legacy") return [];
|
||||
if (this.runtime.kind === "single") return [];
|
||||
return route.selection?.candidates ?? this.runtime.registry.candidates();
|
||||
}
|
||||
|
||||
@@ -292,8 +292,8 @@ const selectableRoute = (
|
||||
};
|
||||
};
|
||||
|
||||
const createLegacyClient = (
|
||||
runtime: LegacyProviderRuntime,
|
||||
const createSingleProviderClient = (
|
||||
runtime: SingleProviderRuntime,
|
||||
target: BinaryTarget,
|
||||
profile: AnalysisProfileCommitment | undefined,
|
||||
context: AnalysisClientContext,
|
||||
|
||||
@@ -6,6 +6,7 @@ import writeFileAtomic from "write-file-atomic";
|
||||
import { parse as parseToml, stringify as stringifyToml } from "smol-toml";
|
||||
|
||||
import { PRODUCT_IDENTITY } from "../identity.js";
|
||||
import { MCP_STARTUP_POLICY } from "../mcpStartupPolicy.js";
|
||||
import { resolveClientConfigTransactionPath } from "./ClientConfigPath.js";
|
||||
import type {
|
||||
ClientConfigurationInspection,
|
||||
@@ -21,8 +22,6 @@ const defaultCommand = (): readonly string[] => [
|
||||
"mcp",
|
||||
];
|
||||
|
||||
const CODEX_STARTUP_TIMEOUT_SECONDS = 30;
|
||||
|
||||
/** Back up, atomically update, and semantically read back one JSON MCP configuration. */
|
||||
export const configureJsonClient = async (
|
||||
client: SetupClient,
|
||||
@@ -299,7 +298,9 @@ const clientConfigurationDesired = (
|
||||
command: command[0] ?? PRODUCT_IDENTITY.cliBinary,
|
||||
args: command.slice(1),
|
||||
...(client.name === "codex"
|
||||
? { startup_timeout_sec: CODEX_STARTUP_TIMEOUT_SECONDS }
|
||||
? {
|
||||
startup_timeout_sec: MCP_STARTUP_POLICY.codexStartupTimeoutSeconds,
|
||||
}
|
||||
: {}),
|
||||
...(Object.keys(environment).length === 0 ? {} : { env: environment }),
|
||||
};
|
||||
|
||||
+42
-15
@@ -1,13 +1,12 @@
|
||||
import type { AppConfig } from "../config.js";
|
||||
import { BinarySession } from "./BinarySession.js";
|
||||
import type { BinarySession } from "./BinarySession.js";
|
||||
import { HopperProvider } from "../hopper/HopperProvider.js";
|
||||
import { GhidraProvider } from "../ghidra/GhidraProvider.js";
|
||||
import { NativeMacOSProvider } from "../native/NativeMacOSProvider.js";
|
||||
import { ArtifactProvider } from "../artifacts/ArtifactProvider.js";
|
||||
import { ManagedStaticProvider } from "../dotnet/ManagedStaticProvider.js";
|
||||
import { silentLogger, type Logger } from "../logger.js";
|
||||
import { GENERATED_AUXILIARY_PROVIDERS } from "../generatedMcpToolCatalog.js";
|
||||
import { AnalysisProviderRegistry } from "./AnalysisProviderRegistry.js";
|
||||
import { SessionProviderRouter } from "./SessionProviderRouter.js";
|
||||
import { composeBinarySession } from "./BinarySessionComposition.js";
|
||||
import { LazyAnalysisProvider } from "./LazyAnalysisProvider.js";
|
||||
|
||||
/**
|
||||
* Compose the target-switching runtime shared directly by CLI and MCP adapters.
|
||||
@@ -20,17 +19,45 @@ export const createBinarySession = (
|
||||
): BinarySession => {
|
||||
const hopper = new HopperProvider(config, logger);
|
||||
const ghidra = new GhidraProvider(config, logger);
|
||||
return new BinarySession(
|
||||
SessionProviderRouter.selectable(
|
||||
new AnalysisProviderRegistry([hopper, ghidra], config.analysisProvider),
|
||||
[
|
||||
new ArtifactProvider(
|
||||
const auxiliary = new Map(
|
||||
GENERATED_AUXILIARY_PROVIDERS.map((provider) => [
|
||||
provider.identity.id,
|
||||
provider,
|
||||
]),
|
||||
);
|
||||
const lazyProvider = (
|
||||
id: string,
|
||||
load: ConstructorParameters<typeof LazyAnalysisProvider>[0]["load"],
|
||||
) => {
|
||||
const generated = auxiliary.get(id);
|
||||
if (generated === undefined)
|
||||
throw new TypeError(`Missing generated provider metadata for ${id}`);
|
||||
return new LazyAnalysisProvider({ ...generated, load });
|
||||
};
|
||||
return composeBinarySession(
|
||||
new AnalysisProviderRegistry([hopper, ghidra], config.analysisProvider),
|
||||
[
|
||||
lazyProvider("rea-artifact-graph", async () => {
|
||||
const { ArtifactProvider } = await import(
|
||||
"../artifacts/ArtifactProvider.js"
|
||||
);
|
||||
return new ArtifactProvider(
|
||||
config.artifactNativeMountEnabled,
|
||||
config.artifactIntegrityContinueEnabled,
|
||||
),
|
||||
new NativeMacOSProvider(),
|
||||
new ManagedStaticProvider(),
|
||||
],
|
||||
),
|
||||
);
|
||||
}),
|
||||
lazyProvider("native-macos", async () => {
|
||||
const { NativeMacOSProvider } = await import(
|
||||
"../native/NativeMacOSProvider.js"
|
||||
);
|
||||
return new NativeMacOSProvider();
|
||||
}),
|
||||
lazyProvider("rea-dotnet-static", async () => {
|
||||
const { ManagedStaticProvider } = await import(
|
||||
"../dotnet/ManagedStaticProvider.js"
|
||||
);
|
||||
return new ManagedStaticProvider();
|
||||
}),
|
||||
],
|
||||
);
|
||||
};
|
||||
|
||||
@@ -50,6 +50,7 @@ export class ArtifactReaderFailure extends Error {
|
||||
| "integrity"
|
||||
| "limit"
|
||||
| "path"
|
||||
| "policy"
|
||||
| "unavailable",
|
||||
message: string,
|
||||
options?: ErrorOptions,
|
||||
|
||||
@@ -35,7 +35,7 @@ const promptCatalog = PROMPT_CONTRACTS.map((contract) => ({
|
||||
/** Canonical fixed resources exposed by every target-free MCP session. */
|
||||
export const MCP_RESOURCE_CATALOG = [
|
||||
{ name: "server-identity", uri: "rea://server/identity" },
|
||||
{ name: "active-residual-unknowns", uri: "rea://unknowns/active" },
|
||||
{ name: "analysis-snapshot", uri: "rea://snapshot/current" },
|
||||
] as const;
|
||||
/** Canonical resource templates exposed by every target-free MCP session. */
|
||||
export const MCP_RESOURCE_TEMPLATE_CATALOG = [
|
||||
@@ -46,8 +46,8 @@ export const MCP_RESOURCE_TEMPLATE_CATALOG = [
|
||||
},
|
||||
{ name: "residual-unknown", uri_template: "rea://unknown/{unknownId}" },
|
||||
{
|
||||
name: "analysis-snapshot",
|
||||
uri_template: "rea://snapshot/{snapshotDigest}",
|
||||
name: "evidence-bundle",
|
||||
uri_template: "rea://evidence-bundle/{bundleDigest}",
|
||||
},
|
||||
{
|
||||
name: "artifact-page",
|
||||
|
||||
@@ -90,14 +90,16 @@ const registerExtractionCommand = (cli: CliInstance, logger: Logger): void => {
|
||||
args: z.object({
|
||||
path: z.string().describe("Application or package path"),
|
||||
outputRoot: z.string().describe("Absent absolute output root"),
|
||||
}),
|
||||
options: z.object({
|
||||
occurrenceIds: z
|
||||
.array(z.string().regex(/^occ_[a-f0-9]{64}$/u))
|
||||
.min(1)
|
||||
.max(500)
|
||||
.describe("Exact artifact occurrence IDs selected for extraction"),
|
||||
}),
|
||||
alias: { outputRoot: "output-root", occurrenceIds: "occurrence-ids" },
|
||||
run: ({ args }) =>
|
||||
alias: { occurrenceIds: "occurrence-ids" },
|
||||
run: ({ args, options }) =>
|
||||
logCliCommand(logger, "extract-artifact", () =>
|
||||
runProviderAnalysis(
|
||||
args.path,
|
||||
@@ -105,7 +107,7 @@ const registerExtractionCommand = (cli: CliInstance, logger: Logger): void => {
|
||||
{
|
||||
approved: true,
|
||||
output_root: args.outputRoot,
|
||||
occurrence_ids: args.occurrenceIds,
|
||||
occurrence_ids: options.occurrenceIds,
|
||||
},
|
||||
logger,
|
||||
),
|
||||
|
||||
@@ -16,6 +16,7 @@ export const registerCoreAnalysisCommands = (
|
||||
): void => {
|
||||
registerCoreCommands(cli, logger);
|
||||
registerFunctionCommand(cli, logger);
|
||||
registerNativeApiCommand(cli, logger);
|
||||
registerInstructionsCommand(cli, logger);
|
||||
registerSearchCommand(cli, logger);
|
||||
registerXrefsCommand(cli, logger);
|
||||
@@ -286,6 +287,55 @@ const registerFunctionCommand = (cli: CliInstance, logger: Logger): void => {
|
||||
});
|
||||
};
|
||||
|
||||
const registerNativeApiCommand = (cli: CliInstance, logger: Logger): void => {
|
||||
cli.command(CLI_COMMANDS.inspectNativeApi, {
|
||||
description: "Reconstruct one native function API boundary with evidence",
|
||||
args: z.object({
|
||||
path: z.string().describe("App or program path"),
|
||||
address: z.string().describe("Procedure name or address"),
|
||||
}),
|
||||
options: z.object({
|
||||
maxPseudocodeChars: z
|
||||
.number()
|
||||
.int()
|
||||
.min(1)
|
||||
.max(100_000)
|
||||
.default(20_000)
|
||||
.describe("Maximum pseudocode characters to inspect"),
|
||||
maxInstructions: z
|
||||
.number()
|
||||
.int()
|
||||
.min(1)
|
||||
.max(5_000)
|
||||
.default(500)
|
||||
.describe("Maximum assembly instructions to inspect"),
|
||||
snapshot: z
|
||||
.string()
|
||||
.min(1)
|
||||
.optional()
|
||||
.describe("Load and update a local analysis snapshot"),
|
||||
provider: providerSelectionOption,
|
||||
}),
|
||||
alias: {
|
||||
maxPseudocodeChars: "max-pseudocode-chars",
|
||||
maxInstructions: "max-instructions",
|
||||
},
|
||||
run: ({ args, options }) =>
|
||||
logCliCommand(logger, "inspect-native-api", () =>
|
||||
runDirectAnalysis(
|
||||
args.path,
|
||||
"inspect_native_api",
|
||||
{
|
||||
procedure: args.address,
|
||||
max_pseudocode_chars: options.maxPseudocodeChars,
|
||||
max_instructions: options.maxInstructions,
|
||||
},
|
||||
directAnalysisOptions(logger, options.snapshot, options.provider),
|
||||
),
|
||||
),
|
||||
});
|
||||
};
|
||||
|
||||
const registerInstructionsCommand = (
|
||||
cli: CliInstance,
|
||||
logger: Logger,
|
||||
|
||||
@@ -12,6 +12,7 @@ export const CLI_COMMANDS = Object.freeze({
|
||||
capabilities: "capabilities",
|
||||
providers: "providers",
|
||||
function: "function",
|
||||
inspectNativeApi: "inspect-native-api",
|
||||
instructions: "instructions",
|
||||
search: "search",
|
||||
importReferenceSource: "import-reference-source",
|
||||
|
||||
@@ -1,3 +1,4 @@
|
||||
import { isAbsolute } from "node:path";
|
||||
import { z } from "zod";
|
||||
|
||||
import type { ToolContract } from "./toolContracts.js";
|
||||
@@ -59,7 +60,11 @@ export const artifactInventoryInputSchema = z
|
||||
/** Exact caller boundary for approved artifact extraction. */
|
||||
export const artifactExtractionInputSchema = z.object({
|
||||
approved: z.literal(true),
|
||||
output_root: z.string().min(1).max(4_096),
|
||||
output_root: z
|
||||
.string()
|
||||
.min(1)
|
||||
.max(4_096)
|
||||
.refine(isAbsolute, "Extraction output root must be absolute"),
|
||||
occurrence_ids: z
|
||||
.array(z.string().regex(/^occ_[a-f0-9]{64}$/u))
|
||||
.min(1)
|
||||
@@ -130,12 +135,12 @@ const artifact = <Name extends string>(
|
||||
export const ARTIFACT_TOOL_CONTRACTS = [
|
||||
artifact(
|
||||
"inventory_artifact",
|
||||
"Inventory the active application or package as a deterministic, content-addressed artifact graph. Returns bounded node and edge pages without extracting or mounting by default.",
|
||||
"After open_binary binds a local archive, application package, or other artifact—or when one is already active—inventory it as a deterministic, content-addressed artifact graph. This tool accepts no path; in a target-free session open the target first. Returns bounded node and edge pages without extracting or mounting by default.",
|
||||
artifactInventoryInputSchema,
|
||||
),
|
||||
artifact(
|
||||
"inspect_artifact",
|
||||
"Inspect the active artifact through one bounded, cancellable inventory substep. Returns the full substep Evidence and its ID, observations, derived relationships, hypotheses, contradictions, unexplored branches, limitations, and format-specific next probes. Any substep failure fails the whole call.",
|
||||
"After open_binary binds a local archive, application package, or other artifact—or when one is already active—inspect it through one bounded, cancellable inventory substep. This tool accepts no path; in a target-free session open the target first. Returns the full substep Evidence and its ID, observations, derived relationships, hypotheses, contradictions, unexplored branches, limitations, and format-specific next probes. Any substep failure fails the whole call.",
|
||||
artifactInspectionInputSchema,
|
||||
),
|
||||
artifact(
|
||||
|
||||
@@ -63,6 +63,17 @@ export const enhancedInputSchemas = {
|
||||
basic_blocks: 0,
|
||||
}),
|
||||
}),
|
||||
inspect_native_api: z.object({
|
||||
procedure: z.string().describe("A procedure name or address"),
|
||||
max_pseudocode_chars: z.number().int().min(1).max(100_000).default(20_000),
|
||||
max_instructions: z.number().int().min(1).max(5_000).default(500),
|
||||
unknown_registry_approved: z
|
||||
.literal(true)
|
||||
.optional()
|
||||
.describe(
|
||||
"Explicit approval to record unsupported native API branches durably",
|
||||
),
|
||||
}),
|
||||
trace_feature: traceLiteralInputSchema,
|
||||
find_code_for_string: traceLiteralInputSchema,
|
||||
trace_call_path: z.object({
|
||||
@@ -95,6 +106,7 @@ export const enhancedToolNameSchema = z.enum([
|
||||
"find_xrefs_to_name",
|
||||
"binary_overview",
|
||||
"analyze_function",
|
||||
"inspect_native_api",
|
||||
"trace_feature",
|
||||
"find_code_for_string",
|
||||
"trace_call_path",
|
||||
|
||||
@@ -0,0 +1,46 @@
|
||||
import { jsonObjectSchema } from "../domain/jsonValue.js";
|
||||
import { enhancedInputSchemas } from "./enhancedInputs.js";
|
||||
import { TOOL_EXAMPLE_OVERRIDES } from "./toolContractExamples.js";
|
||||
import type { ToolContract } from "./toolContractTypes.js";
|
||||
import { toolContractMetadata } from "./toolEffects.js";
|
||||
import { enhancedOutputSchemas } from "./toolOutputSchemas.js";
|
||||
|
||||
type FunctionWorkflowName = "analyze_function" | "inspect_native_api";
|
||||
|
||||
const functionWorkflow = <Name extends FunctionWorkflowName>(
|
||||
name: Name,
|
||||
description: string,
|
||||
): ToolContract<Name> => {
|
||||
const inputSchema = enhancedInputSchemas[name];
|
||||
const outputSchema = enhancedOutputSchemas[name];
|
||||
if (outputSchema === undefined)
|
||||
throw new Error(`Missing function workflow output schema for ${name}`);
|
||||
return {
|
||||
name,
|
||||
...toolContractMetadata(name),
|
||||
description,
|
||||
kind: "enhanced",
|
||||
inputSchema,
|
||||
outputSchema,
|
||||
examples: [
|
||||
{
|
||||
title: `Example ${name.replaceAll("_", " ")} request`,
|
||||
input: jsonObjectSchema.parse(
|
||||
inputSchema.parse(TOOL_EXAMPLE_OVERRIDES[name] ?? {}),
|
||||
),
|
||||
},
|
||||
],
|
||||
};
|
||||
};
|
||||
|
||||
/** Function dossier and native API reconstruction workflow contracts. */
|
||||
export const FUNCTION_WORKFLOW_TOOL_CONTRACTS = [
|
||||
functionWorkflow(
|
||||
"analyze_function",
|
||||
"Preferred bounded analysis for one procedure symbol or address. Returns identity, provider-specific pseudocode, optional assembly, comments, calls, typed-or-explicitly-unavailable references, referenced strings/names, and local CFG blocks with exact truncation metadata. Providers with a structured decompiler model also expose native API boundary types, confidence, evidence, jump-table data/target addresses, and explicit decompiler-artifact labels.",
|
||||
),
|
||||
functionWorkflow(
|
||||
"inspect_native_api",
|
||||
"Reconstruct one native function boundary through inspectable substeps. Returns structured inferred return/parameter types with confidence and evidence, jump-table dispatch/data/target mappings, explicit decompiler-artifact labels, unsupported branches, and residual unknowns.",
|
||||
),
|
||||
] as const satisfies readonly ToolContract[];
|
||||
@@ -1,4 +1,4 @@
|
||||
import { TOOL_CONTRACTS } from "./toolContracts.js";
|
||||
import type { TOOL_CONTRACTS } from "./toolContracts.js";
|
||||
|
||||
type ToolName = (typeof TOOL_CONTRACTS)[number]["name"];
|
||||
|
||||
@@ -149,9 +149,9 @@ export const PROMPT_CONTRACTS = [
|
||||
"Build function dossiers and corroborate references and call relationships. Keep indirect or truncated paths unknown.",
|
||||
},
|
||||
{
|
||||
tools: ["export_evidence_bundle", "record_unknown"],
|
||||
tools: ["snapshot_evidence_bundle", "record_unknown"],
|
||||
instruction:
|
||||
"Cite retained Evidence IDs. Record residual unknowns only after separate explicit approval for registry mutation.",
|
||||
"Snapshot the canonical bundle, copy its opaque URI unchanged, and read that resource before citing retained Evidence IDs. Record residual unknowns only after separate explicit approval for registry mutation.",
|
||||
},
|
||||
],
|
||||
},
|
||||
@@ -184,9 +184,9 @@ export const PROMPT_CONTRACTS = [
|
||||
},
|
||||
steps: [
|
||||
{
|
||||
tools: ["inventory_artifact"],
|
||||
tools: ["open_binary", "inventory_artifact"],
|
||||
instruction:
|
||||
"Inventory each target independently before extraction. Follow nodes, occurrences, and edges to completion and retain every Evidence page for each manifest.",
|
||||
"For each supplied target path, open that target before inventory because inventory_artifact uses the active target and accepts no path. Follow nodes, occurrences, and edges to completion and retain every Evidence page for each manifest.",
|
||||
},
|
||||
{
|
||||
tools: [
|
||||
@@ -198,9 +198,9 @@ export const PROMPT_CONTRACTS = [
|
||||
"For JavaScript/Electron versions, reconstruct each approved artifact independently, optionally reconcile separately retained passive runtime Evidence, then compare authenticated graphs with unique-only identity tiers. Keep ambiguous and incomplete matches unknown.",
|
||||
},
|
||||
{
|
||||
tools: ["export_evidence_bundle", "compare_artifacts"],
|
||||
tools: ["snapshot_evidence_bundle", "compare_artifacts"],
|
||||
instruction:
|
||||
"Resolve any supplied manifest IDs to retained inventory Evidence, validate graph commitments, then compare the complete left and right Evidence page sets.",
|
||||
"Snapshot and read the canonical bundle through its exact resource URI, resolve any supplied manifest IDs to retained inventory Evidence, validate graph commitments, then compare the complete left and right Evidence page sets.",
|
||||
},
|
||||
{
|
||||
tools: ["open_binary", "analyze_function", "compare_functions"],
|
||||
@@ -241,9 +241,9 @@ export const PROMPT_CONTRACTS = [
|
||||
},
|
||||
steps: [
|
||||
{
|
||||
tools: ["export_evidence_bundle"],
|
||||
tools: ["snapshot_evidence_bundle"],
|
||||
instruction:
|
||||
"Load the current canonical bundle and verify that every selected comparison Evidence ID is present and compatible with the intended claim.",
|
||||
"Snapshot the current canonical bundle, copy its opaque URI unchanged, read the resource, and verify that every selected comparison Evidence ID is present and compatible with the intended claim.",
|
||||
},
|
||||
{
|
||||
tools: [
|
||||
@@ -313,12 +313,12 @@ export const PROMPT_CONTRACTS = [
|
||||
},
|
||||
{
|
||||
tools: [
|
||||
"export_evidence_bundle",
|
||||
"snapshot_evidence_bundle",
|
||||
"capture_process_scenario",
|
||||
"correlate_static_and_runtime",
|
||||
],
|
||||
instruction:
|
||||
"Reuse a retained capture when supplied. Otherwise capture only after operator policy and per-call approval, then correlate through explicit hypotheses rather than timing or name coincidence.",
|
||||
"Snapshot and read retained Evidence through the exact resource URI. Reuse a retained capture when supplied. Otherwise capture only after operator policy and per-call approval, then correlate through explicit hypotheses rather than timing or name coincidence.",
|
||||
},
|
||||
{
|
||||
tools: ["record_unknown"],
|
||||
@@ -354,9 +354,9 @@ export const PROMPT_CONTRACTS = [
|
||||
"List current heads first and select only active, session-owned unknown IDs. Preserve their exact revision and requirements.",
|
||||
},
|
||||
{
|
||||
tools: ["export_evidence_bundle", "verify_unknown_resolution"],
|
||||
tools: ["snapshot_evidence_bundle", "verify_unknown_resolution"],
|
||||
instruction:
|
||||
"Inspect cited supporting, contradicting, and mutation Evidence, then validate any resolved head against bundle integrity and authority requirements.",
|
||||
"Snapshot and read the canonical bundle through its exact resource URI, inspect cited supporting, contradicting, and mutation Evidence, then validate any resolved head against bundle integrity and authority requirements.",
|
||||
},
|
||||
{
|
||||
tools: ["update_unknown"],
|
||||
@@ -399,9 +399,9 @@ export const PROMPT_CONTRACTS = [
|
||||
"Inspect capture capability, declared effects, and limits before proposing execution. An unavailable capability is not permission to widen policy.",
|
||||
},
|
||||
{
|
||||
tools: ["export_evidence_bundle"],
|
||||
tools: ["snapshot_evidence_bundle"],
|
||||
instruction:
|
||||
"Review any prior capture for unanswered dimensions, truncation, scenario commitments, and descendant settlement before designing a repeat.",
|
||||
"Snapshot and read the canonical bundle through its exact resource URI, then review any prior capture for unanswered dimensions, truncation, scenario commitments, and descendant settlement before designing a repeat.",
|
||||
},
|
||||
{
|
||||
tools: ["capture_process_scenario"],
|
||||
|
||||
@@ -35,10 +35,13 @@ export const TOOL_EXAMPLE_OVERRIDES: Readonly<
|
||||
get_call_graph: { address: "0x1000" },
|
||||
find_xrefs_to_name: { name: "malloc" },
|
||||
analyze_function: { procedure: "main" },
|
||||
inspect_native_api: { procedure: "main" },
|
||||
trace_feature: { query: "license" },
|
||||
find_code_for_string: { query: "authorization failed" },
|
||||
trace_call_path: { start: "0x1000", goal: "0x1100" },
|
||||
open_binary: { path: "/tmp/fixture" },
|
||||
export_evidence_bundle: { path: "/tmp/evidence.json" },
|
||||
inspect_address_context: { address: "0x1000" },
|
||||
import_evidence_bundle: { path: "evidence.json" },
|
||||
capture_process_scenario: {
|
||||
approved: true,
|
||||
|
||||
@@ -32,7 +32,7 @@ export const TOOL_KINDS = [
|
||||
] as const;
|
||||
|
||||
/** Adapter family responsible for implementing a public MCP tool. */
|
||||
type ToolKind = (typeof TOOL_KINDS)[number];
|
||||
export type ToolKind = (typeof TOOL_KINDS)[number];
|
||||
|
||||
/** Single source of truth for a public MCP tool. */
|
||||
export interface ToolContract<Name extends string = string> {
|
||||
|
||||
@@ -41,6 +41,7 @@ import { binarySessionInputSchema } from "./sessionStatusContract.js";
|
||||
import { functionInstructionInputSchema } from "./functionInstructionContract.js";
|
||||
import { HOPPER_MEMORY_TOOL_DEFINITIONS } from "./hopperMemoryContracts.js";
|
||||
import { analysisSearchInput } from "./analysisSearchContract.js";
|
||||
import { FUNCTION_WORKFLOW_TOOL_CONTRACTS } from "./functionWorkflowToolContracts.js";
|
||||
|
||||
export { binarySessionInputSchema } from "./sessionStatusContract.js";
|
||||
|
||||
@@ -354,11 +355,7 @@ export const ENHANCED_TOOL_CONTRACTS = [
|
||||
"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, provider-specific pseudocode, optional assembly, comments, calls, typed-or-explicitly-unavailable references, referenced strings/names, and local CFG blocks with exact truncation metadata.",
|
||||
enhancedInputSchemas.analyze_function,
|
||||
),
|
||||
...FUNCTION_WORKFLOW_TOOL_CONTRACTS,
|
||||
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.",
|
||||
@@ -378,10 +375,24 @@ export const ENHANCED_TOOL_CONTRACTS = [
|
||||
|
||||
/** Session-owned Evidence bundle export options. */
|
||||
export const exportEvidenceBundleInputSchema = z.strictObject({
|
||||
path: z.string().min(1).optional(),
|
||||
path: z.string().min(1),
|
||||
overwrite: z.boolean().default(false),
|
||||
});
|
||||
|
||||
/** Retain the current canonical Evidence bundle as a session resource. */
|
||||
export const snapshotEvidenceBundleInputSchema = z.strictObject({});
|
||||
|
||||
/** Optional document selection for volatile navigation context. */
|
||||
export const navigationContextInputSchema = z.strictObject({
|
||||
document: z.string().min(1).optional(),
|
||||
});
|
||||
|
||||
/** Explicit reproducible address context query. */
|
||||
export const addressContextInputSchema = z.strictObject({
|
||||
address: z.string().min(1),
|
||||
document: z.string().min(1).optional(),
|
||||
});
|
||||
|
||||
/** Session-owned Evidence bundle import options. */
|
||||
export const importEvidenceBundleInputSchema = z.strictObject({
|
||||
path: z.string().min(1),
|
||||
@@ -406,6 +417,8 @@ export const listUnknownsInputSchema = z.strictObject({
|
||||
.optional(),
|
||||
severity: z.enum(["low", "medium", "high", "critical"]).optional(),
|
||||
domain: z.string().trim().min(1).max(100).optional(),
|
||||
offset: z.number().int().min(0).default(0),
|
||||
limit: z.number().int().min(1).max(500).default(100),
|
||||
});
|
||||
|
||||
/** Exact residual-unknown identity to revalidate. */
|
||||
@@ -432,7 +445,7 @@ export const SESSION_TOOL_CONTRACTS = [
|
||||
),
|
||||
session(
|
||||
"export_evidence_bundle",
|
||||
"Return the session's deterministic Evidence v2 bundle, or atomically write it beneath an operator-approved root. Existing files require overwrite: true; records and manifests use canonical byte-stable ordering.",
|
||||
"Atomically write the session's deterministic Evidence v2 bundle beneath an operator-approved root. Existing files require overwrite: true; records and manifests use canonical byte-stable ordering. For an in-session read, use snapshot_evidence_bundle and read its exact resource URI instead.",
|
||||
exportEvidenceBundleInputSchema,
|
||||
),
|
||||
session(
|
||||
@@ -487,7 +500,7 @@ export const SESSION_TOOL_CONTRACTS = [
|
||||
),
|
||||
session(
|
||||
"list_unknowns",
|
||||
"List current residual-unknown heads in deterministic ID order, with optional exact status, severity, and domain filters. This is read-only; unresolved, contradicted, and non-truth dispositions remain distinct.",
|
||||
"List current residual-unknown heads in deterministic ID order, with optional exact status, severity, and domain filters. Pages default to 100 items; while has_more is true, pass next_offset as offset and continue until false. This is read-only; unresolved, contradicted, and non-truth dispositions remain distinct.",
|
||||
listUnknownsInputSchema,
|
||||
),
|
||||
session(
|
||||
@@ -510,6 +523,21 @@ export const SESSION_TOOL_CONTRACTS = [
|
||||
"Evaluate ordered HTTP and WebSocket events directly against one validated finite replay machine without opening sockets or launching a target. Returns every decision, a capture-value-free transition journal, one redacted action table entry per used transition, captured aliases, final state, and exact configured and consumed limits.",
|
||||
replayMachineRunInputSchema,
|
||||
),
|
||||
session(
|
||||
"snapshot_evidence_bundle",
|
||||
"Retain the current canonical Evidence v2 bundle as an immutable session resource. Returns a compact digest summary and exact opaque URI; copy that URI unchanged and call MCP resources/read (Codex: read_mcp_resource) for the full bundle. Repeating an unchanged snapshot is idempotent.",
|
||||
snapshotEvidenceBundleInputSchema,
|
||||
),
|
||||
session(
|
||||
"get_navigation_context",
|
||||
"Return the selected document, current address, and containing/current procedure in one coherent provider-neutral request. A cursor outside any procedure returns procedure: null. Scalar navigation getters remain available for evaluation and compatibility.",
|
||||
navigationContextInputSchema,
|
||||
),
|
||||
session(
|
||||
"inspect_address_context",
|
||||
"Inspect one explicit reproducible address for its analyzed name, containing procedure, regular and inline comments, and matching bookmarks. Each unsupported facet returns a typed unavailable outcome; xrefs, assembly, and pseudocode remain separate bounded follow-ups.",
|
||||
addressContextInputSchema,
|
||||
),
|
||||
] as const satisfies readonly ToolContract[];
|
||||
|
||||
/** Complete ordered public inventory used by registration and verification. */
|
||||
|
||||
@@ -89,6 +89,7 @@ export const TOOL_EFFECTS: Readonly<Record<string, ToolEffects>> = {
|
||||
find_xrefs_to_name: evidence,
|
||||
binary_overview: evidence,
|
||||
analyze_function: evidence,
|
||||
inspect_native_api: effects({ mutatesSession: true, idempotent: false }),
|
||||
trace_feature: effects({ mutatesSession: true, idempotent: false }),
|
||||
find_code_for_string: effects({ mutatesSession: true, idempotent: false }),
|
||||
trace_call_path: effects({ mutatesSession: true, idempotent: false }),
|
||||
@@ -171,6 +172,9 @@ export const TOOL_EFFECTS: Readonly<Record<string, ToolEffects>> = {
|
||||
writesFilesystem: true,
|
||||
mayDiscardData: true,
|
||||
}),
|
||||
snapshot_evidence_bundle: effects({ mutatesSession: true }),
|
||||
get_navigation_context: effects({ mutatesSession: true }),
|
||||
inspect_address_context: effects({ mutatesSession: true }),
|
||||
import_evidence_bundle: effects({ mutatesSession: true }),
|
||||
capture_process_scenario: effects({
|
||||
mutatesSession: true,
|
||||
|
||||
@@ -1,15 +1,16 @@
|
||||
import { z } from "zod";
|
||||
import { jsonValueSchema } from "../domain/jsonValue.js";
|
||||
|
||||
import {
|
||||
processCaptureComparisonSchema,
|
||||
processCaptureSchema,
|
||||
} from "../domain/processCapture.js";
|
||||
import { evidenceBundleSchema } from "../domain/evidenceBundle.js";
|
||||
import { residualUnknownSchema } from "../domain/residualUnknown.js";
|
||||
import {
|
||||
functionInstructionWindowSchema,
|
||||
referenceKindSchema,
|
||||
} from "../domain/hopperValues.js";
|
||||
import { nativeApiInspectionResultSchema } from "../domain/nativeApiBoundary.js";
|
||||
import {
|
||||
demangleSwiftSchema,
|
||||
inspectMachoSchema,
|
||||
@@ -66,6 +67,15 @@ import {
|
||||
targetKindSchema,
|
||||
} from "./toolOutputSchemaPrimitives.js";
|
||||
|
||||
const contextFacetSchema = z.discriminatedUnion("state", [
|
||||
z.object({ state: z.literal("available"), value: jsonValueSchema }),
|
||||
z.object({
|
||||
state: z.literal("unavailable"),
|
||||
reason: z.string(),
|
||||
remediation: z.string(),
|
||||
}),
|
||||
]);
|
||||
|
||||
/** Exact structured-content schemas shared by direct analysis providers. */
|
||||
export const officialOutputSchemas: Readonly<Record<string, z.ZodObject>> = {
|
||||
address_name: resultOf(nullableText),
|
||||
@@ -272,6 +282,7 @@ export const enhancedOutputSchemas: Readonly<Record<string, z.ZodObject>> = {
|
||||
}),
|
||||
),
|
||||
analyze_function: functionDossierOutput,
|
||||
inspect_native_api: resultOf(nativeApiInspectionResultSchema),
|
||||
trace_feature: literalTraceOutput,
|
||||
find_code_for_string: literalTraceOutput,
|
||||
trace_call_path: callPathTraceOutput,
|
||||
@@ -401,14 +412,40 @@ export const sessionOutputSchemas: Readonly<Record<string, z.ZodObject>> = {
|
||||
]),
|
||||
),
|
||||
export_evidence_bundle: lifecycleResultOf(
|
||||
z.union([
|
||||
evidenceBundleSchema,
|
||||
z.object({
|
||||
path: z.string(),
|
||||
bytes: z.number().int().min(0),
|
||||
records: z.number().int().min(0),
|
||||
}),
|
||||
]),
|
||||
z.object({
|
||||
path: z.string(),
|
||||
bytes: z.number().int().min(0),
|
||||
records: z.number().int().min(0),
|
||||
unknowns: z.number().int().min(0),
|
||||
}),
|
||||
),
|
||||
snapshot_evidence_bundle: lifecycleResultOf(
|
||||
z.object({
|
||||
bundle_digest: z.string().regex(/^[a-f0-9]{64}$/u),
|
||||
bundle_version: z.literal(2),
|
||||
bytes: z.number().int().min(0),
|
||||
records: z.number().int().min(0),
|
||||
unknowns: z.number().int().min(0),
|
||||
bundle_uri: z.string().regex(/^rea:\/\/evidence-bundle\/[a-f0-9]{64}$/u),
|
||||
}),
|
||||
),
|
||||
get_navigation_context: lifecycleResultOf(
|
||||
z.object({
|
||||
document: z.string(),
|
||||
address: z.string(),
|
||||
procedure: z.union([z.string(), z.null()]),
|
||||
}),
|
||||
),
|
||||
inspect_address_context: lifecycleResultOf(
|
||||
z.object({
|
||||
address: z.string(),
|
||||
document: z.string().nullable(),
|
||||
name: contextFacetSchema,
|
||||
procedure: contextFacetSchema,
|
||||
comment: contextFacetSchema,
|
||||
inline_comment: contextFacetSchema,
|
||||
bookmarks: contextFacetSchema,
|
||||
}),
|
||||
),
|
||||
import_evidence_bundle: lifecycleResultOf(
|
||||
z.object({
|
||||
@@ -425,7 +462,21 @@ export const sessionOutputSchemas: Readonly<Record<string, z.ZodObject>> = {
|
||||
build_call_path: resultOf(callPathResultSchema),
|
||||
correlate_static_and_runtime: resultOf(staticRuntimeCorrelationResultSchema),
|
||||
verify_reconstruction: resultOf(reconstructionVerificationResultSchema),
|
||||
list_unknowns: lifecycleResultOf(z.array(residualUnknownSchema)),
|
||||
list_unknowns: lifecycleResultOf(
|
||||
z.object({
|
||||
items: z.array(
|
||||
z.object({
|
||||
unknown: residualUnknownSchema,
|
||||
uri: z.string().regex(/^rea:\/\/unknown\/unk_[a-f0-9]{64}$/u),
|
||||
}),
|
||||
),
|
||||
offset: z.number().int().min(0),
|
||||
limit: z.number().int().min(1).max(500),
|
||||
total: z.number().int().min(0),
|
||||
next_offset: z.number().int().min(0).nullable(),
|
||||
has_more: z.boolean(),
|
||||
}),
|
||||
),
|
||||
record_unknown: lifecycleResultOf(residualUnknownSchema),
|
||||
update_unknown: lifecycleResultOf(residualUnknownSchema),
|
||||
verify_unknown_resolution: lifecycleResultOf(
|
||||
|
||||
@@ -24,6 +24,8 @@ export const analysisErrorRemediationAction = (
|
||||
): string => {
|
||||
if (error instanceof AnalysisInputError)
|
||||
return "Correct the listed arguments and retry.";
|
||||
if (error instanceof UnknownRegistryError && error.reason === "not-found")
|
||||
return "Check that the unknown_id belongs to this session, then retry.";
|
||||
if (error instanceof ReplayPlanStaleError)
|
||||
return "Review the rebuilt replay plan and explicitly approve its new digest.";
|
||||
if (error instanceof PermissionRequiredError)
|
||||
@@ -99,7 +101,7 @@ const artifactErrorCategory = (
|
||||
if (reason === "integrity") return "integrity_mismatch";
|
||||
if (reason === "limit") return "truncated";
|
||||
if (reason === "cancelled") return "cancelled";
|
||||
if (reason === "unavailable") return "unavailable";
|
||||
if (reason === "policy" || reason === "unavailable") return "unavailable";
|
||||
return "execution_failure";
|
||||
};
|
||||
|
||||
@@ -139,6 +141,8 @@ export const analysisErrorUserMessage = (error: AnalysisError): string => {
|
||||
return evidenceFileMessage(error.reason);
|
||||
if (error instanceof InvestigationWorkspaceError)
|
||||
return investigationWorkspaceMessage(error.reason);
|
||||
if (error instanceof UnknownRegistryError && error.reason === "not-found")
|
||||
return "The requested residual unknown does not exist in this session. Check the unknown_id and try again.";
|
||||
if (error instanceof UnknownRegistryError)
|
||||
return "Evidence state changed before the update completed. Refresh the current state and try again.";
|
||||
if (error instanceof ConfigurationError)
|
||||
@@ -203,8 +207,10 @@ const artifactMessage = (reason: ArtifactOperationError["reason"]): string => {
|
||||
return "Artifact is too large to process safely. Narrow the requested path or use a smaller artifact.";
|
||||
if (reason === "path")
|
||||
return "Artifact path is not allowed. Choose a path inside the artifact and try again.";
|
||||
if (reason === "policy")
|
||||
return "Artifact integrity continuation is disabled by policy. Configure REA_ARTIFACT_INTEGRITY_CONTINUE_ENABLED=true and retry only if continuing after mismatches is approved.";
|
||||
if (reason === "unavailable")
|
||||
return "Artifact format is not available on this system. Choose another artifact or supported environment.";
|
||||
return "Artifact processing is unavailable for the current target or policy. Check artifact support and required approvals.";
|
||||
if (reason === "format" || reason === "integrity")
|
||||
return "Artifact is invalid or has changed. Get a fresh copy and try again.";
|
||||
return "Artifact could not be read or written. Check file access and try again.";
|
||||
|
||||
@@ -220,6 +220,7 @@ const requestErrorDetails = (
|
||||
issues: error.issues.map((issue) => ({
|
||||
path: [...issue.path],
|
||||
reason: issue.reason,
|
||||
...(issue.message === undefined ? {} : { message: issue.message }),
|
||||
...(issue.expected === undefined ? {} : { expected: issue.expected }),
|
||||
...(issue.minimum === undefined ? {} : { minimum: issue.minimum }),
|
||||
...(issue.maximum === undefined ? {} : { maximum: issue.maximum }),
|
||||
|
||||
+1
-1
@@ -1,6 +1,6 @@
|
||||
import { describe, expect, it } from "vitest";
|
||||
|
||||
import { projectBoundedCartesian } from "../src/domain/boundedCartesianProjection.js";
|
||||
import { projectBoundedCartesian } from "./boundedCartesianProjection.js";
|
||||
|
||||
describe("bounded Cartesian projection", () => {
|
||||
it("stops projection work at the output limit", () => {
|
||||
@@ -0,0 +1,206 @@
|
||||
import { z } from "zod";
|
||||
|
||||
/** Supported managed-runtime bytecode families. */
|
||||
export const bytecodeFamilySchema = z.enum(["jvm", "python"]);
|
||||
export type BytecodeFamily = z.infer<typeof bytecodeFamilySchema>;
|
||||
|
||||
/** Classification of bytecode provenance. */
|
||||
export const bytecodeProvenanceSchema = z.enum([
|
||||
"application",
|
||||
"generated",
|
||||
"vendored",
|
||||
"bundled",
|
||||
"standard_library",
|
||||
]);
|
||||
export type BytecodeProvenance = z.infer<typeof bytecodeProvenanceSchema>;
|
||||
|
||||
/** A bytecode symbol discovered through static analysis. */
|
||||
export const bytecodeSymbolSchema = z.strictObject({
|
||||
/** Fully qualified name. */
|
||||
name: z.string().min(1),
|
||||
/** Raw bytecode location or offset. */
|
||||
raw_location: z.string().min(1),
|
||||
/** Normalized symbol type. */
|
||||
kind: z.enum([
|
||||
"class",
|
||||
"interface",
|
||||
"method",
|
||||
"field",
|
||||
"function",
|
||||
"module",
|
||||
"variable",
|
||||
]),
|
||||
/** Bytecode version if known. */
|
||||
bytecode_version: z.number().int().nullable(),
|
||||
/** Provenance classification. */
|
||||
provenance: bytecodeProvenanceSchema,
|
||||
/** Whether the symbol is accessible (public). */
|
||||
is_public: z.boolean().default(false),
|
||||
});
|
||||
export type BytecodeSymbol = z.infer<typeof bytecodeSymbolSchema>;
|
||||
|
||||
/** A discovered bytecode artifact (class file, wheel, etc). */
|
||||
export const bytecodeArtifactSchema = z.strictObject({
|
||||
/** Artifact path relative to the analysis root. */
|
||||
path: z.string().min(1),
|
||||
/** Bytecode family. */
|
||||
family: bytecodeFamilySchema,
|
||||
/** Artifact format. */
|
||||
format: z.enum(["class", "jar", "war", "ear", "pyc", "pyo", "whl", "zipapp"]),
|
||||
/** Size in bytes. */
|
||||
size: z.number().int().nonnegative(),
|
||||
/** SHA-256 digest. */
|
||||
digest: z.string().regex(/^[a-f0-9]{64}$/u),
|
||||
/** Discovered symbols. */
|
||||
symbols: z.array(bytecodeSymbolSchema).default([]),
|
||||
/** Whether this is a standard library artifact. */
|
||||
is_standard_library: z.boolean().default(false),
|
||||
/** Whether this is a generated artifact. */
|
||||
is_generated: z.boolean().default(false),
|
||||
/** Whether this is a vendored artifact. */
|
||||
is_vendored: z.boolean().default(false),
|
||||
});
|
||||
export type BytecodeArtifact = z.infer<typeof bytecodeArtifactSchema>;
|
||||
|
||||
/** Static bytecode analysis result. */
|
||||
export const bytecodeAnalysisSchema = z.strictObject({
|
||||
/** Bytecode family. */
|
||||
family: bytecodeFamilySchema,
|
||||
/** All discovered artifacts. */
|
||||
artifacts: z.array(bytecodeArtifactSchema).min(0).max(10_000),
|
||||
/** Total symbols across all artifacts. */
|
||||
total_symbols: z.number().int().nonnegative(),
|
||||
/** Symbols classified as application code. */
|
||||
application_symbols: z.number().int().nonnegative(),
|
||||
/** Symbols classified as generated code. */
|
||||
generated_symbols: z.number().int().nonnegative(),
|
||||
/** Symbols classified as vendored code. */
|
||||
vendored_symbols: z.number().int().nonnegative(),
|
||||
/** Symbols classified as standard library. */
|
||||
standard_library_symbols: z.number().int().nonnegative(),
|
||||
});
|
||||
export type BytecodeAnalysis = z.infer<typeof bytecodeAnalysisSchema>;
|
||||
|
||||
/** Detect bytecode family from file extension. */
|
||||
export function detectBytecodeFamily(path: string): BytecodeFamily | null {
|
||||
const lower = path.toLowerCase();
|
||||
if (
|
||||
lower.endsWith(".class") ||
|
||||
lower.endsWith(".jar") ||
|
||||
lower.endsWith(".war") ||
|
||||
lower.endsWith(".ear")
|
||||
) {
|
||||
return "jvm";
|
||||
}
|
||||
if (
|
||||
lower.endsWith(".pyc") ||
|
||||
lower.endsWith(".pyo") ||
|
||||
lower.endsWith(".whl") ||
|
||||
lower.endsWith(".pyz") ||
|
||||
lower.endsWith(".zipapp")
|
||||
) {
|
||||
return "python";
|
||||
}
|
||||
return null;
|
||||
}
|
||||
|
||||
/** Detect artifact format from file path. */
|
||||
export function detectArtifactFormat(
|
||||
path: string,
|
||||
): `class` | `jar` | `war` | `ear` | `pyc` | `pyo` | `whl` | `zipapp` | null {
|
||||
const lower = path.toLowerCase();
|
||||
if (lower.endsWith(".class")) return "class";
|
||||
if (lower.endsWith(".jar")) return "jar";
|
||||
if (lower.endsWith(".war")) return "war";
|
||||
if (lower.endsWith(".ear")) return "ear";
|
||||
if (lower.endsWith(".pyc")) return "pyc";
|
||||
if (lower.endsWith(".pyo")) return "pyo";
|
||||
if (lower.endsWith(".whl")) return "whl";
|
||||
if (lower.endsWith(".pyz") || lower.endsWith(".zipapp")) return "zipapp";
|
||||
return null;
|
||||
}
|
||||
|
||||
/** Classify bytecode symbol provenance. */
|
||||
export function classifyProvenance(
|
||||
path: string,
|
||||
symbolName: string,
|
||||
): BytecodeProvenance {
|
||||
const lower = path.toLowerCase();
|
||||
// Standard library paths
|
||||
if (
|
||||
lower.includes("/stdlib/") ||
|
||||
lower.includes("/site-packages/") ||
|
||||
lower.includes("java/") ||
|
||||
lower.includes("javax/") ||
|
||||
lower.includes("sun/") ||
|
||||
symbolName.startsWith("java.") ||
|
||||
symbolName.startsWith("javax.") ||
|
||||
symbolName.startsWith("sun.") ||
|
||||
symbolName.startsWith("__")
|
||||
) {
|
||||
return "standard_library";
|
||||
}
|
||||
// Generated code
|
||||
if (
|
||||
lower.includes("/generated/") ||
|
||||
lower.includes("_generated") ||
|
||||
lower.includes("/build/") ||
|
||||
lower.includes("/target/") ||
|
||||
lower.includes("/dist-packages/") ||
|
||||
lower.includes("/__pycache__/") ||
|
||||
symbolName.includes("Generated") ||
|
||||
symbolName.includes("_generated")
|
||||
) {
|
||||
return "generated";
|
||||
}
|
||||
// Vendored code
|
||||
if (
|
||||
lower.includes("/vendor/") ||
|
||||
lower.includes("/vendored/") ||
|
||||
lower.includes("/third_party/") ||
|
||||
lower.includes("/3rdparty/") ||
|
||||
lower.includes("/node_modules/") ||
|
||||
lower.includes("/vendor/")
|
||||
) {
|
||||
return "vendored";
|
||||
}
|
||||
// Bundled code
|
||||
if (
|
||||
lower.includes("/bundle/") ||
|
||||
lower.includes("/bundled/") ||
|
||||
lower.includes(".jar!") ||
|
||||
lower.includes(".war!")
|
||||
) {
|
||||
return "bundled";
|
||||
}
|
||||
return "application";
|
||||
}
|
||||
|
||||
/** Analyze a set of bytecode artifacts and produce a summary. */
|
||||
export function analyzeBytecodeArtifacts(
|
||||
artifacts: readonly BytecodeArtifact[],
|
||||
family: BytecodeFamily,
|
||||
): BytecodeAnalysis {
|
||||
const applicationSymbols = artifacts
|
||||
.flatMap((a) => a.symbols)
|
||||
.filter((s) => s.provenance === "application").length;
|
||||
const generatedSymbols = artifacts
|
||||
.flatMap((a) => a.symbols)
|
||||
.filter((s) => s.provenance === "generated").length;
|
||||
const vendoredSymbols = artifacts
|
||||
.flatMap((a) => a.symbols)
|
||||
.filter((s) => s.provenance === "vendored").length;
|
||||
const standardLibrarySymbols = artifacts
|
||||
.flatMap((a) => a.symbols)
|
||||
.filter((s) => s.provenance === "standard_library").length;
|
||||
|
||||
return {
|
||||
family,
|
||||
artifacts: artifacts.slice(0, 10_000),
|
||||
total_symbols: artifacts.reduce((sum, a) => sum + a.symbols.length, 0),
|
||||
application_symbols: applicationSymbols,
|
||||
generated_symbols: generatedSymbols,
|
||||
vendored_symbols: vendoredSymbols,
|
||||
standard_library_symbols: standardLibrarySymbols,
|
||||
};
|
||||
}
|
||||
@@ -0,0 +1,218 @@
|
||||
import { createHash } from "node:crypto";
|
||||
|
||||
import canonicalize from "canonicalize";
|
||||
import { z } from "zod";
|
||||
|
||||
import { evidenceEnvelopeSchema } from "./evidence.js";
|
||||
import { evidenceBundleSchema } from "./evidenceBundle.js";
|
||||
|
||||
/** Schema version for the conformance package format. */
|
||||
export const CONFORMANCE_PACKAGE_VERSION = 1;
|
||||
|
||||
/** A stable, path-independent identifier for a conformance package. */
|
||||
export const conformancePackageIdSchema = z
|
||||
.string()
|
||||
.regex(/^cp_[a-f0-9]{64}$/u);
|
||||
|
||||
/** Identifier for a single scenario within a package. */
|
||||
export const scenarioIdSchema = z
|
||||
.string()
|
||||
.regex(/^[A-Za-z][A-Za-z0-9._-]{0,99}$/u);
|
||||
|
||||
/** Deterministic manifest for a scenario fixture. */
|
||||
export const scenarioManifestSchema = z.strictObject({
|
||||
scenario_id: scenarioIdSchema,
|
||||
name: z.string().min(1),
|
||||
description: z.string().min(1),
|
||||
/** Source-owned fixture path relative to the repository root. */
|
||||
fixture_path: z.string().min(1),
|
||||
/** Expected exit code or null if unspecified. */
|
||||
expected_exit_code: z.number().int().nullable(),
|
||||
/** Expected output patterns that must appear in the capture. */
|
||||
expected_patterns: z.array(z.string()).default([]),
|
||||
});
|
||||
|
||||
/** Replay plan describing how a scenario is replayed deterministically. */
|
||||
export const replayPlanSchema = z.strictObject({
|
||||
scenario_id: scenarioIdSchema,
|
||||
/** Ordered steps to execute during replay. */
|
||||
steps: z
|
||||
.array(
|
||||
z.strictObject({
|
||||
step_id: z.string().min(1),
|
||||
action: z.string().min(1),
|
||||
arguments: z.array(z.string()).default([]),
|
||||
timeout_ms: z.number().int().positive(),
|
||||
}),
|
||||
)
|
||||
.min(1)
|
||||
.max(100),
|
||||
/** Environment variables to set (never inherit host paths). */
|
||||
environment: z.record(z.string(), z.string()).default({}),
|
||||
});
|
||||
|
||||
/** Shim plan for intercepting observable effects. */
|
||||
export const shimPlanSchema = z.strictObject({
|
||||
scenario_id: scenarioIdSchema,
|
||||
/** Shims to install, each intercepting a named effect. */
|
||||
shims: z
|
||||
.array(
|
||||
z.strictObject({
|
||||
shim_id: z.string().min(1),
|
||||
kind: z.enum(["filesystem", "network", "process", "signal"]),
|
||||
target: z.string().min(1),
|
||||
policy: z.enum(["observe", "allow", "block", "emulate"]),
|
||||
}),
|
||||
)
|
||||
.min(0)
|
||||
.max(50),
|
||||
});
|
||||
|
||||
/** Expected evidence for a scenario, checked against the captured run. */
|
||||
export const expectedEvidenceSchema = z.strictObject({
|
||||
scenario_id: scenarioIdSchema,
|
||||
/** Expected evidence envelopes. */
|
||||
envelopes: z.array(evidenceEnvelopeSchema).min(0).max(100),
|
||||
/** Expected evidence bundle. */
|
||||
bundle: evidenceBundleSchema.nullable(),
|
||||
/** Required dimensions that must be present in the evidence. */
|
||||
required_dimensions: z.array(z.string().min(1)).default([]),
|
||||
});
|
||||
|
||||
/** Verifier contract describing how to validate conformance. */
|
||||
export const verifierContractSchema = z.strictObject({
|
||||
scenario_id: scenarioIdSchema,
|
||||
/** Dimensions to verify. */
|
||||
dimensions: z
|
||||
.array(
|
||||
z.strictObject({
|
||||
name: z.string().min(1),
|
||||
required: z.boolean().default(true),
|
||||
comparison: z.enum(["exact", "semantic", "fuzzy"]),
|
||||
}),
|
||||
)
|
||||
.min(1)
|
||||
.max(50),
|
||||
/** Tolerance for timing differences in milliseconds. */
|
||||
timing_tolerance_ms: z.number().int().nonnegative().default(0),
|
||||
});
|
||||
|
||||
/** Top-level conformance package manifest. */
|
||||
export const conformancePackageSchema = z.strictObject({
|
||||
schema_version: z.literal(CONFORMANCE_PACKAGE_VERSION),
|
||||
package_id: conformancePackageIdSchema,
|
||||
name: z.string().min(1),
|
||||
description: z.string().min(1),
|
||||
created_at: z.string().datetime(),
|
||||
/** Scenario manifests. */
|
||||
scenarios: z.array(scenarioManifestSchema).min(1).max(100),
|
||||
/** Replay plans keyed by scenario_id. */
|
||||
replay_plans: z.array(replayPlanSchema).min(1).max(100),
|
||||
/** Shim plans keyed by scenario_id. */
|
||||
shim_plans: z.array(shimPlanSchema).default([]),
|
||||
/** Expected evidence for each scenario. */
|
||||
expected_evidence: z.array(expectedEvidenceSchema).min(1).max(100),
|
||||
/** Verifier contracts for each scenario. */
|
||||
verifier_contracts: z.array(verifierContractSchema).min(1).max(100),
|
||||
});
|
||||
|
||||
export type ConformancePackage = z.infer<typeof conformancePackageSchema>;
|
||||
export type ScenarioManifest = z.infer<typeof scenarioManifestSchema>;
|
||||
export type ReplayPlan = z.infer<typeof replayPlanSchema>;
|
||||
export type ShimPlan = z.infer<typeof shimPlanSchema>;
|
||||
export type ExpectedEvidence = z.infer<typeof expectedEvidenceSchema>;
|
||||
export type VerifierContract = z.infer<typeof verifierContractSchema>;
|
||||
|
||||
/** Error from validation or package operations. */
|
||||
export type ConformancePackageError =
|
||||
| { kind: "invalid_package"; message: string }
|
||||
| { kind: "scenario_not_found"; scenario_id: string }
|
||||
| { kind: "duplicate_scenario"; scenario_id: string };
|
||||
|
||||
/** Result type for package operations. */
|
||||
export type ConformancePackageResult<T> =
|
||||
| { ok: true; value: T }
|
||||
| { ok: false; error: ConformancePackageError };
|
||||
|
||||
/** Validate a conformance package and cross-check internal references. */
|
||||
export function validateConformancePackage(
|
||||
input: unknown,
|
||||
): ConformancePackageResult<ConformancePackage> {
|
||||
const parsed = conformancePackageSchema.safeParse(input);
|
||||
if (!parsed.success)
|
||||
return {
|
||||
ok: false,
|
||||
error: {
|
||||
kind: "invalid_package",
|
||||
message: parsed.error.issues[0]?.message ?? "invalid package",
|
||||
},
|
||||
};
|
||||
|
||||
const pkg = parsed.data;
|
||||
|
||||
// Check for duplicate scenario IDs
|
||||
const seen = new Set<string>();
|
||||
for (const s of pkg.scenarios) {
|
||||
if (seen.has(s.scenario_id))
|
||||
return {
|
||||
ok: false,
|
||||
error: { kind: "duplicate_scenario", scenario_id: s.scenario_id },
|
||||
};
|
||||
seen.add(s.scenario_id);
|
||||
}
|
||||
|
||||
// Check that replay plans reference existing scenarios
|
||||
for (const rp of pkg.replay_plans) {
|
||||
if (!seen.has(rp.scenario_id))
|
||||
return {
|
||||
ok: false,
|
||||
error: {
|
||||
kind: "scenario_not_found",
|
||||
scenario_id: rp.scenario_id,
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
// Check that expected evidence references existing scenarios
|
||||
for (const ee of pkg.expected_evidence) {
|
||||
if (!seen.has(ee.scenario_id))
|
||||
return {
|
||||
ok: false,
|
||||
error: {
|
||||
kind: "scenario_not_found",
|
||||
scenario_id: ee.scenario_id,
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
// Check that verifier contracts reference existing scenarios
|
||||
for (const vc of pkg.verifier_contracts) {
|
||||
if (!seen.has(vc.scenario_id))
|
||||
return {
|
||||
ok: false,
|
||||
error: {
|
||||
kind: "scenario_not_found",
|
||||
scenario_id: vc.scenario_id,
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
return { ok: true, value: pkg };
|
||||
}
|
||||
|
||||
/** Compute a deterministic package ID from the canonical JSON. */
|
||||
export function computePackageId(
|
||||
pkg: Omit<ConformancePackage, "package_id">,
|
||||
): string {
|
||||
const json = canonicalize(pkg);
|
||||
if (!json) throw new Error("failed to canonicalize package");
|
||||
return `cp_${createHash("sha256").update(json).digest("hex")}`;
|
||||
}
|
||||
|
||||
/** Create a conformance package with an auto-computed package_id. */
|
||||
export function createConformancePackage(
|
||||
pkg: Omit<ConformancePackage, "package_id">,
|
||||
): ConformancePackage {
|
||||
const package_id = computePackageId(pkg);
|
||||
return { package_id, ...pkg };
|
||||
}
|
||||
@@ -0,0 +1,138 @@
|
||||
import { z } from "zod";
|
||||
|
||||
import {
|
||||
conformancePackageSchema,
|
||||
type ConformancePackage,
|
||||
} from "./conformancePackage.js";
|
||||
import { trustGateResultSchema } from "./conformanceTrustGate.js";
|
||||
|
||||
/** Result of a single scenario replay. */
|
||||
export const scenarioReplayResultSchema = z.strictObject({
|
||||
scenario_id: z.string().min(1),
|
||||
status: z.enum(["pass", "fail", "error", "skipped"]),
|
||||
exit_code: z.number().int().nullable(),
|
||||
duration_ms: z.number().int().nonnegative(),
|
||||
output: z.string().default(""),
|
||||
error: z.string().nullable(),
|
||||
});
|
||||
|
||||
/** Result of replaying an entire conformance package. */
|
||||
export const packageReplayResultSchema = z.strictObject({
|
||||
package_id: z.string().min(1),
|
||||
total_scenarios: z.number().int().positive(),
|
||||
passed: z.number().int().nonnegative(),
|
||||
failed: z.number().int().nonnegative(),
|
||||
errored: z.number().int().nonnegative(),
|
||||
skipped: z.number().int().nonnegative(),
|
||||
scenario_results: z.array(scenarioReplayResultSchema),
|
||||
trust_gate_results: z.array(trustGateResultSchema),
|
||||
drift_detected: z.boolean(),
|
||||
first_drift: z
|
||||
.strictObject({
|
||||
scenario_id: z.string().min(1),
|
||||
dimension: z.string().min(1),
|
||||
message: z.string(),
|
||||
})
|
||||
.nullable(),
|
||||
});
|
||||
|
||||
export type ScenarioReplayResult = z.infer<typeof scenarioReplayResultSchema>;
|
||||
export type PackageReplayResult = z.infer<typeof packageReplayResultSchema>;
|
||||
|
||||
/** Callback interface for replaying a scenario. */
|
||||
export interface ScenarioRunner {
|
||||
(scenarioId: string, fixturePath: string): Promise<ScenarioReplayResult>;
|
||||
}
|
||||
|
||||
/**
|
||||
* Default no-op scenario runner that skips all scenarios.
|
||||
* Real CI replays inject an actual runner.
|
||||
*/
|
||||
async function defaultRunner(): Promise<ScenarioReplayResult> {
|
||||
return {
|
||||
scenario_id: "unknown",
|
||||
status: "skipped",
|
||||
exit_code: null,
|
||||
duration_ms: 0,
|
||||
output: "",
|
||||
error: "no runner provided",
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Replay a conformance package from a clean checkout.
|
||||
* Runs each scenario, evaluates trust gates, and detects drift
|
||||
* between the captured run and the committed package.
|
||||
*/
|
||||
export async function replayConformancePackage(
|
||||
packageInput: unknown,
|
||||
actualEvidence: Record<string, Record<string, unknown>>,
|
||||
runner: ScenarioRunner = defaultRunner,
|
||||
options: { truncated?: boolean } = {},
|
||||
): Promise<PackageReplayResult> {
|
||||
const parsed = conformancePackageSchema.safeParse(packageInput);
|
||||
if (!parsed.success)
|
||||
throw new TypeError(
|
||||
`invalid conformance package: ${parsed.error.issues[0]?.message ?? "unknown"}`,
|
||||
);
|
||||
const pkg: ConformancePackage = parsed.data;
|
||||
|
||||
const scenarioResults: ScenarioReplayResult[] = [];
|
||||
let passed = 0;
|
||||
let failed = 0;
|
||||
let errored = 0;
|
||||
let skipped = 0;
|
||||
|
||||
for (const scenario of pkg.scenarios) {
|
||||
const result = await runner(scenario.scenario_id, scenario.fixture_path);
|
||||
scenarioResults.push(result);
|
||||
|
||||
switch (result.status) {
|
||||
case "pass":
|
||||
passed++;
|
||||
break;
|
||||
case "fail":
|
||||
failed++;
|
||||
break;
|
||||
case "error":
|
||||
errored++;
|
||||
break;
|
||||
case "skipped":
|
||||
skipped++;
|
||||
break;
|
||||
}
|
||||
}
|
||||
|
||||
const trustGateResults = evaluatePackageTrustGates(
|
||||
pkg,
|
||||
actualEvidence,
|
||||
options,
|
||||
);
|
||||
|
||||
const driftGates = trustGateResults.filter((r) => r.verdict === "fail");
|
||||
const drift_detected = driftGates.length > 0;
|
||||
const first_drift_gate = driftGates[0];
|
||||
const first_drift = first_drift_gate?.first_divergence
|
||||
? {
|
||||
scenario_id: first_drift_gate.scenario_id,
|
||||
dimension: first_drift_gate.first_divergence.dimension,
|
||||
message: first_drift_gate.first_divergence.message,
|
||||
}
|
||||
: null;
|
||||
|
||||
return {
|
||||
package_id: pkg.package_id,
|
||||
total_scenarios: pkg.scenarios.length,
|
||||
passed,
|
||||
failed,
|
||||
errored,
|
||||
skipped,
|
||||
scenario_results: scenarioResults,
|
||||
trust_gate_results: trustGateResults,
|
||||
drift_detected,
|
||||
first_drift,
|
||||
};
|
||||
}
|
||||
|
||||
/** Import trust gate evaluator for replay. */
|
||||
import { evaluatePackageTrustGates } from "./conformanceTrustGate.js";
|
||||
@@ -0,0 +1,246 @@
|
||||
import { z } from "zod";
|
||||
|
||||
import type {
|
||||
ConformancePackage,
|
||||
VerifierContract,
|
||||
} from "./conformancePackage.js";
|
||||
|
||||
/** Result of comparing a single dimension. */
|
||||
export const dimensionResultSchema = z.strictObject({
|
||||
name: z.string().min(1),
|
||||
status: z.enum(["match", "mismatch", "unknown", "truncated"]),
|
||||
message: z.string().default(""),
|
||||
evidence_ids: z.array(z.string()).default([]),
|
||||
});
|
||||
|
||||
/** Result of evaluating a trust gate for one scenario. */
|
||||
export const trustGateResultSchema = z.strictObject({
|
||||
scenario_id: z.string().min(1),
|
||||
verdict: z.enum(["pass", "fail", "unknown"]),
|
||||
dimension_results: z.array(dimensionResultSchema),
|
||||
first_divergence: z
|
||||
.strictObject({
|
||||
dimension: z.string().min(1),
|
||||
evidence_id: z.string().min(1),
|
||||
message: z.string(),
|
||||
})
|
||||
.nullable(),
|
||||
});
|
||||
|
||||
export type DimensionResult = z.infer<typeof dimensionResultSchema>;
|
||||
export type TrustGateResult = z.infer<typeof trustGateResultSchema>;
|
||||
|
||||
/** Dimension that is volatile due to timing or normalization. */
|
||||
const VOLATILE_DIMENSIONS = new Set([
|
||||
"timing",
|
||||
"timestamp",
|
||||
"pid",
|
||||
"ppid",
|
||||
"duration_ms",
|
||||
"created_at",
|
||||
"updated_at",
|
||||
]);
|
||||
|
||||
/** Dimension that carries semantic content. */
|
||||
const SEMANTIC_DIMENSIONS = new Set([
|
||||
"exit_code",
|
||||
"stdout",
|
||||
"stderr",
|
||||
"filesystem",
|
||||
"process_tree",
|
||||
"shim_events",
|
||||
"protocol_events",
|
||||
"event_journal",
|
||||
]);
|
||||
|
||||
/** Check if a dimension name is volatile (timing/normalization noise). */
|
||||
export function isVolatileDimension(name: string): boolean {
|
||||
return VOLATILE_DIMENSIONS.has(name);
|
||||
}
|
||||
|
||||
/** Check if a dimension name carries semantic content. */
|
||||
export function isSemanticDimension(name: string): boolean {
|
||||
return SEMANTIC_DIMENSIONS.has(name);
|
||||
}
|
||||
|
||||
/**
|
||||
* Compare two values for a dimension, classifying semantic diffs
|
||||
* from timing/normalization noise.
|
||||
*
|
||||
* Volatile dimensions (timing, timestamps, PIDs) are always treated
|
||||
* as matches because their values are expected to differ across
|
||||
* runs and do not carry semantic meaning.
|
||||
*/
|
||||
export function compareDimension(
|
||||
dimensionName: string,
|
||||
expected: unknown,
|
||||
actual: unknown,
|
||||
options: { truncated?: boolean } = {},
|
||||
): DimensionResult {
|
||||
// Volatile dimensions: always match regardless of values
|
||||
if (isVolatileDimension(dimensionName)) {
|
||||
return {
|
||||
name: dimensionName,
|
||||
status: "match",
|
||||
message: "volatile dimension ignored",
|
||||
evidence_ids: [],
|
||||
};
|
||||
}
|
||||
|
||||
if (options.truncated) {
|
||||
return {
|
||||
name: dimensionName,
|
||||
status: "truncated",
|
||||
message: "evidence was truncated",
|
||||
evidence_ids: [],
|
||||
};
|
||||
}
|
||||
|
||||
if (expected === undefined && actual === undefined) {
|
||||
return {
|
||||
name: dimensionName,
|
||||
status: "unknown",
|
||||
message: "both expected and actual are undefined",
|
||||
evidence_ids: [],
|
||||
};
|
||||
}
|
||||
|
||||
if (expected === undefined || actual === undefined) {
|
||||
return {
|
||||
name: dimensionName,
|
||||
status: "mismatch",
|
||||
message: `expected ${expected === undefined ? "present" : "absent"}, actual ${actual === undefined ? "absent" : "present"}`,
|
||||
evidence_ids: [],
|
||||
};
|
||||
}
|
||||
|
||||
// Semantic comparison for structured objects
|
||||
if (typeof expected === "object" && typeof actual === "object") {
|
||||
const expectedJson = JSON.stringify(sortKeys(expected));
|
||||
const actualJson = JSON.stringify(sortKeys(actual));
|
||||
if (expectedJson === actualJson) {
|
||||
return {
|
||||
name: dimensionName,
|
||||
status: "match",
|
||||
message: "",
|
||||
evidence_ids: [],
|
||||
};
|
||||
}
|
||||
return {
|
||||
name: dimensionName,
|
||||
status: "mismatch",
|
||||
message: "semantic content differs",
|
||||
evidence_ids: [],
|
||||
};
|
||||
}
|
||||
|
||||
// Primitive comparison
|
||||
if (expected === actual) {
|
||||
return {
|
||||
name: dimensionName,
|
||||
status: "match",
|
||||
message: "",
|
||||
evidence_ids: [],
|
||||
};
|
||||
}
|
||||
|
||||
return {
|
||||
name: dimensionName,
|
||||
status: "mismatch",
|
||||
message: `expected ${JSON.stringify(expected)}, got ${JSON.stringify(actual)}`,
|
||||
evidence_ids: [],
|
||||
};
|
||||
}
|
||||
|
||||
/** Recursively sort object keys for deterministic comparison. */
|
||||
function sortKeys(value: unknown): unknown {
|
||||
if (value === null || typeof value !== "object") return value;
|
||||
if (Array.isArray(value)) return value.map(sortKeys);
|
||||
const sorted: Record<string, unknown> = {};
|
||||
for (const key of Object.keys(value as Record<string, unknown>).sort()) {
|
||||
sorted[key] = sortKeys((value as Record<string, unknown>)[key]);
|
||||
}
|
||||
return sorted;
|
||||
}
|
||||
|
||||
/**
|
||||
* Evaluate a trust gate for one scenario by comparing expected
|
||||
* evidence against the actual captured run.
|
||||
*/
|
||||
export function evaluateTrustGate(
|
||||
contract: VerifierContract,
|
||||
expectedEvidence: Record<string, unknown>,
|
||||
actualEvidence: Record<string, unknown>,
|
||||
options: { truncated?: boolean } = {},
|
||||
): TrustGateResult {
|
||||
const dimensionResults: DimensionResult[] = [];
|
||||
let firstDivergence: TrustGateResult["first_divergence"] = null;
|
||||
|
||||
for (const dim of contract.dimensions) {
|
||||
if (!dim.required) continue;
|
||||
const expectedValue = expectedEvidence[dim.name];
|
||||
const actualValue = actualEvidence[dim.name];
|
||||
const result = compareDimension(
|
||||
dim.name,
|
||||
expectedValue,
|
||||
actualValue,
|
||||
options,
|
||||
);
|
||||
dimensionResults.push(result);
|
||||
|
||||
if (result.status === "mismatch" && firstDivergence === null) {
|
||||
firstDivergence = {
|
||||
dimension: dim.name,
|
||||
evidence_id: result.evidence_ids[0] ?? "unknown",
|
||||
message: result.message,
|
||||
};
|
||||
}
|
||||
}
|
||||
|
||||
const hasFail = dimensionResults.some(
|
||||
(r) => r.status === "mismatch" || r.status === "truncated",
|
||||
);
|
||||
const hasUnknown = dimensionResults.some((r) => r.status === "unknown");
|
||||
|
||||
const verdict: TrustGateResult["verdict"] = hasFail
|
||||
? "fail"
|
||||
: hasUnknown
|
||||
? "unknown"
|
||||
: "pass";
|
||||
|
||||
return {
|
||||
scenario_id: contract.scenario_id,
|
||||
verdict,
|
||||
dimension_results: dimensionResults,
|
||||
first_divergence: firstDivergence,
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Evaluate trust gates for all scenarios in a conformance package.
|
||||
* Rejects runs that differ in required dimensions. Unknown/truncated
|
||||
* evidence is never treated as equivalence.
|
||||
*/
|
||||
export function evaluatePackageTrustGates(
|
||||
pkg: ConformancePackage,
|
||||
actualEvidence: Record<string, Record<string, unknown>>,
|
||||
options: { truncated?: boolean } = {},
|
||||
): TrustGateResult[] {
|
||||
const results: TrustGateResult[] = [];
|
||||
for (const contract of pkg.verifier_contracts) {
|
||||
const expected = pkg.expected_evidence.find(
|
||||
(e) => e.scenario_id === contract.scenario_id,
|
||||
);
|
||||
if (!expected) continue;
|
||||
const expectedEvidence = expected.envelopes[0] ?? {};
|
||||
const actual = actualEvidence[contract.scenario_id] ?? {};
|
||||
const result = evaluateTrustGate(
|
||||
contract,
|
||||
expectedEvidence as Record<string, unknown>,
|
||||
actual,
|
||||
options,
|
||||
);
|
||||
results.push(result);
|
||||
}
|
||||
return results;
|
||||
}
|
||||
@@ -0,0 +1,173 @@
|
||||
import { z } from "zod";
|
||||
|
||||
import { jsonValueSchema } from "./jsonValue.js";
|
||||
|
||||
/** Supported transport types for custom protocol capture. */
|
||||
export const transportTypeSchema = z.enum([
|
||||
"tcp",
|
||||
"udp",
|
||||
"ipc",
|
||||
"unix-socket",
|
||||
"named-pipe",
|
||||
"xpc",
|
||||
]);
|
||||
export type TransportType = z.infer<typeof transportTypeSchema>;
|
||||
|
||||
/** Direction of a protocol frame. */
|
||||
export const frameDirectionSchema = z.enum(["sent", "received", "intercepted"]);
|
||||
export type FrameDirection = z.infer<typeof frameDirectionSchema>;
|
||||
|
||||
/** A captured protocol frame. */
|
||||
export const protocolFrameSchema = z.strictObject({
|
||||
/** Monotonic sequence number. */
|
||||
sequence: z.number().int().nonnegative(),
|
||||
/** Timestamp in milliseconds. */
|
||||
at_ms: z.number().int().nonnegative(),
|
||||
/** Transport type. */
|
||||
transport: transportTypeSchema,
|
||||
/** Direction of the frame. */
|
||||
direction: frameDirectionSchema,
|
||||
/** Source process identity. */
|
||||
source_pid: z.number().int().nullable(),
|
||||
/** Destination process identity. */
|
||||
dest_pid: z.number().int().nullable(),
|
||||
/** Endpoint address (IP:port, socket path, pipe name). */
|
||||
source_endpoint: z.string().nullable(),
|
||||
/** Destination endpoint. */
|
||||
dest_endpoint: z.string().nullable(),
|
||||
/** Raw frame data as base64. */
|
||||
raw_data: z.string().nullable(),
|
||||
/** Decoded/parsed frame content if known. */
|
||||
decoded_content: jsonValueSchema.nullable(),
|
||||
/** Frame size in bytes. */
|
||||
size: z.number().int().nonnegative(),
|
||||
/** Whether the frame was truncated. */
|
||||
truncated: z.boolean().default(false),
|
||||
});
|
||||
export type ProtocolFrame = z.infer<typeof protocolFrameSchema>;
|
||||
|
||||
/** Authentication flow stage. */
|
||||
export const authStageSchema = z.enum([
|
||||
"init",
|
||||
"challenge",
|
||||
"response",
|
||||
"token_exchange",
|
||||
"renewal",
|
||||
"revocation",
|
||||
"failure",
|
||||
"success",
|
||||
]);
|
||||
export type AuthStage = z.infer<typeof authStageSchema>;
|
||||
|
||||
/** Token lifecycle event. */
|
||||
export const tokenLifecycleEventSchema = z.enum([
|
||||
"issued",
|
||||
"refreshed",
|
||||
"expired",
|
||||
"revoked",
|
||||
"renewed",
|
||||
]);
|
||||
export type TokenLifecycleEvent = z.infer<typeof tokenLifecycleEventSchema>;
|
||||
|
||||
/** A captured authentication flow event. */
|
||||
export const authFlowEventSchema = z.strictObject({
|
||||
/** Monotonic sequence number. */
|
||||
sequence: z.number().int().nonnegative(),
|
||||
/** Timestamp in milliseconds. */
|
||||
at_ms: z.number().int().nonnegative(),
|
||||
/** Authentication stage. */
|
||||
stage: authStageSchema,
|
||||
/** Protocol used. */
|
||||
protocol: z.string().min(1),
|
||||
/** Token type if applicable. */
|
||||
token_type: z.string().nullable(),
|
||||
/** Token lifecycle event. */
|
||||
token_lifecycle: tokenLifecycleEventSchema.nullable(),
|
||||
/** Correlation ID linking challenge-response pairs. */
|
||||
correlation_id: z.string().nullable(),
|
||||
/** Whether credentials were detected and redacted. */
|
||||
credentials_redacted: z.boolean().default(false),
|
||||
/** Whether the authentication succeeded. */
|
||||
succeeded: z.boolean().default(false),
|
||||
/** Error message if authentication failed. */
|
||||
error: z.string().nullable(),
|
||||
});
|
||||
export type AuthFlowEvent = z.infer<typeof authFlowEventSchema>;
|
||||
|
||||
/** A captured protocol session. */
|
||||
export const customProtocolCaptureSchema = z.strictObject({
|
||||
/** Transport type for this session. */
|
||||
transport: transportTypeSchema,
|
||||
/** Captured frames in order. */
|
||||
frames: z.array(protocolFrameSchema).min(0).max(100_000),
|
||||
/** Authentication flow events. */
|
||||
auth_events: z.array(authFlowEventSchema).default([]),
|
||||
/** Whether any frame was truncated. */
|
||||
has_truncated: z.boolean().default(false),
|
||||
/** Whether credentials were detected. */
|
||||
credentials_detected: z.boolean().default(false),
|
||||
});
|
||||
export type CustomProtocolCapture = z.infer<typeof customProtocolCaptureSchema>;
|
||||
|
||||
/** Correlate a frame with process identity. */
|
||||
export function correlateProcessIdentity(
|
||||
frame: ProtocolFrame,
|
||||
pid: number,
|
||||
): boolean {
|
||||
return frame.source_pid === pid || frame.dest_pid === pid;
|
||||
}
|
||||
|
||||
/** Check if a frame contains credential-like content. */
|
||||
export function looksLikeCredentialFrame(frame: ProtocolFrame): boolean {
|
||||
const patterns = [
|
||||
"password",
|
||||
"token",
|
||||
"secret",
|
||||
"api_key",
|
||||
"apikey",
|
||||
"authorization",
|
||||
"credential",
|
||||
];
|
||||
const content = JSON.stringify(frame.decoded_content ?? "").toLowerCase();
|
||||
return patterns.some((p) => content.includes(p));
|
||||
}
|
||||
|
||||
/** Filter frames by transport type. */
|
||||
export function framesByTransport(
|
||||
frames: readonly ProtocolFrame[],
|
||||
transport: TransportType,
|
||||
): ProtocolFrame[] {
|
||||
return frames.filter((f) => f.transport === transport);
|
||||
}
|
||||
|
||||
/** Get all authentication flow events for a specific protocol. */
|
||||
export function authEventsByProtocol(
|
||||
events: readonly AuthFlowEvent[],
|
||||
protocol: string,
|
||||
): AuthFlowEvent[] {
|
||||
return events.filter((e) => e.protocol === protocol);
|
||||
}
|
||||
|
||||
/** Get successful authentication events. */
|
||||
export function successfulAuthEvents(
|
||||
events: readonly AuthFlowEvent[],
|
||||
): AuthFlowEvent[] {
|
||||
return events.filter((e) => e.succeeded);
|
||||
}
|
||||
|
||||
/** Get failed authentication events. */
|
||||
export function failedAuthEvents(
|
||||
events: readonly AuthFlowEvent[],
|
||||
): AuthFlowEvent[] {
|
||||
return events.filter((e) => !e.succeeded);
|
||||
}
|
||||
|
||||
/** Compute the duration of an authentication flow in milliseconds. */
|
||||
export function authFlowDuration(
|
||||
events: readonly AuthFlowEvent[],
|
||||
): number | null {
|
||||
if (events.length === 0) return null;
|
||||
const first = events[0]!;
|
||||
const last = events[events.length - 1]!;
|
||||
return last.at_ms - first.at_ms;
|
||||
}
|
||||
@@ -97,6 +97,8 @@ export interface AnalysisInputIssue {
|
||||
| "out_of_range"
|
||||
| "invalid_value"
|
||||
| "invalid_format";
|
||||
/** Schema-authored correction guidance for cross-field or custom checks. */
|
||||
readonly message?: string;
|
||||
readonly expected?: JsonValue;
|
||||
readonly minimum?: number;
|
||||
readonly maximum?: number;
|
||||
@@ -293,6 +295,7 @@ export class ArtifactOperationError extends AnalysisError {
|
||||
| "integrity"
|
||||
| "limit"
|
||||
| "path"
|
||||
| "policy"
|
||||
| "unavailable"
|
||||
| "io",
|
||||
readonly artifactDetails?: Readonly<{
|
||||
|
||||
@@ -0,0 +1,240 @@
|
||||
import { z } from "zod";
|
||||
|
||||
/** Event types for event-backed process-tree capture. */
|
||||
export const processEventTypeSchema = z.enum([
|
||||
"spawn",
|
||||
"exit",
|
||||
"re_exec",
|
||||
"reparent",
|
||||
"signal",
|
||||
"name_change",
|
||||
"thread_create",
|
||||
"thread_exit",
|
||||
]);
|
||||
export type ProcessEventType = z.infer<typeof processEventTypeSchema>;
|
||||
|
||||
/** A single event-backed process-tree event. */
|
||||
export const processTreeEventSchema = z.strictObject({
|
||||
/** Monotonic event sequence number. */
|
||||
sequence: z.number().int().nonnegative(),
|
||||
/** Event timestamp in milliseconds. */
|
||||
at_ms: z.number().int().nonnegative(),
|
||||
/** Event type. */
|
||||
type: processEventTypeSchema,
|
||||
/** Process ID. */
|
||||
pid: z.number().int().positive(),
|
||||
/** Parent process ID. */
|
||||
ppid: z.number().int().nullable(),
|
||||
/** Process name if known. */
|
||||
process_name: z.string().nullable(),
|
||||
/** Executable path if known. */
|
||||
executable: z.string().nullable(),
|
||||
/** Command line arguments. */
|
||||
arguments: z.array(z.string()).default([]),
|
||||
/** Previous PID (for reparent events). */
|
||||
previous_pid: z.number().int().nullable(),
|
||||
/** Previous PPID (for reparent events). */
|
||||
previous_ppid: z.number().int().nullable(),
|
||||
/** Exit code (for exit events). */
|
||||
exit_code: z.number().int().nullable(),
|
||||
/** Signal number (for signal events). */
|
||||
signal: z.number().int().nullable(),
|
||||
/** Thread ID (for thread events). */
|
||||
tid: z.number().int().nullable(),
|
||||
});
|
||||
export type ProcessTreeEvent = z.infer<typeof processTreeEventSchema>;
|
||||
|
||||
/** Process node in a reconstructed tree. */
|
||||
export const processNodeSchema = z.strictObject({
|
||||
pid: z.number().int().positive(),
|
||||
ppid: z.number().int().nullable(),
|
||||
process_name: z.string().nullable(),
|
||||
executable: z.string().nullable(),
|
||||
arguments: z.array(z.string()).default([]),
|
||||
children: z.array(z.number().int()).default([]),
|
||||
spawn_time_ms: z.number().int().nullable(),
|
||||
exit_time_ms: z.number().int().nullable(),
|
||||
exit_code: z.number().int().nullable(),
|
||||
is_re_exec: z.boolean().default(false),
|
||||
is_reparented: z.boolean().default(false),
|
||||
previous_ppid: z.number().int().nullable(),
|
||||
});
|
||||
export type ProcessNode = z.infer<typeof processNodeSchema>;
|
||||
|
||||
/** Result of event-backed process-tree reconstruction. */
|
||||
export const processTreeReconstructionSchema = z.strictObject({
|
||||
/** Root PID of the process tree. */
|
||||
root_pid: z.number().int().positive(),
|
||||
/** All reconstructed process nodes. */
|
||||
processes: z.array(processNodeSchema).min(0).max(10_000),
|
||||
/** Events that were consumed. */
|
||||
events_consumed: z.number().int().nonnegative(),
|
||||
/** Events that could not be matched. */
|
||||
events_unmatched: z.number().int().nonnegative(),
|
||||
/** Short-lived descendants that were missed by sampling. */
|
||||
short_lived_descendants: z.number().int().nonnegative(),
|
||||
/** Whether any re-exec was detected. */
|
||||
has_re_exec: z.boolean().default(false),
|
||||
/** Whether any reparenting was detected. */
|
||||
has_reparenting: z.boolean().default(false),
|
||||
});
|
||||
export type ProcessTreeReconstruction = z.infer<
|
||||
typeof processTreeReconstructionSchema
|
||||
>;
|
||||
|
||||
/** Reconstruct a process tree from event-backed capture. */
|
||||
export function reconstructProcessTree(
|
||||
events: readonly ProcessTreeEvent[],
|
||||
rootPid: number,
|
||||
): ProcessTreeReconstruction {
|
||||
const nodes = new Map<number, ProcessNode>();
|
||||
const children = new Map<number, number[]>();
|
||||
let eventsConsumed = 0;
|
||||
let eventsUnmatched = 0;
|
||||
let hasReExec = false;
|
||||
let hasReparenting = false;
|
||||
let shortLivedDescendants = 0;
|
||||
|
||||
const sorted = [...events].sort((a, b) => a.at_ms - b.at_ms);
|
||||
|
||||
for (const event of sorted) {
|
||||
eventsConsumed++;
|
||||
let node = nodes.get(event.pid);
|
||||
|
||||
switch (event.type) {
|
||||
case "spawn": {
|
||||
if (!node) {
|
||||
node = {
|
||||
pid: event.pid,
|
||||
ppid: event.ppid,
|
||||
process_name: event.process_name,
|
||||
executable: event.executable,
|
||||
arguments: event.arguments,
|
||||
children: [],
|
||||
spawn_time_ms: event.at_ms,
|
||||
exit_time_ms: null,
|
||||
exit_code: null,
|
||||
is_re_exec: false,
|
||||
is_reparented: false,
|
||||
previous_ppid: null,
|
||||
};
|
||||
nodes.set(event.pid, node);
|
||||
}
|
||||
if (event.ppid !== null) {
|
||||
const parentChildren = children.get(event.ppid) ?? [];
|
||||
parentChildren.push(event.pid);
|
||||
children.set(event.ppid, parentChildren);
|
||||
}
|
||||
break;
|
||||
}
|
||||
case "exit": {
|
||||
if (node) {
|
||||
node.exit_time_ms = event.at_ms;
|
||||
node.exit_code = event.exit_code;
|
||||
if (
|
||||
node.spawn_time_ms !== null &&
|
||||
event.at_ms - node.spawn_time_ms < 100
|
||||
)
|
||||
shortLivedDescendants++;
|
||||
} else {
|
||||
eventsUnmatched++;
|
||||
}
|
||||
break;
|
||||
}
|
||||
case "re_exec": {
|
||||
if (node) {
|
||||
node.is_re_exec = true;
|
||||
node.executable = event.executable ?? node.executable;
|
||||
node.arguments = event.arguments;
|
||||
hasReExec = true;
|
||||
} else {
|
||||
eventsUnmatched++;
|
||||
}
|
||||
break;
|
||||
}
|
||||
case "reparent": {
|
||||
if (node) {
|
||||
node.previous_ppid = node.ppid;
|
||||
node.ppid = event.ppid;
|
||||
node.is_reparented = true;
|
||||
hasReparenting = true;
|
||||
} else {
|
||||
eventsUnmatched++;
|
||||
}
|
||||
break;
|
||||
}
|
||||
case "signal":
|
||||
case "name_change":
|
||||
case "thread_create":
|
||||
case "thread_exit":
|
||||
// These events are recorded but don't modify the tree structure
|
||||
break;
|
||||
}
|
||||
}
|
||||
|
||||
// Attach children to nodes
|
||||
for (const [pid, childPids] of children) {
|
||||
const node = nodes.get(pid);
|
||||
if (node) node.children = childPids;
|
||||
}
|
||||
|
||||
return {
|
||||
root_pid: rootPid,
|
||||
processes: [...nodes.values()],
|
||||
events_consumed: eventsConsumed,
|
||||
events_unmatched: eventsUnmatched,
|
||||
short_lived_descendants: shortLivedDescendants,
|
||||
has_re_exec: hasReExec,
|
||||
has_reparenting: hasReparenting,
|
||||
};
|
||||
}
|
||||
|
||||
/** Get all descendant PIDs of a given root PID. */
|
||||
export function getDescendants(
|
||||
processes: readonly ProcessNode[],
|
||||
rootPid: number,
|
||||
): number[] {
|
||||
const byPid = new Map(processes.map((p) => [p.pid, p]));
|
||||
const visited = new Set<number>();
|
||||
const result: number[] = [];
|
||||
const queue: number[] = [rootPid];
|
||||
while (queue.length > 0) {
|
||||
const pid = queue.shift()!;
|
||||
if (visited.has(pid)) continue;
|
||||
visited.add(pid);
|
||||
const node = byPid.get(pid);
|
||||
if (node) {
|
||||
for (const child of node.children) {
|
||||
if (!visited.has(child)) {
|
||||
result.push(child);
|
||||
queue.push(child);
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
return result;
|
||||
}
|
||||
|
||||
/** Check if a process tree contains a specific PID. */
|
||||
export function containsProcess(
|
||||
processes: readonly ProcessNode[],
|
||||
pid: number,
|
||||
): boolean {
|
||||
return processes.some((p) => p.pid === pid);
|
||||
}
|
||||
|
||||
/** Get the maximum tree depth from the root. */
|
||||
export function maxTreeDepth(
|
||||
processes: readonly ProcessNode[],
|
||||
rootPid: number,
|
||||
): number {
|
||||
const byPid = new Map(processes.map((p) => [p.pid, p]));
|
||||
function depth(pid: number, visited: Set<number>): number {
|
||||
if (visited.has(pid)) return 0;
|
||||
visited.add(pid);
|
||||
const node = byPid.get(pid);
|
||||
if (!node || node.children.length === 0) return 0;
|
||||
return 1 + Math.max(...node.children.map((c) => depth(c, visited)));
|
||||
}
|
||||
return depth(rootPid, new Set());
|
||||
}
|
||||
@@ -65,7 +65,7 @@ const failures = [
|
||||
[
|
||||
75,
|
||||
"hopper_exited_during_startup",
|
||||
"Hopper exited before the REA bridge was ready. Run rea doctor and retry the analysis.",
|
||||
"Hopper exited before the REA bridge was ready. In CI, run rea doctor --provider hopper --detail full --json; if Hopper showed a UI or license prompt, complete it in the runner user session, otherwise close stale Hopper sessions and retry.",
|
||||
],
|
||||
[
|
||||
76,
|
||||
|
||||
@@ -1,8 +1,9 @@
|
||||
import { z } from "zod";
|
||||
|
||||
import type { JsonValue } from "./jsonValue.js";
|
||||
import { jsonValueSchema, type JsonValue } from "./jsonValue.js";
|
||||
import { AnalysisOutputError, HopperProtocolError } from "./errors.js";
|
||||
import { err, ok, type Result } from "./result.js";
|
||||
import { nativeApiBoundarySchema } from "./nativeApiBoundary.js";
|
||||
|
||||
export interface AddressedName {
|
||||
readonly address: string;
|
||||
@@ -275,6 +276,7 @@ export const functionDossierSchema = z
|
||||
instruction_scan: z
|
||||
.object({ scanned: z.number().int().min(0), truncated: z.boolean() })
|
||||
.strict(),
|
||||
native_api: nativeApiBoundarySchema.optional(),
|
||||
limitations: z.array(z.string()).default([]),
|
||||
})
|
||||
.strict();
|
||||
@@ -288,7 +290,7 @@ export const parseFunctionDossier = (
|
||||
): Result<JsonValue, AnalysisOutputError> => {
|
||||
const parsed = functionDossierSchema.safeParse(value);
|
||||
return parsed.success
|
||||
? ok(parsed.data)
|
||||
? ok(jsonValueSchema.parse(parsed.data))
|
||||
: err(
|
||||
new AnalysisOutputError(
|
||||
"analyze_function",
|
||||
|
||||
@@ -46,7 +46,13 @@ const projectIssue = (
|
||||
expected: issue.values.filter(isSafeExpected),
|
||||
},
|
||||
];
|
||||
return [{ path, reason: "invalid_value" }];
|
||||
return [
|
||||
{
|
||||
path,
|
||||
reason: "invalid_value",
|
||||
...(issue.message.length > 0 ? { message: issue.message } : {}),
|
||||
},
|
||||
];
|
||||
};
|
||||
|
||||
const valueAtPath = (
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
import { describe, expect, it } from "vitest";
|
||||
|
||||
import { inferJsonShape } from "../src/domain/jsonShape.js";
|
||||
import { inferJsonShape } from "./jsonShape.js";
|
||||
|
||||
describe("inferJsonShape", () => {
|
||||
it("retains paths and types without retaining JSON values", () => {
|
||||
@@ -0,0 +1,178 @@
|
||||
import { z } from "zod";
|
||||
|
||||
/** Supported mobile artifact formats. */
|
||||
export const mobileArtifactFormatSchema = z.enum([
|
||||
"apk",
|
||||
"aab",
|
||||
"ipa",
|
||||
"dex",
|
||||
"native_lib",
|
||||
]);
|
||||
export type MobileArtifactFormat = z.infer<typeof mobileArtifactFormatSchema>;
|
||||
|
||||
/** Mobile platform. */
|
||||
export const mobilePlatformSchema = z.enum([
|
||||
"android",
|
||||
"ios",
|
||||
"cross_platform",
|
||||
]);
|
||||
export type MobilePlatform = z.infer<typeof mobilePlatformSchema>;
|
||||
|
||||
/** Android manifest entry. */
|
||||
export const androidManifestSchema = z.strictObject({
|
||||
package_name: z.string().min(1),
|
||||
version_name: z.string().nullable(),
|
||||
version_code: z.number().int().nullable(),
|
||||
min_sdk: z.number().int().nullable(),
|
||||
target_sdk: z.number().int().nullable(),
|
||||
permissions: z.array(z.string()).default([]),
|
||||
activities: z.array(z.string()).default([]),
|
||||
services: z.array(z.string()).default([]),
|
||||
receivers: z.array(z.string()).default([]),
|
||||
providers: z.array(z.string()).default([]),
|
||||
});
|
||||
export type AndroidManifest = z.infer<typeof androidManifestSchema>;
|
||||
|
||||
/** iOS app manifest (Info.plist). */
|
||||
export const iosManifestSchema = z.strictObject({
|
||||
bundle_identifier: z.string().min(1),
|
||||
bundle_version: z.string().nullable(),
|
||||
short_version: z.string().nullable(),
|
||||
minimum_os_version: z.string().nullable(),
|
||||
supported_platforms: z.array(z.string()).default([]),
|
||||
ui_required_device_capabilities: z.array(z.string()).default([]),
|
||||
app_permissions: z.array(z.string()).default([]),
|
||||
});
|
||||
export type IosManifest = z.infer<typeof iosManifestSchema>;
|
||||
/** Signing information. */
|
||||
export const signingInfoSchema = z.strictObject({
|
||||
is_signed: z.boolean().default(false),
|
||||
signer_identity: z.string().nullable(),
|
||||
certificate_fingerprint: z.string().nullable(),
|
||||
signature_scheme: z.string().nullable(),
|
||||
is_debuggable: z.boolean().default(false),
|
||||
});
|
||||
export type SigningInfo = z.infer<typeof signingInfoSchema>;
|
||||
|
||||
/** Native library entry. */
|
||||
export const nativeLibrarySchema = z.strictObject({
|
||||
path: z.string().min(1),
|
||||
architecture: z.string().nullable(),
|
||||
size: z.number().int().nonnegative(),
|
||||
digest: z
|
||||
.string()
|
||||
.regex(/^[a-f0-9]{64}$/u)
|
||||
.nullable(),
|
||||
});
|
||||
export type NativeLibrary = z.infer<typeof nativeLibrarySchema>;
|
||||
|
||||
/** Resource entry within a mobile artifact. */
|
||||
export const mobileResourceSchema = z.strictObject({
|
||||
path: z.string().min(1),
|
||||
type: z.enum([
|
||||
"layout",
|
||||
"drawable",
|
||||
"string",
|
||||
"asset",
|
||||
"raw",
|
||||
"native_lib",
|
||||
"manifest",
|
||||
"entitlements",
|
||||
"provisioning",
|
||||
"other",
|
||||
]),
|
||||
size: z.number().int().nonnegative(),
|
||||
});
|
||||
export type MobileResource = z.infer<typeof mobileResourceSchema>;
|
||||
|
||||
/** Static analysis result for a mobile artifact. */
|
||||
export const mobileArtifactManifestSchema = z.strictObject({
|
||||
format: mobileArtifactFormatSchema,
|
||||
platform: mobilePlatformSchema,
|
||||
app_name: z.string().nullable(),
|
||||
android_manifest: androidManifestSchema.nullable(),
|
||||
ios_manifest: iosManifestSchema.nullable(),
|
||||
signing: signingInfoSchema,
|
||||
resources: z.array(mobileResourceSchema).default([]),
|
||||
native_libraries: z.array(nativeLibrarySchema).default([]),
|
||||
total_size: z.number().int().nonnegative(),
|
||||
architectures: z.array(z.string()).default([]),
|
||||
});
|
||||
export type MobileArtifactManifest = z.infer<
|
||||
typeof mobileArtifactManifestSchema
|
||||
>;
|
||||
|
||||
/** Detect mobile artifact format from file extension. */
|
||||
export function detectMobileFormat(path: string): MobileArtifactFormat | null {
|
||||
const lower = path.toLowerCase();
|
||||
if (lower.endsWith(".apk")) return "apk";
|
||||
if (lower.endsWith(".aab")) return "aab";
|
||||
if (lower.endsWith(".ipa")) return "ipa";
|
||||
if (lower.endsWith(".dex")) return "dex";
|
||||
if (lower.endsWith(".so") || lower.endsWith(".dylib") || lower.endsWith(".a"))
|
||||
return "native_lib";
|
||||
return null;
|
||||
}
|
||||
|
||||
/** Detect platform from format. */
|
||||
export function detectPlatform(format: MobileArtifactFormat): MobilePlatform {
|
||||
switch (format) {
|
||||
case "apk":
|
||||
case "aab":
|
||||
case "dex":
|
||||
return "android";
|
||||
case "ipa":
|
||||
return "ios";
|
||||
case "native_lib":
|
||||
return "cross_platform";
|
||||
}
|
||||
}
|
||||
|
||||
/** Classify a resource by its path. */
|
||||
export function classifyMobileResource(path: string): MobileResource["type"] {
|
||||
const lower = path.toLowerCase();
|
||||
if (lower.includes("androidmanifest.xml")) return "manifest";
|
||||
if (lower.includes(".entitlements")) return "entitlements";
|
||||
if (lower.includes("provisioning") || lower.includes(".mobileprovision"))
|
||||
return "provisioning";
|
||||
if (lower.includes("/layout/")) return "layout";
|
||||
if (lower.includes("/drawable/") || lower.includes("/mipmap/"))
|
||||
return "drawable";
|
||||
if (lower.includes("/values/")) return "string";
|
||||
if (lower.includes("assets/") || lower.includes("raw/")) return "asset";
|
||||
if (lower.endsWith(".so") || lower.endsWith(".dylib")) return "native_lib";
|
||||
if (lower.endsWith(".xml")) return "layout";
|
||||
return "other";
|
||||
}
|
||||
|
||||
/** Get all native libraries for a specific architecture. */
|
||||
export function nativeLibsByArchitecture(
|
||||
manifest: MobileArtifactManifest,
|
||||
arch: string,
|
||||
): NativeLibrary[] {
|
||||
return manifest.native_libraries.filter((l) => l.architecture === arch);
|
||||
}
|
||||
|
||||
/** Check if an Android artifact has internet permission. */
|
||||
export function hasInternetPermission(
|
||||
manifest: MobileArtifactManifest,
|
||||
): boolean {
|
||||
if (!manifest.android_manifest) return false;
|
||||
return manifest.android_manifest.permissions.some(
|
||||
(p) => p.includes("INTERNET") || p.includes("android.permission.INTERNET"),
|
||||
);
|
||||
}
|
||||
|
||||
/** Get all unique architectures across native libraries. */
|
||||
export function getAllArchitectures(
|
||||
manifest: MobileArtifactManifest,
|
||||
): string[] {
|
||||
const archs = new Set<string>();
|
||||
for (const lib of manifest.native_libraries) {
|
||||
if (lib.architecture) archs.add(lib.architecture);
|
||||
}
|
||||
for (const arch of manifest.architectures) {
|
||||
archs.add(arch);
|
||||
}
|
||||
return [...archs];
|
||||
}
|
||||
@@ -0,0 +1,153 @@
|
||||
import { z } from "zod";
|
||||
|
||||
const inferenceConfidenceSchema = z.enum(["low", "medium", "high"]);
|
||||
|
||||
const inferenceEvidenceSchema = z
|
||||
.object({
|
||||
kind: z.enum([
|
||||
"signature-source",
|
||||
"decompiler-type",
|
||||
"type-lock",
|
||||
"calling-convention",
|
||||
"jump-table",
|
||||
]),
|
||||
source: z.string().min(1),
|
||||
detail: z.string().min(1),
|
||||
})
|
||||
.strict();
|
||||
|
||||
const inferredBoundaryTypeSchema = z
|
||||
.object({
|
||||
role: z.enum(["return", "parameter"]),
|
||||
ordinal: z.number().int().min(0).nullable(),
|
||||
name: z.string().min(1).nullable(),
|
||||
data_type: z.string().min(1),
|
||||
size_bytes: z.number().int().min(0).nullable(),
|
||||
storage: z.string().min(1).nullable(),
|
||||
confidence: inferenceConfidenceSchema,
|
||||
evidence: z.array(inferenceEvidenceSchema).min(1),
|
||||
decompiler_artifacts: z.array(
|
||||
z.enum([
|
||||
"recovered-signature",
|
||||
"register-or-stack-storage",
|
||||
"compiler-generated-variable",
|
||||
]),
|
||||
),
|
||||
})
|
||||
.strict();
|
||||
|
||||
const jumpTableDataSourceSchema = z
|
||||
.object({
|
||||
address: z.string().min(1),
|
||||
provenance: z.enum([
|
||||
"ghidra-decompiler-load-table",
|
||||
"ghidra-dispatch-block-data-reference",
|
||||
]),
|
||||
entry_size_bytes: z.number().int().min(1).nullable(),
|
||||
entry_count: z.number().int().min(0).nullable(),
|
||||
confidence: inferenceConfidenceSchema,
|
||||
evidence: z.array(inferenceEvidenceSchema).min(1),
|
||||
})
|
||||
.strict();
|
||||
|
||||
const jumpTableMappingSchema = z
|
||||
.object({
|
||||
case_value: z.number().int().nullable(),
|
||||
target_address: z.string().min(1),
|
||||
data_addresses: z.array(z.string().min(1)),
|
||||
confidence: inferenceConfidenceSchema,
|
||||
evidence: z.array(inferenceEvidenceSchema).min(1),
|
||||
})
|
||||
.strict();
|
||||
|
||||
const inferredJumpTableSchema = z
|
||||
.object({
|
||||
dispatch_address: z.string().min(1),
|
||||
data_sources: z.array(jumpTableDataSourceSchema),
|
||||
data_sources_truncated: z.boolean(),
|
||||
mappings: z.array(jumpTableMappingSchema),
|
||||
mappings_truncated: z.boolean(),
|
||||
limitations: z.array(z.string()),
|
||||
})
|
||||
.strict();
|
||||
|
||||
const availableNativeApiBoundarySchema = z
|
||||
.object({
|
||||
available: z.literal(true),
|
||||
provenance: z.string().min(1),
|
||||
signature_source: z.string().min(1),
|
||||
calling_convention: z.string().min(1),
|
||||
return_type: inferredBoundaryTypeSchema,
|
||||
parameters: z.array(inferredBoundaryTypeSchema),
|
||||
parameters_truncated: z.boolean(),
|
||||
jump_tables: z.array(inferredJumpTableSchema),
|
||||
jump_tables_truncated: z.boolean(),
|
||||
pseudocode: z
|
||||
.object({
|
||||
classification: z.literal("decompiler-generated-non-source"),
|
||||
compilable: z.literal(false),
|
||||
})
|
||||
.strict(),
|
||||
decompiler_artifacts: z.array(
|
||||
z.enum([
|
||||
"recovered-signature",
|
||||
"register-and-stack-variables",
|
||||
"compiler-generated-control-flow",
|
||||
"pointer-arithmetic",
|
||||
"pseudocode",
|
||||
]),
|
||||
),
|
||||
limitations: z.array(z.string()),
|
||||
})
|
||||
.strict();
|
||||
|
||||
const unavailableNativeApiBoundarySchema = z
|
||||
.object({
|
||||
available: z.literal(false),
|
||||
reason: z.string().min(1),
|
||||
residual_unknowns: z.array(z.string().min(1)).min(1),
|
||||
})
|
||||
.strict();
|
||||
|
||||
/** Provider-neutral native API boundary observations attached to a function dossier. */
|
||||
export const nativeApiBoundarySchema = z.discriminatedUnion("available", [
|
||||
unavailableNativeApiBoundarySchema,
|
||||
availableNativeApiBoundarySchema,
|
||||
]);
|
||||
|
||||
/** One validated provider-neutral native API boundary observation. */
|
||||
export type NativeApiBoundary = z.infer<typeof nativeApiBoundarySchema>;
|
||||
|
||||
const nativeApiInspectionSubstepSchema = z
|
||||
.object({
|
||||
operation: z.enum([
|
||||
"analyze_function",
|
||||
"project_native_api_boundary",
|
||||
"preserve_residual_unknowns",
|
||||
]),
|
||||
status: z.enum(["completed", "unsupported"]),
|
||||
observations: z.array(z.string().min(1)),
|
||||
})
|
||||
.strict();
|
||||
|
||||
/** Agent-facing projection of structured native API reconstruction substeps. */
|
||||
export const nativeApiInspectionResultSchema = z
|
||||
.object({
|
||||
schema_version: z.literal(1),
|
||||
procedure: z
|
||||
.object({
|
||||
address: z.string().min(1),
|
||||
name: z.string().min(1),
|
||||
})
|
||||
.strict(),
|
||||
boundary: nativeApiBoundarySchema,
|
||||
substeps: z.array(nativeApiInspectionSubstepSchema).min(3).max(3),
|
||||
unsupported_branches: z.array(z.string().min(1)),
|
||||
residual_unknowns: z.array(z.string().min(1)),
|
||||
})
|
||||
.strict();
|
||||
|
||||
/** One validated agent-facing native API inspection result. */
|
||||
export type NativeApiInspectionResult = z.infer<
|
||||
typeof nativeApiInspectionResultSchema
|
||||
>;
|
||||
@@ -0,0 +1,191 @@
|
||||
import { z } from "zod";
|
||||
|
||||
/** Objective-C method type. */
|
||||
export const objcMethodTypeSchema = z.enum([
|
||||
"instance",
|
||||
"class",
|
||||
"ivar_getter",
|
||||
"ivar_setter",
|
||||
]);
|
||||
export type ObjcMethodType = z.infer<typeof objcMethodTypeSchema>;
|
||||
|
||||
/** Objective-C property attribute. */
|
||||
export const objcPropertyAttributeSchema = z.strictObject({
|
||||
name: z.string().min(1),
|
||||
value: z.string(),
|
||||
is_weak: z.boolean().default(false),
|
||||
is_atomic: z.boolean().default(false),
|
||||
is_copy: z.boolean().default(false),
|
||||
is_strong: z.boolean().default(false),
|
||||
});
|
||||
export type ObjcPropertyAttribute = z.infer<typeof objcPropertyAttributeSchema>;
|
||||
|
||||
/** Objective-C method metadata. */
|
||||
export const objcMethodSchema = z.strictObject({
|
||||
selector: z.string().min(1),
|
||||
method_type: objcMethodTypeSchema,
|
||||
address: z.number().int().nullable(),
|
||||
is_required: z.boolean().default(false),
|
||||
is_optional: z.boolean().default(false),
|
||||
});
|
||||
export type ObjcMethod = z.infer<typeof objcMethodSchema>;
|
||||
|
||||
/** Objective-C property metadata. */
|
||||
export const objcPropertySchema = z.strictObject({
|
||||
name: z.string().min(1),
|
||||
type_encoding: z.string().nullable(),
|
||||
attributes: z.array(objcPropertyAttributeSchema).default([]),
|
||||
is_readonly: z.boolean().default(false),
|
||||
getter: z.string().nullable(),
|
||||
setter: z.string().nullable(),
|
||||
});
|
||||
export type ObjcProperty = z.infer<typeof objcPropertySchema>;
|
||||
|
||||
/** Objective-C protocol metadata. */
|
||||
export const objcProtocolSchema = z.strictObject({
|
||||
name: z.string().min(1),
|
||||
methods: z.array(objcMethodSchema).default([]),
|
||||
optional_methods: z.array(objcMethodSchema).default([]),
|
||||
properties: z.array(objcPropertySchema).default([]),
|
||||
});
|
||||
export type ObjcProtocol = z.infer<typeof objcProtocolSchema>;
|
||||
|
||||
/** Objective-C class metadata. */
|
||||
export const objcClassSchema = z.strictObject({
|
||||
name: z.string().min(1),
|
||||
super_class: z.string().nullable(),
|
||||
is_meta_class: z.boolean().default(false),
|
||||
is_root_class: z.boolean().default(false),
|
||||
methods: z.array(objcMethodSchema).default([]),
|
||||
properties: z.array(objcPropertySchema).default([]),
|
||||
protocols: z.array(z.string()).default([]),
|
||||
ivar_count: z.number().int().nonnegative().default(0),
|
||||
instance_size: z.number().int().nonnegative().nullable(),
|
||||
});
|
||||
export type ObjcClass = z.infer<typeof objcClassSchema>;
|
||||
|
||||
/** Swift declaration kind. */
|
||||
export const swiftDeclKindSchema = z.enum([
|
||||
"class",
|
||||
"struct",
|
||||
"enum",
|
||||
"protocol",
|
||||
"extension",
|
||||
"actor",
|
||||
"global_var",
|
||||
"global_func",
|
||||
]);
|
||||
export type SwiftDeclKind = z.infer<typeof swiftDeclKindSchema>;
|
||||
|
||||
/** Swift access level. */
|
||||
export const swiftAccessLevelSchema = z.enum([
|
||||
"private",
|
||||
"fileprivate",
|
||||
"internal",
|
||||
"public",
|
||||
"open",
|
||||
]);
|
||||
export type SwiftAccessLevel = z.infer<typeof swiftAccessLevelSchema>;
|
||||
/** Swift declaration metadata. */
|
||||
export const swiftDeclSchema = z.strictObject({
|
||||
kind: swiftDeclKindSchema,
|
||||
name: z.string().min(1),
|
||||
module: z.string().nullable(),
|
||||
access_level: swiftAccessLevelSchema.default("internal"),
|
||||
super_class: z.string().nullable(),
|
||||
protocols: z.array(z.string()).default([]),
|
||||
is_final: z.boolean().default(false),
|
||||
is_required: z.boolean().default(false),
|
||||
is_convenience_init: z.boolean().default(false),
|
||||
is_override: z.boolean().default(false),
|
||||
});
|
||||
export type SwiftDecl = z.infer<typeof swiftDeclSchema>;
|
||||
|
||||
/** Database save/read operation type. */
|
||||
export const dbOperationSchema = z.enum([
|
||||
"save",
|
||||
"readback",
|
||||
"open_database",
|
||||
"close_database",
|
||||
"export",
|
||||
"import",
|
||||
]);
|
||||
export type DbOperation = z.infer<typeof dbOperationSchema>;
|
||||
|
||||
/** Database save operation result. */
|
||||
export const dbSaveResultSchema = z.strictObject({
|
||||
operation: dbOperationSchema,
|
||||
succeeded: z.boolean(),
|
||||
preserved_names: z.number().int().nonnegative().default(0),
|
||||
preserved_comments: z.number().int().nonnegative().default(0),
|
||||
preserved_bookmarks: z.number().int().nonnegative().default(0),
|
||||
database_path: z.string().nullable(),
|
||||
error: z.string().nullable(),
|
||||
});
|
||||
export type DbSaveResult = z.infer<typeof dbSaveResultSchema>;
|
||||
|
||||
/** Result of deeper ObjC/Swift metadata extraction. */
|
||||
export const objcSwiftMetadataSchema = z.strictObject({
|
||||
objc_classes: z.array(objcClassSchema).default([]),
|
||||
objc_protocols: z.array(objcProtocolSchema).default([]),
|
||||
swift_decls: z.array(swiftDeclSchema).default([]),
|
||||
db_save_result: dbSaveResultSchema.nullable(),
|
||||
});
|
||||
export type ObjcSwiftMetadata = z.infer<typeof objcSwiftMetadataSchema>;
|
||||
|
||||
/** Check if a selector name looks like a getter. */
|
||||
export function isGetterSelector(selector: string): boolean {
|
||||
return /^[a-z][a-zA-Z0-9_]*$/u.test(selector) && !selector.includes(":");
|
||||
}
|
||||
|
||||
/** Check if a selector name looks like a setter. */
|
||||
export function isSetterSelector(selector: string): boolean {
|
||||
return selector.startsWith("set") && selector.endsWith(":");
|
||||
}
|
||||
|
||||
/** Extract property name from a getter/setter selector. */
|
||||
export function propertyNameFromSelector(selector: string): string | null {
|
||||
if (isSetterSelector(selector)) {
|
||||
const inner = selector.slice(3, -1);
|
||||
return inner.charAt(0).toLowerCase() + inner.slice(1);
|
||||
}
|
||||
if (isGetterSelector(selector)) {
|
||||
return selector;
|
||||
}
|
||||
return null;
|
||||
}
|
||||
|
||||
/** Count ObjC methods by type. */
|
||||
export function countMethodsByType(
|
||||
methods: readonly ObjcMethod[],
|
||||
): Record<ObjcMethodType, number> {
|
||||
return {
|
||||
instance: methods.filter((m) => m.method_type === "instance").length,
|
||||
class: methods.filter((m) => m.method_type === "class").length,
|
||||
ivar_getter: methods.filter((m) => m.method_type === "ivar_getter").length,
|
||||
ivar_setter: methods.filter((m) => m.method_type === "ivar_setter").length,
|
||||
};
|
||||
}
|
||||
|
||||
/** Get all Swift declarations of a specific kind. */
|
||||
export function swiftDeclsByKind(
|
||||
decls: readonly SwiftDecl[],
|
||||
kind: SwiftDeclKind,
|
||||
): SwiftDecl[] {
|
||||
return decls.filter((d) => d.kind === kind);
|
||||
}
|
||||
|
||||
/** Check if a database save preserved all expected items. */
|
||||
export function isDbSaveComplete(
|
||||
result: DbSaveResult,
|
||||
expectedNames: number,
|
||||
expectedComments: number,
|
||||
expectedBookmarks: number,
|
||||
): boolean {
|
||||
return (
|
||||
result.succeeded &&
|
||||
result.preserved_names >= expectedNames &&
|
||||
result.preserved_comments >= expectedComments &&
|
||||
result.preserved_bookmarks >= expectedBookmarks
|
||||
);
|
||||
}
|
||||
@@ -0,0 +1,144 @@
|
||||
import { z } from "zod";
|
||||
|
||||
/** Supported Windows package formats. */
|
||||
export const packageFormatSchema = z.enum(["msix", "msi", "appx"]);
|
||||
export type PackageFormat = z.infer<typeof packageFormatSchema>;
|
||||
|
||||
/** A resource entry within a package. */
|
||||
export const packageResourceSchema = z.strictObject({
|
||||
/** Resource path within the package. */
|
||||
path: z.string().min(1),
|
||||
/** Resource type. */
|
||||
type: z.enum([
|
||||
"manifest",
|
||||
"icon",
|
||||
"configuration",
|
||||
"certificate",
|
||||
"executable",
|
||||
"library",
|
||||
"data",
|
||||
"other",
|
||||
]),
|
||||
/** Size in bytes. */
|
||||
size: z.number().int().nonnegative(),
|
||||
/** SHA-256 digest. */
|
||||
digest: z
|
||||
.string()
|
||||
.regex(/^[a-f0-9]{64}$/u)
|
||||
.nullable(),
|
||||
});
|
||||
export type PackageResource = z.infer<typeof packageResourceSchema>;
|
||||
|
||||
/** Digital signature information. */
|
||||
export const digitalSignatureSchema = z.strictObject({
|
||||
/** Whether the package is signed. */
|
||||
is_signed: z.boolean(),
|
||||
/** Signer subject name. */
|
||||
signer_subject: z.string().nullable(),
|
||||
/** Certificate thumbprint. */
|
||||
certificate_thumbprint: z.string().nullable(),
|
||||
/** Whether the signature is valid. */
|
||||
is_valid: z.boolean().default(false),
|
||||
/** Whether the signature is timestamped. */
|
||||
is_timestamped: z.boolean().default(false),
|
||||
/** Timestamp signer if present. */
|
||||
timestamp_signer: z.string().nullable(),
|
||||
});
|
||||
export type DigitalSignature = z.infer<typeof digitalSignatureSchema>;
|
||||
|
||||
/** A Windows package manifest for static analysis. */
|
||||
export const packageManifestSchema = z.strictObject({
|
||||
/** Package format. */
|
||||
format: packageFormatSchema,
|
||||
/** Package identity name. */
|
||||
name: z.string().min(1),
|
||||
/** Package publisher. */
|
||||
publisher: z.string().nullable(),
|
||||
/** Package version. */
|
||||
version: z.string().nullable(),
|
||||
/** Architecture. */
|
||||
architecture: z.enum(["x86", "x64", "arm", "arm64", "neutral", "unknown"]),
|
||||
/** Package resources. */
|
||||
resources: z.array(packageResourceSchema).default([]),
|
||||
/** Digital signature. */
|
||||
signature: digitalSignatureSchema,
|
||||
/** Whether the package is a framework. */
|
||||
is_framework: z.boolean().default(false),
|
||||
/** Package dependencies. */
|
||||
dependencies: z.array(z.string()).default([]),
|
||||
/** Capabilities declared in the manifest. */
|
||||
capabilities: z.array(z.string()).default([]),
|
||||
});
|
||||
export type PackageManifest = z.infer<typeof packageManifestSchema>;
|
||||
|
||||
/** Detect package format from file extension. */
|
||||
export function detectPackageFormat(path: string): PackageFormat | null {
|
||||
const lower = path.toLowerCase();
|
||||
if (lower.endsWith(".msix")) return "msix";
|
||||
if (lower.endsWith(".msi")) return "msi";
|
||||
if (lower.endsWith(".appx")) return "appx";
|
||||
return null;
|
||||
}
|
||||
|
||||
/** Check if a resource path looks like a manifest. */
|
||||
export function isManifestResource(path: string): boolean {
|
||||
const lower = path.toLowerCase();
|
||||
return (
|
||||
lower.includes("appxmanifest.xml") ||
|
||||
lower.includes("appxmanifest") ||
|
||||
lower.includes("manifest.xml") ||
|
||||
lower.endsWith("_manifest.xml")
|
||||
);
|
||||
}
|
||||
|
||||
/** Check if a resource path looks like a configuration file. */
|
||||
export function isConfigurationResource(path: string): boolean {
|
||||
const lower = path.toLowerCase();
|
||||
return (
|
||||
lower.endsWith(".xml") ||
|
||||
lower.endsWith(".json") ||
|
||||
lower.endsWith(".ini") ||
|
||||
lower.endsWith(".config")
|
||||
);
|
||||
}
|
||||
|
||||
/** Classify a resource by its path. */
|
||||
export function classifyResource(path: string): PackageResource["type"] {
|
||||
if (isManifestResource(path)) return "manifest";
|
||||
const lower = path.toLowerCase();
|
||||
if (
|
||||
lower.endsWith(".ico") ||
|
||||
lower.endsWith(".png") ||
|
||||
lower.endsWith(".jpg") ||
|
||||
lower.endsWith(".jpeg")
|
||||
)
|
||||
return "icon";
|
||||
if (isConfigurationResource(path)) return "configuration";
|
||||
if (
|
||||
lower.endsWith(".cer") ||
|
||||
lower.endsWith(".pfx") ||
|
||||
lower.endsWith(".p12")
|
||||
)
|
||||
return "certificate";
|
||||
if (lower.endsWith(".exe") || lower.endsWith(".dll"))
|
||||
return lower.endsWith(".exe") ? "executable" : "library";
|
||||
return "other";
|
||||
}
|
||||
|
||||
/** Get all resources of a specific type. */
|
||||
export function resourcesByType(
|
||||
manifest: PackageManifest,
|
||||
type: PackageResource["type"],
|
||||
): PackageResource[] {
|
||||
return manifest.resources.filter((r) => r.type === type);
|
||||
}
|
||||
|
||||
/** Get the total size of all resources. */
|
||||
export function totalResourceSize(manifest: PackageManifest): number {
|
||||
return manifest.resources.reduce((sum, r) => sum + r.size, 0);
|
||||
}
|
||||
|
||||
/** Check if a package has a valid signature. */
|
||||
export function hasValidSignature(manifest: PackageManifest): boolean {
|
||||
return manifest.signature.is_signed && manifest.signature.is_valid;
|
||||
}
|
||||
@@ -0,0 +1,225 @@
|
||||
import { z } from "zod";
|
||||
|
||||
/** PE/COFF section characteristics flags. */
|
||||
export const sectionCharacteristicsSchema = z.object({
|
||||
/** Section contains executable code. */
|
||||
has_code: z.boolean().default(false),
|
||||
/** Section contains initialized data. */
|
||||
has_initialized_data: z.boolean().default(false),
|
||||
/** Section contains uninitialized data. */
|
||||
has_uninitialized_data: z.boolean().default(false),
|
||||
/** Section can be read. */
|
||||
readable: z.boolean().default(false),
|
||||
/** Section can be written. */
|
||||
writable: z.boolean().default(false),
|
||||
/** Section can be executed. */
|
||||
executable: z.boolean().default(false),
|
||||
});
|
||||
|
||||
/** PE/COFF section header. */
|
||||
export const peSectionSchema = z.strictObject({
|
||||
name: z.string().min(1),
|
||||
virtual_size: z.number().int().nonnegative(),
|
||||
virtual_address: z.number().int().nonnegative(),
|
||||
raw_size: z.number().int().nonnegative(),
|
||||
raw_offset: z.number().int().nonnegative(),
|
||||
characteristics: sectionCharacteristicsSchema,
|
||||
});
|
||||
export type PeSection = z.infer<typeof peSectionSchema>;
|
||||
|
||||
/** PE import entry. */
|
||||
export const peImportSchema = z.strictObject({
|
||||
dll: z.string().min(1),
|
||||
function_name: z.string().min(1),
|
||||
ordinal: z.number().int().nullable(),
|
||||
is_delay_import: z.boolean().default(false),
|
||||
});
|
||||
export type PeImport = z.infer<typeof peImportSchema>;
|
||||
|
||||
/** PE export entry. */
|
||||
export const peExportSchema = z.strictObject({
|
||||
name: z.string().min(1),
|
||||
ordinal: z.number().int().nonnegative(),
|
||||
rva: z.number().int().nonnegative(),
|
||||
forwarder: z.string().nullable(),
|
||||
});
|
||||
export type PeExport = z.infer<typeof peExportSchema>;
|
||||
|
||||
/** PE/COFF resource entry. */
|
||||
export const peResourceSchema = z.strictObject({
|
||||
type: z.string().min(1),
|
||||
name: z.string().nullable(),
|
||||
language: z.number().int().nullable(),
|
||||
rva: z.number().int().nonnegative(),
|
||||
size: z.number().int().nonnegative(),
|
||||
});
|
||||
export type PeResource = z.infer<typeof peResourceSchema>;
|
||||
|
||||
/** PE debug directory entry. */
|
||||
export const peDebugEntrySchema = z.strictObject({
|
||||
type: z.string().min(1),
|
||||
rva: z.number().int().nonnegative(),
|
||||
size: z.number().int().nonnegative(),
|
||||
/** PDB GUID if this is a CodeView entry. */
|
||||
pdb_guid: z.string().nullable(),
|
||||
/** PDB age if this is a CodeView entry. */
|
||||
pdb_age: z.number().int().nullable(),
|
||||
/** PDB path if this is a CodeView entry. */
|
||||
pdb_path: z.string().nullable(),
|
||||
});
|
||||
export type PeDebugEntry = z.infer<typeof peDebugEntrySchema>;
|
||||
|
||||
/** TLS callback entry. */
|
||||
export const peTlsCallbackSchema = z.strictObject({
|
||||
callback_rva: z.number().int().nonnegative(),
|
||||
index: z.number().int().nonnegative(),
|
||||
});
|
||||
export type PeTlsCallback = z.infer<typeof peTlsCallbackSchema>;
|
||||
|
||||
/** Architecture/machine type. */
|
||||
export const peMachineTypeSchema = z.enum([
|
||||
"x86",
|
||||
"x64",
|
||||
"arm",
|
||||
"arm64",
|
||||
"ia64",
|
||||
"unknown",
|
||||
]);
|
||||
export type PeMachineType = z.infer<typeof peMachineTypeSchema>;
|
||||
|
||||
/** PE/COFF manifest for static inspection. */
|
||||
export const peManifestSchema = z.strictObject({
|
||||
/** DOS header magic. */
|
||||
dos_magic: z.literal(0x5a4d),
|
||||
/** PE signature. */
|
||||
pe_signature: z.literal(0x00004550),
|
||||
/** Machine type. */
|
||||
machine: peMachineTypeSchema,
|
||||
/** Number of sections. */
|
||||
number_of_sections: z.number().int().positive(),
|
||||
/** Timestamp from the COFF header. */
|
||||
timestamp: z.number().int().nullable(),
|
||||
/** PE characteristics flags. */
|
||||
is_dll: z.boolean().default(false),
|
||||
is_executable: z.boolean().default(false),
|
||||
is_console: z.boolean().default(true),
|
||||
/** Entry point RVA. */
|
||||
entry_point: z.number().int().nonnegative(),
|
||||
/** Image base. */
|
||||
image_base: z.number().int().nonnegative(),
|
||||
/** Section alignment. */
|
||||
section_alignment: z.number().int().positive(),
|
||||
/** Subsystem version. */
|
||||
subsystem_version: z.string().nullable(),
|
||||
/** Sections. */
|
||||
sections: z.array(peSectionSchema).min(0).max(96),
|
||||
/** Imports. */
|
||||
imports: z.array(peImportSchema).default([]),
|
||||
/** Exports. */
|
||||
exports: z.array(peExportSchema).default([]),
|
||||
/** Resources. */
|
||||
resources: z.array(peResourceSchema).default([]),
|
||||
/** Debug directory entries. */
|
||||
debug_entries: z.array(peDebugEntrySchema).default([]),
|
||||
/** TLS callbacks. */
|
||||
tls_callbacks: z.array(peTlsCallbackSchema).default([]),
|
||||
/** Relocations count (not all entries). */
|
||||
relocations_count: z.number().int().nonnegative().default(0),
|
||||
/** Image file characteristics. */
|
||||
image_characteristics: z.array(z.string()).default([]),
|
||||
});
|
||||
export type PeManifest = z.infer<typeof peManifestSchema>;
|
||||
|
||||
/** Parse machine type from COFF machine field. */
|
||||
export function parseMachineType(machine: number): PeMachineType {
|
||||
switch (machine) {
|
||||
case 0x014c:
|
||||
return "x86";
|
||||
case 0x8664:
|
||||
return "x64";
|
||||
case 0x01c0:
|
||||
case 0x01c4:
|
||||
return "arm";
|
||||
case 0xaa64:
|
||||
return "arm64";
|
||||
case 0x0200:
|
||||
return "ia64";
|
||||
default:
|
||||
return "unknown";
|
||||
}
|
||||
}
|
||||
|
||||
/** Parse section characteristics flags. */
|
||||
export function parseSectionCharacteristics(
|
||||
characteristics: number,
|
||||
): z.infer<typeof sectionCharacteristicsSchema> {
|
||||
const IMAGE_SCN_CNT_CODE = 0x00000020;
|
||||
const IMAGE_SCN_CNT_INITIALIZED_DATA = 0x00000040;
|
||||
const IMAGE_SCN_CNT_UNINITIALIZED_DATA = 0x00000080;
|
||||
const IMAGE_SCN_MEM_READ = 0x40000000;
|
||||
const IMAGE_SCN_MEM_WRITE = 0x80000000;
|
||||
const IMAGE_SCN_MEM_EXECUTE = 0x20000000;
|
||||
|
||||
return {
|
||||
has_code: (characteristics & IMAGE_SCN_CNT_CODE) !== 0,
|
||||
has_initialized_data:
|
||||
(characteristics & IMAGE_SCN_CNT_INITIALIZED_DATA) !== 0,
|
||||
has_uninitialized_data:
|
||||
(characteristics & IMAGE_SCN_CNT_UNINITIALIZED_DATA) !== 0,
|
||||
readable: (characteristics & IMAGE_SCN_MEM_READ) !== 0,
|
||||
writable: (characteristics & IMAGE_SCN_MEM_WRITE) !== 0,
|
||||
executable: (characteristics & IMAGE_SCN_MEM_EXECUTE) !== 0,
|
||||
};
|
||||
}
|
||||
|
||||
/** Parse image characteristics flags. */
|
||||
export function parseImageCharacteristics(characteristics: number): string[] {
|
||||
const IMAGE_DLL = 0x2000;
|
||||
const IMAGE_EXECUTABLE = 0x0002;
|
||||
const IMAGE_CONSOLE = 0x0003;
|
||||
const flags: string[] = [];
|
||||
if (characteristics & IMAGE_DLL) flags.push("DLL");
|
||||
if (characteristics & IMAGE_EXECUTABLE) flags.push("Executable");
|
||||
if ((characteristics & 0x0000000f) === IMAGE_CONSOLE) flags.push("Console");
|
||||
return flags;
|
||||
}
|
||||
|
||||
/** Parse a PE debug directory type. */
|
||||
export function parseDebugType(type: number): string {
|
||||
switch (type) {
|
||||
case 0:
|
||||
return "UNKNOWN";
|
||||
case 1:
|
||||
return "COFF";
|
||||
case 2:
|
||||
return "CODEVIEW";
|
||||
case 3:
|
||||
return "POGO";
|
||||
case 4:
|
||||
return "MISC";
|
||||
default:
|
||||
return "UNKNOWN";
|
||||
}
|
||||
}
|
||||
|
||||
/** Check if a PE manifest has PDB debug info. */
|
||||
export function hasPdbInfo(manifest: PeManifest): boolean {
|
||||
return manifest.debug_entries.some(
|
||||
(e) => e.pdb_guid !== null && e.pdb_path !== null,
|
||||
);
|
||||
}
|
||||
|
||||
/** Get all imported DLLs from a PE manifest. */
|
||||
export function getImportedDlls(manifest: PeManifest): string[] {
|
||||
return [...new Set(manifest.imports.map((i) => i.dll))];
|
||||
}
|
||||
|
||||
/** Get all exported function names from a PE manifest. */
|
||||
export function getExportedFunctions(manifest: PeManifest): string[] {
|
||||
return manifest.exports.map((e) => e.name);
|
||||
}
|
||||
|
||||
/** Count executable sections. */
|
||||
export function countExecutableSections(manifest: PeManifest): number {
|
||||
return manifest.sections.filter((s) => s.characteristics.executable).length;
|
||||
}
|
||||
@@ -0,0 +1,272 @@
|
||||
import { z } from "zod";
|
||||
|
||||
import { jsonValueSchema } from "./jsonValue.js";
|
||||
|
||||
/** Supported protocol families for structured protocol capture. */
|
||||
export const protocolFamilySchema = z.enum([
|
||||
"grpc",
|
||||
"protobuf",
|
||||
"json-rpc",
|
||||
"messagepack",
|
||||
]);
|
||||
export type ProtocolFamily = z.infer<typeof protocolFamilySchema>;
|
||||
|
||||
/** A decoded field from a protocol message. */
|
||||
export const decodedFieldSchema = z.strictObject({
|
||||
/** Field name or path within the message structure. */
|
||||
path: z.string().min(1),
|
||||
/** Wire type or encoding hint. */
|
||||
wire_type: z.string().nullable(),
|
||||
/** Decoded field value. */
|
||||
value: jsonValueSchema.nullable(),
|
||||
/** Whether this field value was inferred rather than decoded. */
|
||||
inferred: z.boolean().default(false),
|
||||
});
|
||||
export type DecodedField = z.infer<typeof decodedFieldSchema>;
|
||||
|
||||
/** Schema inference hypothesis for a repeated message pattern. */
|
||||
export const schemaHypothesisSchema = z.strictObject({
|
||||
/** Hypothesized field name. */
|
||||
field_name: z.string().min(1),
|
||||
/** Inferred type. */
|
||||
inferred_type: z.string().min(1),
|
||||
/** Confidence: 0-1 */
|
||||
confidence: z.number().min(0).max(1),
|
||||
/** Supporting evidence count. */
|
||||
evidence_count: z.number().int().nonnegative(),
|
||||
});
|
||||
export type SchemaHypothesis = z.infer<typeof schemaHypothesisSchema>;
|
||||
|
||||
/** Result of decoding a single protocol message. */
|
||||
export const protocolMessageSchema = z.strictObject({
|
||||
/** Monotonic sequence number. */
|
||||
sequence: z.number().int().nonnegative(),
|
||||
/** Timestamp in milliseconds. */
|
||||
at_ms: z.number().int().nonnegative(),
|
||||
/** Protocol family. */
|
||||
family: protocolFamilySchema,
|
||||
/** Direction of the message. */
|
||||
direction: z.enum(["request", "response"]),
|
||||
/** Transport endpoint or path (e.g. gRPC method path). */
|
||||
endpoint: z.string().nullable(),
|
||||
/** Content type of the raw payload. */
|
||||
content_type: z.string().nullable(),
|
||||
/** Raw payload bytes as base64. */
|
||||
raw_payload: z.string().nullable(),
|
||||
/** Decoded fields from the payload. */
|
||||
decoded_fields: z.array(decodedFieldSchema).default([]),
|
||||
/** Inferred schema hypotheses. */
|
||||
schema_hypotheses: z.array(schemaHypothesisSchema).default([]),
|
||||
/** Whether decoding was truncated. */
|
||||
truncated: z.boolean().default(false),
|
||||
/** Whether credentials were detected and redacted. */
|
||||
credentials_redacted: z.boolean().default(false),
|
||||
});
|
||||
export type ProtocolMessage = z.infer<typeof protocolMessageSchema>;
|
||||
|
||||
/** A captured protocol session with messages and inferred schemas. */
|
||||
export const protocolCaptureSchema = z.strictObject({
|
||||
/** Protocol family for this capture. */
|
||||
family: protocolFamilySchema,
|
||||
/** Captured messages in order. */
|
||||
messages: z.array(protocolMessageSchema).min(0).max(10_000),
|
||||
/** Aggregated schema hypotheses across all messages. */
|
||||
inferred_schema: z.array(schemaHypothesisSchema).default([]),
|
||||
/** Whether any message was truncated. */
|
||||
has_truncated: z.boolean().default(false),
|
||||
/** Whether credentials were detected and redacted. */
|
||||
credentials_detected: z.boolean().default(false),
|
||||
});
|
||||
export type ProtocolCapture = z.infer<typeof protocolCaptureSchema>;
|
||||
|
||||
/** Classification of a byte sequence as a known protocol family. */
|
||||
export function classifyProtocolFamily(
|
||||
contentType: string | null,
|
||||
path: string | null,
|
||||
): ProtocolFamily | null {
|
||||
if (contentType) {
|
||||
if (contentType.includes("application/grpc")) return "grpc";
|
||||
if (contentType.includes("application/x-protobuf")) return "protobuf";
|
||||
if (contentType.includes("application/json-rpc")) return "json-rpc";
|
||||
if (
|
||||
contentType.includes("application/msgpack") ||
|
||||
contentType.includes("application/x-msgpack")
|
||||
)
|
||||
return "messagepack";
|
||||
}
|
||||
if (path) {
|
||||
if (path.startsWith("/grpc.") || path.includes("/grpc/")) return "grpc";
|
||||
if (path.includes("/json-rpc") || path.includes("/jsonrpc"))
|
||||
return "json-rpc";
|
||||
}
|
||||
return null;
|
||||
}
|
||||
|
||||
/** Credential-like field names that should be redacted. */
|
||||
const CREDENTIAL_PATTERNS = [
|
||||
"password",
|
||||
"passwd",
|
||||
"secret",
|
||||
"token",
|
||||
"api_key",
|
||||
"apikey",
|
||||
"authorization",
|
||||
"auth",
|
||||
"credential",
|
||||
"private_key",
|
||||
];
|
||||
|
||||
/** Check if a field path looks like it may contain credentials. */
|
||||
export function looksLikeCredential(path: string): boolean {
|
||||
const lower = path.toLowerCase();
|
||||
return CREDENTIAL_PATTERNS.some((p) => lower.includes(p));
|
||||
}
|
||||
|
||||
/** Decode a JSON-RPC message from raw payload bytes. */
|
||||
export function decodeJsonRpc(rawPayload: Uint8Array): {
|
||||
decoded_fields: DecodedField[];
|
||||
truncated: boolean;
|
||||
} {
|
||||
const text = new TextDecoder().decode(rawPayload);
|
||||
const parsed = JSON.parse(text);
|
||||
const fields: DecodedField[] = [];
|
||||
|
||||
if (typeof parsed === "object" && parsed !== null) {
|
||||
for (const [key, value] of Object.entries(parsed)) {
|
||||
if (looksLikeCredential(key)) {
|
||||
fields.push({
|
||||
path: key,
|
||||
wire_type: "json",
|
||||
value: "[REDACTED]",
|
||||
inferred: false,
|
||||
});
|
||||
} else {
|
||||
fields.push({
|
||||
path: key,
|
||||
wire_type: "json",
|
||||
value: value as never,
|
||||
inferred: false,
|
||||
});
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
return { decoded_fields: fields, truncated: false };
|
||||
}
|
||||
|
||||
/** Decode a MessagePack message (simplified: only checks basic structure). */
|
||||
export function decodeMessagePack(rawPayload: Uint8Array): {
|
||||
decoded_fields: DecodedField[];
|
||||
truncated: boolean;
|
||||
} {
|
||||
const fields: DecodedField[] = [];
|
||||
// MessagePack uses a single-byte type tag
|
||||
if (rawPayload.length === 0) {
|
||||
return { decoded_fields: [], truncated: false };
|
||||
}
|
||||
const tag = rawPayload[0]!;
|
||||
// Map type: 0x80-0x8f (fixmap), 0xde (map16), 0xdf (map32)
|
||||
if ((tag >= 0x80 && tag <= 0x8f) || tag === 0xde || tag === 0xdf) {
|
||||
fields.push({
|
||||
path: "type",
|
||||
wire_type: "msgpack",
|
||||
value: "map",
|
||||
inferred: false,
|
||||
});
|
||||
}
|
||||
// Array type: 0x90-0x9f (fixarray), 0xdc (array16), 0xdd (array32)
|
||||
else if ((tag >= 0x90 && tag <= 0x9f) || tag === 0xdc || tag === 0xdd) {
|
||||
fields.push({
|
||||
path: "type",
|
||||
wire_type: "msgpack",
|
||||
value: "array",
|
||||
inferred: false,
|
||||
});
|
||||
} else {
|
||||
fields.push({
|
||||
path: "type",
|
||||
wire_type: "msgpack",
|
||||
value: "unknown",
|
||||
inferred: true,
|
||||
});
|
||||
}
|
||||
return {
|
||||
decoded_fields: fields,
|
||||
truncated: rawPayload.length > 10_000,
|
||||
};
|
||||
}
|
||||
|
||||
/** Decode a gRPC frame (5-byte header + protobuf payload). */
|
||||
export function decodeGrpcFrame(rawPayload: Uint8Array): {
|
||||
decoded_fields: DecodedField[];
|
||||
truncated: boolean;
|
||||
} {
|
||||
// gRPC uses a 5-byte prefix: 1 byte compressed flag + 4 byte length
|
||||
if (rawPayload.length < 5) {
|
||||
return {
|
||||
decoded_fields: [
|
||||
{
|
||||
path: "error",
|
||||
wire_type: "grpc",
|
||||
value: "frame too short",
|
||||
inferred: false,
|
||||
},
|
||||
],
|
||||
truncated: false,
|
||||
};
|
||||
}
|
||||
const compressed = rawPayload[0] !== 0;
|
||||
const length =
|
||||
(rawPayload[1]! << 24) |
|
||||
(rawPayload[2]! << 16) |
|
||||
(rawPayload[3]! << 8) |
|
||||
rawPayload[4]!;
|
||||
return {
|
||||
decoded_fields: [
|
||||
{
|
||||
path: "compressed",
|
||||
wire_type: "grpc",
|
||||
value: compressed,
|
||||
inferred: false,
|
||||
},
|
||||
{
|
||||
path: "message_length",
|
||||
wire_type: "grpc",
|
||||
value: length,
|
||||
inferred: false,
|
||||
},
|
||||
],
|
||||
truncated: length > 10_000,
|
||||
};
|
||||
}
|
||||
|
||||
/** Infer schema hypotheses from a set of decoded messages. */
|
||||
export function inferMessageSchema(
|
||||
messages: readonly ProtocolMessage[],
|
||||
): SchemaHypothesis[] {
|
||||
const fieldCounts = new Map<string, { count: number; types: Set<string> }>();
|
||||
for (const msg of messages) {
|
||||
for (const field of msg.decoded_fields) {
|
||||
const existing = fieldCounts.get(field.path);
|
||||
if (existing) {
|
||||
existing.count++;
|
||||
if (field.wire_type) existing.types.add(field.wire_type);
|
||||
} else {
|
||||
fieldCounts.set(field.path, {
|
||||
count: 1,
|
||||
types: new Set(field.wire_type ?? "unknown"),
|
||||
});
|
||||
}
|
||||
}
|
||||
}
|
||||
const hypotheses: SchemaHypothesis[] = [];
|
||||
for (const [field_name, data] of fieldCounts) {
|
||||
hypotheses.push({
|
||||
field_name,
|
||||
inferred_type: [...data.types].join("|"),
|
||||
confidence: Math.min(1, data.count / messages.length || 0),
|
||||
evidence_count: data.count,
|
||||
});
|
||||
}
|
||||
return hypotheses;
|
||||
}
|
||||
@@ -5,7 +5,7 @@ import {
|
||||
discoverObjcClasses,
|
||||
discoverObjcProtocols,
|
||||
discoverSwiftClasses,
|
||||
} from "../src/domain/symbolAnalysis.js";
|
||||
} from "./symbolAnalysis.js";
|
||||
|
||||
describe("symbol analysis", () => {
|
||||
it("filters Swift classes and reports the uncapped match count", () => {
|
||||
File diff suppressed because one or more lines are too long
@@ -1,9 +1,9 @@
|
||||
/** Generated from package.json and package-lock.json; do not edit. */
|
||||
export const PACKAGE_METADATA = {
|
||||
name: "rea-agents",
|
||||
version: "2.5.1", // x-release-please-version
|
||||
serverSdkVersion: "2.0.0-beta.4",
|
||||
clientSdkVersion: "2.0.0-beta.4",
|
||||
coreSdkVersion: "2.0.0-beta.4",
|
||||
version: "3.0.0", // x-release-please-version
|
||||
serverSdkVersion: "2.0.0",
|
||||
clientSdkVersion: "2.0.0",
|
||||
coreSdkVersion: "2.0.0",
|
||||
skillVersion: "23",
|
||||
} as const;
|
||||
|
||||
@@ -17,4 +17,4 @@ export const GHIDRA_MAX_QUEUED_REQUESTS = 32;
|
||||
/** Maximum encoded response line accepted from the Java bridge. */
|
||||
export const GHIDRA_MAX_LINE_BYTES = 1024 * 1024;
|
||||
/** Version of REA's Java bridge handshake and request protocol. */
|
||||
export const GHIDRA_BRIDGE_VERSION = 5;
|
||||
export const GHIDRA_BRIDGE_VERSION = 6;
|
||||
|
||||
@@ -11,6 +11,7 @@ import {
|
||||
jsonValueSchema,
|
||||
type JsonValue,
|
||||
} from "../domain/jsonValue.js";
|
||||
import { nativeApiBoundarySchema } from "../domain/nativeApiBoundary.js";
|
||||
import { err, ok, type Result } from "../domain/result.js";
|
||||
import {
|
||||
ghidraBoundedIdentifierSchema,
|
||||
@@ -220,8 +221,40 @@ const procedureInfo = z
|
||||
})
|
||||
.strict();
|
||||
|
||||
const ghidraFunctionDossier = functionDossierSchema.superRefine(
|
||||
const ghidraNativeApiBoundary = nativeApiBoundarySchema.superRefine(
|
||||
(value, context) => {
|
||||
if (!value.available) return;
|
||||
if (value.provenance !== "ghidra-high-function")
|
||||
context.addIssue({
|
||||
code: "custom",
|
||||
message:
|
||||
"Ghidra native API observations require HighFunction provenance",
|
||||
});
|
||||
const addresses = value.jump_tables.flatMap((table) => [
|
||||
table.dispatch_address,
|
||||
...table.data_sources.map(({ address }) => address),
|
||||
...table.mappings.flatMap(({ target_address, data_addresses }) => [
|
||||
target_address,
|
||||
...data_addresses,
|
||||
]),
|
||||
]);
|
||||
if (
|
||||
addresses.some(
|
||||
(address) => !ghidraCanonicalAddressSchema.safeParse(address).success,
|
||||
)
|
||||
)
|
||||
context.addIssue({
|
||||
code: "custom",
|
||||
message:
|
||||
"Ghidra native API observation contains a non-canonical address",
|
||||
});
|
||||
},
|
||||
);
|
||||
|
||||
const ghidraFunctionDossier = functionDossierSchema
|
||||
.extend({ native_api: ghidraNativeApiBoundary })
|
||||
.strict()
|
||||
.superRefine((value, context) => {
|
||||
const addresses = [
|
||||
value.procedure.address,
|
||||
...value.comments.items.map(({ address }) => address),
|
||||
@@ -288,8 +321,7 @@ const ghidraFunctionDossier = functionDossierSchema.superRefine(
|
||||
code: "custom",
|
||||
message: "Ghidra dossier omitted required uncertainty limitations",
|
||||
});
|
||||
},
|
||||
);
|
||||
});
|
||||
const ghidraFunctionInstructionWindow = functionInstructionWindowSchema
|
||||
.extend({ procedure: procedureIdentity })
|
||||
.strict();
|
||||
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user