brainwires_agent_network/
agent_manager.rs

1//! AgentManager trait and supporting types for agent lifecycle abstraction
2//!
3//! Provides a reusable trait that any MCP server implementation can implement
4//! to expose agent spawning, monitoring, and control operations without
5//! depending on CLI-specific types.
6
7use anyhow::Result;
8use async_trait::async_trait;
9use serde::{Deserialize, Serialize};
10use serde_json::Value;
11
12/// Configuration for spawning a new agent
13#[derive(Debug, Clone, Serialize, Deserialize)]
14pub struct SpawnConfig {
15    /// Description of the task for the agent to execute
16    pub description: String,
17    /// Optional working directory for file operations
18    pub working_directory: Option<String>,
19    /// Optional maximum number of iterations (default: 100)
20    pub max_iterations: Option<u32>,
21    /// Enable automatic validation checks before completion
22    pub enable_validation: Option<bool>,
23    /// Build type for validation (e.g. "npm", "cargo", "typescript")
24    pub build_type: Option<String>,
25    /// Opaque blob for implementation-specific config (e.g. MDAP settings)
26    pub extra: Option<Value>,
27}
28
29/// Information about a running or completed agent
30#[derive(Debug, Clone, Serialize, Deserialize)]
31pub struct AgentInfo {
32    /// Unique agent identifier
33    pub agent_id: String,
34    /// Current agent status (e.g. "running", "completed", "failed")
35    pub status: String,
36    /// Description of the task the agent is working on
37    pub task_description: String,
38    /// Number of iterations completed so far
39    pub iterations: u32,
40}
41
42/// Result from a completed agent
43#[derive(Debug, Clone, Serialize, Deserialize)]
44pub struct AgentResult {
45    /// Unique agent identifier
46    pub agent_id: String,
47    /// Whether the agent completed successfully
48    pub success: bool,
49    /// Human-readable summary of what was accomplished
50    pub summary: String,
51    /// Total number of iterations used
52    pub iterations: u32,
53}
54
55/// Trait for agent lifecycle management
56///
57/// Implement this trait to expose agent spawning and control capabilities
58/// via an MCP server without coupling to CLI-specific internals.
59#[async_trait]
60pub trait AgentManager: Send + Sync {
61    /// Spawn a new agent and return its ID
62    async fn spawn_agent(&self, config: SpawnConfig) -> Result<String>;
63
64    /// List all currently active agents
65    async fn list_agents(&self) -> Result<Vec<AgentInfo>>;
66
67    /// Get the current status of a specific agent
68    async fn agent_status(&self, agent_id: &str) -> Result<AgentInfo>;
69
70    /// Stop a running agent
71    async fn stop_agent(&self, agent_id: &str) -> Result<()>;
72
73    /// Wait for an agent to complete and return its result
74    ///
75    /// If `timeout_secs` is `Some`, returns an error if the agent has not
76    /// completed within the given number of seconds.
77    async fn await_agent(&self, agent_id: &str, timeout_secs: Option<u64>) -> Result<AgentResult>;
78
79    /// Return pool-level statistics as a JSON value
80    async fn pool_stats(&self) -> Result<Value>;
81
82    /// Return all currently held file locks as a JSON value
83    async fn file_locks(&self) -> Result<Value>;
84}
brainwires_agent_network/agent_manager.rs

brainwires_agent_network/
agent_manager.rs
