loopkeel 0.1.0

A resilient CLI orchestrator for agentic work loops
pub mod state;
pub mod stop_criteria;

mod config;
mod persistence;
mod retry;

use crate::{
    adapters,
    cli::{Agent, OutputFormat, StartArgs},
    error::{LoopError, Result},
};
use state::{now, LoopState, LoopStatus};
use std::{path::PathBuf, time::Duration};
use tokio::{fs, sync::mpsc, time};
use tracing::{info, warn, Instrument};

#[derive(Debug)]
pub struct Engine {
    root: PathBuf,
    agent: Agent,
    output: OutputFormat,
}

impl Engine {
    pub fn root_dir(&self) -> PathBuf {
        self.root.clone()
    }
}

#[derive(Debug)]
pub struct EngineOptions {
    pub goal: String,
    pub plan: Option<PathBuf>,
    pub max_iterations: Option<u64>,
    pub timeout: Option<u64>,
    pub success_command: Option<String>,
    pub retries: Option<u32>,
    pub backoff_ms: Option<u64>,
    pub buffer_limit: Option<usize>,
}

impl From<StartArgs> for EngineOptions {
    fn from(a: StartArgs) -> Self {
        Self {
            goal: a.goal.unwrap_or_default(),
            plan: a.plan,
            max_iterations: a.max_iterations,
            timeout: a.timeout,
            success_command: a.success_command,
            retries: a.retries,
            backoff_ms: a.backoff_ms,
            buffer_limit: a.buffer_limit,
        }
    }
}

impl Engine {
    pub fn new(root: PathBuf, agent: Agent, output: OutputFormat) -> Result<Self> {
        Ok(Self {
            root,
            agent,
            output,
        })
    }
    fn dir(&self) -> PathBuf {
        self.root.join(".loop")
    }
    pub async fn start(&self, mut opts: EngineOptions) -> Result<()> {
        if opts.goal.is_empty() {
            if let Some(plan) = &opts.plan {
                opts.goal = fs::read_to_string(plan).await?;
            }
        }
        if opts.goal.is_empty() {
            return Err(LoopError::MissingGoal);
        }
        let config = config::read(&self.root).await?;
        let max_iterations = opts.max_iterations.or(config.max_iterations).unwrap_or(10);
        let timeout = opts.timeout.or(config.timeout);
        let success_command = opts.success_command.or(config.success_command);
        let retries = opts.retries.or(config.retries).unwrap_or(3);
        let backoff_ms = opts.backoff_ms.or(config.backoff_ms).unwrap_or(500);
        let buffer_limit = opts.buffer_limit.or(config.buffer_limit).unwrap_or(64);
        let mut state = match persistence::load(&self.root).await {
            Ok(existing) if !matches!(existing.status, LoopStatus::Completed) => existing,
            _ => LoopState::new(opts.goal),
        };
        persistence::save(&self.root, &state).await?;
        persistence::append_event(&self.root, &state, "started").await?;
        let (tx, mut rx) = mpsc::channel::<String>(8);
        let control = persistence::control_path(&self.root);
        let watcher = tokio::spawn(async move {
            let mut tick = time::interval(Duration::from_millis(250));
            loop {
                tick.tick().await;
                if let Ok(cmd) = fs::read_to_string(&control).await {
                    let _ = tx.send(cmd.trim().to_string()).await;
                    let _ = fs::remove_file(&control).await;
                }
            }
        });
        let mut ticks = time::interval(Duration::from_millis(10));
        let mut terminate =
            tokio::signal::unix::signal(tokio::signal::unix::SignalKind::terminate())?;
        loop {
            tokio::select! {
                signal = tokio::signal::ctrl_c() => { signal?; state.status = LoopStatus::Stopped; state.updated_at = now(); state.last_action = "interrupted; checkpoint saved".into(); persistence::save(&self.root, &state).await?; persistence::append_event(&self.root, &state, "stopped").await?; break; }
                signal = terminate.recv() => { signal.ok_or(LoopError::NoCheckpoint)?; state.status = LoopStatus::Stopped; state.updated_at = now(); state.last_action = "terminated; checkpoint saved".into(); persistence::save(&self.root, &state).await?; persistence::append_event(&self.root, &state, "stopped").await?; break; }
                Some(command) = rx.recv() => { match command.as_str() { "pause" => state.status = LoopStatus::Paused, "resume" => state.status = LoopStatus::Running, "stop" => state.status = LoopStatus::Stopped, "complete" => state.status = LoopStatus::Completed, _ => warn!(command = %command, "unknown control command") } state.updated_at = now(); persistence::save(&self.root, &state).await?; persistence::append_event(&self.root, &state, &command).await?; if !matches!(state.status, LoopStatus::Running | LoopStatus::Paused) { break; } }
                _ = ticks.tick(), if state.status == LoopStatus::Running => { let passed = self.perform_step(&mut state, timeout, success_command.as_deref(), retries, backoff_ms, buffer_limit).await?; if stop_criteria::reached(&state, max_iterations, passed) { state.status = LoopStatus::Completed; persistence::save(&self.root, &state).await?; break; } }
            }
        }
        watcher.abort();
        info!(iteration = state.iteration, status = ?state.status, "loop finished");
        Ok(())
    }

    async fn perform_step(
        &self,
        state: &mut LoopState,
        timeout: Option<u64>,
        success_command: Option<&str>,
        retries: u32,
        backoff_ms: u64,
        _buffer_limit: usize,
    ) -> Result<bool> {
        let span = tracing::info_span!("iteration", number = state.iteration + 1);
        async {
            state.iteration += 1;
            state.updated_at = now();
            state.last_action = format!("agent planning/executing goal: {}", state.goal);
            persistence::append_event(&self.root, state, &state.last_action).await?;
            let rendered = adapters::render(
                &self.agent,
                &self.output,
                state.iteration,
                &state.last_action,
                &state.goal,
            );
            info!(message = %rendered, "iteration action");
            let passed = if let Some(command) = success_command {
                match retry::command(command, retries, backoff_ms, timeout).await {
                    Ok(true) => {
                        state.successes += 1;
                        state.last_action = "success condition passed".into();
                        true
                    }
                    Ok(false) => false,
                    Err(error) => {
                        state.errors += 1;
                        state.last_error = Some(error.to_string());
                        state.status = LoopStatus::Failed;
                        persistence::save(&self.root, state).await?;
                        return Err(error);
                    }
                }
            } else {
                state.successes += 1;
                false
            };
            persistence::save(&self.root, state).await?;
            Ok::<bool, LoopError>(passed)
        }
        .instrument(span)
        .await
    }
    pub async fn step(&self) -> Result<()> {
        let mut state = persistence::load(&self.root).await?;
        if state.status == LoopStatus::Paused
            || matches!(state.status, LoopStatus::Completed | LoopStatus::Stopped)
        {
            return Ok(());
        }
        let goal = state.goal.clone();
        self.perform_step(&mut state, None, None, 0, 0, 64).await?;
        let _ = goal;
        Ok(())
    }
    pub async fn status(&self) -> Result<()> {
        let state = persistence::load(&self.root).await?;
        match self.output {
            OutputFormat::Json => println!("{}", serde_json::to_string(&state)?),
            OutputFormat::Text => println!(
                "status={:?} iteration={} successes={} last_action={}",
                state.status, state.iteration, state.successes, state.last_action
            ),
        }
        Ok(())
    }
    pub async fn control(&self, command: &str) -> Result<()> {
        fs::create_dir_all(self.dir()).await?;
        fs::write(persistence::control_path(&self.root), command).await?;
        println!("sent {command}");
        Ok(())
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    #[tokio::test]
    async fn checkpoint_is_written_each_step() {
        let dir = tempfile::tempdir().unwrap();
        let e = Engine::new(dir.path().into(), Agent::Codex, OutputFormat::Json).unwrap();
        e.start(EngineOptions {
            goal: "test".into(),
            plan: None,
            max_iterations: Some(1),
            timeout: None,
            success_command: None,
            retries: None,
            backoff_ms: None,
            buffer_limit: Some(4),
        })
        .await
        .unwrap();
        let s = persistence::load(dir.path()).await.unwrap();
        assert_eq!(s.iteration, 1);
        assert_eq!(s.status, LoopStatus::Completed);
    }
}