Module coordination 

Coordination — programmatic agent fleet management

Responsibility

Provide a complete agent coordination layer: define tasks in TOML, spawn agent processes, let them claim work atomically via filesystem locks, and monitor fleet health — all without manual terminal pane management.

Architecture

tasks.toml ──► TaskQueue (file-locked claiming)
                   │
                   ├──► AgentWorker 0 ──► claude process
                   ├──► AgentWorker 1 ──► claude process
                   ├──► AgentWorker N ──► claude process
                   │
              AgentMonitor (health checks, status)

Modules

• task — Task struct, TaskStatus, priority ordering
• config — CoordinationConfig with defaults and validation
• queue — TaskQueue with file-locked concurrent claiming
• worker — AgentWorker: spawn claude process, capture output
• spawner — AgentSpawner: spawn N agents, manage fleet lifecycle
• monitor — AgentMonitor: health checks, fleet status snapshots

Guarantees

• Atomic claiming: no task is ever executed twice (filesystem locks)
• Crash recovery: stale locks from dead agents are reclaimable
• Priority ordering: highest-priority tasks are claimed first
• Observable: fleet status available at any time via monitor snapshots
• Zero panics: all operations return Result, never panic

NOT Responsible For

• LLM inference (see: worker module at crate root)
• Pipeline stages (see: stages module)
• Web API (see: web_api module)

Example

use tokio_prompt_orchestrator::coordination::{
    config::CoordinationConfig,
    queue::TaskQueue,
    spawner::{AgentSpawner, await_fleet},
};
use std::sync::Arc;

let config = Arc::new(CoordinationConfig::default());
let queue = Arc::new(TaskQueue::new(config.clone()).await?);
let spawner = AgentSpawner::new(config);
let handles = spawner.spawn_fleet(queue).await?;
let stats = await_fleet(handles).await;
for s in &stats {
    println!("{}: {} completed, {} failed", s.agent_id, s.tasks_completed, s.tasks_failed);
}

Modules

config

CoordinationConfig — agent fleet configuration

monitor

AgentMonitor - fleet health monitoring

queue

TaskQueue — file-locked concurrent task claiming

spawner

AgentSpawner — fleet spawning and coordination

task

Task — coordination work unit

worker

AgentWorker — single agent process manager

Enums

CoordinationError

Errors specific to the agent coordination layer.