Eve library

Desktop Compensating Actions

Guide

Revision 1

On this page

Implementation task: 180.C.13.11

Desktop fallback input has no trustworthy native undo stack. A click, focus change, drag, or key event can reach any foreground application, open modal state, submit a form, or trigger operating-system UI that Bellona cannot roll back generically. Bellona therefore treats desktop fallback mutations as rollback-declared actions with explicit compensating-action metadata.

Protocol Catalog#

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

  • RemoteDesktopCompensatingAction
  • RemoteDesktopCompensatingActionKind
  • RemoteDesktopCompensatingActionVerification
  • RemoteDesktopMutatingCommandName
  • REMOTE_DESKTOP_COMPENSATING_ACTIONS
  • REMOTE_DESKTOP_COMPENSATING_ACTION_METADATA_KEY

Command envelope metadata stays primitive-only for compatibility with RemoteCommandEnvelope. Mutating desktop 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 recipe Verification
desktop.window.focus manual_remediation_only compensating-action:desktop-window-focus-explicit-refocus Refocus the operator-reviewed window with desktop.window.focus, or manually restore focus if macOS/app focus rules block deterministic refocus. focused_window_restored
desktop.click manual_remediation_only compensating-action:desktop-click-explicit-remediation Review before/after evidence. Use click-back only for operator-confirmed idempotent targets; otherwise perform an app-specific remediation and record it. operator_attestation
desktop.type manual_remediation_only compensating-action:desktop-type-key-undo-or-remediation Use an app-specific undo shortcut only after operator review, or explicitly remediate by selecting/deleting the typed text or applying the target app's documented reversal. operator_attestation
desktop.emergency_stop manual_remediation_only compensating-action:desktop-emergency-stop-session-review Review interrupted command ids and current session state before allowing further desktop input. Already-dispatched native input is not undone by the emergency stop itself. session_state_reviewed

desktop.screenshot and desktop.window.list remain read-only desktop commands. They do not require rollback metadata.

Future Mutating Command Requirements#

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

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

Expected future action kinds are:

  • click_back for operator-confirmed idempotent toggles
  • drag_back for reversible drags where the source and destination are known
  • key_undo for commands with an app-specific undo shortcut such as Cmd+Z/Ctrl+Z
  • explicit_remediation when the target application owns the reversal path
  • session_state_review when the only safe step is reviewing and attesting current state before continuing

If a desktop 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 keypress or repeat click might work in some applications.

Dispatch Boundary#

180.C.13.11 introduces the desktop catalog, populates current desktop mutation metadata, and rejects safe-mutation desktop envelopes whose command name has no protocol-owned compensating action or whose metadata carries the wrong action id or rollback strategy.

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