[PR #1910] [MERGED] fix(mcp): provide native evidence paging continuation #4902

Closed
opened 2026-10-31 00:56:36 +00:00 by bsakaguchi · 0 comments
Owner

📋 Pull Request Information

Original PR: https://github.com/morluto/rea/pull/1910
Author: @cold-atom
Created: 10/11/2026
Status: ✅ Merged
Merged: 10/11/2026
Merged by: @N0zoM1z0

Base: main ← Head: fix/1849-native-evidence-continuation


📝 Commits (5)

  • 830eee2 fix(mcp): provide native evidence paging continuation
  • d150890 Merge remote-tracking branch 'upstream/main' into fix/1849-native-evidence-continuation
  • 79bd300 test(mcp): exercise native continuation through the transport
  • 9281746 chore: merge upstream main and resolve audit wording conflict
  • d0aedf6 test(mcp): bind native continuation size to the transport budget

📊 Changes

3 files changed (+138 additions, -8 deletions)

View changed files

📝 docs/mcp-contracts.md (+12 -2)
📝 src/server/toolResult.ts (+35 -6)
📝 tests/boundary/mcp/analysisViewMcp.test.ts (+91 -0)

📄 Description

Summary

Give callers a ready-to-call pseudocode page when completed native function Evidence exceeds MCP delivery capacity. Preserve the complete canonical record and only offer continuation after session recording is acknowledged.

Fixes #1849.

Problem and expected behavior

An oversized analyze_function result already retains useful Evidence, but generic export advice leaves callers to reconstruct the supported view request. The error should supply exact arguments for the existing bounded source view, without silently replacing or truncating the requested full result.

Change and scope

Attach a named, schema-validated inspect_analysis_view continuation to the completed-result transport error. Start at offset zero with the existing 64-unit default, then follow coverage.next_offset. Keep export advice and explain that arbitrary source or metadata can still require a smaller limit or export. The follow-up regression checks the pinned SDK receive-buffer bound rather than a fixed 12,000-byte envelope; preserved caller paths make envelope size depend on the local directory.

Contract and boundary impact

  • Semantic owner and earliest changed stage: MCP result delivery, after explicit Evidence recording acknowledgment.
  • CLI and MCP/tool-catalog contract: additive details.reported_limits.continuation and actionable remediation; reuse the existing named input contract. CLI behavior and advertised operation schemas are unchanged.
  • Provider, bridge, target-format, or platform compatibility: native function results from existing providers; no engine, import or bridge changes.
  • Evidence, artifact, provenance, or reconstruction contract: preserve full canonical result, exact procedure parameters, target digest and retained reference. No new recording claim for unacknowledged or failed retention.
  • Process execution, authorization, cleanup, or containment impact: no expanded authority or process changes; view retrieval does not invoke the provider again.
  • Generated metadata (docs/public/product-catalog.json), package, or installation impact: owning MCP documentation updated; no dependency, installer or authored catalog-schema change.

Evidence and regression coverage

  • Tests added or updated: obtain a completed-result transport failure through the registered Ghidra adapter and MCP client, use its continuation directly, retrieve exact first/second source slices, preserve complete parent Evidence, and ping successfully. Existing delivery, unacknowledged retention, failed retention and oversized-view regressions retained.
  • Base reproduction or other evidence: the parent implementation only supplies the retained reference and generic export guidance. Review of head 92817465f also reproduced a path-dependent assertion: a correct 64-unit page serialized to 12,017 bytes, exceeding an arbitrary 12,000-byte test threshold. Follow-up d0aedf63e uses the actual protocol bound.
  • User-visible CLI/MCP output: reported_limits.continuation.name is inspect_analysis_view; its arguments contain the reported retained reference and {kind: "native", facet: "pseudocode", offset: 0, limit: 64}. The next page uses the returned offset.
  • Remaining proof gaps: paging improves delivery and continuation, not native analysis cost or general directory projection. Real Hopper/IDA and local Windows/macOS provider runs were not performed. Simulated Ghidra results establish transport semantics, not engine correctness.

For evidence-bearing changes:

  • Observed, derived, and inferred claims remain distinguishable.
  • Artifact identity, source provenance, and failed attempts remain preserved.
  • Unsupported, incomplete, unavailable, or uncertain outcomes remain visible.

Validation performed

  • npm run test:focused -- tests/boundary/mcp/analysisViewMcp.test.ts tests/boundary/mcp/toolResult.test.ts src/server/toolResultEncoding.test.ts — 28 passed across 3 files, including the follow-up on an isolated long-path worktree.
  • npm run check — passed, including typecheck, lint, formatting, metadata/unused-code checks and architecture guards.
  • npm run docs:check — passed.
  • Fresh stdio MCP with real Ghidra 12.1.4, unchanged stripped x86-64 ELF and procedure 0x41bf30: full result exceeded the 10,485,760-byte receive buffer (at least 10,512,118 bytes). Used the supplied continuation directly: first/second responses each 28,863 bytes, exact 64-unit source slices, next offsets 64/128. Export verified the complete 39,225 UTF-16-unit pseudocode and original selected procedure/digest. Ping, explicit close and unchanged target bytes passed.
  • The real-provider workflow completed in 275.20 s, including startup, export and close, under one CPU, 768-MiB Java heap and a 3-GiB scope. Peak memory 1,268,264,960 bytes; all scope OOM/max events zero.

Compatibility, safety, and release

  • Breaking changes or migration steps: none; complete-result requests retain their contract and transport guard. A continuation is an optional recovery request, not an automatic fallback or completeness guarantee.
  • Real Hopper/Ghidra, browser, or OS coverage: real Linux Ghidra through stdio MCP verified above; remaining local provider/platform scope explicitly unverified.
  • Package or release metadata impact: no dependency/version edits; owning delivery documentation updated.
  • Security, privacy, process, or containment review: no source execution, executable mutation, GUI control, native database save or added installation. Canonical provenance and caller-selected inputs remain intact; local artifacts and verification files are not committed.

Review checklist

  • This PR addresses a concrete problem or an agreed enhancement.
  • 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.

🔄 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/1910 **Author:** [@cold-atom](https://github.com/cold-atom) **Created:** 10/11/2026 **Status:** ✅ Merged **Merged:** 10/11/2026 **Merged by:** [@N0zoM1z0](https://github.com/N0zoM1z0) **Base:** `main` ← **Head:** `fix/1849-native-evidence-continuation` --- ### 📝 Commits (5) - [`830eee2`](https://github.com/morluto/rea/commit/830eee209e00b0fb7db77897fb27ca5d4a26742a) fix(mcp): provide native evidence paging continuation - [`d150890`](https://github.com/morluto/rea/commit/d150890129affe602e1a819317e1ba8e78429bd8) Merge remote-tracking branch 'upstream/main' into fix/1849-native-evidence-continuation - [`79bd300`](https://github.com/morluto/rea/commit/79bd3007fa064a6efac099765a8aee7d35338594) test(mcp): exercise native continuation through the transport - [`9281746`](https://github.com/morluto/rea/commit/92817465f3302ea91119c851b0db7d89b2e4b6e9) chore: merge upstream main and resolve audit wording conflict - [`d0aedf6`](https://github.com/morluto/rea/commit/d0aedf63e8af2bed9c6f3d5ee60093b011887713) test(mcp): bind native continuation size to the transport budget ### 📊 Changes **3 files changed** (+138 additions, -8 deletions) <details> <summary>View changed files</summary> 📝 `docs/mcp-contracts.md` (+12 -2) 📝 `src/server/toolResult.ts` (+35 -6) 📝 `tests/boundary/mcp/analysisViewMcp.test.ts` (+91 -0) </details> ### 📄 Description ## Summary Give callers a ready-to-call pseudocode page when completed native function Evidence exceeds MCP delivery capacity. Preserve the complete canonical record and only offer continuation after session recording is acknowledged. Fixes #1849. ## Problem and expected behavior An oversized `analyze_function` result already retains useful Evidence, but generic export advice leaves callers to reconstruct the supported view request. The error should supply exact arguments for the existing bounded source view, without silently replacing or truncating the requested full result. ## Change and scope Attach a named, schema-validated `inspect_analysis_view` continuation to the completed-result transport error. Start at offset zero with the existing 64-unit default, then follow `coverage.next_offset`. Keep export advice and explain that arbitrary source or metadata can still require a smaller limit or export. The follow-up regression checks the pinned SDK receive-buffer bound rather than a fixed 12,000-byte envelope; preserved caller paths make envelope size depend on the local directory. ## Contract and boundary impact - Semantic owner and earliest changed stage: MCP result delivery, after explicit Evidence recording acknowledgment. - CLI and MCP/tool-catalog contract: additive `details.reported_limits.continuation` and actionable remediation; reuse the existing named input contract. CLI behavior and advertised operation schemas are unchanged. - Provider, bridge, target-format, or platform compatibility: native function results from existing providers; no engine, import or bridge changes. - Evidence, artifact, provenance, or reconstruction contract: preserve full canonical result, exact procedure parameters, target digest and retained reference. No new recording claim for unacknowledged or failed retention. - Process execution, authorization, cleanup, or containment impact: no expanded authority or process changes; view retrieval does not invoke the provider again. - Generated metadata (`docs/public/product-catalog.json`), package, or installation impact: owning MCP documentation updated; no dependency, installer or authored catalog-schema change. ## Evidence and regression coverage - Tests added or updated: obtain a completed-result transport failure through the registered Ghidra adapter and MCP client, use its continuation directly, retrieve exact first/second source slices, preserve complete parent Evidence, and ping successfully. Existing delivery, unacknowledged retention, failed retention and oversized-view regressions retained. - Base reproduction or other evidence: the parent implementation only supplies the retained reference and generic export guidance. Review of head `92817465f` also reproduced a path-dependent assertion: a correct 64-unit page serialized to 12,017 bytes, exceeding an arbitrary 12,000-byte test threshold. Follow-up `d0aedf63e` uses the actual protocol bound. - User-visible CLI/MCP output: `reported_limits.continuation.name` is `inspect_analysis_view`; its arguments contain the reported retained reference and `{kind: "native", facet: "pseudocode", offset: 0, limit: 64}`. The next page uses the returned offset. - Remaining proof gaps: paging improves delivery and continuation, not native analysis cost or general directory projection. Real Hopper/IDA and local Windows/macOS provider runs were not performed. Simulated Ghidra results establish transport semantics, not engine correctness. For evidence-bearing changes: - [x] Observed, derived, and inferred claims remain distinguishable. - [x] Artifact identity, source provenance, and failed attempts remain preserved. - [x] Unsupported, incomplete, unavailable, or uncertain outcomes remain visible. ## Validation performed - `npm run test:focused -- tests/boundary/mcp/analysisViewMcp.test.ts tests/boundary/mcp/toolResult.test.ts src/server/toolResultEncoding.test.ts` — **28 passed across 3 files**, including the follow-up on an isolated long-path worktree. - `npm run check` — passed, including typecheck, lint, formatting, metadata/unused-code checks and architecture guards. - `npm run docs:check` — passed. - Fresh stdio MCP with real **Ghidra 12.1.4**, unchanged stripped x86-64 ELF and procedure `0x41bf30`: full result exceeded the 10,485,760-byte receive buffer (at least **10,512,118 bytes**). Used the supplied continuation directly: first/second responses each **28,863 bytes**, exact 64-unit source slices, next offsets **64/128**. Export verified the complete **39,225 UTF-16-unit** pseudocode and original selected procedure/digest. Ping, explicit close and unchanged target bytes passed. - The real-provider workflow completed in **275.20 s**, including startup, export and close, under one CPU, 768-MiB Java heap and a 3-GiB scope. Peak memory **1,268,264,960 bytes**; all scope OOM/max events zero. ## Compatibility, safety, and release - Breaking changes or migration steps: none; complete-result requests retain their contract and transport guard. A continuation is an optional recovery request, not an automatic fallback or completeness guarantee. - Real Hopper/Ghidra, browser, or OS coverage: real Linux Ghidra through stdio MCP verified above; remaining local provider/platform scope explicitly unverified. - Package or release metadata impact: no dependency/version edits; owning delivery documentation updated. - Security, privacy, process, or containment review: no source execution, executable mutation, GUI control, native database save or added installation. Canonical provenance and caller-selected inputs remain intact; local artifacts and verification files are not committed. ## Review checklist - [x] This PR addresses a concrete problem or an agreed enhancement. - [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. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>
bsakaguchi 2026-10-31 00:56:36 +00:00
Sign in to join this conversation.
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
morluto/rea#4902
No description provided.