[PR #1568] [MERGED] feat(javascript): return a retained summary view on request #2977

New issue

Closed

opened 2026-10-17 21:12:28 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-17 21:12:28 +00:00

Owner

📋 Pull Request Information

Original PR: https://github.com/morluto/rea/pull/1568
Author: @kaoru0822-kitauji
Created: 10/10/2026
Status: ✅ Merged
Merged: 10/10/2026
Merged by: @kaoru0822-kitauji

Base: main ← Head: feat/analysis-summary-detail

📝 Commits (1)

98e4c40 feat(javascript): return a retained summary view on request

📊 Changes

9 files changed (+279 additions, -7 deletions)

View changed files

📝 .agents/skills/reverse-engineer-anything/SKILL.md (+3 -0)
📝 docs/javascript-artifact-reconstruction.md (+10 -0)
📝 docs/mcp-contracts.md (+7 -0)
📝 src/application/analysisView/AnalysisViewService.test.ts (+52 -2)
📝 src/application/analysisView/AnalysisViewService.ts (+43 -0)
📝 src/contracts/javascript/electronToolContracts.ts (+26 -3)
📝 src/server/createServer.ts (+1 -0)
📝 src/server/registerElectronTools.ts (+12 -2)
➕ tests/boundary/mcp/analysisSummaryDetailMcp.test.ts (+125 -0)

📄 Description

Problem

Follow-up to #1560, which reduced the per-turn tool-definition context. This PR covers the other half of the feedback, output size. analyze_javascript_application always returns the complete application graph inline. Measured over SDK 2.3.1 stdio:

Fixture	Complete reply text	`detail: "summary"` reply text
2 files, 3 functions (185 source bytes)	84,791 B	10,149 B
300-function single file (#1065 reproduction)	fails: `resource_constraint` (over the 10 MiB stdio budget)	10,177 B, and the next ping succeeds

The repo already has the right primitive: inspect_analysis_view reads summaries, module pages and items from retained Evidence. But agents only reach it after paying for (or failing on) the complete first reply.

Change

analyze_javascript_application gets an optional detail input:

complete (default): unchanged. The complete analysis Evidence is returned inline.
summary: the server records the complete analysis Evidence in the session, then returns the derived inspect_analysis_view summary Evidence (operation: "inspect_analysis_view"). Its normalized_result.parent_evidence_id and evidence_links name the retained analysis. Callers page modules, select items, or pass {"kind":"retained-evidence", ...} to the application workflows, without repeating the analysis.
A server that cannot retain Evidence (fixed-target embedders) refuses summary with capability_unavailable and advice to select detail complete. It never returns a summary whose analysis can't be reached.

Notes for review:

Output schema: normalized_result is now union(application analysis, analysis view). The root stays type: object, so there are no root combinators. Default responses are byte-identical to before. A consumer that statically types normalized_result as the analysis result should use operation / normalized_result.kind to tell them apart.
Layering: the summary logic is the application function summarizeRetainedAnalysis (src/application/analysisView/AnalysisViewService.ts). The MCP adapter only removes detail before analysis, so detail never enters the analysis Evidence.
CLI: unchanged and always complete. The CLI has no session retention, and its output goes to a file or pipe rather than model context. inspect-analysis-view already reads inline Evidence files.
Docs: docs/mcp-contracts.md, docs/javascript-artifact-reconstruction.md and the packaged skill (.agents/skills/...) describe when to use summary detail. The generated catalog and skill were regenerated.

Not in scope (possible follow-ups): the same option for analyze_function and inspect_binary_layout, which inspect_analysis_view also supports, and the text/structured duplication on the wire (#723).

Relates to #723, #1065.

Verification

npm run check:ci passes: typecheck, lint, format, knip, metadata, jscpd and architecture guards.
npm run docs:check passes.
npm run check:changed: 27 files, 280 tests.
npm run test:focused over all tests/boundary/mcp, tests/boundary/cli and tests/conformance files: 135 passed, 2 skipped (573 tests). Skill and setup tests pass.
New tests/boundary/mcp/analysisSummaryDetailMcp.test.ts (real fixture over the MCP client):
- the default reply is the complete analysis;
- summary returns the view, smaller than the complete reply, linked to the complete Evidence ID;
- a follow-up inspect_analysis_view module page on the retained parent works;
- a non-retaining server refuses with capability_unavailable.
New unit tests for summarizeRetainedAnalysis: it records before projecting, refuses without retention, and propagates a recording conflict.
Manual stdio run of the #1065 300-function reproduction (table above).

No real Hopper/Ghidra/IDA verification was performed (they are not affected). No real host-client lanes were run.

🤖 Generated with Claude Code

_{🔄 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/1568 **Author:** [@kaoru0822-kitauji](https://github.com/kaoru0822-kitauji) **Created:** 10/10/2026 **Status:** ✅ Merged **Merged:** 10/10/2026 **Merged by:** [@kaoru0822-kitauji](https://github.com/kaoru0822-kitauji) **Base:** `main` ← **Head:** `feat/analysis-summary-detail` --- ### 📝 Commits (1) - [`98e4c40`](https://github.com/morluto/rea/commit/98e4c40bfd58aa2af8c0326912f80d97e4681bcc) feat(javascript): return a retained summary view on request ### 📊 Changes **9 files changed** (+279 additions, -7 deletions) <details> <summary>View changed files</summary> 📝 `.agents/skills/reverse-engineer-anything/SKILL.md` (+3 -0) 📝 `docs/javascript-artifact-reconstruction.md` (+10 -0) 📝 `docs/mcp-contracts.md` (+7 -0) 📝 `src/application/analysisView/AnalysisViewService.test.ts` (+52 -2) 📝 `src/application/analysisView/AnalysisViewService.ts` (+43 -0) 📝 `src/contracts/javascript/electronToolContracts.ts` (+26 -3) 📝 `src/server/createServer.ts` (+1 -0) 📝 `src/server/registerElectronTools.ts` (+12 -2) ➕ `tests/boundary/mcp/analysisSummaryDetailMcp.test.ts` (+125 -0) </details> ### 📄 Description ## Problem Follow-up to #1560, which reduced the per-turn tool-definition context. This PR covers the other half of the feedback, **output** size. `analyze_javascript_application` always returns the complete application graph inline. Measured over SDK 2.3.1 stdio: | Fixture | Complete reply text | `detail: "summary"` reply text | | --- | ---: | ---: | | 2 files, 3 functions (185 source bytes) | 84,791 B | 10,149 B | | 300-function single file (#1065 reproduction) | **fails**: `resource_constraint` (over the 10 MiB stdio budget) | 10,177 B, and the next ping succeeds | The repo already has the right primitive: `inspect_analysis_view` reads summaries, module pages and items from retained Evidence. But agents only reach it after paying for (or failing on) the complete first reply. ## Change `analyze_javascript_application` gets an optional `detail` input: - `complete` (default): unchanged. The complete analysis Evidence is returned inline. - `summary`: the server records the complete analysis Evidence in the session, then returns the derived `inspect_analysis_view` summary Evidence (`operation: "inspect_analysis_view"`). Its `normalized_result.parent_evidence_id` and `evidence_links` name the retained analysis. Callers page modules, select items, or pass `{"kind":"retained-evidence", ...}` to the application workflows, without repeating the analysis. - A server that cannot retain Evidence (fixed-target embedders) refuses `summary` with `capability_unavailable` and advice to select `detail complete`. It never returns a summary whose analysis can't be reached. Notes for review: - **Output schema:** `normalized_result` is now `union(application analysis, analysis view)`. The root stays `type: object`, so there are no root combinators. Default responses are byte-identical to before. A consumer that statically types `normalized_result` as the analysis result should use `operation` / `normalized_result.kind` to tell them apart. - **Layering:** the summary logic is the application function `summarizeRetainedAnalysis` (`src/application/analysisView/AnalysisViewService.ts`). The MCP adapter only removes `detail` before analysis, so `detail` never enters the analysis Evidence. - **CLI:** unchanged and always complete. The CLI has no session retention, and its output goes to a file or pipe rather than model context. `inspect-analysis-view` already reads inline Evidence files. - **Docs:** `docs/mcp-contracts.md`, `docs/javascript-artifact-reconstruction.md` and the packaged skill (`.agents/skills/...`) describe when to use summary detail. The generated catalog and skill were regenerated. Not in scope (possible follow-ups): the same option for `analyze_function` and `inspect_binary_layout`, which `inspect_analysis_view` also supports, and the text/structured duplication on the wire (#723). Relates to #723, #1065. ## Verification - `npm run check:ci` passes: typecheck, lint, format, knip, metadata, jscpd and architecture guards. - `npm run docs:check` passes. - `npm run check:changed`: 27 files, 280 tests. - `npm run test:focused` over all `tests/boundary/mcp`, `tests/boundary/cli` and `tests/conformance` files: 135 passed, 2 skipped (573 tests). Skill and setup tests pass. - New `tests/boundary/mcp/analysisSummaryDetailMcp.test.ts` (real fixture over the MCP client): - the default reply is the complete analysis; - `summary` returns the view, smaller than the complete reply, linked to the complete Evidence ID; - a follow-up `inspect_analysis_view` module page on the retained parent works; - a non-retaining server refuses with `capability_unavailable`. - New unit tests for `summarizeRetainedAnalysis`: it records before projecting, refuses without retention, and propagates a recording conflict. - Manual stdio run of the #1065 300-function reproduction (table above). No real Hopper/Ghidra/IDA verification was performed (they are not affected). No real host-client lanes were run. 🤖 Generated with [Claude Code](https://claude.com/claude-code) --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

bsakaguchi

2026-10-17 21:12:28 +00:00