# What Are the Six Durable Control‑Plane Layers in LoopX Architecture?

> Discover the six durable control-plane layers in LoopX architecture: Kernel, Capability Pack, Provider, Agent, Scheduler, and Runtime. Understand LoopX's robust design.

- Repository: [huangruiteng/loopx](https://github.com/huangruiteng/loopx)
- Tags: deep-dive
- Published: 2026-09-04

---

**The LoopX control‑plane consists of six durable layers: Kernel, Capability Pack, Provider, Agent, Scheduler, and Runtime.**

LoopX is an open‑source control‑plane framework designed to orchestrate agents, capabilities, and providers with strong durability guarantees. Understanding its six durable control‑plane layers is essential for building resilient automation workflows that survive process restarts and system failures.

## The Six Durable Control‑Plane Layers Explained

Each layer in LoopX serves a distinct purpose and maintains durable state across executions. Below is the definitive breakdown of these layers as implemented in `huangruiteng/loopx`.

### 1. Kernel: The Durable Source of Truth

The **Kernel** layer owns the durable truth for all persistent data in LoopX. It maintains:

- **Goal**: The high‑level objective being pursued
- **Todo**: Pending tasks and their states
- **Gate**: Conditional checkpoints and approval gates
- **Evidence**: Recorded results and audit trails
- **Quota**: Resource limits and consumption tracking
- **Recovery**: Failure recovery and state restoration logic
- **Scheduling**: Prioritization and timing metadata

The Kernel is implemented in [`loopx/kernel.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/kernel.py) and provides the single source of truth that persists across runs.

```python
from loopx.kernel import Kernel

# Retrieve the global kernel instance

kernel = Kernel.get()

# Inspect current durable goal

current_goal = kernel.goal
print(f"Current goal: {current_goal}")

```

### 2. Capability Pack: Cohesive Capability Grouping

A **Capability Pack** groups related capabilities under a unified contract. Packs define:

- The public‑safe API surface for their capabilities
- Lifecycle management rules
- Discovery and composition metadata
- Versioning and compatibility boundaries

Capability packs make capabilities discoverable and composable across different providers and agents.

```python
from loopx.capabilities import CapabilityPack

class MyPack(CapabilityPack):
    name = "my_pack"
    # declare the capabilities this pack provides

    capabilities = ["my_capability"]

# Register the pack so providers can be discovered

MyPack.register()

```

### 3. Provider: Concrete Capability Implementation

The **Provider** layer implements the actual logic for a declared capability. Providers:

- Expose interfaces defined by their capability pack
- Manage external resources (cloud services, models, tools)
- Handle authentication, rate limiting, and error translation
- Return structured evidence to the Kernel

```python
from loopx.providers import ProviderBase

class MyProvider(ProviderBase):
    capability = "my_capability"

    def run(self, input_data):
        # concrete logic for the capability

        return f"processed: {input_data}"

```

### 4. Agent: Runtime Execution Unit

**Agents** are the worker processes that execute tasks on behalf of the control‑plane. They:

- Run tasks dispatched by the Scheduler
- Communicate with Providers to fulfill capabilities
- Update the Kernel's durable state with progress and results
- Handle local execution context and sandboxing

```python
from loopx.agent import Agent

agent = Agent(name="example-agent")
result = agent.run_task({"input": "hello"})
print(result)

```

### 5. Scheduler: Execution Orchestration

The **Scheduler** decides *when* agents should run. It orchestrates execution by:

- Reading quota, goal, and priority data from the Kernel
- Enqueuing tasks based on available resources
- Managing retries with exponential backoff
- Load‑balancing across multiple agents

```python
from loopx.scheduler import Scheduler

scheduler = Scheduler()

# Ask the scheduler to enqueue a task based on current quota

scheduler.enqueue(agent="example-agent", task={"input": "data"})

```

### 6. Runtime: Execution Environment Glue

The **Runtime** provides the surrounding environment that binds all layers together. It:

- Hosts the daemon, server, or CLI entry points
- Handles I/O, persistence, and external‑surface interactions
- Initializes and wires together Kernel, Scheduler, Agents, and Providers
- Manages graceful shutdown and state checkpointing

```bash
loopx daemon start   # launches the runtime daemon that wires all layers together

```

## Durability Guarantees Across Layers

What makes these six layers **durable** is their persistence contract. Each layer persists essential state to survive:

- Process restarts
- Node failures
- Network partitions
- Graceful and ungraceful shutdowns

The Kernel's durable store backs all higher layers. Agents checkpoint progress through the Kernel. The Scheduler reconstructs queue state from Kernel data. This design ensures LoopX workflows are **crash‑recoverable by default**.

## Source Files for Each Layer

| Layer | Source File | Purpose |
|-------|-------------|---------|
| Kernel | [`loopx/kernel.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/kernel.py) | Durable state management |
| Capability Pack | [`loopx/capabilities/__init__.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/capabilities/__init__.py) | Capability grouping and registration |
| Provider | [`loopx/providers/base.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/providers/base.py) | Capability implementation base |
| Agent | [`loopx/agent.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/agent.py) | Task execution workers |
| Scheduler | [`loopx/scheduler.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/scheduler.py) | Execution orchestration |
| Runtime | [`loopx/runtime/__main__.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/runtime/__main__.py) | CLI and daemon entry points |

## Summary

- The **Kernel** is the foundational durable store for goals, todos, gates, evidence, quota, recovery, and scheduling data
- **Capability Packs** group related capabilities with defined contracts and lifecycle rules
- **Providers** implement concrete logic for capabilities and manage external resources
- **Agents** execute tasks and update durable state through the Kernel
- The **Scheduler** orchestrates when agents run based on quota and priority
- The **Runtime** provides the execution environment that binds all layers together

## Frequently Asked Questions

### What makes LoopX layers "durable" rather than just persistent?

Durable layers in LoopX maintain **transactional consistency** across process boundaries. Unlike simple persistence that writes to disk, durability in LoopX means each layer can reconstruct its full operational state from the Kernel after any failure—without losing in‑flight work or violating workflow guarantees.

### How does the Scheduler interact with the Kernel's quota system?

The Scheduler consults the Kernel's durable quota records before enqueuing any agent task. If quota is exhausted or reserved by higher‑priority goals, the Scheduler defers execution. This prevents resource overcommitment and ensures quota enforcement survives Scheduler restarts.

### Can I run LoopX without all six layers?

The six durable control‑plane layers are **mandatory** for correct LoopX operation. However, the optional **probe surface** (for debugging and observability) can be omitted in production. Removing any core layer would break durability guarantees and crash recovery.

### Where is the complete architecture documented?

The authoritative description of LoopX's six durable control‑plane layers resides in the repository's architecture overview at [`docs/architecture.md`](https://github.com/huangruiteng/loopx/blob/main/docs/architecture.md) in the `huangruiteng/loopx` repository. This document defines layer contracts, interaction patterns, and durability semantics.