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
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142

//! Parent relationship validation runtime tests.
//!
//! Responsibilities:
//! - Cover `parent_id` warnings and cycle errors.
//! - Verify parent lookup across active queue and done archive.
//! - Keep parent-chain semantics isolated from other relationships.
//!
//! Not handled here:
//! - Dependency graph validation.
//! - JSON deserialization coverage.
//!
//! Invariants/assumptions:
//! - Missing or self-parent cases are warnings, not hard errors.
//! - True parent cycles remain validation errors.

use crate::contracts::{QueueFile, TaskStatus};

use super::support::task_with_parent;
use crate::queue::validation::validate_queue_set;

#[test]
fn validate_warns_on_missing_parent() {
    let active = QueueFile {
        version: 1,
        tasks: vec![
            task_with_parent("RQ-0001", None),
            task_with_parent("RQ-0002", Some("RQ-9999")),
        ],
    };

    let warnings =
        validate_queue_set(&active, None, "RQ", 4, 10).expect("Should not error on missing parent");
    assert!(
        warnings
            .iter()
            .any(|warning| warning.task_id == "RQ-0002"
                && warning.message.contains("does not exist")),
        "Should warn about missing parent: {:?}",
        warnings
    );
}

#[test]
fn validate_warns_on_self_parent() {
    let active = QueueFile {
        version: 1,
        tasks: vec![task_with_parent("RQ-0001", Some("RQ-0001"))],
    };

    let warnings =
        validate_queue_set(&active, None, "RQ", 4, 10).expect("Should not error on self-parent");
    assert!(
        warnings
            .iter()
            .any(|warning| warning.task_id == "RQ-0001" && warning.message.contains("itself")),
        "Should warn about self-parent: {:?}",
        warnings
    );
}

#[test]
fn validate_errors_on_parent_cycle() {
    let active = QueueFile {
        version: 1,
        tasks: vec![
            task_with_parent("RQ-0001", Some("RQ-0002")),
            task_with_parent("RQ-0002", Some("RQ-0001")),
        ],
    };

    let err =
        validate_queue_set(&active, None, "RQ", 4, 10).expect_err("Should error on parent cycle");
    assert!(
        err.to_string().contains("Circular parent chain"),
        "Error should mention circular parent chain: {err}"
    );
}

#[test]
fn validate_ignores_whitespace_parent_id() {
    let mut child = task_with_parent("RQ-0001", None);
    child.parent_id = Some("   ".to_string());

    let active = QueueFile {
        version: 1,
        tasks: vec![child],
    };

    let warnings = validate_queue_set(&active, None, "RQ", 4, 10)
        .expect("Should not error on whitespace parent_id");
    assert!(
        warnings.is_empty(),
        "Should not warn about whitespace parent_id: {:?}",
        warnings
    );
}

#[test]
fn validate_accepts_valid_parent() {
    let active = QueueFile {
        version: 1,
        tasks: vec![
            task_with_parent("RQ-0001", None),
            task_with_parent("RQ-0002", Some("RQ-0001")),
        ],
    };

    let warnings =
        validate_queue_set(&active, None, "RQ", 4, 10).expect("Should not error on valid parent");
    assert!(
        !warnings
            .iter()
            .any(|warning| warning.message.contains("parent")),
        "Should not warn about valid parent: {:?}",
        warnings
    );
}

#[test]
fn validate_finds_parent_in_done() {
    let active = QueueFile {
        version: 1,
        tasks: vec![task_with_parent("RQ-0002", Some("RQ-0001"))],
    };
    let mut parent = task_with_parent("RQ-0001", None);
    parent.status = TaskStatus::Done;
    parent.completed_at = Some("2026-01-18T00:00:00Z".to_string());
    let done = QueueFile {
        version: 1,
        tasks: vec![parent],
    };

    let warnings = validate_queue_set(&active, Some(&done), "RQ", 4, 10)
        .expect("Should not error when parent is in done");
    assert!(
        !warnings
            .iter()
            .any(|warning| warning.message.contains("does not exist")),
        "Should not warn when parent exists in done: {:?}",
        warnings
    );
}