Struct Kernel 

pub struct Kernel {

    pub session_id: SessionId,
    pub event_bus: Arc<EventBus>,
    pub capsules: Arc<RwLock<CapsuleRegistry>>,
    pub mcp: SecureMcpClient,
    pub capabilities: Arc<CapabilityStore>,
    pub vfs: Arc<dyn Vfs>,
    pub overlay_vfs: Arc<OverlayVfs>,
    pub vfs_root_handle: DirHandle,
    pub workspace_root: PathBuf,
    pub global_root: Option<PathBuf>,
    pub cli_socket_listener: Option<Arc<Mutex<UnixListener>>>,
    pub kv: Arc<SurrealKvStore>,
    pub audit_log: Arc<AuditLog>,
    pub active_connections: AtomicUsize,
    pub session_token: Arc<SessionToken>,
    pub allowance_store: Arc<AllowanceStore>,
    /* private fields */
}

The core Operating System Kernel.

Fields

session_id: SessionId

The unique identifier for this kernel session.

event_bus: Arc<EventBus>

The global IPC message bus.

capsules: Arc<RwLock<CapsuleRegistry>>

The process manager (loaded WASM capsules).

mcp: SecureMcpClient

The secure MCP client with capability-based authorization and audit logging.

capabilities: Arc<CapabilityStore>

The capability store for this session.

vfs: Arc<dyn Vfs>

The global Virtual File System mount.

overlay_vfs: Arc<OverlayVfs>

Concrete reference to the OverlayVfs for commit/rollback operations.

vfs_root_handle: DirHandle

The global physical root handle (cap-std) for the VFS.

workspace_root: PathBuf

The physical path the VFS is mounted to.

global_root: Option<PathBuf>

The global shared resources directory (~/.astrid/shared/). Capsules declaring fs_read = ["global://"] can read files under this root. Scoped to shared/ so that keys, databases, and capsule .env files in ~/.astrid/ are NOT accessible. Write access is intentionally not granted to any shipped capsule.

Always Some in production (boot requires AstridHome). Remains Option for compatibility with CapsuleContext and test fixtures.

cli_socket_listener: Option<Arc<Mutex<UnixListener>>>

The natively bound Unix Socket for the CLI proxy.

kv: Arc<SurrealKvStore>

Shared KV store backing all capsule-scoped stores and kernel state.

audit_log: Arc<AuditLog>

Chain-linked cryptographic audit log with persistent storage.

active_connections: AtomicUsize

Number of active client connections (CLI sessions).

session_token: Arc<SessionToken>

Session token for socket authentication. Generated at boot, written to ~/.astrid/sessions/system.token. CLI sends this as its first message.

allowance_store: Arc<AllowanceStore>

Shared allowance store for capsule-level approval decisions.

Capsules can check existing allowances and create new ones when users approve actions with session/always scope.

Implementations

impl Kernel

pub async fn new( session_id: SessionId, workspace_root: PathBuf, ) -> Result<Arc<Self>, Error>

Boot a new Kernel instance mounted at the specified directory.

Panics

Panics if called on a single-threaded tokio runtime. The capsule system uses block_in_place which requires a multi-threaded runtime.

Errors

Returns an error if the VFS mount paths cannot be registered.

pub async fn load_all_capsules(&self)

Auto-discover and load all capsules from the standard directories (~/.astrid/capsules and .astrid/capsules).

Capsules are loaded in dependency order (topological sort) with uplink/daemon capsules loaded first. Each uplink must signal readiness before non-uplink capsules are loaded.

After all capsules are loaded, tool schemas are injected into every capsule’s KV namespace and the astrid.v1.capsules_loaded event is published.

pub fn connection_opened(&self)

Record that a new client connection has been established.

pub fn connection_closed(&self)

Record that a client connection has been closed.

Uses fetch_update for atomic saturating decrement - avoids the TOCTOU window where fetch_sub wraps to usize::MAX before a corrective store.

When the last connection closes (counter reaches 0), clears all session-scoped allowances so they don’t leak into the next CLI session.

pub fn connection_count(&self) -> usize

Number of active client connections.

pub async fn shutdown(&self, reason: Option<String>)

Gracefully shut down the kernel.

1. Publish KernelShutdown event on the bus.
2. Drain and unload all capsules (stops MCP child processes, WASM engines).
3. Flush and close the persistent KV store.
4. Remove the Unix socket file.