Module engine 

Core engine loop implementation. Core engine loop implementation.

Provides the generic CoreEngine<Ctx, Out> struct with a run method that executes the agent loop, along with an EngineBuilder<Ctx, Out> for fluent construction.

Architecture

The engine orchestrates the agent data-flow pipeline:

Ctx → [ContextBuilder chain] → Thinker → [OutputProcessor chain] → Signal

Each iteration:

1. Context flows through a chain of context builders (each can modify it)
2. The thinker produces output from the context
3. Output flows through a chain of processors (any can signal Stop)

Type Erasure

Since Rust’s native async functions in traits are not object-safe, this module provides type-erased wrapper types (DynThinker, DynContextBuilder, DynOutputProcessor) that allow heterogeneous chains of different concrete types via boxing. Each wrapper struct implements the corresponding trait by dispatching to an internal erased trait object.

Example

use xz_agent_core::engine::{CoreEngine, EngineBuilder};
use xz_agent_core::traits::thinker::Thinker;
use xz_agent_core::traits::context::ContextBuilder;
use xz_agent_core::traits::processor::OutputProcessor;
use xz_agent_core::error::EngineError;
use xz_agent_core::types::signal::Signal;

// A simple thinker that echoes input.
struct EchoThinker;
impl Thinker for EchoThinker {
    type Context = String;
    type Output = String;
    async fn think(&self, ctx: &Self::Context) -> Result<Self::Output, EngineError> {
        Ok(ctx.clone())
    }
}

// A processor that stops after the first turn.
struct OneShot;
impl OutputProcessor for OneShot {
    type Context = String;
    type Output = String;
    async fn process(
        &self,
        _output: &Self::Output,
        _ctx: &mut Self::Context,
    ) -> Result<Signal, EngineError> {
        Ok(Signal::Stop)
    }
}

let engine: CoreEngine<String, String> = EngineBuilder::new()
    .thinker(EchoThinker)
    .processor(OneShot)
    .build()
    .unwrap();

Structs

CoreEngine

The core agent engine that orchestrates the agent loop.

DynContextBuilder

A concrete wrapper that implements ContextBuilder via type-erased dispatch.

DynOutputProcessor

A concrete wrapper that implements OutputProcessor via type-erased dispatch.

DynThinker

A concrete wrapper that implements Thinker via type-erased dispatch.

EngineBuilder

Fluent builder for constructing a CoreEngine.

TurnResult

Result of a single engine turn (CoreEngine::run_once).