Struct Ring 

pub struct Ring { /* private fields */ }

The Ring — the central coordinator for the Punch Agent Combat System.

Thread-safe by design: all collections use DashMap and all shared state is behind Arc. Wrap the Ring itself in an Arc to share across tasks.

Implementations

impl Ring

pub fn new( config: PunchConfig, memory: Arc<MemorySubstrate>, driver: Arc<dyn LlmDriver>, ) -> Self

Create a new Ring.

The caller provides the already-initialised memory substrate, LLM driver, and configuration. The Ring will create its own event bus and scheduler internally.

pub fn with_quota_config( config: PunchConfig, memory: Arc<MemorySubstrate>, driver: Arc<dyn LlmDriver>, quota_config: QuotaConfig, ) -> Self

Create a new Ring with a custom quota configuration.

pub fn event_bus(&self) -> &EventBus

Get a reference to the event bus.

pub fn scheduler(&self) -> &Scheduler

Get a reference to the scheduler.

pub fn memory(&self) -> &Arc<MemorySubstrate>

Get a reference to the memory substrate.

pub fn config(&self) -> &PunchConfig

Get a reference to the configuration.

pub fn background(&self) -> &BackgroundExecutor

Get a reference to the background executor.

pub fn workflow_engine(&self) -> &WorkflowEngine

Get a reference to the workflow engine.

pub fn metering(&self) -> &MeteringEngine

Get a reference to the metering engine.

pub fn budget_enforcer(&self) -> &Arc<BudgetEnforcer>

Get a reference to the budget enforcer.

pub fn trigger_engine(&self) -> &TriggerEngine

Get a reference to the trigger engine.

pub fn metrics(&self) -> &Arc<MetricsRegistry>

Get a reference to the metrics registry.

pub fn tenant_registry(&self) -> &TenantRegistry

Get a reference to the tenant registry.

pub fn marketplace(&self) -> &SkillMarketplace

Access the skill marketplace.

pub fn mcp_clients(&self) -> &Arc<DashMap<String, Arc<McpClient>>>

Access the active MCP clients.

pub async fn spawn_mcp_servers(&self)

Spawn and initialize all MCP servers defined in the configuration.

Each server is started as a subprocess, initialized via JSON-RPC 2.0 handshake, and its tools are discovered. Servers that fail to start are logged and skipped — they don’t block the Ring from operating.

pub async fn shutdown_mcp_servers(&self)

Shut down all active MCP servers gracefully.

pub async fn mcp_tools(&self) -> Vec<ToolDefinition>

Collect tool definitions from all active MCP servers.

pub async fn spawn_fighter_for_tenant( &self, tenant_id: &TenantId, manifest: FighterManifest, ) -> PunchResult<FighterId>

Spawn a fighter scoped to a tenant, enforcing quota limits.

Returns an error if the tenant is suspended or the fighter quota is exceeded.

pub fn list_fighters_for_tenant( &self, tenant_id: &TenantId, ) -> Vec<(FighterId, FighterManifest, FighterStatus)>

List fighters that belong to a specific tenant.

pub fn kill_fighter_for_tenant( &self, fighter_id: &FighterId, tenant_id: &TenantId, ) -> PunchResult<()>

Kill a fighter, validating that the caller tenant owns it.

Returns an error if the fighter doesn’t belong to the given tenant.

pub fn check_tenant_tool_access( &self, tenant_id: &TenantId, tool_name: &str, ) -> bool

Check whether a tenant’s tool access is allowed for the given tool name.

Returns true if the tenant has no tool restrictions (empty list) or the tool is in the allowed list.

pub fn register_trigger(&self, trigger: Trigger) -> TriggerId

Register a trigger with the engine.

pub fn remove_trigger(&self, id: &TriggerId)

Remove a trigger by ID.

pub fn list_triggers(&self) -> Vec<(TriggerId, TriggerSummary)>

List all triggers with summary information.

pub async fn spawn_fighter(&self, manifest: FighterManifest) -> FighterId

Spawn a new fighter from a manifest.

Returns the newly-assigned FighterId. The fighter starts in FighterStatus::Idle and is persisted to the memory substrate.

pub async fn ensure_creed(&self, fighter_name: &str, manifest: &FighterManifest)

Create a default creed for a fighter if none exists. The default creed includes self-awareness from the manifest.

pub async fn send_message( &self, fighter_id: &FighterId, message: String, ) -> PunchResult<FighterLoopResult>

Send a user message to a fighter and run the agent loop (without coordinator).

Convenience wrapper around [send_message_with_coordinator] that passes None, meaning the fighter will not have access to inter-agent tools.

pub async fn send_message_with_coordinator( &self, fighter_id: &FighterId, message: String, coordinator: Option<Arc<dyn AgentCoordinator>>, content_parts: Vec<ContentPart>, ) -> PunchResult<FighterLoopResult>

Send a user message to a fighter and run the agent loop.

This creates (or reuses) a bout for the fighter, checks quotas, then delegates to run_fighter_loop. Usage is recorded through the metering engine after a successful completion.

If coordinator is provided, the fighter can use inter-agent tools (agent_spawn, agent_message, agent_list).

pub fn heartbeat_scheduler(&self) -> &HeartbeatScheduler

Access the heartbeat scheduler (e.g. for refresh after heartbeat config changes).

pub fn set_channel_notifier(&self, notifier: Arc<dyn ChannelNotifier>)

Set the channel notifier for proactive heartbeat notifications.

Should be called once during API server setup after the channel bridge is constructed. Existing heartbeat monitors will pick up the notifier on their next refresh cycle.

pub fn kill_fighter(&self, fighter_id: &FighterId)

Kill (remove) a fighter.

pub fn list_fighters(&self) -> Vec<(FighterId, FighterManifest, FighterStatus)>

List all fighters with their current status.

pub fn get_fighter(&self, fighter_id: &FighterId) -> Option<FighterEntry>

Get a snapshot of a single fighter’s entry.

pub fn register_gorilla(&self, manifest: GorillaManifest) -> GorillaId

Register a gorilla with the Ring.

Returns the newly-assigned GorillaId. The gorilla starts in GorillaStatus::Caged.

pub async fn unleash_gorilla(&self, gorilla_id: &GorillaId) -> PunchResult<()>

Unleash (start) a gorilla’s background task.

This uses the BackgroundExecutor to spawn the gorilla’s autonomous loop, which will run the fighter loop on the gorilla’s schedule.

pub async fn cage_gorilla(&self, gorilla_id: &GorillaId) -> PunchResult<()>

Cage (stop) a gorilla’s background task.

pub async fn list_gorillas( &self, ) -> Vec<(GorillaId, GorillaManifest, GorillaStatus, GorillaMetrics)>

List all gorillas with their current status and metrics.

pub async fn get_gorilla_manifest( &self, gorilla_id: &GorillaId, ) -> Option<GorillaManifest>

Get a gorilla’s manifest by ID.

pub async fn find_gorilla_by_name(&self, name: &str) -> Option<GorillaId>

Find a gorilla ID by name (case-insensitive).

pub async fn run_gorilla_tick( &self, gorilla_id: &GorillaId, ) -> PunchResult<FighterLoopResult>

Run a single autonomous tick for a gorilla (for testing/debugging).

This executes the gorilla’s autonomous prompt once, without starting the background scheduler. Useful for verifying configuration.

pub fn driver(&self) -> &Arc<dyn LlmDriver>

Get the LLM driver (useful for CLI commands that need to run ticks directly).

pub async fn fighter_to_fighter( &self, source_id: &FighterId, target_id: &FighterId, message: String, ) -> PunchResult<FighterLoopResult>

Send a message from one fighter to another.

The source fighter’s message becomes the target fighter’s input, enriched with source context so the target knows who is speaking. The target processes it through its own fighter loop (with its own creed) and the response is returned.

pub fn find_fighter_by_name_sync( &self, name: &str, ) -> Option<(FighterId, FighterManifest)>

Find a fighter by name (case-insensitive).

Returns the fighter ID and manifest if found.

pub async fn update_fighter_relationships( &self, fighter_a_name: &str, fighter_b_name: &str, )

Update relationship tracking in both fighters’ creeds after inter-agent communication.

Loads both creeds, adds or updates the peer relationship entry (incrementing interaction_count), and saves them back.

pub fn troop_manager(&self) -> &TroopManager

Get a reference to the troop manager.

pub fn swarm_coordinator(&self) -> &SwarmCoordinator

Get a reference to the swarm coordinator.

pub fn message_router(&self) -> &MessageRouter

Get a reference to the message router.

pub fn form_troop( &self, name: String, leader: FighterId, members: Vec<FighterId>, strategy: CoordinationStrategy, ) -> PunchResult<TroopId>

Form a new troop with a leader and initial members.

pub fn disband_troop(&self, troop_id: &TroopId) -> PunchResult<()>

Disband (dissolve) a troop.

pub fn assign_troop_task( &self, troop_id: &TroopId, task_description: &str, ) -> PunchResult<Vec<FighterId>>

Assign a task to a troop, returning the fighters that should handle it.

pub async fn assign_troop_task_async( &self, troop_id: &TroopId, task: &str, ) -> PunchResult<TaskAssignmentResult>

Assign a task to a troop asynchronously, returning full results including responses from fighters.

pub fn get_troop_status(&self, troop_id: &TroopId) -> Option<Troop>

Get the current status of a troop.

pub fn list_troops(&self) -> Vec<Troop>

List all troops.

pub fn recruit_to_troop( &self, troop_id: &TroopId, fighter_id: FighterId, ) -> PunchResult<()>

Recruit a fighter into a troop.

pub fn dismiss_from_troop( &self, troop_id: &TroopId, fighter_id: &FighterId, ) -> PunchResult<()>

Dismiss a fighter from a troop.

pub fn kill_fighter_safe(&self, fighter_id: &FighterId)

Kill a fighter, warning if they’re in a troop.

Unlike [kill_fighter], this checks troop membership and dismisses the fighter from all troops before killing them.

pub fn register_workflow(&self, workflow: Workflow) -> WorkflowId

Register a workflow with the engine.

pub async fn execute_workflow( &self, workflow_id: &WorkflowId, input: String, ) -> PunchResult<WorkflowRunId>

Execute a workflow by ID with the given input.

pub fn shutdown(&self)

Gracefully shut down the Ring, stopping all gorillas and background tasks.

Trait Implementations

impl AgentCoordinator for Ring

fn spawn_fighter<'life0, 'async_trait>( &'life0 self, manifest: FighterManifest, ) -> Pin<Box<dyn Future<Output = PunchResult<FighterId>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Spawn a new fighter from a manifest.

fn send_message_to_agent<'life0, 'life1, 'async_trait>( &'life0 self, target: &'life1 FighterId, message: String, ) -> Pin<Box<dyn Future<Output = PunchResult<AgentMessageResult>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Send a message to a fighter and get its response.

fn find_fighter_by_name<'life0, 'life1, 'async_trait>( &'life0 self, name: &'life1 str, ) -> Pin<Box<dyn Future<Output = PunchResult<Option<FighterId>>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Find a fighter by name.

fn list_fighters<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = PunchResult<Vec<AgentInfo>>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

List all active fighters.