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

Dyn Compatibility§

This trait is dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors§