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:
RemoteBrowserCompensatingActionRemoteBrowserCompensatingActionKindRemoteBrowserCompensatingActionVerificationRemoteBrowserMutatingCommandNameREMOTE_BROWSER_COMPENSATING_ACTIONSREMOTE_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_actionormanual_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_navigationfor reversible page transitions that can return to a known previous URLcancel_navigationfor in-flight navigations or downloads that can be safely stoppeddelete_downloadfor downloaded artifacts that Bellona owns and can removerevoke_form_submissionfor site-specific form/account changes that have an explicit revocation pathmanual_remediationwhen 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.