Skip to main content

ExecutionService

algocline_core::execution::service

Trait ExecutionService 

Source 
pub trait ExecutionService: Send + Sync {
    // Required methods
    fn spawn<'life0, 'async_trait>(
        &'life0 self,
        spec: SessionSpec,
    ) -> Pin<Box<dyn Future<Output = Result<SessionId, SpawnError>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait;
    fn state<'life0, 'life1, 'async_trait>(
        &'life0 self,
        id: &'life1 SessionId,
    ) -> Pin<Box<dyn Future<Output = Result<ExecutionState, StateError>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait;
    fn resume<'life0, 'life1, 'async_trait>(
        &'life0 self,
        id: &'life1 SessionId,
        payload: ResumePayload,
    ) -> Pin<Box<dyn Future<Output = Result<ResumeOutcome, ResumeError>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait;
    fn cancel<'life0, 'life1, 'async_trait>(
        &'life0 self,
        id: &'life1 SessionId,
        reason: CancelReason,
    ) -> Pin<Box<dyn Future<Output = Result<(), CancelError>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait;
    fn observe(
        &self,
        id: &SessionId,
    ) -> Result<Box<dyn ObserverHandle>, ObserveError>;
    fn await_terminal<'life0, 'life1, 'async_trait>(
        &'life0 self,
        id: &'life1 SessionId,
    ) -> Pin<Box<dyn Future<Output = Result<TerminalOutcome, AwaitError>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait;
}
Expand description

Pure service trait for managing execution sessions.

Implementors must ensure the following invariants hold:

  1. Wire-concept exclusion: no MCP/rmcp types, progressToken, _meta fields, notifications/* paths, or mcp_-prefixed identifiers are referenced by this trait or its supporting types.
  2. SessionId is the sole handle: all verbs after spawn accept only a &SessionId; no session-internal handles leak through the API.
  3. Pure value types: all inputs and outputs are value types (no callbacks, no Arc-leaked internals).
  4. Cooperative cancellation only: cancel signals the session via a CancellationToken; no JoinHandle::abort() or process kill may be invoked.
  5. Sink-free progress fan-out: observe returns a broadcast::Receiver wrapper that is valid without any pre-registered observer. Multiple concurrent subscribers each receive the full event stream independently.
  6. Immediate SessionId return: spawn returns the SessionId before execution completes.
  7. Single trait, all verbs: CLI, Server, and programmatic callers all use this single trait.

§Async vs sync verbs

All verbs are async fn except observe, which is a synchronous fn. observe is sync because broadcast::Sender::subscribe() is itself synchronous and does not perform I/O — making it async would force callers to .await without reason and obscure the sink-free subscription semantics.

Required Methods§

Source

fn spawn<'life0, 'async_trait>( &'life0 self, spec: SessionSpec, ) -> Pin<Box<dyn Future<Output = Result<SessionId, SpawnError>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait,

Spawn a new execution session from the given specification.

Returns the SessionId immediately; execution proceeds in the background.

§Errors
Source

fn state<'life0, 'life1, 'async_trait>( &'life0 self, id: &'life1 SessionId, ) -> Pin<Box<dyn Future<Output = Result<ExecutionState, StateError>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Query the current state of a session.

§Errors
Source

fn resume<'life0, 'life1, 'async_trait>( &'life0 self, id: &'life1 SessionId, payload: ResumePayload, ) -> Pin<Box<dyn Future<Output = Result<ResumeOutcome, ResumeError>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Resume a paused session by providing LLM responses.

The payload kind must match the pause kind of the session (single vs batch).

§Errors
Source

fn cancel<'life0, 'life1, 'async_trait>( &'life0 self, id: &'life1 SessionId, reason: CancelReason, ) -> Pin<Box<dyn Future<Output = Result<(), CancelError>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Request cooperative cancellation of a session.

cancel is idempotent: calling it on a session already in a terminal state (Done, Failed, Cancelled) returns Ok(()). The only error case is when no session with the given id exists.

Cancellation is delivered via a CancellationToken; the engine checks at exactly four checkpoints (A/B/C/D) and transitions cooperatively to Cancelled. No JoinHandle::abort() or process kill path is introduced.

§Errors
Source

fn observe( &self, id: &SessionId, ) -> Result<Box<dyn ObserverHandle>, ObserveError>

Subscribe to the progress event stream for a session.

Returns a Box<dyn ObserverHandle> that delivers super::progress::ProgressEvent events from the session’s broadcast channel. Multiple concurrent subscribers each receive the full event stream independently (sink-free fan-out).

This is a synchronous fn (not async) because broadcast::Sender::subscribe() is synchronous and performs no I/O.

§Errors
Source

fn await_terminal<'life0, 'life1, 'async_trait>( &'life0 self, id: &'life1 SessionId, ) -> Pin<Box<dyn Future<Output = Result<TerminalOutcome, AwaitError>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Await the terminal state of a session.

Blocks (asynchronously) until the session transitions to Done, Cancelled, or Failed. Returns the terminal outcome.

§Errors

Implementors§