forge_agent/workflow/
mod.rs

1//! Workflow orchestration system for multi-step agent operations.
2//!
3//! The workflow module provides a DAG-based task scheduling system that:
4//! - Executes tasks in topological order based on dependencies
5//! - Validates workflows for cycles and missing dependencies before execution
6//! - Records all task events to the audit log
7//! - Supports sequential execution with failure handling
8//! - Provides cooperative cancellation for long-running workflows
9//! - Supports timeout configuration for tasks and workflows
10//!
11//! # Architecture
12//!
13//! The workflow system is built around three core components:
14//! - [`DAG`](crate::workflow::dag::Workflow): Directed acyclic graph for task representation
15//! - [`WorkflowTask`](crate::workflow::task::WorkflowTask): Async trait for task execution
16//! - [`WorkflowExecutor`](crate::workflow::executor::WorkflowExecutor): Sequential task executor
17//!
18//! # Cancellation and Timeouts
19//!
20//! ## Cancellation
21//!
22//! Workflows support cooperative cancellation via [`CancellationToken`]:
23//!
24//! ```ignore
25//! use forge_agent::workflow::{CancellationTokenSource, WorkflowExecutor};
26//! use forge_agent::workflow::dag::Workflow;
27//!
28//! let source = CancellationTokenSource::new();
29//! let mut executor = WorkflowExecutor::new(workflow)
30//!     .with_cancellation_source(source);
31//!
32//! // Cancel from anywhere
33//! source.cancel();
34//! ```
35//!
36//! Tasks can cooperatively respond to cancellation by polling the token:
37//!
38//! ```ignore
39//! use forge_agent::workflow::task::TaskContext;
40//!
41//! async fn my_task(context: &TaskContext) -> Result<TaskResult, TaskError> {
42//!     while !context.cancellation_token().map_or(false, |t| t.poll_cancelled()) {
43//!         // Do work
44//!     }
45//!     Ok(TaskResult::Cancelled)
46//! }
47//! ```
48//!
49//! See [`examples`](crate::workflow::examples) for complete cancellation-aware task examples.
50//!
51//! ## Timeouts
52//!
53//! Both tasks and workflows can have timeout limits:
54//!
55//! ```ignore
56//! use std::time::Duration;
57//! use forge_agent::workflow::{WorkflowExecutor, WorkflowTimeout};
58//!
59//! let mut executor = WorkflowExecutor::new(workflow)
60//!     .with_workflow_timeout(WorkflowTimeout::from_secs(300));
61//! ```
62//!
63//! See [`timeout`](crate::workflow::timeout) module for timeout configuration options.
64//!
65//! # Quick Start
66//!
67//! ```ignore
68//! use forge_agent::{Workflow, WorkflowExecutor, MockTask};
69//!
70//! let mut workflow = Workflow::new();
71//! workflow.add_task(MockTask::new("a", "Task A"));
72//! workflow.add_task(MockTask::new("b", "Task B").depends_on("a"));
73//!
74//! let mut executor = WorkflowExecutor::new(workflow);
75//! let result = executor.execute().await?;
76//! ```
77//!
78//! # Workflow Validation
79//!
80//! Workflows are validated before execution to detect:
81//! - Cycles in the dependency graph
82//! - Missing dependencies (references to non-existent tasks)
83//! - Orphan tasks (disconnected from the main graph)
84//!
85//! # Execution Model
86//!
87//! The executor processes tasks sequentially in topological order:
88//! 1. Validate workflow structure
89//! 2. Calculate execution order via topological sort
90//! 3. Execute each task with audit logging
91//! 4. Stop on first failure (rollback is deferred to phase 08-05)
92
93pub mod auto_detect;
94pub mod builder;
95pub mod cancellation;
96pub mod checkpoint;
97pub mod combinators;
98pub mod dag;
99pub mod deadlock;
100pub mod examples;
101pub mod executor;
102pub mod rollback;
103pub mod state;
104pub mod task;
105pub mod tasks;
106pub mod timeout;
107pub mod tools;
108pub mod validate;
109pub mod yaml;
110
111// Re-export core types for public API
112pub use auto_detect::{
113    AutoDetectConfig, DependencyAnalyzer, DependencyReason, DependencySuggestion, SuggestedTaskType,
114    TaskSuggestion,
115};
116pub use builder::WorkflowBuilder;
117pub use cancellation::{CancellationToken, CancellationTokenSource, ChildToken};
118pub use checkpoint::{
119    can_proceed, extract_confidence, requires_rollback, validate_checkpoint, CheckpointId,
120    CheckpointSummary, RollbackRecommendation, ValidationCheckpoint, ValidationResult, ValidationStatus,
121    WorkflowCheckpoint, WorkflowCheckpointService,
122};
123pub use combinators::{ConditionalTask, ParallelTasks, TryCatchTask};
124pub use dag::{Workflow, WorkflowError};
125pub use deadlock::{DeadlockDetector, DeadlockError, DeadlockWarning, DeadlockWarningType};
126pub use executor::{WorkflowExecutor, WorkflowResult};
127pub use examples::{
128    CancellationAwareTask, PollingTask, TimeoutAndCancellationTask,
129    cooperative_cancellation_example, timeout_cancellation_example,
130};
131pub use rollback::{
132    CompensationReport, ExecutableCompensation, RollbackEngine, RollbackError, RollbackReport,
133    RollbackStrategy,
134};
135pub use state::{TaskStatus, TaskSummary, WorkflowState, WorkflowStatus};
136pub use task::{CompensationAction, CompensationType, Dependency, TaskContext, TaskError, TaskId, TaskResult, WorkflowTask};
137pub use tasks::{AgentLoopTask, FileEditTask, FunctionTask, GraphQueryTask, GraphQueryType, ShellCommandTask};
138pub use timeout::{TaskTimeout, TimeoutConfig, TimeoutError, WorkflowTimeout};
139pub use tools::{ProcessGuard, Tool, ToolError, ToolInvocation, ToolInvocationResult, ToolRegistry, ToolResult};
140pub use validate::{ValidationReport, WorkflowValidator};
141pub use yaml::{YamlWorkflow, YamlTask, YamlTaskParams, YamlTaskType, YamlWorkflowError};
forge_agent/workflow/mod.rs

forge_agent/workflow/
mod.rs
