morluto/rea

Fork 0

mirror of https://github.com/morluto/rea.git synced 2026-11-05 06:45:22 +00:00

[PR #555] [MERGED] fix(tools)!: simplify direct invocation and harden boundary contracts #2071

New issue

Closed

opened 2026-10-16 21:13:56 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-16 21:13:56 +00:00

Owner

📋 Pull Request Information

Original PR: https://github.com/morluto/rea/pull/555
Author: @morluto
Created: 10/5/2026
Status: ✅ Merged
Merged: 10/5/2026
Merged by: @morluto

Base: main ← Head: fix/tool-boundary-contracts

📝 Commits (1)

00424ed fix(tools)!: simplify direct invocation and harden boundary contracts

📊 Changes

350 files changed (+5345 additions, -10597 deletions)

View changed files

📝 AGENTS.md (+5 -3)
📝 README.md (+49 -66)
📝 bridge/hopper_bridge.py (+6 -0)
📝 bridge/native/ReaNativeUI.swift (+10 -9)
📝 docs/adr/0002-controlled-replay-authority-and-sandbox.md (+5 -0)
📝 docs/adr/0003-managed-code-evidence-and-provider-boundary.md (+17 -13)
📝 docs/architecture.mermaid (+1 -1)
📝 docs/browser-observation.md (+28 -44)
📝 docs/browser-scenario-contract.md (+37 -35)
📝 docs/controlled-javascript-replay.md (+13 -17)
📝 docs/electron-observation.md (+21 -28)
📝 docs/error-contract.schema.json (+34 -250)
📝 docs/javascript-application-workflows.md (+6 -8)
📝 docs/javascript-artifact-reconstruction.md (+4 -3)
📝 docs/javascript-runtime-observation.md (+7 -9)
📝 docs/javascript-runtime-reconciliation.md (+7 -9)
📝 docs/managed-code-analysis.md (+12 -12)
📝 docs/mcp-contracts.md (+28 -62)
📝 docs/mcp-prompts.md (+4 -6)
📝 docs/native-investigation.md (+16 -14)

...and 80 more files

📄 Description

Summary

Agents can invoke REA's local tools directly, with caller-selected commands, paths, actions, and capture facets. Remove grant/ceiling configuration, permission elicitation, repeated approval fields, inert settings, and heuristic rewriting of local evidence. Harden the contracts exercised during the audit of all 122 tools.

Related: #545, #548. Existing fixes for #528 and #530 remain intact.

Problem and expected behavior

A process scenario using node or a Windows path was rejected by POSIX-only validation. Browser capture could deny a request whose scope already fit its ceiling. Fixed literals and approval booleans forced callers to restate implementation behavior. Providers could also return results inconsistent with advertised schemas or replay cached values without matching Evidence.

Tool selection expresses intent. Validate actual inputs and protocol requirements, preserve selected local diagnostics, and report real host/provider failures with their coverage limits.

Change and scope

Delete permission authorities, project grant storage, policy commands, capability enable gates, and filesystem/env allowlists; keep shared CLI/MCP application workflows.
Process capture resolves command names through PATH, defaults cwd to ., inherits the host environment with explicit overrides, and takes optional filesystem_observation_paths.
Remove approval booleans, fixed containment/lifecycle declarations, and unused capture/redaction settings. Keep meaningful capture facets and runtime budgets.
Preserve ordinary URLs, selected output, paths, and environment values. Redact transport credentials and explicitly declared sensitive values; avoid persisting the whole ambient environment.
Fix snapshot-to-Evidence binding, archive path collisions, Mach-O bounds, source-map contents, managed EH parsing, provider cancellation cleanup, native PNG validation, Hopper result shape/unknown coverage, and optional replay readiness in doctor.
Add prose boundary guidance and regenerate canonical tool metadata and docs.

Contract and boundary impact

Semantic owner and earliest changed stage: domain input schemas and config parsing; provider adapters validate actual producer representations.
CLI and MCP/tool-catalog contract: equivalent direct invocation, refreshed schemas and examples; 122 tools retained.
Provider, bridge, target-format, or platform compatibility: Hopper now emits required reference fields with unknown coverage explicit. Portable scenario parsing does not establish Windows execution support.
Evidence, artifact, provenance, or reconstruction contract: cached results require matching target/profile/Evidence; malformed or incomplete inputs remain visible.
Process execution, authorization, cleanup, or containment impact: local execution uses the current user's OS permissions. Owned-process cleanup, target identity checks, replay digest checks, and actual Linux replay confinement remain.
Generated metadata, package, or installation impact: catalogs/error schema regenerated; optional Linux replay does not block macOS setup health. Setup still discloses changes and requires approval.

Evidence and regression coverage

Tests cover minimal and portable inputs, actual cancellation/cleanup, schema dialect validity, evidence tampering, malformed binary/source-map data, explicit-secret handling, and CLI/MCP parity.
The real Hopper lane exposed a missing unresolved_calls field; the bridge now returns it and records its unknown coverage. Packaged setup exposed the optional replay readiness defect. Real browser capture verifies query preservation and explicit-secret handling.
Representative MCP input for capture_process_scenario (cwd and observation defaults apply):

{"executable":"node","arguments":["--version"]}

The same input can be saved as scenario.json and run with rea capture-process scenario.json. Results include inline Evidence, lifecycle/cleanup facts, and residual unknowns; no REA grant round-trip is required.

Remaining proof gaps: Windows execution, Linux replay, real Ghidra/Electron, and external managed-runtime/ILSpy lanes were unavailable on this macOS host. Windows process capture still reports its missing process-tree ownership support.
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 check:pr — passed on the final rebased commit: 364 test files, 1,948 tests passed, three skipped; typecheck, lint, format, knip, build, metadata, and generated-doc checks passed.
npm run docs:generate — regenerated metadata; no documentation errors.
node scripts/verify-package.mjs — passed installed CLI/MCP, setup/idempotence, catalog, and lifecycle checks.
npm run verify:hopper — passed real Hopper, two documents, function/reference analysis, and clean shutdown.
node scripts/verify-real-browser.mjs — passed real Chrome, CLI/MCP, declared-secret handling, attach/launch cleanup, and large screenshots.
node scripts/verify-real-javascript-runtime-observation.mjs — passed real Node Inspector fixtures through CLI/MCP.
node scripts/verify-native-ui.mjs --allow-permission-denial — actual positive native UI capture/action and CLI parity passed; no permission-denial fallback used.
npm run verify:managed — passed conformance fixtures; optional external runtime/decompiler coverage remains unsupported.

Real-provider and packaged-artifact checks ran during the audit. The final rebase preserved the verified provider implementations and passed the full PR gate.

Compatibility, safety, and release

Breaking changes or migration steps: refresh tool schemas; remove grant/ceiling environment configuration and deleted approval/fixed-confirmation fields. Replace filesystem_roots with optional observation paths, approved_plan_sha256 with plan_sha256, and replay passthrough-approved-origins with passthrough-declared-origins.
Real Hopper/Ghidra, browser, or OS coverage: real Hopper, Chrome, Node Inspector, and macOS native UI performed; real Ghidra and other unavailable lanes are explicitly unverified.
Package or release metadata impact: breaking Conventional Commit title/footer; generated catalog updated, no manually edited release version or committed packaged binaries.
Security, privacy, process, or containment review: REA grant restrictions are removed for local tools. Actual OS permissions, target binding, protocol constraints, lifecycle cleanup, and replay confinement remain. Sensitive transport credentials and caller-marked secrets remain redacted.

Review checklist

The PR has one focused outcome and a Conventional Commit title.
Related issues are linked.
Tests cover observable behavior and meaningful failure paths.
Owning docs, contracts, and generated metadata are updated.
CLI/MCP changes include representative input and result behavior.
Final diff checked for secrets, unrelated changes, 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/555 **Author:** [@morluto](https://github.com/morluto) **Created:** 10/5/2026 **Status:** ✅ Merged **Merged:** 10/5/2026 **Merged by:** [@morluto](https://github.com/morluto) **Base:** `main` ← **Head:** `fix/tool-boundary-contracts` --- ### 📝 Commits (1) - [`00424ed`](https://github.com/morluto/rea/commit/00424ed0f8ce61ed54a3f056474f5d7f733f7890) fix(tools)!: simplify direct invocation and harden boundary contracts ### 📊 Changes **350 files changed** (+5345 additions, -10597 deletions) <details> <summary>View changed files</summary> 📝 `AGENTS.md` (+5 -3) 📝 `README.md` (+49 -66) 📝 `bridge/hopper_bridge.py` (+6 -0) 📝 `bridge/native/ReaNativeUI.swift` (+10 -9) 📝 `docs/adr/0002-controlled-replay-authority-and-sandbox.md` (+5 -0) 📝 `docs/adr/0003-managed-code-evidence-and-provider-boundary.md` (+17 -13) 📝 `docs/architecture.mermaid` (+1 -1) 📝 `docs/browser-observation.md` (+28 -44) 📝 `docs/browser-scenario-contract.md` (+37 -35) 📝 `docs/controlled-javascript-replay.md` (+13 -17) 📝 `docs/electron-observation.md` (+21 -28) 📝 `docs/error-contract.schema.json` (+34 -250) 📝 `docs/javascript-application-workflows.md` (+6 -8) 📝 `docs/javascript-artifact-reconstruction.md` (+4 -3) 📝 `docs/javascript-runtime-observation.md` (+7 -9) 📝 `docs/javascript-runtime-reconciliation.md` (+7 -9) 📝 `docs/managed-code-analysis.md` (+12 -12) 📝 `docs/mcp-contracts.md` (+28 -62) 📝 `docs/mcp-prompts.md` (+4 -6) 📝 `docs/native-investigation.md` (+16 -14) _...and 80 more files_ </details> ### 📄 Description ## Summary Agents can invoke REA's local tools directly, with caller-selected commands, paths, actions, and capture facets. Remove grant/ceiling configuration, permission elicitation, repeated approval fields, inert settings, and heuristic rewriting of local evidence. Harden the contracts exercised during the audit of all 122 tools. Related: #545, #548. Existing fixes for #528 and #530 remain intact. ## Problem and expected behavior A process scenario using `node` or a Windows path was rejected by POSIX-only validation. Browser capture could deny a request whose scope already fit its ceiling. Fixed literals and approval booleans forced callers to restate implementation behavior. Providers could also return results inconsistent with advertised schemas or replay cached values without matching Evidence. Tool selection expresses intent. Validate actual inputs and protocol requirements, preserve selected local diagnostics, and report real host/provider failures with their coverage limits. ## Change and scope - Delete permission authorities, project grant storage, policy commands, capability enable gates, and filesystem/env allowlists; keep shared CLI/MCP application workflows. - Process capture resolves command names through PATH, defaults cwd to `.`, inherits the host environment with explicit overrides, and takes optional `filesystem_observation_paths`. - Remove approval booleans, fixed containment/lifecycle declarations, and unused capture/redaction settings. Keep meaningful capture facets and runtime budgets. - Preserve ordinary URLs, selected output, paths, and environment values. Redact transport credentials and explicitly declared sensitive values; avoid persisting the whole ambient environment. - Fix snapshot-to-Evidence binding, archive path collisions, Mach-O bounds, source-map contents, managed EH parsing, provider cancellation cleanup, native PNG validation, Hopper result shape/unknown coverage, and optional replay readiness in doctor. - Add prose boundary guidance and regenerate canonical tool metadata and docs. ## Contract and boundary impact - Semantic owner and earliest changed stage: domain input schemas and config parsing; provider adapters validate actual producer representations. - CLI and MCP/tool-catalog contract: equivalent direct invocation, refreshed schemas and examples; 122 tools retained. - Provider, bridge, target-format, or platform compatibility: Hopper now emits required reference fields with unknown coverage explicit. Portable scenario parsing does not establish Windows execution support. - Evidence, artifact, provenance, or reconstruction contract: cached results require matching target/profile/Evidence; malformed or incomplete inputs remain visible. - Process execution, authorization, cleanup, or containment impact: local execution uses the current user's OS permissions. Owned-process cleanup, target identity checks, replay digest checks, and actual Linux replay confinement remain. - Generated metadata, package, or installation impact: catalogs/error schema regenerated; optional Linux replay does not block macOS setup health. Setup still discloses changes and requires approval. ## Evidence and regression coverage - Tests cover minimal and portable inputs, actual cancellation/cleanup, schema dialect validity, evidence tampering, malformed binary/source-map data, explicit-secret handling, and CLI/MCP parity. - The real Hopper lane exposed a missing `unresolved_calls` field; the bridge now returns it and records its unknown coverage. Packaged setup exposed the optional replay readiness defect. Real browser capture verifies query preservation and explicit-secret handling. - Representative MCP input for `capture_process_scenario` (cwd and observation defaults apply): ```json {"executable":"node","arguments":["--version"]} ``` The same input can be saved as `scenario.json` and run with `rea capture-process scenario.json`. Results include inline Evidence, lifecycle/cleanup facts, and residual unknowns; no REA grant round-trip is required. - Remaining proof gaps: Windows execution, Linux replay, real Ghidra/Electron, and external managed-runtime/ILSpy lanes were unavailable on this macOS host. Windows process capture still reports its missing process-tree ownership support. - [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 check:pr` — passed on the final rebased commit: 364 test files, 1,948 tests passed, three skipped; typecheck, lint, format, knip, build, metadata, and generated-doc checks passed. - `npm run docs:generate` — regenerated metadata; no documentation errors. - `node scripts/verify-package.mjs` — passed installed CLI/MCP, setup/idempotence, catalog, and lifecycle checks. - `npm run verify:hopper` — passed real Hopper, two documents, function/reference analysis, and clean shutdown. - `node scripts/verify-real-browser.mjs` — passed real Chrome, CLI/MCP, declared-secret handling, attach/launch cleanup, and large screenshots. - `node scripts/verify-real-javascript-runtime-observation.mjs` — passed real Node Inspector fixtures through CLI/MCP. - `node scripts/verify-native-ui.mjs --allow-permission-denial` — actual positive native UI capture/action and CLI parity passed; no permission-denial fallback used. - `npm run verify:managed` — passed conformance fixtures; optional external runtime/decompiler coverage remains unsupported. Real-provider and packaged-artifact checks ran during the audit. The final rebase preserved the verified provider implementations and passed the full PR gate. ## Compatibility, safety, and release - Breaking changes or migration steps: refresh tool schemas; remove grant/ceiling environment configuration and deleted approval/fixed-confirmation fields. Replace `filesystem_roots` with optional observation paths, `approved_plan_sha256` with `plan_sha256`, and replay `passthrough-approved-origins` with `passthrough-declared-origins`. - Real Hopper/Ghidra, browser, or OS coverage: real Hopper, Chrome, Node Inspector, and macOS native UI performed; real Ghidra and other unavailable lanes are explicitly unverified. - Package or release metadata impact: breaking Conventional Commit title/footer; generated catalog updated, no manually edited release version or committed packaged binaries. - Security, privacy, process, or containment review: REA grant restrictions are removed for local tools. Actual OS permissions, target binding, protocol constraints, lifecycle cleanup, and replay confinement remain. Sensitive transport credentials and caller-marked secrets remain redacted. ## Review checklist - [x] The PR has one focused outcome and a Conventional Commit title. - [x] Related issues are linked. - [x] Tests cover observable behavior and meaningful failure paths. - [x] Owning docs, contracts, and generated metadata are updated. - [x] CLI/MCP changes include representative input and result behavior. - [x] Final diff checked for secrets, unrelated changes, 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-16 21:13:56 +00:00

closed this issue
added the
pull-request
label

bsakaguchi referenced this issue

2026-10-17 21:01:59 +00:00

[GH-ISSUE #3796] [Tracker] Open feature requests by area (October 2026) #1471

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#2071

No description provided.

Rows
Columns