Struct AgentRunner 

pub struct AgentRunner {

    pub event_publication: Arc<EventPublication>,
    pub visible_messages: Arc<VisibleMessageStream>,
    pub event_sender: Sender<AgentEvent>,
    pub cancel_token: CancellationToken,
    pub status: AgentStatus,
    pub started_at: DateTime<Utc>,
    pub completed_at: Option<DateTime<Utc>>,
    pub last_budget_event: Option<AgentEvent>,
    pub last_critical_events: Vec<AgentEvent>,
    pub last_tool_name: Option<String>,
    pub last_tool_phase: Option<String>,
    pub last_event_at: Option<DateTime<Utc>>,
    pub round_count: u32,
    pub run_id: String,
    /* private fields */
}

Runner that manages agent execution for a session.

Each active agent run has an associated AgentRunner that coordinates event broadcasting, cancellation, and status tracking.

Event Broadcasting

Uses a broadcast channel to support multiple subscribers watching the same agent run simultaneously.

Cancellation

Provides a cancellation token that can be used to gracefully stop an in-progress agent execution.

Fields

event_publication: Arc<EventPublication>

Generation fence and activity clock shared only by this run’s producers.

visible_messages: Arc<VisibleMessageStream>

Message-only visible-text replay and broadcast for this exact run.

event_sender: Sender<AgentEvent>

Broadcast sender for agent events.

Allows multiple clients to subscribe to agent events via event_sender.subscribe().

cancel_token: CancellationToken

Cancellation token for graceful shutdown.

When triggered, the agent should stop execution at the next safe point.

status: AgentStatus

Current status of the agent run.

started_at: DateTime<Utc>

Timestamp when the run was started.

completed_at: Option<DateTime<Utc>>

Timestamp when the run completed (if finished).

last_budget_event: Option<AgentEvent>

Last token budget event to replay for new subscribers.

When a new client subscribes to an ongoing run, this allows them to receive the most recent token usage info.

last_critical_events: Vec<AgentEvent>

Small ring of critical state events (TaskListUpdated, SubAgent*, etc.) cached for replay to late/reconnecting subscribers.

Bounded to [CRITICAL_EVENTS_CAPACITY] entries; oldest are evicted.

last_tool_name: Option<String>

Name of the most recently executed tool (if any). Updated live during execution for diagnostic visibility.

last_tool_phase: Option<String>

Phase of the most recently executed tool: “begin”, “finished”, or “error”. Updated live during execution for diagnostic visibility.

last_event_at: Option<DateTime<Utc>>

Timestamp of the last event received during this run. Updated live during execution for liveness checks.

round_count: u32

Number of completed rounds (turns) so far. Updated live during execution for progress tracking.

run_id: String

Unique identifier for this execution run. Generated fresh for every try_reserve_runner call so that frontend SSE events can be matched to the correct run even across reconnects.

Implementations

impl AgentRunner

pub const EVENT_CHANNEL_CAPACITY: usize = 1000

Broadcast channel capacity for agent events.

pub const CRITICAL_EVENTS_CAPACITY: usize = 32

Maximum number of critical events cached for late-subscriber replay.

pub fn root_reset_admission_reserved(&self) -> bool

Denial-only maintenance signal; never a claim that this run is idle.

pub fn last_activity_at(&self) -> Option<DateTime<Utc>>

Includes lock-free event traffic as well as legacy diagnostic updates.

pub fn bind_supervisor_run_target( &mut self, target: &SupervisorCurrentUserTarget, workspace_path: Option<&str>, )

Host-only observation, set under the exact live router-owner fence.

pub fn exact_execution_finalized(&self) -> bool

This bit is set only by finalization of the matching run ID.

pub fn supervisor_run_observation_matches( &self, target: &SupervisorCurrentUserTarget, workspace_path: Option<&str>, ) -> Option<bool>

Compare an existing Host observation without treating it as a grant. Ordinary metadata edits may advance metadata_version, while the canonical target and Workspace are separately revalidated by the Host.

pub fn supervisor_run_is_finalized_for( &self, target: &SupervisorCurrentUserTarget, workspace_path: Option<&str>, ) -> bool

Only the exact execution finalizer can establish this terminal fact.

pub fn new() -> Self

Create a new agent runner with default settings.

Initializes a broadcast channel, a fresh cancellation token, and Pending status.

pub fn push_critical_event(&mut self, event: AgentEvent)

Push a critical state event into the bounded replay cache.

Sub-agent lifecycle entries are snapshots keyed by stable child id, not an event log: a rerunnable/resident child can produce many generations, and replaying older Start/Complete pairs makes the current generation ambiguous to reconnecting clients. Keep only the newest lifecycle state for each child while live subscribers still receive every event.

If the remaining cache is full, the oldest entry is evicted.

Trait Implementations

impl Clone for AgentRunner

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 AgentRunner

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

Formats the value using the given formatter.

impl Default for AgentRunner

fn default() -> Self

Returns the “default value” for a type.