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

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 and provides the single source of truth that persists across runs.

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.

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

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

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

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

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	Durable state management
Capability Pack	loopx/capabilities/__init__.py	Capability grouping and registration
Provider	loopx/providers/base.py	Capability implementation base
Agent	loopx/agent.py	Task execution workers
Scheduler	loopx/scheduler.py	Execution orchestration
Runtime	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 in the huangruiteng/loopx repository. This document defines layer contracts, interaction patterns, and durability semantics.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}