← Changelog

Docs · pin 6.4.0

Upgrade without breaking your runbooks

From 6.0.0 (2026-10-08) through 6.4.0 (2026-10-11), several minor releases changed MCP inputs, Evidence shape, and saved captures. This page is the operator checklist for those breaks. Dates are GitHub release published_at values. The teaching pin on rea.run is [email protected].

always-bump-minor is not a compatibility promise

Upstream’s 6.2 migration guide states the policy in one sentence: the repository uses always-bump-minor, including breaking releases. A minor number does not mean old scripts, old Evidence files, or old captures still validate. npm latest on 2026-10-13 was still 6.4.0. Floating @latest in a runbook will pick up the next minor whenever it publishes, breaks included.

Factory Droid (droid) and DeepSeek Harness (dsh) are on main only until an npm release after 6.4.0. Do not add them to a 6.4.0 setup plan.

Upgrade steps

1. Record the pin you run today: the version in MCP args, and npm view rea-agents version if you use a global CLI. They can differ.
2. Read every row you will cross in the table below. Jumping 6.1 → 6.4.0 still includes the 6.2 and 6.3 contracts.
3. Copy Evidence bundles, analysis snapshots, and process captures to a side directory. Do not rewrite them in place.
4. Point the client at the pin and approve a scoped setup plan:

   npx -y [email protected] setup --client codex --dry-run --json
   # review, then:
   npx -y [email protected] setup --client codex --yes --json

5. Restart or reconnect the agent. Cached tools/list schemas from the previous package are a common first failure.
6. Run npx -y [email protected] doctor --json and attach the JSON to the change ticket.
7. Re-run one authorized target you already understand. Diff field names before you trust a dashboard or a script.
8. If a consumer still reads structuredContent.result, switch it to normalized_result (6.2). If it reads network.websocket_events, switch it to network.websocket_connections (6.4). There is no legacy alias for the WebSocket field.

Manual MCP JSON for this pin:

{
  "mcpServers": {
    "rea": {
      "command": "npx",
      "args": ["-y", "[email protected]", "mcp"]
    }
  }
}

Operator-relevant breaks, 6.0 through 6.4.0

Earlier majors in the same ten days (4.0.0, 5.0.0) have their own breaks. They are listed on the changelog. This runbook starts where MCP path and Evidence consumers usually break: 6.0.

6.0.0 — absolute MCP paths

Published 2026-10-08. MCP filesystem inputs require absolute host paths. That includes target and snapshot paths, Evidence bundle paths, managed and firmware inputs, browser and Electron launch paths, and expected server paths. Optional paths stay optional. A call shaped like open_binary with "./app" must send /home/analyst/app or C:\analysis\app. The CLI still accepts operator-relative paths. Agents that build MCP arguments from a relative workspace root need pwd joined in, not a string the model invented.

Sources: #948, #1004, release rea-agents-6.0.0.

6.1.0 — Hopper callers

Published 2026-10-09. If you drive Hopper search from REA: regex mode is ECMAScript Unicode syntax, not Python re. Matching runs in a cancellable worker with a five-second deadline. Literal mode keeps Unicode casefold matching. set_current_document is removed. Switch targets with open_binary. Document arguments are scoped to the active target.

6.2.0 — Evidence, snapshots, and saved inventories

Published 2026-10-09. Read docs/migration-6.2.md on the 6.4.0 tag before you upgrade a consumer. The notes below are the operator extract. Commit 63bf914 and #1277 are the contract change.

Success payload

Evidence-producing tools return the complete Evidence record in structuredContent and in the JSON text. The old { result, evidence_id, evidence } wrapper is gone.

// 6.1
const value = reply.structuredContent.result;
const evidence = reply.structuredContent.evidence;

// 6.2 and later, including 6.4.0
const evidence = reply.structuredContent;
const value = evidence.normalized_result;
const evidenceId = evidence.evidence_id;

Check isError before success fields. Errors set isError: true, put the typed diagnostic in a text content block, and omit structuredContent so they do not have to match the success schema. Lifecycle and other non-Evidence tools keep their own output contracts. Do not assume every successful tool is Evidence.

Every Evidence record requires analysis_profile: the observed profile object, or null. The field is part of Evidence identity. Inserting null into an old file does not preserve the old evidence_id. Keep the original and regenerate with 6.2 or later. Records that already match the full canonical contract stay usable.

binary_session no longer has top-level provider and providers aliases. Read analysis_provider_binding, analysis_provider_candidates, and per-operation capabilities. Select a deep provider with open_binary.provider_id or CLI --provider.

A transport resource_constraint can carry details.reported_limits.evidence_reference. Consume the retained Evidence on the same connection with inspect_analysis_view or export_evidence_bundle. Response budgets are fixed when the server starts. Recreate the server to change them. Raising the server budget does not raise the client’s receive limit.

Snapshots and artifact roles

Snapshots require workflow_entries and a profile-bound Evidence record for every cached query. Import rejects incomplete bindings. Keep the old snapshot and write a new path, for example:

npx -y [email protected] analyze /absolute/path/to/program --provider ghidra --snapshot /absolute/path/to/analysis/program-6.4.json

In MCP, open without the incompatible snapshot_path, run the queries, then save through close_binary.snapshot_path. Do not invent missing provider profiles.

Join an occurrence to its content node with artifact_id. Identical bytes can share a node and still have different path roles. A merged content node cannot recover per-path facts that were never stored. Regenerate old inventories.

Other 6.2 consumer breaks

• Process captures. Legacy v3 conversion on import is gone (2a77469). Captures need explicit selected/launch executable identity and event_journal. An empty journal is valid; an omitted journal is not. Keep old captures as history and recapture when you need a current comparison. Do not invent launch identity from a later digest, or event order from separate logs.
• Filesystem effects may report status: "unknown" with a reason. Unknown is not “absent”.
• Cleanup. A finished one-shot analysis can report cleanup_incomplete instead of silent success when provider cleanup fails (#1211). Keep details.partial_observation or the primary diagnostic. A good observation does not prove cleanup.
• JavaScript projections require presence of present, absent, or unknown-coverage. Unknown values and unknown presence are different. Object operations use properties.property_path (segments or null), not a flattened name.
• Function comparisons use unchanged, changed, or unknown. The truncated status and summary.truncated counter are gone.
• Symlinks with target_state unreadable or unknown require target: null. External targets keep the observed absolute path. A display placeholder such as <outside-root> is not lookup data. Reimport those graphs.

6.3.0 — capture producer accounting

Published 2026-10-09. Historical captures that lack current producer accounting or transaction identity are rejected, and web diffs that omit accessibility or storage dimensions are rejected (3283a45). Preserve the original capture and recapture with the current producer. Comparison consumers must include every dimension. Do not fill a missing observation so the diff still renders.

Same release, still operator-visible if you store these objects:

• JSON shape paths use typed property and array-element segments. WebMCP input_schema_shape is replaced by input_schema and input_schema_sha256.
• Filesystem digest omissions require system_code. Budget and changed-file omissions use null. Unavailable-file omissions keep the operating-system error code.
• Provider analysis outputs must supply metadata that used to be repaired with defaults. Unsupported nullable facets are null, not omitted.
• JavaScript semantic graphs store evidence context IDs and locations, and results require an inline evidence_contexts table.
• Source-map URLs live on target observations selected by declared_url_sha256. Doctor skill identity no longer emits installed_catalog_digest; use identity.skill.state.
• The never-incremented truncated_scopes statistic is removed from JavaScript application analysis.

6.4.0 — WebSocket results and stored graphs

Published 2026-10-11. Current npm latest as checked 2026-10-13. Release: rea-agents-6.4.0.

WebSocket field rename

Read network.websocket_connections. Do not read network.websocket_events. No legacy alias remains (db4e360). Each connection has request_id, url, and events. payload_bytes may be null when the size is unknown. Update dashboards before you call a missing field a capture failure.

Stored Evidence and graphs

• Saved reference graphs. Exclusions need their matching pattern and must distinguish project-ignored from default-ignored. Re-import graphs that lack that provenance (6585293).
• Artifact graph edges. Child artifact IDs and paths come from the occurrence selected by occurrence_id, not from edge fields child_artifact_id / logical_path. Older inventory Evidence does not validate against the new commitment (#1493).
• Semantic graph schema. Nodes and relations no longer include identifier_strategy, and relation IDs no longer hash it. Older Evidence does not validate (#1474).
• Semantic identities. Select IDs from the parent graph. Read event names from event_name, endpoints from endpoint, and literal values from properties.value. New analyses use digest-based IDs for long or reserved names. Previously stored graphs keep their original IDs and remain valid workflow inputs (#1427 and related).
• Capture comparisons that use custom normalization must recapture both sides with literal-replacements-v1. Legacy unversioned pattern captures stay readable but cannot be compared with new pattern captures. Captures without patterns are unaffected (#1456).
• Terminal captures keep the initial and resized buffers within 1,000,000 cells using columns × (rows + scrollback). Oversized scenarios are rejected before launch.

Library authors, not MCP JSON

Direct in-process resource APIs now take a caller-owned ArtifactResourceScope (inventory, extraction, JavaScript analysis, reference imports, web exports). For readJavaScriptArtifactFiles, scope is argument three and the abort signal is argument four. CLI and MCP inputs for those operations are unchanged. If you only call tools over stdio, do not add a scope object to the tool arguments.

Optional agent-verification reports accept schema version 4. Production CLI and MCP contracts for that report are unchanged.

Related

• Changelog, 3.2.0 through 6.4.0
• Install, pinned to 6.4.0
• Client matrix for 6.4.0
• 6.4.0 operator guide (ADB, JEB, compact schema)
• JEB, bring your own license
• Android ADB device lane