clawft

Process Table

PID allocation, process state machine, ProcessEntry fields, resource tracking, and agent supervisor integration in WeftOS.

The WeftOS process table tracks all kernel-managed agents using PIDs (process identifiers). It provides lock-free concurrent access via DashMap, allowing multiple kernel subsystems to query and update process state without contention.

Source: crates/clawft-kernel/src/process.rs, crates/clawft-kernel/src/supervisor.rs

PID Allocation

PIDs are monotonically increasing 64-bit integers allocated from an atomic counter that starts at 1; PID 0 is reserved for the kernel. The table does not reuse PIDs:

pub type Pid = u64;

pub struct ProcessTable {
    next_pid: AtomicU64,
    entries: DashMap<Pid, ProcessEntry>,
    max_processes: u32,
    chain_manager: Option<Arc<ChainManager>>, // exochain feature
}

When the table is at max_processes, insert returns KernelError::ProcessTableFull { max }. With a chain manager set, insert appends a process register event and update_state appends a state event (EVENT_KIND_PROCESS_REGISTER, EVENT_KIND_PROCESS_STATE).

ProcessState State Machine

pub enum ProcessState {
    Starting,       // Process is initializing
    Running,        // Process is actively running
    Suspended,      // Process has been paused
    Stopping,       // Process is in the process of stopping
    Exited(i32),    // Process has exited with a status code
}

Valid transitions:

Starting ------> Running ------> Suspended
    |               |                |
    |               |                +----> Running (resume)
    |               |                +----> Stopping
    |               |                +----> Exited(code)
    |               +----> Stopping
    |               +----> Exited(code)
    +----> Exited(code)

Stopping --------> Exited(code)
Exited ----------> (terminal)

The can_transition_to() method enforces these transitions:

impl ProcessState {
    pub fn can_transition_to(&self, next: &ProcessState) -> bool {
        matches!(
            (self, next),
            (Starting, Running) | (Starting, Exited(_))
            | (Running, Suspended) | (Running, Stopping) | (Running, Exited(_))
            | (Suspended, Running) | (Suspended, Stopping) | (Suspended, Exited(_))
            | (Stopping, Exited(_))
        )
    }
}

ProcessEntry Fields

pub struct ProcessEntry {
    pub pid: Pid,
    pub agent_id: String,
    pub state: ProcessState,
    pub capabilities: AgentCapabilities,
    pub resource_usage: ResourceUsage,
    pub cancel_token: CancellationToken,
    pub parent_pid: Option<Pid>,
}

The CancellationToken enables cooperative shutdown -- when a process is stopped, its token is cancelled and the agent loop exits gracefully.

Resource Tracking

pub struct ResourceUsage {
    pub memory_bytes: u64,
    pub cpu_time_ms: u64,
    pub tool_calls: u64,
    pub messages_sent: u64,
}

Counters are updated with update_resources and checked against the process's ResourceLimits by CapabilityChecker::check_resource_limit (see Capabilities), which returns ResourceLimitExceeded. This page does not claim an automatic suspend or terminate on breach.

ProcessTable public API

impl ProcessTable {
    pub fn new(max_processes: u32) -> Self;
    pub fn allocate_pid(&self) -> Pid;
    pub fn insert(&self, entry: ProcessEntry) -> Result<Pid, KernelError>;
    pub fn insert_with_pid(&self, entry: ProcessEntry) -> Result<(), KernelError>;
    pub fn get(&self, pid: Pid) -> Option<ProcessEntry>;
    pub fn remove(&self, pid: Pid) -> Option<ProcessEntry>;
    pub fn list(&self) -> Vec<ProcessEntry>;
    pub fn update_state(&self, pid: Pid, new_state: ProcessState) -> Result<(), KernelError>;
    pub fn update_resources(&self, pid: Pid, usage: ResourceUsage) -> Result<(), KernelError>;
    pub fn set_capabilities(/* pid, capabilities */) -> Result<(), KernelError>;
    pub fn count_by_state(&self, state: &ProcessState) -> usize;
    pub fn len(&self) -> usize;
    pub fn max_processes(&self) -> u32;
}

update_state rejects transitions that can_transition_to forbids with KernelError::InvalidStateTransition.

Agent supervisor integration

AgentSupervisor (crates/clawft-kernel/src/supervisor.rs) wraps the process table:

pub struct SpawnRequest {
    pub agent_id: String,
    pub capabilities: Option<AgentCapabilities>,
    pub parent_pid: Option<Pid>,
    pub env: HashMap<String, String>,
    pub backend: Option<SpawnBackend>,
}

pub enum SpawnBackend {
    Native,
    Wasm { module: PathBuf },
    Container { image: String },
    Tee { enclave: EnclaveConfig },
    Remote { node_id: String },
}

AgentSupervisor::spawn accepts only None or Native. Every other backend returns KernelError::BackendNotAvailable: Wasm ("WASM sandbox requires K3"), Container (agents do not run in containers yet; cog workloads run in containers through workload_runtime::WorkloadHost, ADR-099 s5), Tee ("requires K6+ and hardware support") and Remote (remote workloads run through workload_runtime adapters, ADR-099 s5). Spawn inserts a ProcessEntry in state Starting and returns the new PID. The agent loop, inbox and chain events are wired by the daemon's agent service; see IPC.

On this page