diff --git a/docs/browser-scenario-contract.md b/docs/browser-scenario-contract.md index a581129b7..1639faa61 100644 --- a/docs/browser-scenario-contract.md +++ b/docs/browser-scenario-contract.md @@ -23,9 +23,9 @@ that rejection does not roll back browser effects. REA removes its owned future-document scripts, restores live frame methods, then disconnects. Add secret declarations, storage seeds, and additional artifact or event capture only when needed. Action, secret, and storage counts are not capped. -Duration, action, and navigation -timeouts remain fixed provider-owned liveness limits; the request does not -accept a caller-controlled `limits` object. +Duration, action, and navigation timeouts remain fixed provider-owned liveness +limits. `capture.limits` controls retained event and network-content budgets; +it does not change those liveness deadlines. ## Minimal launch example @@ -179,12 +179,44 @@ declared action. Each step reports action status, elapsed time, sanitized URLs, event bounds, and independently typed capture states for screenshot, DOM, accessibility, URL, history, and storage. Console, page-error, network, WebSocket, frame, worker, popup, and cancelled-download events are attributed to -steps and all observed events and requested artifacts are returned inline. -There are no event, frame, worker, popup, WebSocket, DOM-node, -accessibility-node, storage-entry, screenshot-count, or cumulative -metadata-byte caps. Requested artifacts and observed events are returned -inline without application-defined size ceilings. Other missing sections -remain explicit and make the capture ineligible for equality claims. +steps. Retained events and requested artifacts are returned inline; omitted +events are counted by kind and identify affected network transactions. +Event and selected network-content retention have caller-selected limits under +`capture.limits`. Omitted values use the defaults below; every supplied value +must be a positive safe integer, and callers can raise or lower a default. +Byte limits are conservative allocation-cost estimates for retained event +values, including UTF-16 storage and JSON expansion, rather than serialized +bytes or a promise about exact process memory. `events.omissions.by_kind` +reports counts and reasons for omitted event kinds. Its +`network_transactions` rows identify affected transaction IDs and omitted +event kinds; `network_transaction_range` identifies the contiguous IDs beyond +the transaction limit. Omission metadata is bounded by the selected +transaction limit. Other missing sections remain explicit and make the capture +ineligible for equality claims. + +The default limits are 10,000 events, 4 MiB estimated allocation for one +event, 16 MiB estimated allocation across retained events, 1,024 network +transactions, 64 KiB of body bytes per transaction phase, 1 MiB estimated +allocation for body redaction/base64, 1 MiB for retained header values, and +1 MiB for network metadata. The same limits are included in the capture +Evidence. Playwright materializes response bodies before REA can inspect their +byte length; `max_network_body_bytes` bounds subsequent retained copies and +does not bound the browser API read itself. A body that exceeds its selected +limit has an explicit `body-size-limit` or `body-allocation-limit` unavailable +state with the observed and allowed values. + +Additional implementation bounds are 16 simultaneous network-content reads, +a 5-second deadline for each provider API read, and 2,048 live event-listener +owners. These are not caller-selectable. The concurrency bound queues admitted +content jobs and does not itself omit observations; a provider read timeout +produces a typed unavailable state, while exceeding listener capacity produces +event-kind omission counts. A preflight avoids body redaction and base64 copies +when the currently available event budget already rejects the body. +Concurrent reads may each pass that check before their events are retained; +their retained-copy work is bounded by 16 times the selected per-body +allocation limit. The Playwright response Buffer itself is materialized before +REA can apply that limit. Requested artifacts and retained events are returned +inline within the declared limits. Attach-mode captures also declare the unavoidable pre-attach event gap. Selected event families are observed on the root page and discovered descendant @@ -288,16 +320,21 @@ retained representation after redaction. Only completed responses are read. At the end of the final step, observation stops; requests still in flight emit `request-unfinished`, and their observed -responses have explicitly unavailable bodies. This cutoff does not wait for -long-lived streaming connections. Already-started content reads settle before -browser cleanup, with a provider-owned five-second timeout per read and -cancellation support. Failed or unexposed reads retain per-content states and make selected -event coverage incomplete. Body events can arrive during later steps or final -drain; event bounds describe receipt during the step, while the source event -reference establishes the transaction phase. Comparison attributes content, like -every other event of its transaction, to the step that sent the request (the -receipt step when that request was not observed) and excludes the sequence -reference from normalization. +responses have explicitly unavailable bodies. Already-admitted content reads +drain before browser cleanup. At most 16 reads run at once; queued work is +bounded by the selected network-transaction limit and by successful admission +of its request or response event. Each provider API read has its own five-second +timeout once it starts, so queue wait adds to total drain and cleanup time; this +is not a five-second total capture cutoff. Cancellation interrupts active reads +and queued jobs produce cancelled states without calling their provider APIs. +This drain does not wait for long-lived unfinished streaming connections and +does not refetch unfinished response bodies. Failed or unexposed reads retain +per-content states and make selected event coverage incomplete. Body events can +arrive during later steps or final drain; event bounds describe receipt during +the step, while the source event reference establishes the transaction phase. +Comparison attributes content, like every other event of its transaction, to +the step that sent the request (the receipt step when that request was not +observed) and excludes the sequence reference from normalization. Playwright scenario capture does not supply initiator stacks; passive CDP observation retains its own initiator evidence. diff --git a/docs/cli.md b/docs/cli.md index 407e5d3f0..736c0de37 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -319,11 +319,44 @@ redirected, which keeps large results smaller for agents and scripts; pipe through `jq .` for indented files. Output selection and formatting do not change operation status. -| Status | Meaning | -| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | -| `0` | The operation completed. Its result may include partial evidence, warnings or unresolved questions. | -| `1` | The operation could not complete. Structured output identifies invalid input, permissions, cancellation, timeouts or another failure when available. | -| `128 + N` | Signal `N` ended the process, where the shell or runtime preserves the conventional signal-derived status. | +For `cutter-command`, `--json-output` requests command-specific JSON from +Cutter when available. This is separate from `--format json`, which selects the +CLI result representation; the global `--json` flag selects that same CLI +representation. + +Cutter still accepts deprecated `--json=true` and `--json=false` compatibility +values. When both forms are present, `--json-output` takes precedence in either +argument order. Bare `--json` retains its global meaning of selecting JSON CLI +output formatting. + +| Status | Meaning | +| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `0` | The operation completed. Its result may include partial evidence, warnings or unresolved questions. | +| `1` | The operation could not complete. Structured output identifies invalid input, permissions, cancellation, timeouts or another failure when available. | +| `128 + N` | Signal-derived status. An unhandled signal may have ended the process, with the shell or runtime preserving the conventional status; a command may instead have handled the signal, waited for its operation and cleanup to settle, and assigned the same status (`130` for SIGINT, `143` for SIGTERM). In the handled case, it may also have printed a structured `cancelled` result. | + +A `cancelled` result does not by itself determine the exit status; it depends on +the command's signal handling. Commands routed through the shared +`withCommandCancellation` handler in the CLI set status `130` for SIGINT or +`143` for SIGTERM after their operation settles. Current source registrations +use that handler for process capture and comparison (`capture-process`, +`compare-process-captures`), JavaScript application analysis (`analyze` when it +selects the JavaScript lane, and `analyze-javascript-application`), selected +browser, web and Electron commands (including `analyze-web-bundle`, +`observe-web-execution`, `capture-browser-scenario` and +`capture-electron-scenario`), and the platform and provider command families +for Android/ADB, Apktool/JEB/Flutter, firmware, PCAP and signal analysis, +WASM/EVM, Go/Rust and binary diagnostics, Frida instrumentation, the Cutter +command, objdump, Rizin and GDB. In these paths, a returned structured +`cancelled` result can be printed before the wrapper assigns the +signal-derived status. This describes the current source routing; it is not a +claim that every command or provider runtime has been independently exercised. + +`inspect-artifact` also returns a structured cancelled result, but its direct +analysis cancellation path does not set a signal-derived exit status, so it +exits `1`. Setup has its own contract: cancellation exits `0`. Treat the +structured result and process status as separate signals when scripting +cancellation. `setup --dry-run` returns `planned` and exits `0`; a cancelled setup also exits `0`. Setup returns `1` for `needs_confirmation` or `needs_human`. diff --git a/docs/javascript-application-workflows.md b/docs/javascript-application-workflows.md index 6d47fc095..7b581e8ae 100644 --- a/docs/javascript-application-workflows.md +++ b/docs/javascript-application-workflows.md @@ -60,6 +60,8 @@ provider implicitly. `trace_javascript_semantics` queries the authenticated companion graph without rereading mutable files. A seed may identify a semantic or application node, literal, function fingerprint, property, endpoint, event, or boundary field. +For a recovered parse, coercion, or validation boundary, its field value is the +static operation's method name (for example, `Number`). The query declares backward provenance, forward influence, callers, or ownership and can restrict admitted relation kinds. REA returns every matching seed and the complete reachable subgraph; callers do not choose node, relation, diff --git a/docs/jeb-analysis.md b/docs/jeb-analysis.md index 601753257..884024314 100644 --- a/docs/jeb-analysis.md +++ b/docs/jeb-analysis.md @@ -16,6 +16,12 @@ URL after validating its syntax. That validation does not establish that the JEB service is reachable or that a project is open; use the existing `inspect-jeb-client` command for a read-only service query. +MCP `binary_session` probes the live JEB service and its advertised tool catalog. +Availability is reported per operation: a reachable headless client can support +inspection and decompilation while refusing `open_jeb_project`. Catalog discovery +uses one 60-second deadline across connection and pagination; a responsive server +cannot keep discovery running indefinitely by returning more pages. + Verified against JEB 5.48.0 (Linux x64, licensed build) serving `jeb-mcp-server` 1.3.0 over streamable HTTP. ## Operations diff --git a/docs/mcp-contracts.md b/docs/mcp-contracts.md index 02d048014..8c5582328 100644 --- a/docs/mcp-contracts.md +++ b/docs/mcp-contracts.md @@ -38,13 +38,10 @@ socket and device entries are not opened. Case-distinct archive members remain separate observations. Their case-insensitive materialization diagnostic does not reduce traversal coverage when both spellings were read. -Current output also retains `coverage_status` (`complete` or `partial`) for existing clients, derived from the scoped traversal status. The owning parser normalizes retained `coverage_status` records to scoped coverage and rejects conflicting declarations. - -The coverage field is optional when reading older retained Evidence. The owning -inventory parser recognizes historical REA scope notices for compatibility; -unfamiliar legacy limitations remain conservative. Typed records do not derive -coverage from limitation text. Pages from one inventory must carry the same -coverage declaration. +Current inventory Evidence requires scoped `coverage` with a `complete` or +`unknown` status. Consumers use this producer-owned fact and reject records +without it; limitations are explanatory and do not supply or infer coverage. +Pages from one inventory must carry the same coverage declaration. Function dossiers can declare per-facet coverage in the optional `normalized_result.facet_availability` map. Each supplied facet is either diff --git a/docs/native-investigation.md b/docs/native-investigation.md index 2476f7bc5..b9b42dcb8 100644 --- a/docs/native-investigation.md +++ b/docs/native-investigation.md @@ -481,8 +481,9 @@ user's permissions and may change files, show UI or use the network. Debugging must be allowed for the user (Developer Tools access). A hardened-runtime target without `com.apple.security.get-task-allow` cannot be -debugged; `inspect_signature` reports this as the debugger-attach facet, and -the tool fails with a `debugger-attach-denied` reason. +debugged; `inspect_signature` reports the signature's `hardened_runtime` value +and its `entitlements`, including `com.apple.security.get-task-allow` when it +is present. A denied trace reports the `debugger-attach-denied` reason. ## Provider and verification boundaries diff --git a/native/windows/README.md b/native/windows/README.md index ec2fb1bde..428b33a5c 100644 --- a/native/windows/README.md +++ b/native/windows/README.md @@ -26,6 +26,29 @@ its manifest. Release CI builds both, and `prepublishOnly` rejects a missing, stale, mismatched, or wrong-architecture artifact. A development tarball built without this lane reports Windows native controls as unavailable. +## Restore the artifact in a source checkout + +The source tree omits `native/windows/build/` from Git. To run Windows +provider-backed workflows from a checkout without the MinGW build lane, extract +the two files from the published `rea-agents` tarball whose version exactly +matches the checkout's `package.json` version. Do not use `latest` or copy files +from another REA version; the loader verifies the manifest version, ABI, +architecture, and addon digest before it grants authority. + +From the checkout root, replace `` with the `version` in +`package.json`: + +```sh +npm pack rea-agents@ +tar -xzf rea-agents-.tgz +mkdir -p native/windows/build +cp package/native/windows/build/manifest.json native/windows/build/ +cp package/native/windows/build/rea-windows-x64.node native/windows/build/ +``` + +This is a manual recovery step. REA does not fetch or install the artifact +automatically. Alternatively, build it using the Linux/MinGW lane above. + ## Boundaries - Opaque Node objects carry a native type tag, resource kind, and closed state.