ralph-agent-loop 0.4.0

A Rust CLI for managing AI agent loops with a structured JSON task queue
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71

//! Shared context and mutation helpers for batch task CLI operations.
//!
//! Responsibilities:
//! - Load queue/done state and shared batch metadata.
//! - Acquire queue locks and create undo snapshots for mutating operations.
//! - Persist updated queue/done files after batch mutations.
//!
//! Does not handle:
//! - Operation-specific queue mutations.
//! - Dry-run rendering or task selection.

use crate::config;
use crate::contracts::QueueFile;
use crate::lock;
use crate::queue;
use crate::timeutil;
use anyhow::Result;

pub(super) struct BatchContext<'a> {
    pub resolved: &'a config::Resolved,
    pub queue_file: QueueFile,
    pub done_file: QueueFile,
    pub now: String,
    pub max_depth: u8,
}

impl<'a> BatchContext<'a> {
    pub(super) fn load(resolved: &'a config::Resolved) -> Result<Self> {
        Ok(Self {
            resolved,
            queue_file: queue::load_queue(&resolved.queue_path)?,
            done_file: queue::load_queue_or_default(&resolved.done_path)?,
            now: timeutil::now_utc_rfc3339()?,
            max_depth: resolved.config.queue.max_dependency_depth.unwrap_or(10),
        })
    }

    pub(super) fn done_ref(&self) -> Option<&QueueFile> {
        if self.done_file.tasks.is_empty() && !self.resolved.done_path.exists() {
            None
        } else {
            Some(&self.done_file)
        }
    }

    pub(super) fn begin_mutation(
        &self,
        force: bool,
        snapshot_label: &str,
    ) -> Result<lock::DirLock> {
        let queue_lock = queue::acquire_queue_lock(&self.resolved.repo_root, "task batch", force)?;
        crate::undo::create_undo_snapshot(self.resolved, snapshot_label)?;
        Ok(queue_lock)
    }

    pub(super) fn reload_queue(&self) -> Result<QueueFile> {
        queue::load_queue(&self.resolved.queue_path)
    }

    pub(super) fn reload_done(&self) -> Result<QueueFile> {
        queue::load_queue_or_default(&self.resolved.done_path)
    }

    pub(super) fn save_queue(&self, queue_file: &QueueFile) -> Result<()> {
        queue::save_queue(&self.resolved.queue_path, queue_file)
    }

    pub(super) fn save_done(&self, done_file: &QueueFile) -> Result<()> {
        queue::save_queue(&self.resolved.done_path, done_file)
    }
}