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.
Boot Sequence and Lifecycle
WeftOS kernel boot state machine, boot phases and events, service registration, shutdown sequence, and boot event logging.
IPC and A2A Messaging
Kernel IPC message envelopes, MessageTarget variants, MessagePayload types, A2A routing, GlobalPid for cross-node addressing, and request-response patterns.