# Understanding the Architecture of LoopX: A Six-Layer Control Plane for AI Workflows

> Discover the LoopX architecture: a six-layer control plane for AI workflows. Learn how LoopX ensures inspectable and recoverable long-running AI tasks with its provider-neutral design.

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

---

**LoopX implements a provider-neutral control plane with six durable persistence layers that separate agent execution from state management, enabling long-running AI workflows to remain inspectable and recoverable.**

LoopX is a lightweight, provider-neutral system designed to make long-running AI work durable and inspectable. According to the huangruiteng/loopx source code, the architecture of LoopX centers on a strict separation between execution logic and durable state, organized into six permanent layers plus an optional probe surface that facilitates read-only observation.

## The Six Durable Layers of LoopX

The architecture of LoopX is built around six permanent persistence layers that maintain the state of AI workflows independently of any specific runtime or provider. As documented in [`docs/architecture.md`](https://github.com/huangruiteng/loopx/blob/main/docs/architecture.md), these layers ensure that work remains recoverable and auditable across restarts.

### 1. Registry (Global Index)

The **Registry** serves as the global index containing goals, adapters, authority sources, status flags, and guards. Implemented in [`loopx/registry.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/registry.py), this layer acts as the top-level control-plane index that the Kernel consults to locate and validate active work.

### 2. Goal State

The **Goal state** layer maintains the active JSON state file for a single goal. This durable representation persists the current plan, context, and metadata required to resume work after interruptions.

### 3. Run Log

The **Run log** generates JSON and Markdown reports per goal, creating an immutable audit trail of what actions were attempted, what observations were made, and what results were produced during each execution cycle.

### 4. Run History

**Run history** maintains a compact chronological index consumed by agents, heartbeat monitors, and the UI. This layer enables fast querying of recent activity without parsing full log files.

### 5. Status and Attention Queue

The **Status/attention queue** provides a first-screen summary indicating who must act next—whether that is an autonomous agent, a human operator, or an external system awaiting input.

### 6. Compute Quota

The **Compute quota** layer implements local policy that limits how much automatic agent compute a goal may consume. This prevents runaway costs and ensures fair resource allocation across competing goals.

### Optional Probe Surface

An optional **probe surface** allows a goal to register a free-form `next_probe` command. According to [`docs/architecture.md`](https://github.com/huangruiteng/loopx/blob/main/docs/architecture.md) (lines 15-19), this command is stored but never executed unless the host explicitly enforces a read-only observation mode, enabling safe debugging without side effects.

## Runtime Responsibility Model

The architecture of LoopX defines four distinct responsibilities that flow through each turn cycle, as specified in [`docs/architecture.md`](https://github.com/huangruiteng/loopx/blob/main/docs/architecture.md) (lines 71-84):

- **Agent**: Owns planning, analysis, tool use, and single bounded execution through a host/runtime.
- **Provider**: Handles external calls, observations, effect results, and read-back from external systems.
- **Capability**: Defines the caller-facing contract, domain policy, observation normalization, validation, and typed transition proposals.
- **LoopX Kernel**: Manages the goal, todo, claim, gate, monitor, quota, accepted write-back, recovery, and scheduling.

The data flow follows a strict pattern: **Agent → Capability → Provider → external system**, with the reverse path **external → Provider → Capability → Kernel**. This unidirectional flow ensures that capabilities cannot bypass the Kernel to write state directly, maintaining data integrity as documented in [`docs/architecture.md`](https://github.com/huangruiteng/loopx/blob/main/docs/architecture.md) (lines 84-90).

## Turn Decision Vocabulary

LoopX replaces informal state management with explicit enums defined in `loopx/control_plane/turn_driver/`. These enums encode the result of a turn in a type-safe manner:

**`LoopXTurnRoute`** (pre-host decisions):
- `ready_for_host`
- `repair_required`
- `replan_required`
- `user_action_required`
- `wait`
- `blocked`
- `contract_error`

**`LoopXTurnResultKind`** (post-host outcomes):
- `validated_progress`
- `validated_completion`
- `repair_required`
- `replan_required`
- `user_action_required`
- `wait`
- `host_failure`
- `validation_failed`
- `writeback_failed`
- `quota_spend_failed`

## Capabilities vs Extensions

The architecture of LoopX maintains a strict distinction between these two concepts:

- **Capability**: A product-level contract that normalizes provider output and proposes a typed transition to the Kernel.
- **Extension**: A separately-managed delivery unit that may install optional providers for one or more capabilities.

The **CapabilityRegistry** in [`loopx/registry.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/registry.py) enforces this separation, ensuring that extensions cannot directly manipulate capability contracts without registering through the proper control plane channels.

## State Interaction Model

Any new feature in LoopX must declare its state contract according to the rules in [`docs/state-interaction-model.md`](https://github.com/huangruiteng/loopx/blob/main/docs/state-interaction-model.md). Specifically, implementations must define:

1. **What state it reads** (e.g., the goal's `todos`).
2. **What state it writes** (e.g., updates to a specific `todo`).
3. **Who owns the write** (the Kernel owns durable state; capabilities cannot bypass it).
4. **How the dashboard proves the change** (via the compact status projection).

This model ensures that the goal, a Codex App executor, a human operator, and the dashboard each maintain clearly defined read/write boundaries.

## Command Flow and CLI Interface

A typical LoopX execution cycle follows a minimal, testable command surface that can be driven by any host runtime. As documented in the README (lines 35-42), the core tick is deliberately small:

```bash

# Ask quota if an agent may run now

loopx quota should-run --goal-id my_goal

# Claim the next todo for the current agent

loopx todo claim --goal-id my_goal

# (run your agent code here…)

# Apply the result after the agent finishes

loopx todo update --goal-id my_goal --todo-id T123 \
    --evidence "model output: …" --status completed

# Rebuild the projected state for the next tick

loopx refresh-state --goal-id my_goal

# Spend compute quota for the completed turn

loopx quota spend-slot --goal-id my_goal

```

The [`loopx/runtime.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/runtime.py) file orchestrates this turn cycle, coordinating the quota check, todo claim, and state refresh operations.

## Core Implementation Files

The architecture of LoopX is embodied in these key source files:

| File | Purpose |
|------|---------|
| [`docs/architecture.md`](https://github.com/huangruiteng/loopx/blob/main/docs/architecture.md) | Describes the six durable layers, optional probe surface, and overall design rationale. |
| [`docs/state-interaction-model.md`](https://github.com/huangruiteng/loopx/blob/main/docs/state-interaction-model.md) | Defines actor boundaries and state contracts for goals, executors, operators, and dashboards. |
| [`loopx/registry.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/registry.py) | Core logic for the Registry layer; implements `inspect_registry()` and the CapabilityRegistry. |
| [`loopx/quota.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/quota.py) | Implements the compute-quota layer that gates agent execution via local policy. |
| [`loopx/runtime.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/runtime.py) | Orchestrates the turn cycle, binding quota checks to todo claims and state refreshes. |
| `loopx/control_plane/turn_driver/` | Contains enum definitions (`LoopXTurnRoute`, `LoopXTurnResultKind`) encoding turn decisions. |
| [`loopx/todos.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/todos.py) | Handles durable `todo` objects that drive the work-lane flow and state transitions. |

To inspect a registry file programmatically:

```python
from pathlib import Path
from loopx.registry import inspect_registry

# Path to a registry file (usually .loopx/registry.json)

registry_path = Path(".loopx/registry.json")
result = inspect_registry(registry_path)

print("Registry OK:", result["ok"])
print("Goals found:", result["goal_count"])
for g in result["goals"]:
    print("- Goal", g["id"], "status:", g["status"])

```

*(source [`loopx/registry.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/registry.py), lines 71-90)*

## Summary

- The architecture of LoopX consists of six durable layers (Registry, Goal state, Run log, Run history, Status queue, and Compute quota) plus an optional probe surface.
- Four distinct responsibilities (Agent, Provider, Capability, Kernel) flow through each turn with strict data directionality to prevent unauthorized state mutations.
- Turn decisions use explicit enums (`LoopXTurnRoute`, `LoopXTurnResultKind`) defined in `loopx/control_plane/turn_driver/` rather than informal string flags.
- Capabilities define contracts while Extensions deliver providers; the `CapabilityRegistry` enforces this separation.
- The state interaction model requires every feature to declare read/write contracts and prove changes via the compact status projection.
- The minimal CLI surface (`quota should-run`, `todo claim`, `refresh-state`, etc.) enables testable, host-agnostic execution cycles.

## Frequently Asked Questions

### What is the six-layer architecture in LoopX?

The six-layer architecture refers to the permanent persistence layers that make AI workflows durable: the **Registry** (global index), **Goal state** (active JSON files), **Run log** (immutable audit reports), **Run history** (chronological index), **Status/attention queue** (actionable summaries), and **Compute quota** (resource limits). These layers ensure that work survives restarts and remains inspectable regardless of which provider or runtime executes the agent code.

### How does the LoopX Kernel differ from the Agent?

The **LoopX Kernel** owns durable state management including goals, todos, claims, gates, monitors, quota enforcement, and recovery scheduling. The **Agent** owns only the transient execution concerns: planning, analysis, tool use, and bounded execution through a host. Agents cannot write state directly; they must propose transitions through Capabilities, which the Kernel validates and persists according to the state interaction model defined in [`docs/state-interaction-model.md`](https://github.com/huangruiteng/loopx/blob/main/docs/state-interaction-model.md).

### What is the difference between a Capability and an Extension in LoopX?

A **Capability** is a product-level contract that normalizes provider output and proposes typed state transitions to the Kernel. An **Extension** is a separately-managed delivery unit that may install optional providers for one or more capabilities. While capabilities define the interface, extensions provide the implementation, and the `CapabilityRegistry` in [`loopx/registry.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/registry.py) enforces this separation to maintain architectural integrity.

### How does LoopX handle compute quota management?

LoopX implements compute quota as a local policy layer that limits how much automatic agent compute a goal may consume. The [`loopx/quota.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/quota.py) module provides commands like `quota should-run` to check if execution is permitted and `quota spend-slot` to deduct resources after a turn completes. This prevents runaway costs and ensures that resource-intensive goals cannot starve other workflows, operating entirely within the local control plane without external dependencies.