Eve library

Browser Compensating Actions

Guide

Revision 1

On this page

Implementation task: 180.C.11.11

Browser automation has no reliable native undo stack for form submissions, downloads, uploads, account changes, or managed-session lifecycle changes. Bellona browser mutations therefore declare explicit compensating-action metadata instead of implying that the browser can undo an operation.

This document defines the Browser CDP MVP compensating-action framework and the requirements future mutating browser commands must satisfy before dispatch.

Protocol Catalog#

The source of truth lives in libs/bellona/remote-protocol/src/browser.ts:

  • RemoteBrowserCompensatingAction
  • RemoteBrowserCompensatingActionKind
  • RemoteBrowserCompensatingActionVerification
  • RemoteBrowserMutatingCommandName
  • REMOTE_BROWSER_COMPENSATING_ACTIONS
  • REMOTE_BROWSER_COMPENSATING_ACTION_METADATA_KEY

Command envelope metadata stays primitive-only for compatibility with RemoteCommandEnvelope. Mutating browser commands therefore carry a compensating_action_id plus primitive summary fields, and clients resolve the full descriptor from the protocol catalog.

Current Mutating Commands#

Command Rollback strategy Compensating action id Reversal path Verification
browser.launch_managed compensating_action compensating-action:browser-launch-managed-close-session Dispatch browser.close for the launched managed session with profile cleanup enabled. profile_removed
browser.close manual_remediation_only compensating-action:browser-close-managed-session-manual-relaunch No previous profile state is restored. If needed, an operator launches a new isolated session and replays explicitly approved read-only navigation. operator_attestation

browser.navigate, browser.snapshot, and browser.screenshot remain read-only Browser CDP MVP commands. They do not require rollback strategy metadata because they do not mutate remote browser state under the current schema.

Future Mutating Command Requirements#

Future mutating browser commands must add a catalog entry before becoming routable. The descriptor must include:

  • stable action id
  • mutating browser command name
  • rollback strategy, either compensating_action or manual_remediation_only
  • action kind
  • operator-readable label and limitations
  • suggested Bellona command when an automated compensating command exists
  • verification method and verification description

Expected future action kinds are:

  • back_navigation for reversible page transitions that can return to a known previous URL
  • cancel_navigation for in-flight navigations or downloads that can be safely stopped
  • delete_download for downloaded artifacts that Bellona owns and can remove
  • revoke_form_submission for site-specific form/account changes that have an explicit revocation path
  • manual_remediation when no truthful automated reversal exists

If a command cannot name a truthful reversal path, it must use manual_remediation_only and state the operator action required. It must not claim compensating_action just because a best-effort cleanup exists.

Dispatch Boundary#

180.C.11.11 introduces and documents the catalog and populates current browser mutation metadata. 180.C.11.12 makes compensating_action_id mandatory for mutating browser envelopes and rejects missing, unknown, or command-mismatched ids before dispatch.

Agents should treat the catalog as binding metadata: every mutating browser command must carry the catalog id and primitive summary fields so audit, timeline, and rollback planning can name the available reversal path.