## Changes Related to #545 and the permission-system removal in #555. - Upgrade the shipped skill to v24 and remove obsolete filesystem grants, per-call approval flags, Electron file-root configuration, and DMG approval flags. Calls follow the user-requested investigation directly. Keep setup plan confirmation, actual OS requirements, and process/archive lifecycle boundaries. - Correct the passive browser guide: endpoint/scope come from requests; ordinary local URL queries are retained, while credentials remain redacted. - Audit canonical tool effects: declare possible DMG process/temp-directory effects, mark fresh extraction non-idempotent, and mark comparisons of supplied captures/PNGs as closed-world. Align artifact-provider capability effects with temporary mount-directory writes. - Retain non-read-only hints for calls that add Evidence to the session; document that annotations are hints and that clients control their confirmation UI. Do not mislabel session mutations as read-only to suppress prompts. - Regenerate package, skill, MCP, and product metadata from source. ## Verification - `npm run test:focused -- <11 affected test files>`: **40 tests passed**, including skill transaction/backup/idempotence, SDK tools/list annotations, actual local capture/PNG comparisons, artifact extraction/containment/cancellation, DMG launcher/cleanup seam, setup confirmation, browser MCP and scenario MCP, CLI catalog parity. - `npm run check`: typecheck, lint, format, knip, package metadata. - `npm run docs:check`: generated catalogs, skill metadata, documentation facts, completion ledger, error schema. No local real Hopper/Ghidra run: their adapters and analysis operations are unchanged. Native macOS DMG behavior is covered locally through the launcher seam; no local macOS/hdiutil claim is made. Real browser verification passed using existing Headless Chrome143.0.7499.4: actual CLI/stdio MCP,9,331,407-byte PNG, passive capture/source maps, and owned/external scenario cleanup. An initial full Chrome143 run failed the existing screenshot-height assertion (1397 versus1536); the dedicated headless-shell run passed the complete verifier without code changes. The verifier run-lineage field remained unavailable; no lineage-coverage claim is made. Browser download into `.codex` was blocked by CDN403, so the successful run used an existing browser without changing host configuration.
126 lines
7.0 KiB
Markdown
126 lines
7.0 KiB
Markdown
# MCP runtime contracts
|
|
|
|
## Identity and discovery
|
|
|
|
`binary_session` reports the active package, server, SDK, and negotiated
|
|
protocol details. `rea doctor` separately inspects supported JSON/TOML client
|
|
registrations, reports their command vectors as aligned, stale, missing, or
|
|
invalid, and keeps live-server state `unknown` unless the active connection
|
|
supplies identity.
|
|
|
|
Canonical tool names remain stable, while `tools/list` advertises only the
|
|
operations callable for the current target, provider, host, and
|
|
negotiated client capabilities. `binary_session.tool_availability` remains the
|
|
complete inventory: it explains advertised and hidden operations with stable
|
|
availability reasons and remediation. Each entry also reports required and
|
|
optional negotiated client features plus the currently missing features.
|
|
Opening or closing a target or observing a provider health transition emits
|
|
`notifications/tools/list_changed`.
|
|
|
|
`binary_session.analysis_provider_candidates` is authoritative for deep-engine
|
|
discovery. Target-free discovery is sorted by provider ID, reports host
|
|
availability and `unknown` target support, and does not create an analysis
|
|
client. `open_binary.provider_id` accepts a concrete provider ID or `auto`; it
|
|
uses the same parser and selection policy as CLI `--provider` and
|
|
`REA_ANALYSIS_PROVIDER`. A successful deep open exposes one immutable provider,
|
|
concrete version, selection source, and complete analysis profile through
|
|
`analysis_provider_binding`. Ambiguity and unknown, unavailable, or unsupported
|
|
choices return typed selection details. A selected provider is never replaced
|
|
automatically after a runtime failure.
|
|
|
|
Every successful target transition allocates `binary_session.analysis_run.run_id`
|
|
before any provider startup. `process_lineage` is `not_observed` until a dynamic
|
|
provider starts, then becomes `snapshots` with every started provider's identity
|
|
and retained ownership observation. Each observation records `observed_at` and
|
|
is `unavailable` with a reason when ownership could not be revalidated, or
|
|
`verified` with launcher PID, parent PID, process group, and descendants observed
|
|
at that bounded check. These are historical snapshots, not live process
|
|
inventories, and do not claim that no short-lived descendant existed.
|
|
|
|
## Progress and cancellation
|
|
|
|
REA accepts ordinary `tools/call` progress tokens. Updates are monotonic,
|
|
rate-bounded to at most one intermediate update per 100 ms, and always allow a
|
|
terminal update. Unknown totals are omitted; REA does not fabricate percentages.
|
|
Provider calls receive the request cancellation signal. Artifact traversal,
|
|
hashing, version comparisons, Hopper requests, and process capture
|
|
check the same signal. Cancellation is distinct from timeout. A cleanup failure
|
|
uses `cleanup_incomplete` and lists only the owned resource kinds that remain.
|
|
Derived comparisons and reconstruction verification yield before computation
|
|
and before publication, so cancellation cannot race with successful Evidence.
|
|
|
|
CLI calls work without a progress token and translate SIGINT into the same
|
|
AbortSignal used by providers. Existing controlled-process cleanup and provider
|
|
shutdown rules still apply; REA never kills a process it cannot prove it owns.
|
|
|
|
## Tool results
|
|
|
|
Evidence-producing tools return `{ result, evidence_id, evidence }` in both
|
|
text and structured content. `evidence` is the complete canonical Evidence
|
|
record, including `normalized_result`, which equals `result`. The same record
|
|
is retained in the session bundle. Read `result` directly, or pass `evidence`
|
|
to a compatible comparison tool: `analyze_function` Evidence can be passed
|
|
directly to `compare_functions`, and `inspect_artifact` Evidence to
|
|
`compare_artifacts`. Use `get_evidence_bundle` when the task needs broader
|
|
retained session history or an explicit bundle for transfer.
|
|
|
|
## Aggregate native context
|
|
|
|
`get_navigation_context` composes the selected document, current address, and
|
|
current/containing procedure. Its capability inventory exposes a
|
|
`current_selection` mode and an `explicit_document` mode; the latter works when
|
|
the caller supplies `document` and the provider lacks `current_document`. A
|
|
cursor outside a procedure is represented as
|
|
`procedure: null`. `inspect_address_context` requires an explicit address and
|
|
returns name, procedure, comment, inline-comment, and bookmark facets;
|
|
unsupported facets are local `unavailable` outcomes. Use `current_document`,
|
|
`current_address`, and `current_procedure` for direct single-field lookups; use
|
|
the aggregate tools when you need related context together.
|
|
|
|
## Request scope and local effects
|
|
|
|
Each tool request names the target and lifecycle it will use. Browser calls
|
|
carry a loopback CDP endpoint and target ID, with optional origin filters;
|
|
process and Electron scenarios carry the executable, arguments, actions, and
|
|
cleanup behavior; artifact tools carry the input path and requested operation.
|
|
REA runs the declared request directly and does not infer a broader target or
|
|
action from it.
|
|
|
|
REA does not require permission grants or per-call approval flags. Setup still
|
|
prints its plan and requires confirmation before changing configuration or
|
|
installing Hopper. MCP clients control their own confirmation UI.
|
|
|
|
Tool annotations describe effects and are hints, not authorization controls
|
|
([MCP ToolAnnotations](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations)).
|
|
`readOnlyHint` includes session state: an analysis call that records additive
|
|
Evidence is marked non-read-only even when it leaves the target unchanged.
|
|
`destructiveHint` describes possible data loss, not ordinary Evidence recording.
|
|
Effect metadata covers possible behavior across supported inputs: DMG inventory
|
|
can launch `hdiutil` and create an owned temporary mount directory; extraction
|
|
creates a fresh output directory on every call. Comparing supplied web captures
|
|
or PNG artifacts uses local data without contacting the browser.
|
|
|
|
Host requirements remain in force. macOS may deny Accessibility,
|
|
Screen Recording, or native mounting; provider tools require their selected
|
|
analysis runtime. These failures are reported at the operation that needs
|
|
them. A configured provider or an endpoint alone does not establish that a
|
|
target is supported.
|
|
|
|
Evidence bundles, snapshots, and extraction use the paths and output behavior
|
|
declared by their tools. Artifact extraction materializes the selected regular
|
|
files into a fresh REA-chosen temporary directory and reports its path.
|
|
|
|
`analyze_javascript_application` reads the supplied local directory or ASAR path
|
|
and returns its result and Evidence inline.
|
|
|
|
## Integrity record-and-continue
|
|
|
|
Artifact integrity fails closed by default. A request can explicitly select
|
|
`integrity_policy=record-and-continue` when the investigation needs verified
|
|
siblings to continue after a mismatch.
|
|
|
|
Contradictory bytes are quarantined from nested expansion and recorded with
|
|
declared and observed hashes, trust, provenance, path, and unpacked state.
|
|
Verified siblings continue. Comparisons classify the result as a contradiction
|
|
and reconstruction cannot treat it as unchanged.
|