LoopX Extension vs Built‑In Capability Boundary Rules Explained

LoopX enforces four strict architectural boundaries—Kernel, Capability, Provider, and Extension—to separate permanent core features from optional installable components.

The LoopX system, developed in the huangruiteng/loopx repository, uses a layered architecture to maintain stability while enabling extensibility. Understanding the boundary rules between built‑in capabilities (shipped with the product) and extensions (optional provider packages) is essential for developers building on or contributing to the platform.

The Four Architectural Boundaries

LoopX defines four distinct ownership layers that prevent extensions from interfering with core system guarantees:

Boundary	Core Responsibility	Location in Codebase
Kernel	Owns durable goal state, todos, gates, evidence, quota, recovery, and scheduling truth	loopx/kernel/ (referenced in README.md lines 66‑69)
Capability	Defines a stable, provider‑neutral contract that produces one bounded, verifiable outcome from LoopX state	loopx/capabilities/
Provider	Calls external systems or local implementations; returns observations, effect results, and read‑back data	Implementation varies (built‑in or extension)
Extension	Packages an optional provider and manages lifecycle (install, enable, upgrade, disable, rollback)	extensions/ or packages/ for distribution

These boundaries ensure that extensions never own kernel state or modify capability contracts—they merely deliver alternative provider implementations.

How Built‑In Capabilities Work

Built‑in capabilities are permanent features shipped with every LoopX installation. They define three things:

• The contract (input/output schema)
• Validation rules for provider read‑backs
• A default provider implementation

Locating Built‑In Capabilities

Built‑in capabilities reside under loopx/capabilities/ and are documented in loopx/capabilities/README.md. Each capability has its own subdirectory with documentation and implementation.

# List all shipped capabilities

loopx capability list --format json

# Inspect the built-in Issue Fix capability

loopx capability show issue-fix --format json

The issue-fix capability lives at loopx/capabilities/issue_fix/, with detailed documentation in loopx/capabilities/issue_fix/README.md. This exemplifies how built‑in capabilities are always available without any extension installation.

How Extensions Extend (Without Overriding)

Extensions enter the architecture only when a capability needs a non‑default provider. An extension:

• Packages provider code in extensions/<provider-name>/
• Registers runtime lifecycle hooks
• Remains stateless with respect to the kernel

Extension Installation and Activation Workflow

# Install an optional provider for the "explore" capability

loopx extension install explore-openai-provider

# Enable the new provider

loopx extension enable explore-openai-provider

# Run explore capability (now using the extension's provider)

loopx capability show explore --format json

The explore-openai-provider extension does not modify loopx/capabilities/explore/ or any kernel files. As documented in extensions/explore-openai-provider/README.md, it only supplies an alternative provider implementation.

Registering a Custom Provider via Extension

Developers can create custom providers using the extension registration API. The capability contract remains unchanged—the extension merely adds a new provider to the registry.

from loopx.extensions import register_provider

@register_provider('my_custom_provider')
def fetch_data(state):
    # External API call or local computation

    return {"result": "ok", "observations": [...]}

After registration, the capability can select this provider at runtime:

loopx capability run my-capability --provider my_custom_provider

The register_provider decorator adds the function to the extension registry without altering the capability definition or kernel state.

Comparison: Built‑In vs Extension Boundaries

Aspect	Built‑In Capability	Extension
Permanence	Shipped with LoopX; cannot be uninstalled	Optional; can be installed, disabled, or removed
State ownership	May interact with kernel state	Never owns kernel state
Contract control	Defines and owns the capability contract	Must conform to existing contract
Lifecycle	Fixed with product release	Managed via install, enable, disable, rollback
Code location	loopx/capabilities/	extensions/ or external packages

Critical Boundary Enforcement Rules

According to the LoopX source code, these rules are architecturally enforced:

1. Extensions are not control‑plane owners — They deliver providers; they do not manage kernel scheduling or goal state.
2. Capability contracts are provider‑neutral — The same capability can run with built‑in or extension providers without code changes.
3. Provider read‑backs are validated by the capability — The capability layer, not the extension, validates that provider results satisfy the contract.
4. Extension lifecycle hooks are runtime‑only — Installation and enablement do not modify capability definitions or kernel data structures.

Key Files for Understanding Boundaries

File Path	Purpose
README.md (lines 66‑73, Capability surface section)	High‑level overview of four boundaries and their interactions
loopx/capabilities/README.md	Index of all shipped built‑in capabilities
docs/reference/extensions.md	Extension lifecycle specification and plugin architecture
loopx/capabilities/issue_fix/README.md	Concrete example of built‑in capability structure
extensions/<provider-name>/README.md	Example: optional provider packaged as extension

Summary

• LoopX kernel owns all durable state—extensions can never modify it directly.
• Built‑in capabilities are permanent, provider‑neutral contracts in loopx/capabilities/.
• Extensions only package optional providers and manage their lifecycle—no capability or kernel ownership.
• The register_provider decorator (from loopx.extensions) is the sanctioned extension point for adding providers.
• Consult docs/reference/extensions.md and the README's Capability surface section for authoritative boundary specifications.

Frequently Asked Questions

Can an extension modify a built‑in capability's contract?

No. Extensions strictly implement existing capability contracts. The contract—input schema, validation rules, and output guarantees—is owned by the capability layer and cannot be altered by extensions. An extension that needs different contract semantics must target a different capability or propose changes to the core repository.

What happens if I disable an extension that is currently active?

The capability falls back to its default provider or fails gracefully with a provider‑unavailable error. Because extensions do not own kernel state, disabling one cannot corrupt goals, todos, or scheduling data. The extension lifecycle is documented in docs/reference/extensions.md.

How do I know whether a capability is built‑in or requires an extension?

Run loopx capability list --format json. Built‑in capabilities show source: "core"; extension‑provided capabilities indicate their source extension. The capability catalog at loopx/capabilities/README.md also documents all shipped capabilities.

Can I use multiple providers for the same capability simultaneously?

Yes. The capability contract permits runtime provider selection via --provider flags or configuration. You can enable multiple provider extensions and switch between them per invocation without reinstalling or reconfiguring the capability itself.

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