# How LoopX Is Structured: A Three-Layer Architecture for Long-Running Agents

> Discover LoopX's three-layer architecture: core control-plane, CLI orchestration, and extensible presentation. Keep runtime logic pure and expose rich functionality.

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

---

**LoopX is organized into three distinct layers — a public-safe core control-plane, a thin CLI orchestration layer, and an extensible presentation layer — designed to keep runtime logic pure while exposing rich functionality to users and external systems.**

This deep dive examines the **LoopX repository structure** as implemented in `huangruiteng/loopx`, exploring how its modular design separates concerns between immutable state management, command-line interfaces, and output rendering.

## The Three-Layer Architecture

LoopX follows a **single-package Python project** structure under `loopx/` with clear boundaries between layers:

| Layer | Purpose | Principal Modules |
|-------|---------|-------------------|
| **1️⃣ Core Control-Plane** | Public-safe helpers for turns, state, registry, and quota | [`turn_identity.py`](https://github.com/huangruiteng/loopx/blob/main/turn_identity.py), [`state_refresh.py`](https://github.com/huangruiteng/loopx/blob/main/state_refresh.py), [`state_projection.py`](https://github.com/huangruiteng/loopx/blob/main/state_projection.py), [`registry.py`](https://github.com/huangruiteng/loopx/blob/main/registry.py), [`quota.py`](https://github.com/huangruiteng/loopx/blob/main/quota.py) |
| **2️⃣ CLI & Command Orchestration** | Click-based commands exposing the core API | `cli_commands/`, [`worker_bridge.py`](https://github.com/huangruiteng/loopx/blob/main/worker_bridge.py), [`visible_multi_agent_launcher.py`](https://github.com/huangruiteng/loopx/blob/main/visible_multi_agent_launcher.py) |
| **3️⃣ Presentation & Extensions** | Rendering projections, static sites, and optional sinks | `presentation/`, [`visible_governance.py`](https://github.com/huangruiteng/loopx/blob/main/visible_governance.py), [`upgrade.py`](https://github.com/huangruiteng/loopx/blob/main/upgrade.py) |

This **layered architecture** ensures that sensitive runtime details never leak into public interfaces while maintaining flexibility for extension.

## Core Control-Plane Layer

The foundation of **LoopX's structure** resides in its public-safe core modules that model agent execution semantics.

### Turn Identity and State Management

Every agent execution in LoopX is framed as a **turn** with a validated, public-safe identifier:

```python
from loopx.turn_identity import normalize_turn_instance_id

turn_id = normalize_turn_instance_id("my-turn-01")

# Returns a normalized, validated turn instance identifier

```

*Source:* [[`loopx/turn_identity.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/turn_identity.py)](https://github.com/huangruiteng/loopx/blob/main/loopx/turn_identity.py)

State management follows an **immutable state graph** pattern across three specialized modules:

- **[`state_refresh.py`](https://github.com/huangruiteng/loopx/blob/main/state_refresh.py)** — Persists and refreshes state snapshots
- **[`state_projection.py`](https://github.com/huangruiteng/loopx/blob/main/state_projection.py)** — Creates public-safe views of internal state
- **[`state_migration.py`](https://github.com/huangruiteng/loopx/blob/main/state_migration.py)** — Evolves state schemas over time

### Registry, Quota, and Lifecycle Gates

The core layer enforces resource boundaries through:

| Module | Function |
|--------|----------|
| [`registry.py`](https://github.com/huangruiteng/loopx/blob/main/registry.py) | Stores and retrieves public-safe objects |
| [`quota.py`](https://github.com/huangruiteng/loopx/blob/main/quota.py) | Enforces resource limits with request-grant semantics |
| [`ready_score.py`](https://github.com/huangruiteng/loopx/blob/main/ready_score.py) | Calculates numeric readiness metrics for turns |
| [`promotion_gate.py`](https://github.com/huangruiteng/loopx/blob/main/promotion_gate.py) | Determines promotion eligibility based on ready scores |

```python
from loopx.registry import Registry
from loopx.state_projection import project_state

registry = Registry()
registry.register("turn", turn_id, {"status": "running"})

proj = project_state()  # Public-safe projection of entire system

```

## CLI and Command Orchestration Layer

All user-facing interaction flows through **`loopx/cli_commands/`**, a directory of thin Click wrappers that parse arguments, delegate to core helpers, and emit structured output.

### Core Command Modules

| Command | Purpose | Source File |
|---------|---------|-------------|
| `turn` | Starts agent turns with validated IDs | [[`cli_commands/turn.py`](https://github.com/huangruiteng/loopx/blob/main/cli_commands/turn.py)](https://github.com/huangruiteng/loopx/blob/main/loopx/cli_commands/turn.py) |
| `todo` | Manages task lists attached to turns | [[`cli_commands/todo.py`](https://github.com/huangruiteng/loopx/blob/main/cli_commands/todo.py)](https://github.com/huangruiteng/loopx/blob/main/loopx/cli_commands/todo.py) |
| `project_lifecycle` | Installs/upgrades project skills | [[`cli_commands/project_lifecycle.py`](https://github.com/huangruiteng/loopx/blob/main/cli_commands/project_lifecycle.py)](https://github.com/huangruiteng/loopx/blob/main/loopx/cli_commands/project_lifecycle.py) |
| `quota_request` | Requests additional resources | [[`cli_commands/quota_request.py`](https://github.com/huangruiteng/loopx/blob/main/cli_commands/quota_request.py)](https://github.com/huangruiteng/loopx/blob/main/loopx/cli_commands/quota_request.py) |
| `presentation` | Generates UI artifacts from state | [[`cli_commands/presentation.py`](https://github.com/huangruiteng/loopx/blob/main/cli_commands/presentation.py)](https://github.com/huangruiteng/loopx/blob/main/loopx/cli_commands/presentation.py) |

### Worker Bridge and Multi-Agent Launcher

Two specialized modules extend CLI capabilities:

- **[`worker_bridge.py`](https://github.com/huangruiteng/loopx/blob/main/worker_bridge.py)** — Connects CLI processes to background workers for long-running tasks
- **[`visible_multi_agent_launcher.py`](https://github.com/huangruiteng/loopx/blob/main/visible_multi_agent_launcher.py)** — Spawns coordinated tmux sessions for interactive multi-agent debugging

```bash

# Start a new turn via CLI

loopx turn --instance-id my-turn-01

# List todos for current turn

loopx todo list

# Request additional quota

loopx quota request --memory 2GB

```

## Presentation and Extensions Layer

LoopX treats all UI surfaces as **projections** of public-safe state, enabling multiple output formats without core changes.

### Static Site Generation and Sinks

- **[`presentation/static_site.py`](https://github.com/huangruiteng/loopx/blob/main/presentation/static_site.py)** — Renders markdown/HTML from state graph
- **`presentation/sinks/`** — Stream output to external services (e.g., [`openviking_periodic_report.py`](https://github.com/huangruiteng/loopx/blob/main/openviking_periodic_report.py))

### Governance and Self-Upgrade

| Module | Responsibility |
|--------|----------------|
| [`visible_governance.py`](https://github.com/huangruiteng/loopx/blob/main/visible_governance.py) | Runtime governance checks |
| [`upgrade.py`](https://github.com/huangruiteng/loopx/blob/main/upgrade.py) | Self-upgrade logic encapsulated |

```bash

# Generate static site from current state

loopx presentation static-site --output ./site

```

## Execution Flow: How Layers Interact

The **LoopX structure** enforces a unidirectional flow:

1. **User invokes CLI command** — Click parses arguments in `cli_commands/`
2. **Command calls core helpers** — Turn identity, registry, state projection
3. **Core manipulates immutable state** — May spawn workers via `worker_bridge`
4. **Presentation renders output** — Static sites, reports, or interactive sessions

This separation guarantees that **runtime logic remains pure**, the **CLI stays thin**, and **presentation layers are interchangeable**.

## Summary

- **LoopX structure** comprises three layers: core control-plane, CLI orchestration, and presentation/extensions
- Core modules in `loopx/` enforce **public-safe contracts** — no credential leakage
- CLI commands in `cli_commands/` are thin Click wrappers delegating to core helpers
- Presentation layer treats UI as **state projections**, enabling multiple output formats
- **Immutable state graph** with refresh, projection, and migration lifecycle
- Worker bridge and multi-agent launcher support background and interactive execution

## Frequently Asked Questions

### What is the purpose of turn identity in LoopX?

**Turn identity provides a validated, public-safe identifier for each agent execution cycle.** The `normalize_turn_instance_id()` function in [`loopx/turn_identity.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/turn_identity.py) ensures consistent naming conventions while preventing identifier collisions across long-running agent sessions.

### How does LoopX prevent sensitive data from leaking through its CLI?

**All CLI commands delegate to core helpers that enforce public-safe contracts.** The core control-plane never exposes internal state directly; instead, [`state_projection.py`](https://github.com/huangruiteng/loopx/blob/main/state_projection.py) creates sanitized views. This architecture guarantees that credentials and runtime internals remain isolated from user-facing interfaces.

### Can LoopX be used programmatically without the CLI?

**Yes — the core modules are designed for direct import.** Python scripts can use `from loopx.turn_identity import normalize_turn_instance_id`, `from loopx.registry import Registry`, and other core helpers without invoking any Click commands, enabling integration into larger applications.

### What role does the worker bridge play in LoopX architecture?

**The worker bridge connects synchronous CLI processes to asynchronous background workers.** Defined in [`loopx/worker_bridge.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/worker_bridge.py), it enables long-running tasks to execute outside the CLI process lifecycle while maintaining state coherence through the core control-plane's registry and projection systems.