Struct ControlState 

pub struct ControlState { /* private fields */ }

The control-ownership state machine. Pure: ControlState::apply is the only way to change it, and it never touches a clock, a socket, or a lock.

Every event is safe to feed at any time — an event that doesn’t apply to the current state (HandBack with nothing handed back, a stale GracePeriodExpired after an on-time hand-back) is a no-op rather than an error, because these are UI-driven events a real client can double- fire under an ordinary race without that being a bug.

Implementations

impl ControlState

pub fn new() -> Self

pub fn owner(&self) -> ControlOwner

pub fn current_action(&self) -> Option<&str>

pub fn pending_signin(&self) -> Option<&PendingSignIn>

pub fn user_engaged(&self) -> bool

Is a person demonstrably at this browser right now — holding control, or having driven it since the current sign-in was requested?

The one question the sign-in timeout has to answer. See ControlState::user_engaged.

pub fn may_agent_act(&self) -> bool

The tool-boundary check a browse tool call makes before it runs: “may the agent act right now?” false whenever the user holds control (or no agent has attached at all).

This is also what closes the approval race: a browse action pending at an approval prompt (a separate, pre-existing concern — see assistant::governance/agent_loop::ApprovalDecision, not modeled here) must not execute while the user holds control even if it gets approved mid-race, and must run only after hand-back. That falls out for free as long as the caller re-checks may_agent_act() at the moment it is ABOUT TO EXECUTE the approved action, rather than caching the answer from when approval was requested or granted — approval and execution are different moments, and only the second one may be gated on stale information for this to be correct. See the approval_race_* test below.

pub fn user_holds_control(&self) -> bool

Whether the user explicitly holds control right now — owner == User, nothing else.

This is deliberately NOT the same predicate as may_agent_act (owner == Agent): they only disagree in the NoAgent case, where may_agent_act is false (correct for the tool-boundary check, which always runs after the calling tool has already attached) but user_holds_control is also false (correct for a call site that needs to gate BEFORE it has attached — e.g. browser_record_start/ browser_record_stop/browser_await_signin, which check this before ever touching a session, so their very first invocation ever — NoAgent, nothing to wait for — is never mistaken for the user holding control). Use may_agent_act when the caller has already established a session; use this when it hasn’t yet.

pub fn is_blackout_active(&self) -> bool

Whether no screenshot/frame may reach the model right now. true while the user holds control OR a sign-in is pending — sign-in implies the same privacy boundary even though it’s the agent’s own browser_await_signin call, not an explicit Take Control press, that puts the page in front of the user.

pub fn apply(&mut self, event: ControlEvent) -> Vec<ControlEffect>

Apply one event, mutating in place, and return what the caller (or a caller of its result) should do as a result.

Trait Implementations

impl Clone for ControlState

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for ControlState

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for ControlState

fn default() -> Self

Returns the “default value” for a type.

impl Eq for ControlState

impl PartialEq for ControlState

fn eq(&self, other: &Self) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl StructuralPartialEq for ControlState