ralph-workflow 0.7.18

PROMPT-driven multi-agent orchestrator for git repos
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

//! Pipeline event types for reducer architecture.
//!
//! Defines all possible events that can occur during pipeline execution.
//! Each event represents a **fact** about what happened, not a command about
//! what to do next.
//!
//! # Event-Sourced Reducer Architecture
//!
//! Ralph's pipeline follows an event-sourced reducer pattern:
//!
//! ```text
//! State → Orchestrate → Effect → Handle → Event → Reduce → State'
//! ```
//!
//! ## The Core Contract
//!
//! | Component | Pure? | Responsibility |
//! |-----------|-------|----------------|
//! | **Orchestration** | ✓ | Derives next effect from state only |
//! | **Handler** | ✗ | Executes effect, emits events describing outcome |
//! | **Reducer** | ✓ | Decides new state based on event |
//!
//! **Events are facts, not commands.**
//!
//! # Event Categories
//!
//! Events are organized into logical categories for type-safe routing to
//! category-specific reducers. Each category has a dedicated enum:
//!
//! - [`LifecycleEvent`] - Pipeline start/stop/resume
//! - [`PlanningEvent`] - Plan generation events
//! - [`DevelopmentEvent`] - Development iteration and continuation events
//! - [`ReviewEvent`] - Review pass and fix attempt events
//! - [`AgentEvent`] - Agent invocation and chain management events
//! - [`RebaseEvent`] - Git rebase operation events
//! - [`CommitEvent`] - Commit generation events
//! - [`AwaitingDevFixEvent`] - Dev-fix flow events
//! - [`PromptInputEvent`] - Prompt materialization events
//! - [`ErrorEvent`] - Typed error events from handlers
//!
//! The main [`PipelineEvent`] enum wraps these category enums to enable
//! type-safe dispatch in the reducer.
//!
//! # Frozen Policy
//!
//! Both [`LifecycleEvent`] and [`PipelineEvent`] are **FROZEN** - adding new variants
//! is prohibited. See their documentation for rationale and alternatives.
//!
//! # See Also
//!
//! - `docs/architecture/event-loop-and-reducers.md` - Detailed architecture doc
//! - `reducer::state_reduction` - Reducer implementations
//! - `reducer::orchestration` - Effect orchestration logic
//! - `reducer::handler` - Effect handler implementations

// These imports are used by constructors.rs (and included sub-files) via `super::`.
// Child modules can access private items from their parent module's scope.
use crate::agents::AgentRole;
use crate::reducer::state::DevelopmentStatus;
use std::path::PathBuf;

// ============================================================================
// Type Definitions Module
// ============================================================================

#[path = "types.rs"]
mod types;

// Re-export all type definitions
pub use types::{
    default_timeout_output_kind, AgentErrorKind, AwaitingDevFixEvent, CheckpointTrigger,
    CommitEvent, ConflictStrategy, LifecycleEvent, MaterializedPromptInput, PlanningEvent,
    ProcessExecutionResult, PromptInputEvent, PromptInputKind, RebaseEvent, RebasePhase,
    TimeoutOutputKind,
};

// ============================================================================
// Category Event Modules
// ============================================================================

#[path = "development.rs"]
mod development;
pub use development::DevelopmentEvent;

#[path = "review.rs"]
mod review;
pub use review::ReviewEvent;

#[path = "agent.rs"]
mod agent;
pub use agent::AgentEvent;

#[path = "error.rs"]
mod error;
pub use error::ErrorEvent;
pub use error::WorkspaceIoErrorKind;

// ============================================================================
// Constructor Module
// ============================================================================

#[path = "constructors.rs"]
mod constructors;

// ============================================================================
// Main Event Enum and Pipeline Phase
// ============================================================================

#[path = "pipeline_phase.rs"]
mod pipeline_phase;
pub use pipeline_phase::PipelinePhase;

#[path = "pipeline_event.rs"]
mod pipeline_event;
pub use pipeline_event::PipelineEvent;