Struct AgentController 

pub struct AgentController { /* private fields */ }

Process-lifetime Agent controller for one immutable Provider binding.

The controller, not the Provider, owns normalized run_seq, journal records, public inspection, command acknowledgement, and EOF-to-Unknown handling. One controller may host many isolated Runs.

Implementations

impl AgentController

pub fn new( provider: Arc<dyn AgentProvider>, binding_ref: ProviderBindingRef, ) -> Result<Self, AgentProtocolError>

pub fn with_event_buffer( provider: Arc<dyn AgentProvider>, binding_ref: ProviderBindingRef, event_buffer: usize, ) -> Result<Self, AgentProtocolError>

pub fn with_journal_store( provider: Arc<dyn AgentProvider>, binding_ref: ProviderBindingRef, journal_store: Arc<dyn AgentJournalStore>, ) -> Result<Self, AgentProtocolError>

pub fn with_journal_store_and_event_buffer( provider: Arc<dyn AgentProvider>, binding_ref: ProviderBindingRef, journal_store: Arc<dyn AgentJournalStore>, event_buffer: usize, ) -> Result<Self, AgentProtocolError>

pub fn descriptor(&self) -> &AgentDescriptorEnvelope

pub async fn start( self: &Arc<Self>, run: AgentRunEnvelope, ) -> Result<AgentExecutionRef, AgentControlError>

Starts or idempotently reopens one immutable Run and begins consuming its atomic Provider stream in the background.

pub async fn inspect( &self, run_id: &RunId, ) -> Result<AgentRunView, AgentControlError>

Returns the bounded Host projection for a Run.

pub async fn initial_input( &self, run_id: &RunId, ) -> Result<Vec<Content>, AgentControlError>

Returns the immutable initial input from the registered Run spec.

This is separate from the bounded public Run projection because it is conversation content, not reducible execution state. Authenticated Host surfaces can use it to reconstruct a transcript without duplicating the input in a transport-specific registry.

pub async fn run_extensions( &self, run_id: &RunId, ) -> Result<Extensions, AgentControlError>

Returns digest-bound metadata from the immutable Run specification.

pub async fn catalog_runs( &self, ) -> Result<Vec<AgentRunCatalogEntry>, AgentControlError>

Lists durable Runs directly from the Host journal. Transport-specific session registries must not maintain a second Run ownership index.

pub async fn can_control_run( &self, run_id: &RunId, ) -> Result<bool, AgentControlError>

Reports whether a durable Run was registered against this controller’s current immutable Provider contract.

Discovery surfaces use this before enriching a native session with a Host-controlled Run. A Provider upgrade may legitimately change its descriptor digest; those older journals remain durable history, but they cannot be rehydrated or controlled by the new binding.

pub async fn has_run(&self, run_id: &RunId) -> Result<bool, AgentControlError>

pub async fn events( &self, run_id: &RunId, after_run_seq: u64, ) -> Result<Vec<AgentJournalRecord>, AgentControlError>

Replays normalized durable facts after the supplied Run sequence.

pub async fn subscribe( &self, run_id: &RunId, ) -> Result<Receiver<AgentControlEvent>, AgentControlError>

Subscribes to events published after subscription. Call events first (and again after broadcast lag) for lossless durable replay.

pub async fn command( &self, command: AgentCommandEnvelope, ) -> Result<CommandAck, AgentControlError>

Records, forwards, and durably projects one idempotent Provider command. Replays return the existing Host acknowledgement without forwarding.

pub async fn cancel( &self, run_id: &RunId, reason: impl Into<String>, ) -> Result<CommandAck, AgentControlError>

Requests cancellation with a fresh idempotency identity. Callers that need retry-stable command IDs should construct an AgentCommandEnvelope once and use Self::command directly.

pub async fn recorded_command( &self, run_id: &RunId, command_id: &CommandId, ) -> Result<Option<AgentCommandEnvelope>, AgentControlError>

Reads immutable command identity without recovering or attaching native work. Session-level retries use this even after the target Run ends.

pub async fn command_ack( &self, run_id: &RunId, command_id: &CommandId, ) -> Result<CommandAck, AgentControlError>

pub async fn recover( self: &Arc<Self>, run_id: &RunId, ) -> Result<AgentRunView, AgentControlError>

Conservatively reattaches a Provider stream after a Host-recorded EOF.

The reference controller requires the recovered stream to replay the complete committed Provider prefix with stable event IDs and draft digests. It restores continuity only after that prefix matches; opaque adapters that cannot provide such evidence remain Unknown rather than being guessed healthy.

pub async fn wait_for_terminal( &self, run_id: &RunId, ) -> Result<AgentRunView, AgentControlError>

Waits until the Run reaches an authoritative terminal. Unknown is returned explicitly rather than guessed as success or cancellation.