ralph-agent-loop 0.3.1

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
72
73

//! Task start handler for `ralph task start`.
//!
//! Responsibilities:
//! - Set `started_at` for a task (RFC3339 UTC).
//! - Transition task status to `doing` when appropriate.
//!
//! Not handled here:
//! - Terminal completion/archiving (see `status.rs` and `queue::complete_task`).
//! - Batch operations (see `batch.rs`).
//!
//! Invariants/assumptions:
//! - Queue file is locked during mutation.
//! - Status transition policy centralizes timestamp invariants (preferred).

use crate::cli::task::args::TaskStartArgs;
use crate::config;
use crate::contracts::TaskStatus;
use crate::queue;
use crate::timeutil;
use anyhow::{Result, bail};

pub fn handle(args: &TaskStartArgs, force: bool, resolved: &config::Resolved) -> Result<()> {
    let _queue_lock = queue::acquire_queue_lock(&resolved.repo_root, "task start", force)?;

    // Create undo snapshot before mutation
    crate::undo::create_undo_snapshot(resolved, &format!("task start {}", args.task_id))?;

    let mut queue_file = queue::load_queue(&resolved.queue_path)?;
    let now = timeutil::now_utc_rfc3339()?;

    let task_id = args.task_id.clone();

    let task = queue_file
        .tasks
        .iter_mut()
        .find(|t| t.id == task_id)
        .ok_or_else(|| {
            anyhow::anyhow!(
                "{}",
                crate::error_messages::task_not_found_in_queue(&task_id)
            )
        })?;

    if matches!(task.status, TaskStatus::Done | TaskStatus::Rejected) {
        bail!(
            "Cannot start task {} because it is terminal (status: {}).",
            task.id,
            task.status
        );
    }

    if task.started_at.is_some() && !args.reset {
        println!(
            "Task {} already started at {}; no change.",
            task.id,
            task.started_at.as_deref().unwrap_or("")
        );
        return Ok(());
    }

    let task_id_for_msg = task.id.clone();
    task.started_at = Some(now.clone());

    if task.status != TaskStatus::Doing {
        queue::apply_status_policy(task, TaskStatus::Doing, &now, None)?;
    } else {
        task.updated_at = Some(now.clone());
    }

    queue::save_queue(&resolved.queue_path, &queue_file)?;
    println!("Started task {} (status: doing).", task_id_for_msg);
    Ok(())
}