# Understanding LoopX Kernel Capabilities, Providers, and Extensions: Architecture Explained

> Explore the LoopX kernel architecture. Understand how capabilities define what the system does, providers implement how, and extensions manage these providers for seamless operation.

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

---

**The LoopX kernel uses a three-layer design where capabilities define *what* the system can do, providers implement *how* it's done, and extensions package and lifecycle-manage those providers.**

LoopX is an open-source AI agent framework that keeps its core kernel lightweight by separating interface contracts from implementation details. This article breaks down the relationship between **LoopX Kernel Capabilities, Providers, and Extensions** based on the actual source code in `huangruiteng/loopx`.

## What Are Capabilities in LoopX?

Capabilities are kernel-level contracts that describe concrete outcomes without containing any implementation logic. Think of them as interfaces that declare: what inputs they accept, what outputs they produce, and what authority model governs access.

In [`loopx/capabilities/registry.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/capabilities/registry.py), capabilities are registered in a central registry that maps capability names to their runtime handlers. A capability like `reward_memory` or `periodic_report` defines the shape of its request and response, but **never** talks to external services or runs business logic directly.

```python

# Request a capability – the kernel looks up the provider_id

request = {
    "capability": "reward_memory",
    "provider_id": "loopx_cli",   # provider provided by an extension

    "payload": {...}
}
session = execute_reward_memory_recall(request)   # core capability logic

```

This separation allows the kernel to remain stable while implementations evolve.

## What Are Providers in LoopX?

Providers are the concrete implementations that satisfy a capability's contract. When the kernel receives a capability request, it delegates execution to the provider specified by `provider_id` in the request payload.

Provider code lives in the **extensions** layer. For example, [`loopx/extensions/lark/provider.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/extensions/lark/provider.py) implements a provider that fulfills the `periodic_report` capability by talking to Lark APIs:

```python

# A minimal provider implementation inside an extension

# loopx/extensions/lark/provider.py

class LarkProvider:
    def __call__(self, request):
        # talk to Lark APIs, produce a bounded observation

        return {"observation": "...", "effect": "..."}

```

The test suite in [`tests/capabilities/test_provider_gateway.py`](https://github.com/huangruiteng/loopx/blob/main/tests/capabilities/test_provider_gateway.py) demonstrates how requests are routed from capability to the selected provider using the `provider_id` field.

## What Are Extensions in LoopX?

Extensions are the packaging and lifecycle wrapper around one or more providers. An extension bundles providers, declares which capabilities they implement, and exposes a manifest that the kernel reads at startup.

The extension runtime in [`loopx/extensions/runtime.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/extensions/runtime.py) handles:

- Installation and loading
- Readiness checks
- Enable/disable toggles
- Upgrades and versioning

Each extension includes an [`extension.toml`](https://github.com/huangruiteng/loopx/blob/main/extension.toml) manifest:

```toml

# Extension manifest declares which capability it implements

# loopx/extensions/lark/extension.toml

[[provides]]
capability = "periodic_report"
provider_id = "lark"

```

When an extension is enabled, its providers become visible to the capability registry and can be invoked by the kernel.

## How LoopX Kernel Capabilities, Providers, and Extensions Work Together

The relationship follows a clear delegation chain:

1. **Kernel** receives a capability request containing a `capability` name and `provider_id`
2. **Capability registry** validates that the capability exists and the provider is authorized
3. **Extension runtime** ensures the provider's extension is loaded and enabled
4. **Provider** executes the actual implementation and returns a bounded result

This architecture gives LoopX three critical properties:

- **Kernel stays lightweight** — core code only handles routing and contracts
- **Providers are swappable** — same capability, different implementations via different `provider_id` values
- **Extensions are self-contained** — add new capabilities by dropping in a new extension directory

## Key Source Files for LoopX Extension Architecture

| Component | File Path | Purpose |
|-----------|-----------|---------|
| Capability registry | [`loopx/capabilities/registry.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/capabilities/registry.py) | Maps capability names to runtime handlers |
| Provider example | [`loopx/extensions/lark/provider.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/extensions/lark/provider.py) | Sample implementation of `periodic_report` |
| Extension runtime | [`loopx/extensions/runtime.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/extensions/runtime.py) | Loads manifests, manages provider lifecycle |
| Architecture docs | [`docs/reference/extensions.md`](https://github.com/huangruiteng/loopx/blob/main/docs/reference/extensions.md) | Conceptual overview of the three-layer model |
| Integration tests | [`tests/capabilities/test_provider_gateway.py`](https://github.com/huangruiteng/loopx/blob/main/tests/capabilities/test_provider_gateway.py) | Demonstrates request routing through the stack |

## Adding a New LoopX Extension: Practical Steps

To extend LoopX with a new capability:

1. **Define the capability contract** in `loopx/capabilities/` (or reuse existing)
2. **Create a provider class** that implements `__call__(self, request)` and returns the expected response shape
3. **Package as extension** with [`extension.toml`](https://github.com/huangruiteng/loopx/blob/main/extension.toml) declaring `[[provides]]` entries
4. **Place in `loopx/extensions/`** or install dynamically via the extension runtime

The kernel automatically discovers enabled extensions at startup and registers their providers with the capability registry.

## Summary

- **Capabilities** describe *what* must be achieved — kernel-level contracts with no implementation
- **Providers** deliver *how* it is achieved — concrete classes in extensions that satisfy capability contracts
- **Extensions** own *deployment* of providers — packaging, lifecycle, and manifest declaration
- The **kernel** routes requests from capability name + `provider_id` to the correct provider through the capability registry and extension runtime

This design keeps LoopX core minimal while making new integrations pluggable via simple extension additions.

## Frequently Asked Questions

### What is the difference between a LoopX capability and a provider?

A **capability** is an interface definition — it specifies inputs, outputs, and authority but has no code that executes. A **provider** is the actual implementation that fulfills that contract. Multiple providers can exist for the same capability, selected at request time via `provider_id`.

### How does LoopX know which provider to use for a capability request?

The request payload includes a `provider_id` field. The kernel consults [`loopx/capabilities/registry.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/capabilities/registry.py) to validate the capability, then asks the extension runtime in [`loopx/extensions/runtime.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/extensions/runtime.py) to locate the provider with matching ID from loaded extensions.

### Can I use multiple providers for the same capability in LoopX?

Yes. The same capability can have multiple providers across different extensions, each with a unique `provider_id`. Requesters choose which provider to invoke by specifying the appropriate ID in their request payload.

### Where do I add a new capability implementation in LoopX?

Create a new directory under `loopx/extensions/`, add your provider class (typically [`provider.py`](https://github.com/huangruiteng/loopx/blob/main/provider.py)), and include an [`extension.toml`](https://github.com/huangruiteng/loopx/blob/main/extension.toml) manifest declaring which capabilities your extension provides. The extension runtime will discover and register your provider automatically.