pub struct ProcessRegistry { /* private fields */ }Expand description
Central registry for managing running agent processes
The ProcessRegistry maintains a thread-safe map of all running processes, providing lifecycle management, monitoring, and termination capabilities.
§Thread Safety
The registry uses async-aware locking (tokio::sync::Mutex) for the
process map to avoid blocking async tasks. Process handles use
standard std::sync::Mutex for synchronous operations.
§Process Lifecycle
1. Register → Process added to registry with metadata
2. Running → Process executes, output is captured
3. Kill → Graceful shutdown attempted, then force kill
4. Cleanup → Process removed from registryImplementations§
Source§impl ProcessRegistry
impl ProcessRegistry
Sourcepub fn generate_id(&self) -> Result<i64, String>
pub fn generate_id(&self) -> Result<i64, String>
Generate a unique run ID
Returns the next available run ID and increments the counter. IDs start at 1,000,000 and increase sequentially.
§Errors
Returns an error if the ID counter mutex is poisoned.
§Example
use bamboo_agent::process::registry::ProcessRegistry;
let registry = ProcessRegistry::new();
let id = registry.generate_id().unwrap();
assert!(id >= 1000000);Sourcepub async fn register_process(
&self,
config: ProcessRegistrationConfig,
child: Child,
) -> Result<(), String>
pub async fn register_process( &self, config: ProcessRegistrationConfig, child: Child, ) -> Result<(), String>
Register a new agent run process
Adds a newly spawned agent process to the registry with its configuration and process handle.
§Arguments
config- Registration configuration with agent metadatachild- The spawned child process handle
§Returns
Returns Ok(()) if registration succeeds.
§Errors
Returns an error if the process map lock fails.
§Example
use bamboo_agent::process::registry::{ProcessRegistry, ProcessRegistrationConfig};
use tokio::process::Command;
#[tokio::main]
async fn main() -> Result<(), String> {
let registry = ProcessRegistry::new();
let mut child = Command::new("agent-binary")
.spawn()
.map_err(|e| e.to_string())?;
let config = ProcessRegistrationConfig {
run_id: 1000001,
agent_id: 1,
agent_name: "MyAgent".to_string(),
pid: child.id().unwrap_or(0),
project_path: "/project".to_string(),
task: "Analyze code".to_string(),
model: "claude-3-5-sonnet".to_string(),
};
registry.register_process(config, child).await
}Sourcepub async fn register_sidecar_process(
&self,
config: ProcessRegistrationConfig,
) -> Result<(), String>
pub async fn register_sidecar_process( &self, config: ProcessRegistrationConfig, ) -> Result<(), String>
Register a sidecar process without a direct child handle
Used for processes that are managed externally (e.g., by Tauri) but still need to be tracked in the registry for monitoring.
§Arguments
config- Registration configuration with agent metadata
§Returns
Returns Ok(()) if registration succeeds.
§Errors
Returns an error if the process map lock fails.
Sourcepub async fn register_claude_session(
&self,
session_id: String,
pid: u32,
project_path: String,
task: String,
model: String,
child: Arc<Mutex<Option<Child>>>,
) -> Result<i64, String>
pub async fn register_claude_session( &self, session_id: String, pid: u32, project_path: String, task: String, model: String, child: Arc<Mutex<Option<Child>>>, ) -> Result<i64, String>
Register a Claude interactive session process
Adds a Claude session to the registry, generating a unique run ID if one isn’t provided.
§Arguments
session_id- Claude session identifierpid- Operating system process IDproject_path- Project directory pathtask- Task descriptionmodel- Model identifierchild- Optional child process handle wrapped in Arc
§Returns
Returns the generated or provided run ID on success.
§Errors
Returns an error if ID generation or process map lock fails.
Sourcepub async fn get_running_claude_sessions(
&self,
) -> Result<Vec<ProcessInfo>, String>
pub async fn get_running_claude_sessions( &self, ) -> Result<Vec<ProcessInfo>, String>
Sourcepub async fn get_claude_session_by_id(
&self,
session_id: &str,
) -> Result<Option<ProcessInfo>, String>
pub async fn get_claude_session_by_id( &self, session_id: &str, ) -> Result<Option<ProcessInfo>, String>
Sourcepub async fn unregister_process(&self, run_id: i64) -> Result<(), String>
pub async fn unregister_process(&self, run_id: i64) -> Result<(), String>
Remove a process from the registry
Unregisters a process by its run ID. This does NOT kill the process; it only removes it from tracking.
§Arguments
run_id- The run ID of the process to remove
§Returns
Returns Ok(()) whether or not the process existed.
§Errors
Returns an error if the process map lock fails.
Sourcepub async fn get_running_processes(&self) -> Result<Vec<ProcessInfo>, String>
pub async fn get_running_processes(&self) -> Result<Vec<ProcessInfo>, String>
Sourcepub async fn get_running_agent_processes(
&self,
) -> Result<Vec<ProcessInfo>, String>
pub async fn get_running_agent_processes( &self, ) -> Result<Vec<ProcessInfo>, String>
Sourcepub async fn get_process(
&self,
run_id: i64,
) -> Result<Option<ProcessInfo>, String>
pub async fn get_process( &self, run_id: i64, ) -> Result<Option<ProcessInfo>, String>
Sourcepub async fn kill_process(&self, run_id: i64) -> Result<bool, String>
pub async fn kill_process(&self, run_id: i64) -> Result<bool, String>
Kill a process by run ID
Attempts graceful shutdown first using the child process handle, then falls back to system-level process termination if needed.
§Process
- Send kill signal via child handle
- Wait up to 5 seconds for graceful exit
- If timeout, use system kill command (kill -KILL or taskkill)
- Remove process from registry
§Arguments
run_id- The run ID of the process to kill
§Returns
Ok(true) if the process was killed successfully,
Ok(false) if the process wasn’t found.
§Errors
Returns an error if process termination fails critically.
§Cross-Platform
- Unix: Uses SIGTERM first, then SIGKILL if needed
- Windows: Uses taskkill /F
Sourcepub async fn kill_process_by_pid(
&self,
run_id: i64,
pid: u32,
) -> Result<bool, String>
pub async fn kill_process_by_pid( &self, run_id: i64, pid: u32, ) -> Result<bool, String>
Kill a process by its operating system PID
Uses system commands to terminate a process when the child handle is not available or has already been dropped.
§Arguments
run_id- Run ID for registry cleanuppid- Operating system process ID
§Returns
Ok(true) if kill succeeded, Ok(false) if it failed.
§Errors
Returns an error if the kill command cannot be executed.
§Cross-Platform Behavior
- Unix: Tries SIGTERM first, waits 2 seconds, then SIGKILL
- Windows: Uses taskkill /F immediately
Sourcepub async fn append_live_output(
&self,
run_id: i64,
output: &str,
) -> Result<(), String>
pub async fn append_live_output( &self, run_id: i64, output: &str, ) -> Result<(), String>
Append output to a process’s live output buffer
Adds a line of output to the process’s output buffer for later retrieval.
§Arguments
run_id- The run ID of the processoutput- The output text to append
§Returns
Returns Ok(()) whether or not the process exists.
§Errors
Returns an error if lock acquisition fails.