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

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 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:

# List all registered goals

loopx status --list-goals

The implementation in loopx/cli_rollout.py parses this flag and reads 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.

# 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.

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 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.

# Get items requiring operator attention

loopx status --attention-queue

The attention_queue function in 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.

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 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 and enforced through contracts in 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 manages capability-to-provider mappings. Extension design patterns are documented in docs/reference/extensions.md.

Key Implementation Files

Area	File	Purpose
Architecture spec	docs/architecture.md	Full layer descriptions and effect-interpreter model
CLI entry point	loopx/cli_rollout.py	Top-level commands interacting with core layers
Turn contracts	loopx/control_plane/turn_driver/turn_contracts.py	Runtime routing enums (LoopXTurnRoute, LoopXTurnResultKind)
Capability registry	loopx/capability_registry.py	Provider mapping management
Quota enforcement	loopx/quota.py	Compute quota layer implementation
Run log API	loopx/control_plane/run_log.py	Audit record creation and appending
Status aggregation	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.

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