Struct MailboxService 

pub struct MailboxService { /* private fields */ }

Event-driven mailbox service that replaces polling-based dispatch.

Each thread gets a ThreadMailbox that tracks whether it’s idle or running. When a message arrives and the thread is idle, dispatch happens immediately (zero-latency). When the thread is busy, messages are buffered and dispatched automatically on run completion.

Implementations

impl MailboxService

pub fn new( os: Arc<AgentOs>, mailbox_store: Arc<dyn MailboxStore>, consumer_id: impl Into<String>, ) -> Self

pub fn mailbox_store(&self) -> &Arc<dyn MailboxStore>

Returns a reference to the underlying mailbox store.

pub async fn submit( self: &Arc<Self>, agent_id: &str, request: RunRequest, options: EnqueueOptions, ) -> Result<(String, String, String), ApiError>

Submit a background run request. Returns (thread_id, run_id, entry_id).

If the thread is idle, the run is dispatched immediately. If the thread is busy, the entry is buffered for later dispatch.

pub async fn submit_streaming( self: &Arc<Self>, agent_id: &str, request: RunRequest, options: EnqueueOptions, ) -> Result<RunStream, ApiError>

Submit a streaming run request. Returns a RunStream for SSE consumption.

This bypasses the buffering path — the entry is claimed inline and the run stream is returned directly. The stream is wrapped so that on_run_complete fires when it exhausts.

pub async fn control( self: &Arc<Self>, thread_id: &str, signal: ControlSignal, ) -> Result<ControlResult, ApiError>

Send a control signal to a thread’s mailbox.

pub async fn recover(self: &Arc<Self>) -> Result<usize, ApiError>

Recover mailbox state from the persistent store on startup.

Loads all queued entries and buffers them in the appropriate ThreadMailbox.

pub async fn run_sweep_forever(self: Arc<Self>)

Background sweep that picks up orphaned entries.

Runs at a low frequency (30s) as a safety net. Most dispatch happens via the event-driven path.