APX Keeps One Core So APC Can Reach Every Surface

A lot of agent tools quietly split into separate products.

The CLI has one behavior. The web panel grows another. Telegram gets a simplified bot loop. Voice gets its own prompt stack. A desktop helper starts reimplementing the same decisions again.

That architecture looks fast at first, but it usually creates drift.

APC and APX avoid that split on purpose.

APC is the portable context layer. It keeps the durable project contract in the repository: AGENTS.md, .apc/, agent files, skills, commands, and MCP hints. APX is the daily-use runtime and tooling layer. It reads that context, runs the agent loop, and exposes it through surfaces like CLI, web, desktop, routines, and Telegram.

The key detail is this: APX tries to keep one core agent loop instead of building a different brain for every surface.

Why this matters

The APX architecture decision record is explicit about the split: src/core/ holds shared logic, src/host/ holds long-running daemon processes, and src/interfaces/ holds user-facing surfaces.

That is not just folder cleanup.

It means the important behavior lives once.

The prompt builder, model routing, tool loop, memory broker, lazy tool activation, and judge loop belong in core/. The daemon adapts that logic to HTTP, plugins, and runtime processes. CLI, web, desktop, and other interfaces stay thin.

That design protects APC too.

If every surface started inventing its own prompt rules and its own reading of project context, APC would stop being a portable contract and become a vague suggestion interpreted differently by each entry point. A portable context layer only works when the runtime keeps interpretation consistent.

Concrete example from APX

In APX, runSuperAgent() lives in src/core/agent/super-agent.js.

That single function assembles relevant memory, active thread context, lazy tool state, model routing, confirmation handling, and the optional judge loop before calling the shared agent runner.

Then multiple surfaces call into that same logic.

The code graph shows inbound calls from the daemon API, desktop plugin flow, Telegram reply path, routines, code mode, and subagent execution. That is exactly the point: different surfaces, same core behavior.

The system prompt assembly follows the same rule. buildSuperAgentSystem() in src/core/agent/prompt-builder.js layers identity, memory, channel context, project index, project agent context, skills, and voice-mode rules into one composed system prompt. The surface can pass channel metadata, but it does not fork the whole prompt model.

So when APC project context changes, APX does not need five separate implementations to catch up.

What thin surfaces buy you

This approach has three practical benefits.

First, behavior stays aligned. If the core agent loop learns a new safety rule or memory rule, web and Telegram do not lag behind the CLI.

Second, new surfaces get cheaper. Adding a desktop voice shell or browser admin is mostly adapter work if the core already knows how to read APC context, route models, and run tools.

Third, bugs become easier to reason about. When one surface behaves strangely, you can ask whether the problem is in the shared core or only in the adapter. That is much clearer than debugging five near-copies of the same runtime.

Why APC depends on this discipline

APC should stay small, portable, and repo-owned. It should define what the project means, not how every transport invents its own execution semantics.

APX is where execution semantics belong.

But if APX let each surface grow a separate runtime brain, the result would still damage portability. The same AGENTS.md and .apc/ files would lead to different agent behavior depending on whether you came in through CLI, desktop, web, or Telegram.

That would make APC weaker, even if APC itself stayed clean on disk.

So the real win is not only that APX has many interfaces. The win is that those interfaces stay thin enough to share one interpretation layer.

APC carries the project contract.
APX carries the execution machinery.
Keeping one core inside APX is what lets that contract survive contact with daily use.