[PR #456] [MERGED] feat!: make evidence bundles canonical MCP resources #2003

Closed
opened 2026-10-16 21:13:15 +00:00 by bsakaguchi · 0 comments
Owner

📋 Pull Request Information

Original PR: https://github.com/morluto/rea/pull/456
Author: @morluto
Created: 7/29/2026
Status: ✅ Merged
Merged: 7/29/2026
Merged by: @morluto

Base: main ← Head: agent/mcp-resource-snapshots-context-tools


📝 Commits (8)

  • 1712e6d feat!: make evidence bundles canonical MCP resources
  • ba098f2 test(eval): cover navigation and address tool routing
  • 2a45d8d docs: document resource snapshot workflow
  • 17d7dbc build: upgrade MCP SDK to 2.0.0
  • c824db1 docs: refresh generated SDK metadata
  • ab4193c test: derive MCP SDK identity expectations
  • f3b3fb0 fix: address MCP resource review feedback
  • ede91ff fix: align aggregate tools with session capabilities

📊 Changes

47 files changed (+1311 additions, -392 deletions)

View changed files

📝 README.md (+1 -1)
📝 README_ar.md (+1 -1)
📝 README_ja.md (+1 -1)
📝 README_ko.md (+1 -1)
📝 README_zh.md (+1 -1)
📝 docs/mcp-contracts.md (+21 -5)
📝 docs/product-catalog.json (+13 -10)
📝 docs/verification/managed-conformance-manifest.json (+2 -2)
📝 package-lock.json (+13 -13)
📝 package.json (+2 -2)
📝 scripts/verify-agent-experience.mjs (+55 -34)
📝 skills/reverse-engineer-anything/SKILL.md (+2 -2)
➕ src/application/AnalysisContextQueries.ts (+212 -0)
📝 src/application/BinarySession.ts (+1 -0)
📝 src/application/BinarySessionPort.ts (+13 -0)
📝 src/application/BinarySessionRecords.ts (+93 -9)
📝 src/application/CapabilityInventory.ts (+20 -0)
📝 src/catalogIdentity.ts (+3 -3)
📝 src/contracts/promptContracts.ts (+12 -12)
📝 src/contracts/toolContractExamples.ts (+2 -0)

...and 27 more files

📄 Description

Description

Make durable Evidence v2 bundles canonical MCP resources while keeping query, mutation, and volatile provider state in tools.

This change adds snapshot_evidence_bundle, which retains an immutable, content-addressed session bundle at rea://evidence-bundle/{digest}. Retention is idempotent and bounded to 16 distinct digests and 64 MiB without eviction. export_evidence_bundle is now file-only and requires path.

Resource discovery is bounded: exhaustive Evidence, unknown, workspace, coverage, and reconstructed-resource listings/completions are removed. list_unknowns now returns deterministic pages with exact item URIs and bounded ResourceLink blocks. Every tool result containing a resource link includes ordinary instructions to copy the opaque URI unchanged and call MCP resources/read.

The native analysis cache is exposed through the fixed mutable rea://snapshot/current resource with typed available/unavailable states and update notifications. Provider-neutral get_navigation_context and inspect_address_context tools compose the existing scalar operations; the scalar tools remain available for compatibility and evaluation.

The MCP client and server packages are upgraded from 2.0.0-beta.4 to stable 2.0.0. The stable SDK owns era-aware cache metadata: 2026-07-28 cacheable responses receive the conservative defaults ttlMs: 0 and cacheScope: "private", while legacy responses remain unchanged. REA does not duplicate that protocol projection in resource callbacks.

This remains a draft because the repository requests prior alignment for large contract changes and no related issue was found. Successful aggregate-versus-scalar model evaluation still needs an active native provider fixture.

Type of Change

  • Bug fix
  • New feature
  • Documentation update
  • Performance improvement
  • Refactoring (no functional change)
  • Tool contract change (MCP schema modification)

Testing Performed

  • Unit tests added or updated
  • TypeScript typecheck passes (npm run typecheck)
  • Linting passes (npm run lint)
  • Full test suite passes (npm test)
  • Real Hopper verification performed (npm run verify:hopper)
  • Linux real Hopper verification performed (npm run verify:hopper:linux) or unavailability explained
  • Real browser verification performed (npm run verify:browser) or unavailability explained
  • Package verification performed (npm run verify:package)

Executed on the final tree:

  • npx vitest run tests/analysisContextQueries.test.ts tests/evidenceResources.test.ts tests/sessionMcp.test.ts tests/toolContracts.test.ts tests/contractSnapshot.test.ts — 19 tests passed.
  • npx vitest run tests/processCaptureElicitation.test.ts tests/codexAgentEval.test.ts — 16 tests passed, including the pinned 2026-07-28 stdio client/server flow.
  • npm run typecheck — passed.
  • npm run metadata:check — passed.
  • npm run format:check — passed.
  • Pre-push npm run check:fast — typecheck and lint passed; lint reported warnings but no errors.
  • Five Codex routing trials — aggregate tool selected first in 1/5 trials (navigation 1/3, address 0/2), with zero repeated calls, validation failures, or wrong-server routing. Four trials selected binary_session and stopped because no native target was open. These trials cover unavailable-state discovery only and do not support scalar removal.

Earlier broader validation on the implementation tree completed npm run check:ci and npm run verify:package. Real npm run verify:hopper reached the verifier but failed because binary_overview was disabled in the available Hopper environment. Those runs predate the final aggregate argument, subscription-capability, and stable-SDK changes, so they are not marked as final-tree checks above.

Tool Contract Impact

  • Adds snapshot_evidence_bundle({}).
  • Breaking: export_evidence_bundle now requires path and no longer returns an inline bundle.
  • Adds get_navigation_context({ document? }).
  • Adds inspect_address_context({ address, document? }).
  • Changes list_unknowns to a bounded page envelope with offset, limit, and exact item URIs.
  • Removes rea://unknowns/active and digest-addressed analysis snapshot resources.
  • Adds rea://evidence-bundle/{bundleDigest} and fixed rea://snapshot/current resources.
  • Retains all scalar navigation/address getters pending successful comparative evaluation.
  • Upgrades @modelcontextprotocol/client, @modelcontextprotocol/server, and their resolved core dependency to stable 2.0.0.

Compatibility and review guidance

This requires the repository's breaking-version treatment. Filesystem export remains the durable cross-session path; retained bundle resources live only for the MCP session. Stable MCP SDK 2.0.0 supplies required modern cache fields at its era-aware encoding seam and omits them for legacy clients.

Suggested review order:

  1. BinarySessionRecords and Evidence resource registration for retention, limits, and read-only resource behavior.
  2. Tool contracts and registerSessionRecordTools for the breaking export and unknown pagination.
  3. AnalysisContextQueries and snapshot notification wiring.
  4. MCP/contract tests, stable SDK dependency update, then generated catalog and documentation.

Known gaps before merge:

  • Run successful native-provider navigation/address trials against both aggregate and scalar paths.
  • Run the final full/package/real-provider validation gates after any remaining changes.

No directly related issue was found.


🔄 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/456 **Author:** [@morluto](https://github.com/morluto) **Created:** 7/29/2026 **Status:** ✅ Merged **Merged:** 7/29/2026 **Merged by:** [@morluto](https://github.com/morluto) **Base:** `main` ← **Head:** `agent/mcp-resource-snapshots-context-tools` --- ### 📝 Commits (8) - [`1712e6d`](https://github.com/morluto/rea/commit/1712e6d821965ce5edc3880fe4ebab2e3cc02fd4) feat!: make evidence bundles canonical MCP resources - [`ba098f2`](https://github.com/morluto/rea/commit/ba098f24e59efbd567ae8438f65e31af0f0b8050) test(eval): cover navigation and address tool routing - [`2a45d8d`](https://github.com/morluto/rea/commit/2a45d8de7d52d0a234672d03c7dae794859f8ced) docs: document resource snapshot workflow - [`17d7dbc`](https://github.com/morluto/rea/commit/17d7dbc461cd61d6416acd5ded42b8908f079cfc) build: upgrade MCP SDK to 2.0.0 - [`c824db1`](https://github.com/morluto/rea/commit/c824db1ab7aed2886e9050c1b7fe2136b77e3698) docs: refresh generated SDK metadata - [`ab4193c`](https://github.com/morluto/rea/commit/ab4193c1f48020ff6baa42cb75e033110ee72b36) test: derive MCP SDK identity expectations - [`f3b3fb0`](https://github.com/morluto/rea/commit/f3b3fb07ded3d1ad72c0a4f24ca3147ef9722c5d) fix: address MCP resource review feedback - [`ede91ff`](https://github.com/morluto/rea/commit/ede91ff1f04563001f695ec3869daeb3c826154a) fix: align aggregate tools with session capabilities ### 📊 Changes **47 files changed** (+1311 additions, -392 deletions) <details> <summary>View changed files</summary> 📝 `README.md` (+1 -1) 📝 `README_ar.md` (+1 -1) 📝 `README_ja.md` (+1 -1) 📝 `README_ko.md` (+1 -1) 📝 `README_zh.md` (+1 -1) 📝 `docs/mcp-contracts.md` (+21 -5) 📝 `docs/product-catalog.json` (+13 -10) 📝 `docs/verification/managed-conformance-manifest.json` (+2 -2) 📝 `package-lock.json` (+13 -13) 📝 `package.json` (+2 -2) 📝 `scripts/verify-agent-experience.mjs` (+55 -34) 📝 `skills/reverse-engineer-anything/SKILL.md` (+2 -2) ➕ `src/application/AnalysisContextQueries.ts` (+212 -0) 📝 `src/application/BinarySession.ts` (+1 -0) 📝 `src/application/BinarySessionPort.ts` (+13 -0) 📝 `src/application/BinarySessionRecords.ts` (+93 -9) 📝 `src/application/CapabilityInventory.ts` (+20 -0) 📝 `src/catalogIdentity.ts` (+3 -3) 📝 `src/contracts/promptContracts.ts` (+12 -12) 📝 `src/contracts/toolContractExamples.ts` (+2 -0) _...and 27 more files_ </details> ### 📄 Description ## Description Make durable Evidence v2 bundles canonical MCP resources while keeping query, mutation, and volatile provider state in tools. This change adds `snapshot_evidence_bundle`, which retains an immutable, content-addressed session bundle at `rea://evidence-bundle/{digest}`. Retention is idempotent and bounded to 16 distinct digests and 64 MiB without eviction. `export_evidence_bundle` is now file-only and requires `path`. Resource discovery is bounded: exhaustive Evidence, unknown, workspace, coverage, and reconstructed-resource listings/completions are removed. `list_unknowns` now returns deterministic pages with exact item URIs and bounded `ResourceLink` blocks. Every tool result containing a resource link includes ordinary instructions to copy the opaque URI unchanged and call MCP `resources/read`. The native analysis cache is exposed through the fixed mutable `rea://snapshot/current` resource with typed available/unavailable states and update notifications. Provider-neutral `get_navigation_context` and `inspect_address_context` tools compose the existing scalar operations; the scalar tools remain available for compatibility and evaluation. The MCP client and server packages are upgraded from `2.0.0-beta.4` to stable `2.0.0`. The stable SDK owns era-aware cache metadata: 2026-07-28 cacheable responses receive the conservative defaults `ttlMs: 0` and `cacheScope: "private"`, while legacy responses remain unchanged. REA does not duplicate that protocol projection in resource callbacks. This remains a draft because the repository requests prior alignment for large contract changes and no related issue was found. Successful aggregate-versus-scalar model evaluation still needs an active native provider fixture. ## Type of Change - [ ] Bug fix - [x] New feature - [x] Documentation update - [ ] Performance improvement - [ ] Refactoring (no functional change) - [x] Tool contract change (MCP schema modification) ## Testing Performed - [x] Unit tests added or updated - [x] TypeScript typecheck passes (`npm run typecheck`) - [x] Linting passes (`npm run lint`) - [ ] Full test suite passes (`npm test`) - [ ] Real Hopper verification performed (`npm run verify:hopper`) - [ ] Linux real Hopper verification performed (`npm run verify:hopper:linux`) or unavailability explained - [ ] Real browser verification performed (`npm run verify:browser`) or unavailability explained - [ ] Package verification performed (`npm run verify:package`) Executed on the final tree: - `npx vitest run tests/analysisContextQueries.test.ts tests/evidenceResources.test.ts tests/sessionMcp.test.ts tests/toolContracts.test.ts tests/contractSnapshot.test.ts` — 19 tests passed. - `npx vitest run tests/processCaptureElicitation.test.ts tests/codexAgentEval.test.ts` — 16 tests passed, including the pinned 2026-07-28 stdio client/server flow. - `npm run typecheck` — passed. - `npm run metadata:check` — passed. - `npm run format:check` — passed. - Pre-push `npm run check:fast` — typecheck and lint passed; lint reported warnings but no errors. - Five Codex routing trials — aggregate tool selected first in 1/5 trials (navigation 1/3, address 0/2), with zero repeated calls, validation failures, or wrong-server routing. Four trials selected `binary_session` and stopped because no native target was open. These trials cover unavailable-state discovery only and do not support scalar removal. Earlier broader validation on the implementation tree completed `npm run check:ci` and `npm run verify:package`. Real `npm run verify:hopper` reached the verifier but failed because `binary_overview` was disabled in the available Hopper environment. Those runs predate the final aggregate argument, subscription-capability, and stable-SDK changes, so they are not marked as final-tree checks above. ## Tool Contract Impact - Adds `snapshot_evidence_bundle({})`. - Breaking: `export_evidence_bundle` now requires `path` and no longer returns an inline bundle. - Adds `get_navigation_context({ document? })`. - Adds `inspect_address_context({ address, document? })`. - Changes `list_unknowns` to a bounded page envelope with `offset`, `limit`, and exact item URIs. - Removes `rea://unknowns/active` and digest-addressed analysis snapshot resources. - Adds `rea://evidence-bundle/{bundleDigest}` and fixed `rea://snapshot/current` resources. - Retains all scalar navigation/address getters pending successful comparative evaluation. - Upgrades `@modelcontextprotocol/client`, `@modelcontextprotocol/server`, and their resolved core dependency to stable 2.0.0. ## Compatibility and review guidance This requires the repository's breaking-version treatment. Filesystem export remains the durable cross-session path; retained bundle resources live only for the MCP session. Stable MCP SDK 2.0.0 supplies required modern cache fields at its era-aware encoding seam and omits them for legacy clients. Suggested review order: 1. `BinarySessionRecords` and Evidence resource registration for retention, limits, and read-only resource behavior. 2. Tool contracts and `registerSessionRecordTools` for the breaking export and unknown pagination. 3. `AnalysisContextQueries` and snapshot notification wiring. 4. MCP/contract tests, stable SDK dependency update, then generated catalog and documentation. Known gaps before merge: - Run successful native-provider navigation/address trials against both aggregate and scalar paths. - Run the final full/package/real-provider validation gates after any remaining changes. ## Related Issues No directly related issue was found. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>
bsakaguchi 2026-10-16 21:13:15 +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#2003
No description provided.