Skip to content

browser-scenario-contract.md

Latest commit

 

History

History
80 lines (68 loc) · 4.52 KB

browser-scenario-contract.md

File metadata and controls

80 lines (68 loc) · 4.52 KB
Raw

Browser scenario contract

capture_browser_scenario accepts the versioned provider-neutral browserScenarioSchema through both MCP and the capture-browser-scenario INPUT_JSON CLI command. Version 1 is declarative and bounded: it admits a fixed action vocabulary, exact HTTP(S) origins, deterministic browser settings, explicit storage and request replay, and finite capture limits. INPUT_JSON may be inline JSON or a JSON file path.

The browser boundary is part of the contract. Launch mode requires a caller-selected absolute executable, a provider-owned temporary profile, headless operation, and close-plus-delete cleanup. Connect mode accepts only an explicit-port loopback CDP endpoint, declares the browser externally owned, and permits disconnect-only cleanup. The Playwright driver preserves this distinction: it closes and deletes provider-owned profiles, but only disconnects from an external CDP browser. Real-browser verification checks both outcomes and confirms that an attached external browser remains alive.

URLs contain a query-free HTTP(S) base plus ordered query entries. Every query, form, storage, cookie, and replay value is either an explicitly public literal or a reference to a declared environment-backed secret. Raw credentials in URLs and literal credential headers are rejected. Secret query names must also appear in the redaction policy, and the required credential headers cannot be removed from that policy. Durable results must replace resolved secret values with their secret references.

Every start, navigation, storage, replay, and redirect origin must be listed in allowed_origins. Unsupported action tags, unknown fields, duplicate step or route IDs, undeclared or unused secrets, and provider-owned replay headers fail validation. HTTP and WebSocket routing enforces the same declared scope. Exact replay may abort unmatched requests or pass through only approved origins.

The result is Evidence v2 with an initial state followed by one record per 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 bounded by the scenario limits. Missing and truncated sections remain explicit and make the capture ineligible for equality claims. Attach-mode captures also declare the unavoidable pre-attach event gap.

Browser automation is disabled by default. The administrator ceiling is configured with:

  • REA_BROWSER_SCENARIO_ENABLED
  • REA_BROWSER_SCENARIO_EXECUTABLE_ROOTS_JSON
  • REA_BROWSER_SCENARIO_CDP_ENDPOINTS_JSON
  • REA_BROWSER_SCENARIO_ALLOWED_ORIGINS_JSON
  • REA_BROWSER_SCENARIO_ALLOWED_ENV_JSON

Unlike passive observation, browser automation is not granted automatically. Use an explicit project/session grant, or opt into the administrator grant with REA_BROWSER_SCENARIO_AUTO_GRANT=true for a trusted unattended environment. Authorization commits the exact executable or CDP endpoint, origins, environment variable names, network class, and scenario digest before any browser side effect.

Scenario comparison

compare_web_captures and compare-web-captures also accept two complete browser scenario captures. Steps align only by exact, unique step_id. Duplicate IDs, missing counterparts, changed action kinds, and incompatible browser/origin capture context are returned as alignment failures. They prevent an unchanged claim; observed differences may still prove a changed result.

The comparison records its full normalization commitment and SHA-256 digest. Built-in rules exclude step elapsed time and event sequence/index fields, compare screenshots by content digest, and compare DOM/accessibility captures by normalized text. Optional caller rules are bounded exact-literal replacements over named artifact kinds. Rules and artifact-kind lists are sorted canonically before application, making the same policy reproducible regardless of input order. Rules operate only on already-redacted durable capture fields and are preserved in the result.

Each aligned step reports changed, unchanged, or unknown. Changed and unknown action, screenshot, DOM, accessibility, URL, history, storage, and event artifacts carry their normalized before/after digests and capture states. max_changes bounds retained artifact records while total and omitted counts remain visible. Missing, truncated, or mismatched capture coverage remains unknown instead of being treated as equality.