Struct AgentSupervisor 

pub struct AgentSupervisor<P: Platform> { /* private fields */ }

Manages the lifecycle of kernel-managed agent processes.

The supervisor sits between the CLI/API surface and the core AgentLoop, providing:

• Spawn: creates a process entry, assigns capabilities, allocates a PID, and tracks the agent in the process table.
• Stop: signals cancellation (graceful) or immediate termination.
• Restart: stops then re-spawns with the same configuration.
• Inspect: returns full process entry with capabilities and resource usage.
• Watch: returns a receiver for process state changes.

The supervisor does not own the actual AgentLoop execution; that remains the responsibility of the caller (kernel boot or CLI). Instead, the supervisor manages the process table entries and provides the cancellation tokens that control agent lifecycle.

Implementations

impl<P: Platform> AgentSupervisor<P>

pub fn new( process_table: Arc<ProcessTable>, kernel_ipc: Arc<KernelIpc>, default_capabilities: AgentCapabilities, ) -> Self

Create a new agent supervisor.

Arguments

• process_table - Shared process table (also held by Kernel)
• kernel_ipc - IPC subsystem for sending lifecycle signals
• default_capabilities - Capabilities assigned to agents that don’t specify their own

pub fn with_a2a_router( self, a2a_router: Arc<A2ARouter>, cron_service: Arc<CronService>, ) -> Self

Configure A2A router and cron service.

When set, spawn_and_run will create per-agent inboxes via the A2ARouter and pass the cron service handle to the agent work loop.

pub fn a2a_router(&self) -> Option<&Arc<A2ARouter>>

Get the A2A router (if configured).

pub fn cron_service(&self) -> Option<&Arc<CronService>>

Get the cron service (if configured).

pub fn with_exochain( self, tree_manager: Option<Arc<TreeManager>>, chain_manager: Option<Arc<ChainManager>>, ) -> Self

Configure exochain integration (tree + chain managers).

When set, agent spawn/stop/restart events are recorded in the resource tree and hash chain.

pub fn spawn(&self, request: SpawnRequest) -> KernelResult<SpawnResult>

Spawn a new supervised agent process.

This creates a process table entry and returns the assigned PID. The actual agent execution (AgentLoop) must be started separately by the caller using the returned SpawnResult and the cancellation token from the process entry.

Errors

Returns KernelError::ProcessTableFull if the process table has reached its maximum capacity.

pub fn spawn_and_run<F, Fut>( &self, request: SpawnRequest, work: F, ) -> KernelResult<SpawnResult>

where F: FnOnce(Pid, CancellationToken) -> Fut, Fut: Future<Output = i32> + Send + 'static,

Spawn a supervised agent and run its work as a tokio task.

Unlike spawn, this method also:

1. Transitions the process to Running
2. Registers the agent in the resource tree (if exochain enabled)
3. Spawns a tokio task to execute the provided work closure
4. On completion: transitions to Exited, unregisters from tree, logs chain events, and cleans up the task handle

The work closure receives the assigned PID and a CancellationToken; it should return an exit code (0 = success).

Errors

Returns KernelError::ProcessTableFull if the process table has reached its maximum capacity.

pub fn stop(&self, pid: Pid, graceful: bool) -> KernelResult<()>

Stop a supervised agent process.

If graceful is true, the process is moved to Stopping state and its cancellation token is cancelled, allowing the agent to finish its current work. If graceful is false, the process is immediately moved to Exited(-1).

Stopping an already-exited process is idempotent and returns Ok.

Errors

Returns KernelError::ProcessNotFound if the PID is not in the process table.

pub fn restart(&self, pid: Pid) -> KernelResult<SpawnResult>

Restart a supervised agent process.

Stops the existing process (gracefully), then spawns a new one with the same agent_id and capabilities. The new process gets a fresh PID; the old entry remains in the table with Exited(0) state.

The parent_pid of the new process is set to the restarted PID, creating a restart lineage.

Errors

Returns KernelError::ProcessNotFound if the PID is not in the process table.

pub fn inspect(&self, pid: Pid) -> KernelResult<ProcessEntry>

Inspect a supervised agent process.

Returns a clone of the full ProcessEntry including capabilities and resource usage.

Errors

Returns KernelError::ProcessNotFound if the PID is not in the process table.

pub fn list_by_state(&self, state: ProcessState) -> Vec<ProcessEntry>

List processes filtered by state.

pub fn list_agents(&self) -> Vec<ProcessEntry>

List all running agent processes (excludes kernel PID 0).

pub fn process_table(&self) -> &Arc<ProcessTable>

Get a reference to the shared process table.

pub fn ipc(&self) -> &Arc<KernelIpc>

Get a reference to the IPC subsystem.

pub fn default_capabilities(&self) -> &AgentCapabilities

Get the default capabilities assigned to new agents.

pub fn running_count(&self) -> usize

Count running processes (excluding kernel PID 0).

pub fn running_task_count(&self) -> usize

Get the number of actively tracked running agent tasks.

pub fn abort_all(&self)

Abort all running agent tasks (used during forced shutdown).

pub async fn watchdog_sweep(&self) -> Vec<(Pid, i32)>

Sweep finished agent handles that were not cleaned up normally.

Iterates running_agents, checks is_finished() on each JoinHandle, and for any that are finished:

1. Removes the handle from the map
2. If the process table still shows Running, transitions to Exited(-2) (watchdog reap) or Exited(-3) (panic reap)
3. Logs a chain event (when exochain is enabled)

Returns a list of (pid, exit_code) for all reaped processes.

pub async fn shutdown_all(&self, timeout: Duration) -> Vec<(Pid, i32)>

Gracefully shut down all running agents with a timeout.

1. Cancels all agent cancellation tokens via the process table
2. Drains all JoinHandles from running_agents
3. Waits for all tasks to complete, with a timeout
4. On timeout, aborts any remaining tasks

Returns a list of (pid, exit_code) for all agents.

pub fn tree_manager(&self) -> Option<&Arc<TreeManager>>

Get the tree manager (when exochain feature is enabled).

pub fn chain_manager(&self) -> Option<&Arc<ChainManager>>

Get the chain manager (when exochain feature is enabled).