An APX Interface Should Ask the Daemon, Not a Plugin

A new APX interface should not learn how to manage plugins. It should ask the daemon.

That sounds like an implementation detail, but it is a boundary that keeps agent behavior coherent as APX gains surfaces.

APC is the portable context layer. A repository can carry AGENTS.md, .apc/agents/, skills, and other durable project rules. APX is the daily-use runtime and tooling layer: it reads that context, runs agent work locally, and exposes it through a CLI, web panel, desktop client, and other interfaces.

The important split inside APX is just as deliberate. The architecture documents three layers: core/ for shared logic, host/ for long-running processes, and interfaces/ for surfaces. The daemon lives in host/. It is the only layer that talks to plugins. Interfaces communicate with the daemon over HTTP.

Why plugin ownership belongs in one place

A plugin lifecycle has runtime consequences. It can affect tool availability, connected services, configuration, and the current local installation. If a web panel, CLI, and desktop client each called plugins directly, each surface would need its own lifecycle code and its own interpretation of failure, configuration, and state.

That creates drift fast. A plugin might look enabled in one surface, unavailable in another, and half-configured in a third. Worse, a new interface could accidentally become a second runtime with rules that only apply there.

The daemon is the right owner because it is already the long-running APX process. It can coordinate plugin lifecycle once, keep the runtime state local, and expose one API to every surface. An interface then has a simpler job: collect a human action, call the daemon, and render the response.

A practical design test

Imagine adding a button to an APX panel that connects an integration. The button should not import a plugin package and start configuring it in the browser code. Instead, the panel sends a request to the daemon. The daemon checks the runtime configuration, performs the lifecycle work, records the local result, and returns a status the panel can show.

The same operation can then be reached from another interface without reimplementing the integration:

• the CLI can call the daemon endpoint or command path
• the web panel can display progress and errors
• a desktop surface can trigger the same action

One operation; one runtime owner.

This also gives failures a clear home. If a connection fails, debug daemon and plugin boundary first. If the daemon reports success but one screen renders it incorrectly, debug that interface. Without this separation, every incident starts as a guessing game across several partial implementations.

What APC has to do with it

APC does not own plugin lifecycle. Its job is to preserve project context that can travel with a clone. A project may state safe, durable tool expectations in its context, but it should not turn a plugin's live local state into repository truth.

APX turns that portable context into daily work. Keeping plugin ownership in the daemon lets every interface use the same runtime interpretation of the project while keeping machine-specific operational state out of APC.

That is the useful rule:

• APC carries shared project context.
• APX core contains shared logic.
• APX daemon owns plugin contact and runtime lifecycle.
• APX interfaces stay clients, not alternate runtimes.

A thin interface is not less capable. It is more reliable because it does not need to guess how the runtime works.