[PR #5660] [MERGED] feat(analysis)!: default function MCP output to retained summaries #7018

New issue

Closed

opened 2026-11-01 21:44:44 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-11-01 21:44:44 +00:00

Owner

📋 Pull Request Information

Original PR: https://github.com/morluto/rea/pull/5660
Author: @CryptoJones
Created: 10/20/2026
Status: ✅ Merged
Merged: 10/24/2026
Merged by: @gensokyo-dev

Base: main ← Head: perf/ghidra-analyze-function-pseudocode-default

📝 Commits (10+)

e067efd feat(ghidra): bound one procedure's decompile without closing the session
0f2a2e5 fix(ghidra): report decompile limit as a request timeout
cb754c9 fix(ghidra): budget the decompile limit and report cancellation-closed sessions
7bee52c feat(ghidra)!: default analyze_function to a retained summary
a7450d5 feat(cli): expose analyze_function detail on the function command
3595773 refactor(ghidra): harden analyze_function summary after independent review
c8fa938 test(ghidra): cover analyze_function detail wiring on both adapters
d7c9564 fix(ghidra): keep analyze_function delivery detail out of provider inputs
422c5b1 fix(ghidra): keep omitted function facets unknown in the summary
804ff3a fix(scripts): request complete analyze_function dossiers in real-provider checks

📊 Changes

68 files changed (+1678 additions, -206 deletions)

View changed files

📝 .agents/skills/reverse-engineer-anything/SKILL.md (+7 -1)
📝 .agents/skills/reverse-engineer-anything/references/evidence-workflows.md (+3 -1)
📝 .agents/skills/reverse-engineer-anything/references/native-and-artifacts.md (+7 -2)
📝 docs/cli.md (+10 -0)
📝 docs/ida-provider.md (+1 -1)
📝 docs/kuna-provider.md (+1 -1)
📝 docs/mcp-contracts.md (+22 -7)
📝 docs/native-function-matching.md (+7 -5)
➕ docs/verification/native-function-summary-2026-10-23.md (+149 -0)
📝 scripts/lib/ghidra-reference-snapshot-e2e.mjs (+1 -1)
📝 scripts/lib/native-value-e2e.mjs (+8 -2)
📝 scripts/lib/real-ghidra-address-boundaries.mjs (+5 -2)
📝 scripts/lib/real-ghidra-boundaries.mjs (+16 -6)
📝 scripts/lib/real-ghidra-entry-aliases.mjs (+2 -1)
📝 scripts/lib/real-ghidra-large-results.mjs (+3 -0)
📝 scripts/lib/real-ghidra-namespace-annotations.mjs (+6 -2)
📝 scripts/lib/real-ghidra-snapshot-lifecycle.mjs (+12 -5)
📝 scripts/lib/real-ghidra-target-admission.mjs (+5 -2)
📝 scripts/lib/real-hopper-boundaries.mjs (+8 -1)
📝 scripts/lib/real-hopper-cli-selectors.mjs (+2 -1)

...and 48 more files

📄 Description

Refs #5032.

MCP analyze_function always returned the full native dossier, so large reference/value-flow results could consume the response budget before the requested code was useful. It now defaults to detail: "summary": function identity, availability, facet counts, limitations and a retained parent Evidence ID. inspect_analysis_view pages that parent; detail: "complete" preserves the previous inline dossier. This default is a breaking MCP change. Delivery detail stays outside provider inputs and parent Evidence identity.

CLI rea function still defaults to complete output. Explicit summary delivery requires --evidence_output /absolute/path/dossier.json, writes an exclusive complete Evidence bundle and returns the summary. The saved bundle can be paged through an evidence-file source and selected evidence_id after the provider closes. For example, select the returned parent ID with a native pseudocode view (offset: 0, limit: 4096). Summary delivery requires retention and an artifact-bound parent.

The existing summary/view pipeline owns projection and provenance. Function addresses and relationship coverage survive; omitted or unavailable counts remain null. Bundle import and file projection share authentication rather than parallel parsers. Ambiguous-bundle guidance keeps complete IDs within a 2 KiB encoded preview, with explicit omissions. Canonical hashing avoids copying large emitted strings while preserving its byte stream.

Measured equivalent real Linux Ghidra MCP task (small-function pseudocode plus large-function availability/counts/20 assembly rows, then warm repeats and a matched complete-small read): selected facts match exactly, target digests stay unchanged and cleanup completes.

Whole benchmark	Before	After
Estimated SDK exchange tokens	44,217,047	1,033,322
Elapsed seconds	237.715	128.600
Waited family CPU seconds	211.656	123.083
Sampled family RSS MiB	3951.7	2827.8
Catalog/tool exchanges	8	12

The 97.66% token reduction includes all catalog/argument/SDK-result projections and extra page calls. These are tokenx estimates, not model usage; client rendering and prompts are unmeasured. Whole timings include counting and evidence writes; measured MCP phases total 217.33 → 127.54 s. One pair, baseline first, shared host, unflushed OS caches: no universal speed claim. The warm small task is about 6.7 ms slower despite a smaller answer. An earlier 240-second baseline timeout is retained separately and excluded from completed comparisons.

Validation:

Full npm run check, 139 focused contract/CLI/progress/snapshot/path tests, 15 actual SDK/schema checks and docs:check passed after integrating main a062529b. Initial stale generated-catalog and CLI harness-envelope failures are recorded in the report.
Real CLI default-complete output verified. Summary delivery writes a 29,141,012-byte bundle; independent CLI processes authenticate and page its first/final 20 assembly rows with Ghidra unavailable. Each fresh file-page command scans/authenticates the complete file (17.218 / 18.175 s), so sublinear disk access is not claimed.
CI run 40042416832 failed on independently established main baselines; all 12 failed/cancelled logs and 1,015 assertion markers were audited. Cancelled coverage remains unverified.
Real-provider scope is Linux Ghidra 12.1.4 / JDK 21. Hopper/IDA/Kuna, macOS and Windows were not newly runtime-verified. Existing complete-dossier verifiers explicitly request complete delivery.

Verification report pins source/artifact/harness identities, cold/warm phases, limits and incomplete controls.

Scope: existing read-only native analysis and caller-selected Evidence file output; no new provider, target execution/injection, executable mutation, attached-GUI authority or installation behavior.

Author readiness

Human owner: @CryptoJones

I reviewed the final diff and relevant existing code, understand the change and its edge cases, and take responsibility for the complete PR, including AI-assisted work.
I checked the evidence above, confirmed it supports the current change, and recorded meaningful validation gaps.
I declare this PR ready for initial maintainer review.

Before merge

This PR addresses a concrete problem or an agreed enhancement.
Material scope and authority questions are resolved, and any required maintainer scope decision covers the final diff.
The PR has one focused outcome and the title follows type(scope): outcome.
Related issue is linked, or the reason for not linking one is stated above.
Tests cover changed observable behavior and meaningful failure paths.
Owning docs, contracts, and generated metadata are updated where needed.
User-visible CLI/MCP changes include representative output.
I checked the final diff for secrets, unrelated cleanup, and unsupported claims.

🤖 Generated with Claude Code

https://claude.ai/code/session_01AoJZDPcrgmMsCqLG4LfiFb

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/morluto/rea/pull/5660 **Author:** [@CryptoJones](https://github.com/CryptoJones) **Created:** 10/20/2026 **Status:** ✅ Merged **Merged:** 10/24/2026 **Merged by:** [@gensokyo-dev](https://github.com/gensokyo-dev) **Base:** `main` ← **Head:** `perf/ghidra-analyze-function-pseudocode-default` --- ### 📝 Commits (10+) - [`e067efd`](https://github.com/morluto/rea/commit/e067efd6ed979285abebc7805cfc9341d84af094) feat(ghidra): bound one procedure's decompile without closing the session - [`0f2a2e5`](https://github.com/morluto/rea/commit/0f2a2e5e633908b7cb18f86fa0e1c0af4a060827) fix(ghidra): report decompile limit as a request timeout - [`cb754c9`](https://github.com/morluto/rea/commit/cb754c9258de3bd6a2c9da1bf71da63085a49288) fix(ghidra): budget the decompile limit and report cancellation-closed sessions - [`7bee52c`](https://github.com/morluto/rea/commit/7bee52c98a4d02dafe7309d49bff3ff93418ecf1) feat(ghidra)!: default analyze_function to a retained summary - [`a7450d5`](https://github.com/morluto/rea/commit/a7450d50fd9ad4c9c4f842899692b6f8532230b6) feat(cli): expose analyze_function detail on the function command - [`3595773`](https://github.com/morluto/rea/commit/35957735d1882e6c56404487d6ac9c49d682e5f3) refactor(ghidra): harden analyze_function summary after independent review - [`c8fa938`](https://github.com/morluto/rea/commit/c8fa938246a8face6d2db7c5d17aed19c65bd6e2) test(ghidra): cover analyze_function detail wiring on both adapters - [`d7c9564`](https://github.com/morluto/rea/commit/d7c95641edad4525bab779fadfb9fe93e1551dc0) fix(ghidra): keep analyze_function delivery detail out of provider inputs - [`422c5b1`](https://github.com/morluto/rea/commit/422c5b1ad005d0210ef6b05a504009368a36693e) fix(ghidra): keep omitted function facets unknown in the summary - [`804ff3a`](https://github.com/morluto/rea/commit/804ff3a234d128aa56b0ca50e1d4428ca46fe7fc) fix(scripts): request complete analyze_function dossiers in real-provider checks ### 📊 Changes **68 files changed** (+1678 additions, -206 deletions) <details> <summary>View changed files</summary> 📝 `.agents/skills/reverse-engineer-anything/SKILL.md` (+7 -1) 📝 `.agents/skills/reverse-engineer-anything/references/evidence-workflows.md` (+3 -1) 📝 `.agents/skills/reverse-engineer-anything/references/native-and-artifacts.md` (+7 -2) 📝 `docs/cli.md` (+10 -0) 📝 `docs/ida-provider.md` (+1 -1) 📝 `docs/kuna-provider.md` (+1 -1) 📝 `docs/mcp-contracts.md` (+22 -7) 📝 `docs/native-function-matching.md` (+7 -5) ➕ `docs/verification/native-function-summary-2026-10-23.md` (+149 -0) 📝 `scripts/lib/ghidra-reference-snapshot-e2e.mjs` (+1 -1) 📝 `scripts/lib/native-value-e2e.mjs` (+8 -2) 📝 `scripts/lib/real-ghidra-address-boundaries.mjs` (+5 -2) 📝 `scripts/lib/real-ghidra-boundaries.mjs` (+16 -6) 📝 `scripts/lib/real-ghidra-entry-aliases.mjs` (+2 -1) 📝 `scripts/lib/real-ghidra-large-results.mjs` (+3 -0) 📝 `scripts/lib/real-ghidra-namespace-annotations.mjs` (+6 -2) 📝 `scripts/lib/real-ghidra-snapshot-lifecycle.mjs` (+12 -5) 📝 `scripts/lib/real-ghidra-target-admission.mjs` (+5 -2) 📝 `scripts/lib/real-hopper-boundaries.mjs` (+8 -1) 📝 `scripts/lib/real-hopper-cli-selectors.mjs` (+2 -1) _...and 48 more files_ </details> ### 📄 Description Refs #5032. MCP `analyze_function` always returned the full native dossier, so large reference/value-flow results could consume the response budget before the requested code was useful. It now defaults to `detail: "summary"`: function identity, availability, facet counts, limitations and a retained parent Evidence ID. `inspect_analysis_view` pages that parent; `detail: "complete"` preserves the previous inline dossier. This default is a **breaking MCP change**. Delivery detail stays outside provider inputs and parent Evidence identity. CLI `rea function` still defaults to complete output. Explicit summary delivery requires `--evidence_output /absolute/path/dossier.json`, writes an exclusive complete Evidence bundle and returns the summary. The saved bundle can be paged through an `evidence-file` source and selected `evidence_id` after the provider closes. For example, select the returned parent ID with a native `pseudocode` view (`offset: 0`, `limit: 4096`). Summary delivery requires retention and an artifact-bound parent. The existing summary/view pipeline owns projection and provenance. Function addresses and relationship coverage survive; omitted or unavailable counts remain `null`. Bundle import and file projection share authentication rather than parallel parsers. Ambiguous-bundle guidance keeps complete IDs within a 2 KiB encoded preview, with explicit omissions. Canonical hashing avoids copying large emitted strings while preserving its byte stream. Measured equivalent real Linux Ghidra MCP task (small-function pseudocode plus large-function availability/counts/20 assembly rows, then warm repeats and a matched complete-small read): selected facts match exactly, target digests stay unchanged and cleanup completes. | Whole benchmark | Before | After | | --- | ---: | ---: | | Estimated SDK exchange tokens | 44,217,047 | 1,033,322 | | Elapsed seconds | 237.715 | 128.600 | | Waited family CPU seconds | 211.656 | 123.083 | | Sampled family RSS MiB | 3951.7 | 2827.8 | | Catalog/tool exchanges | 8 | 12 | The 97.66% token reduction includes all catalog/argument/SDK-result projections and extra page calls. These are `tokenx` estimates, not model usage; client rendering and prompts are unmeasured. Whole timings include counting and evidence writes; measured MCP phases total 217.33 → 127.54 s. One pair, baseline first, shared host, unflushed OS caches: no universal speed claim. The warm small task is about 6.7 ms slower despite a smaller answer. An earlier 240-second baseline timeout is retained separately and excluded from completed comparisons. Validation: - Full `npm run check`, **139** focused contract/CLI/progress/snapshot/path tests, **15** actual SDK/schema checks and `docs:check` passed after integrating main `a062529b`. Initial stale generated-catalog and CLI harness-envelope failures are recorded in the report. - Real CLI default-complete output verified. Summary delivery writes a 29,141,012-byte bundle; independent CLI processes authenticate and page its first/final 20 assembly rows with Ghidra unavailable. Each fresh file-page command scans/authenticates the complete file (17.218 / 18.175 s), so sublinear disk access is not claimed. - CI run 40042416832 failed on independently established main baselines; all 12 failed/cancelled logs and 1,015 assertion markers were audited. Cancelled coverage remains unverified. - Real-provider scope is Linux Ghidra 12.1.4 / JDK 21. Hopper/IDA/Kuna, macOS and Windows were not newly runtime-verified. Existing complete-dossier verifiers explicitly request complete delivery. [Verification report](https://github.com/CryptoJones/rea/blob/c6cbd2d985d09118b8bd8ee76131ff744649ea2a/docs/verification/native-function-summary-2026-10-23.md) pins source/artifact/harness identities, cold/warm phases, limits and incomplete controls. Scope: existing read-only native analysis and caller-selected Evidence file output; no new provider, target execution/injection, executable mutation, attached-GUI authority or installation behavior. ## Author readiness Human owner: @CryptoJones - [x] I reviewed the final diff and relevant existing code, understand the change and its edge cases, and take responsibility for the complete PR, including AI-assisted work. - [x] I checked the evidence above, confirmed it supports the current change, and recorded meaningful validation gaps. - [x] I declare this PR ready for initial maintainer review. ## Before merge - [x] This PR addresses a concrete problem or an agreed enhancement. - [x] Material scope and authority questions are resolved, and any required maintainer scope decision covers the final diff. - [x] The PR has one focused outcome and the title follows `type(scope): outcome`. - [x] Related issue is linked, or the reason for not linking one is stated above. - [x] Tests cover changed observable behavior and meaningful failure paths. - [x] Owning docs, contracts, and generated metadata are updated where needed. - [x] User-visible CLI/MCP changes include representative output. - [x] I checked the final diff for secrets, unrelated cleanup, and unsupported claims. 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_01AoJZDPcrgmMsCqLG4LfiFb --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

bsakaguchi

2026-11-01 21:44:44 +00:00