Struct CoreEngine 

pub struct CoreEngine<Ctx, Out> { /* private fields */ }

The core agent engine that orchestrates the agent loop.

Generic over the context type Ctx and output type Out. Construct using EngineBuilder. The engine drives the main think-process cycle with plugin-based extension points for context building and output processing.

The loop continues until an output processor signals Signal::Stop or the cancellation token is triggered.

Implementations

impl<Ctx, Out> CoreEngine<Ctx, Out>

where Ctx: Clone + Send + Sync, Out: Send + Sync,

pub async fn run(&self, initial: Ctx) -> Result<Ctx, EngineError>

Runs the agent loop to completion and returns the final context.

Each iteration:

1. Checks the cancellation token
2. Runs the context builder chain (each may modify the context)
3. Calls the thinker to produce output
4. Runs the output processor chain (first Stop wins)

The loop continues until a processor returns Signal::Stop or cancellation is triggered.

If no output processors are registered, the loop executes exactly one turn and returns. This prevents an infinite loop when the engine has nothing that can signal stop.

Parameters

• initial — The starting context for the first iteration.

Returns

The final context after the last processor chain (or after a single turn when no processors are configured). Processors may have mutated the context (for example, appended messages).

Errors

Returns EngineError::Cancelled if the cancellation token is triggered. Propagates errors from thinkers, context builders, and output processors.

pub async fn run_with_output( &self, initial: Ctx, ) -> Result<(Ctx, Option<Out>), EngineError>

Runs the agent loop to completion, returning the final context and the last thinker output (if any turn completed).

Same loop as run, but also yields the output from the final turn so outer paradigms (e.g. Ralph) can verify it without losing the result when processors signal Signal::Stop.

Returns

(final_ctx, Some(last_output)) after at least one successful think. (final_ctx, None) only if the loop exits before thinking (should not occur under normal processor configurations).

pub async fn run_once( &self, ctx: &mut Ctx, ) -> Result<TurnResult<Out>, EngineError>

Runs a single turn of the engine loop.

Executes one complete iteration:

1. Checks the cancellation token
2. Runs the context builder chain on the mutable context
3. Calls the thinker to produce output
4. Runs the output processor chain (shared &output, first Stop wins)

Always returns the thinker output. TurnResult::stopped is true when a processor signalled Signal::Stop (including a normal terminal text turn from tool orchestration).

Errors

Returns EngineError::Cancelled if the cancellation token is triggered. Propagates errors from thinkers, context builders, and output processors.

pub fn cancel_handle(&self) -> CancellationToken

Returns a cloneable handle to the engine’s cancellation token.

External code can clone this token and call .cancel() to trigger graceful shutdown of the engine loop at the start of the next iteration.