# LoopX Architecture Core Components: The 6 Control-Plane Layers Explained

> Discover the LoopX architecture's 6 control-plane layers and 4-part runtime model. Understand how state ownership and execution logic are separated for robust system design.

- Repository: [huangruiteng/loopx](https://github.com/huangruiteng/loopx)
- Tags: architecture
- Published: 2026-08-14

---

**The LoopX architecture consists of six durable control-plane layers plus an optional probe surface, governed by a four-part runtime responsibility model that separates state ownership from execution logic.**

LoopX is an open-source automation framework designed around explicit state boundaries and clear ownership of system actions. Its core components are defined in [`docs/architecture.md`](https://github.com/huangruiteng/loopx/blob/main/docs/architecture.md) and implemented across the `loopx/control_plane/` and `loopx/` directories. Understanding these components is essential for extending the system or operating agents at scale.

## The Six Control-Plane Layers

LoopX stores all durable state in six distinct layers. Each layer serves a specific purpose and is accessed through well-defined APIs.

### 1. Registry: The Central Catalogue

The **Registry** layer maintains a system-wide catalogue of all goals. It tracks repositories, adapters, authority sources, status, and guards for each goal.

Access it via the CLI:

```bash

# List all registered goals

loopx status --list-goals

```

The implementation in [`loopx/cli_rollout.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/cli_rollout.py) parses this flag and reads [`registry.json`](https://github.com/huangruiteng/loopx/blob/main/registry.json) from the control-plane directory.

### 2. Goal State: Per-Goal Active State

The **Goal State** layer stores the active state file for a single goal: current belief, priority stack, and next action.

```bash

# Display state for a specific goal

loopx status --goal my_goal_id

```

The CLI loads `goal_state/{goal_id}.json` for this operation.

### 3. Run Log: Audit and Debug Records

The **Run Log** layer saves JSON/Markdown reports per goal, useful for auditing and debugging individual runs.

```python
from loopx.control_plane.run_log import RunLog

run_log = RunLog(goal_id="my_goal_id")
run_log.append({
    "event": "agent_start",
    "timestamp": "2024-08-14T12:00:00Z"
})

```

The `RunLog` class in [`loopx/control_plane/run_log.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/control_plane/run_log.py) writes entries to `run_log/{goal_id}.json`.

### 4. Run History: Compact Activity Indexes

The **Run History** layer provides compact indexes consumed by agents, heartbeats, and the UI to reconstruct past activity without parsing full run logs.

### 5. Status / Attention Queue: Operator Inbox

The **Status / Attention Queue** layer presents a first-screen summary showing who needs to act next—operator inbox items and queued todos.

```bash

# Get items requiring operator attention

loopx status --attention-queue

```

The `attention_queue` function in [`loopx/status.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/status.py) aggregates data from Registry, Run History, and Status layers to produce compact JSON output.

### 6. Compute Quota: Local Policy Limits

The **Compute Quota** layer enforces local policy limits on automatic agent compute consumption per goal.

```python
from loopx.quota import QuotaManager

qm = QuotaManager(goal_id="my_goal_id")
if qm.can_spend(cost=5):
    qm.spend(cost=5)
else:
    print("Quota exceeded – aborting turn.")

```

The `QuotaManager` in [`loopx/quota.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/quota.py) checks and updates `quota/{goal_id}.json`.

## Optional Probe Surface

The **Probe Surface** is not a peer layer but an optional registration point. A goal may define a `next_probe` command for read-only observation without triggering state changes. This enables safe external monitoring without violating layer boundaries.

## The Four Runtime Responsibilities

The LoopX architecture defines four logical owners that orchestrate each turn. This separation prevents capability leaks and ensures safe automation.

| Responsibility | Owns | Must **not** own |
|---|---|---|
| **Agent** | Planning, analysis, tool use, one bounded host execution | Durable goal lifecycle or unscoped effect authority |
| **Provider** | External calls, bounded observations, effect results, read-backs | Domain transition policy or LoopX todo state |
| **Capability** | Caller-facing outcome contract, validation, observation normalisation | Scheduling, claim/gate logic, direct lifecycle writes |
| **LoopX Kernel** | Goal, todo, claim, gate, monitor, quota, write-back, recovery | Domain-specific reasoning or provider implementation details |

This model is defined in [`docs/architecture.md`](https://github.com/huangruiteng/loopx/blob/main/docs/architecture.md) and enforced through contracts in [`loopx/control_plane/turn_driver/turn_contracts.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/control_plane/turn_driver/turn_contracts.py), which specifies `LoopXTurnRoute` and `LoopXTurnResultKind` enums used by the Kernel for routing decisions.

## Capabilities and Extensions

LoopX extends functionality through two mechanisms that preserve the four-responsibility boundary:

- **Capabilities** are product contracts exposing callable outcomes (e.g., Issue Fix, Periodic Report)
- **Extensions** install optional providers for capabilities but never become a fifth runtime owner

The `CapabilityRegistry` in [`loopx/capability_registry.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/capability_registry.py) manages capability-to-provider mappings. Extension design patterns are documented in [`docs/reference/extensions.md`](https://github.com/huangruiteng/loopx/blob/main/docs/reference/extensions.md).

## Key Implementation Files

| Area | File | Purpose |
|---|---|---|
| Architecture spec | [`docs/architecture.md`](https://github.com/huangruiteng/loopx/blob/main/docs/architecture.md) | Full layer descriptions and effect-interpreter model |
| CLI entry point | [`loopx/cli_rollout.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/cli_rollout.py) | Top-level commands interacting with core layers |
| Turn contracts | [`loopx/control_plane/turn_driver/turn_contracts.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/control_plane/turn_driver/turn_contracts.py) | Runtime routing enums (`LoopXTurnRoute`, `LoopXTurnResultKind`) |
| Capability registry | [`loopx/capability_registry.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/capability_registry.py) | Provider mapping management |
| Quota enforcement | [`loopx/quota.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/quota.py) | Compute quota layer implementation |
| Run log API | [`loopx/control_plane/run_log.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/control_plane/run_log.py) | Audit record creation and appending |
| Status aggregation | [`loopx/status.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/status.py) | Attention queue generation |

## Summary

- The **LoopX architecture** centers on **six durable control-plane layers**: Registry, Goal State, Run Log, Run History, Status/Attention Queue, and Compute Quota
- An **optional Probe Surface** enables read-only observation without state mutation
- **Four runtime responsibilities**—Agent, Provider, Capability, and Kernel—prevent ownership conflicts during turn execution
- All layers are accessed through explicit APIs in `loopx/control_plane/` and `loopx/` modules
- Extensions add capabilities without violating the responsibility model

## Frequently Asked Questions

### What is the difference between Run Log and Run History in LoopX?

**Run Log** stores full JSON/Markdown reports for debugging and audit purposes, while **Run History** provides compact, indexed summaries optimized for agent consumption, heartbeat processing, and UI reconstruction. Use Run Log for deep investigation; use Run History for operational queries.

### How does LoopX prevent agents from consuming unlimited compute?

The **Compute Quota** layer enforces local policy limits. Each goal has a quota file (`quota/{goal_id}.json`) checked by `QuotaManager.can_spend()` before any turn execution. When exceeded, the turn aborts before resource consumption occurs.

### Can external systems monitor LoopX goals without modifying state?

Yes. The **Probe Surface** allows goals to register a `next_probe` command for read-only observation. This is explicitly not a peer layer—probes observe without write access, maintaining the integrity of the six control-plane layers.

### What happens when a capability needs to schedule future work?

Capabilities **must not** own scheduling, claim/gate logic, or direct lifecycle writes. These responsibilities belong to the **LoopX Kernel**. A capability validates inputs and normalizes observations, then returns an outcome contract; the Kernel handles all durable state transitions and scheduling decisions.