Struct AutonomousDriver 

pub struct AutonomousDriver {
    pub session: Option<AutonomousSession>,
    pub pending_start_arc: Arc<Mutex<Option<(String, String, u32)>>>,
    /* private fields */
}

Drives autonomous turns cooperatively from within Agent::run’s tokio::select! loop.

When session is Some and the session is AutonomousState::Running, should_tick() returns true and next_tick().await completes after the configured inter-turn delay. The agent’s main loop calls run_autonomous_turn() in a dedicated select branch — no tokio::spawn is used, preserving exclusive &mut Agent access.

The Interval is created lazily on the first start_session call so that AutonomousDriver can be constructed outside a Tokio runtime context (e.g., during unit-test builder setup).

Fields

session: Option<AutonomousSession>

Active session, if any. At most one at a time (invariant A1).

pending_start_arc: Arc<Mutex<Option<(String, String, u32)>>>

Pending session start requested by a command handler.

handle_goal runs inside Box::pin(async move) and cannot call start_session directly (borrow conflict with &mut Agent). Instead it writes (goal_id, goal_text, max_turns) here. The main agent loop calls flush_pending_start() after each command handler returns to actually start the session.

Implementations

impl AutonomousDriver

pub fn new(turn_delay: Duration) -> Self

Create a driver with the given inter-turn delay.

No Tokio runtime is required at construction time — the interval is created lazily.

Panics

Panics if turn_delay is zero (would busy-loop the reactor).

pub fn flush_pending_start(&mut self) -> Option<(Option<String>, String)>

Drain any pending session start that was queued by a command handler.

Returns the cancelled session’s goal ID (if one was pre-empted) and the goal ID of the newly started session (if a start was pending). Call this from the main agent loop after each command handler returns and &mut self is exclusively available.

Returns None when no pending start was queued.

pub fn should_tick(&self) -> bool

Returns true when there is a running session that should produce the next tick.

pub async fn next_tick(&mut self)

Await the next tick of the inter-turn interval.

Requires a Tokio runtime. Creates the interval on first call. The caller is responsible for checking should_tick first (typically via the if guard on the select! branch).

pub fn start_session( &mut self, goal_id: impl Into<String>, goal_text: impl Into<String>, max_turns: u32, ) -> Option<String>

Start a new autonomous session, cancelling any previously active session.

Returns the goal ID of the cancelled session if one was aborted, so the caller can notify the user.

pub fn abort(&mut self) -> Option<String>

Abort the current session (if any), setting state to AutonomousState::Aborted.

Returns the goal ID that was aborted, or None if no session was active.