[GH-ISSUE #4135] [Feature] Cluster artifacts from retained Evidence references and summaries #1627

New issue

Open

opened 2026-10-16 21:08:11 +00:00 by bsakaguchi · 1 comment

bsakaguchi commented

2026-10-16 21:08:11 +00:00

Owner

Originally created by @0xLLVEL on GitHub (Oct 15, 2026).
Original GitHub issue: https://github.com/morluto/rea/issues/4135

Before submitting

I searched the open and closed issues and pull requests for a related proposal.
I understand the contribution scope must be reviewed before integration; open questions are welcome here.
This request does not include credentials, private samples, or sensitive target data.

Area

Evidence, artifacts, or reconstruction

Current limitation

cluster_artifacts and rea cluster-artifacts accept every member as a
complete inline inspect_artifact inventory. That is correct but heavy: a
caller who has already inspected a handful of large artifacts must copy each
complete Evidence record into the call, and an analyst who holds only an
inspect_analysis_view summary cannot cluster at all, even though the complete
parent inventory is still retained in the session.

compare_artifacts already solves the same problem in the other direction: it
accepts either the nested inventory Evidence or its summary, and resolves the
exact retained parent before comparing. Clustering has no equivalent path yet.

Opened alongside #4133, which
introduced clustering with inline members only.

Use cases

An investigation that has inspected ten artifacts in one session clusters
them without re-sending ten complete inventories.
An agent that received a summary view (and whose context no longer holds the
complete inventory) can still ask which artifacts are the same build, with the
tool resolving the retained parent the same way compare_artifacts does.

Desired outcome and success criteria

A member entry can name retained Evidence by id, or be the summary an
inspect_analysis_view returned, and the call clusters the exact retained
parent inventory that produced it.
A reference that does not resolve, that is not artifact inventory Evidence, or
whose summary does not match its retained parent is reported as a typed
failure that names the member — never as a member that is absent or different.
Unplaced reasons stay unchanged: incomplete-inventory,
contradictory-integrity, incomparable-coverage-scope.
Complete Evidence records remain accepted so existing callers and the CLI
(which has no session) keep working unchanged.

Expected interaction with targets

Read existing files or captured data

Target and scope details (optional)

No target is launched, attached to or modified; the capability only consumes
Evidence the session already retains. The CLI reads Evidence JSON files and has
no session, so retained-reference members are inherently MCP-only.

Verification available so far

I have a prototype or observed results

Verification details (optional)

The boundary test added in #4133
already drives the real MCP session (open_binary → inspect_artifact →
cluster_artifacts) with Evidence read back from the session, so it is the
natural place to assert the reference path: pass member ids instead of inline
records and require the same families, index and unplaced rows. Failure paths
worth covering are a reference to a closed session's Evidence and a summary
whose parent was re-inspected with different parameters.

Alternatives considered

Copying complete Evidence inline works today and stays supported, but it scales
with the number of members: the same bytes are transported, parsed and
authenticated once per call. Narrowing the result (paging) does not help,
because the cost is in the input shape rather than the output.

Possible direction

Reuse the existing Evidence input contract and the resolution helper that
compare_artifacts uses for summaries, so clustering resolves members the same
way comparison does rather than adding a second reference mechanism.

References

#4133 — cluster_artifacts with inline members, member index and unplaced reasons.
Closes by pull request #4133, which ships cluster_artifacts with inline
members.
docs/mcp-contracts.md — artifact inventory coverage, comparison, and the cluster_artifacts contract.

Originally created by @0xLLVEL on GitHub (Oct 15, 2026). Original GitHub issue: https://github.com/morluto/rea/issues/4135 ### Before submitting - [x] I searched the open and closed issues and pull requests for a related proposal. - [x] I understand the [contribution scope](https://github.com/morluto/rea/blob/main/CONTRIBUTING.md#contribution-scope) must be reviewed before integration; open questions are welcome here. - [x] This request does not include credentials, private samples, or sensitive target data. ### Area Evidence, artifacts, or reconstruction ### Current limitation `cluster_artifacts` and `rea cluster-artifacts` accept every member as a complete inline `inspect_artifact` inventory. That is correct but heavy: a caller who has already inspected a handful of large artifacts must copy each complete Evidence record into the call, and an analyst who holds only an `inspect_analysis_view` summary cannot cluster at all, even though the complete parent inventory is still retained in the session. `compare_artifacts` already solves the same problem in the other direction: it accepts either the nested inventory Evidence or its summary, and resolves the exact retained parent before comparing. Clustering has no equivalent path yet. Opened alongside [#4133](https://github.com/morluto/rea/pull/4133), which introduced clustering with inline members only. ### Use cases - An investigation that has inspected ten artifacts in one session clusters them without re-sending ten complete inventories. - An agent that received a summary view (and whose context no longer holds the complete inventory) can still ask which artifacts are the same build, with the tool resolving the retained parent the same way `compare_artifacts` does. ### Desired outcome and success criteria - A member entry can name retained Evidence by id, or be the summary an `inspect_analysis_view` returned, and the call clusters the exact retained parent inventory that produced it. - A reference that does not resolve, that is not artifact inventory Evidence, or whose summary does not match its retained parent is reported as a typed failure that names the member — never as a member that is absent or different. - Unplaced reasons stay unchanged: `incomplete-inventory`, `contradictory-integrity`, `incomparable-coverage-scope`. - Complete Evidence records remain accepted so existing callers and the CLI (which has no session) keep working unchanged. ### Expected interaction with targets - Read existing files or captured data ### Target and scope details (optional) No target is launched, attached to or modified; the capability only consumes Evidence the session already retains. The CLI reads Evidence JSON files and has no session, so retained-reference members are inherently MCP-only. ### Verification available so far - I have a prototype or observed results ### Verification details (optional) The boundary test added in [#4133](https://github.com/morluto/rea/pull/4133) already drives the real MCP session (`open_binary` → `inspect_artifact` → `cluster_artifacts`) with Evidence read back from the session, so it is the natural place to assert the reference path: pass member ids instead of inline records and require the same families, index and unplaced rows. Failure paths worth covering are a reference to a closed session's Evidence and a summary whose parent was re-inspected with different parameters. ### Alternatives considered Copying complete Evidence inline works today and stays supported, but it scales with the number of members: the same bytes are transported, parsed and authenticated once per call. Narrowing the result (paging) does not help, because the cost is in the input shape rather than the output. ### Possible direction Reuse the existing Evidence input contract and the resolution helper that `compare_artifacts` uses for summaries, so clustering resolves members the same way comparison does rather than adding a second reference mechanism. ### References - [#4133](https://github.com/morluto/rea/pull/4133) — `cluster_artifacts` with inline members, member index and unplaced reasons. - Closes by pull request #4133, which ships `cluster_artifacts` with inline members. - `docs/mcp-contracts.md` — artifact inventory coverage, comparison, and the `cluster_artifacts` contract.

bsakaguchi commented

2026-10-17 21:02:34 +00:00

Author

Owner

@nikhilsaxena04 commented on GitHub (Oct 16, 2026):

Opened PR #4589 addressing this issue, building upon #4133 to accept members by retained Evidence ID or inspect_analysis_view summary.

@nikhilsaxena04 commented on GitHub (Oct 16, 2026): Opened PR #4589 addressing this issue, building upon #4133 to accept members by retained Evidence ID or `inspect_analysis_view` summary.

bsakaguchi referenced this issue

2026-10-31 00:54:13 +00:00

[PR #1627] [MERGED] fix(onboarding): isolate client homes and clarify npm release support #4710

bsakaguchi referenced this issue

2026-10-31 00:54:15 +00:00

[PR #1631] [MERGED] test(javascript): share semantic graph fixtures #4713

bsakaguchi referenced this issue

2026-11-03 21:43:16 +00:00

[GH-ISSUE #1587] [Feature] Improve task-centered REA onboarding and recovery in Codex skills #535