DEV Community: Manuel Bruña

A Local Admin Panel Still Needs Auth in APX

Manuel Bruña — Wed, 05 Aug 2026 12:04:02 +0000

A Local Admin Panel Still Needs Auth in APX

A local admin panel should feel convenient, not anonymous.

That boundary matters for APC and APX.

APC is the portable context layer. It keeps project meaning in the repo through AGENTS.md, .apc/, agent files, skills, and other committed artifacts. APX is the daily-use runtime and tooling layer. It exposes that project through a daemon, CLI, web admin, pairing flow, and local state under ~/.apx/.

Because APX owns runtime state, it also has to protect it.

That is why the web admin in APX does not treat localhost like a permission model.

At first glance, a local-only UI can look harmless. If the browser and daemon are on the same machine, it is tempting to assume the panel can just trust every request. But the panel can read projects, sessions, messages, MCPs, config, and other runtime-only data. APC keeps portable project context in the repository, but APX keeps operational state outside the repo for a reason. That state still needs an access boundary.

APX handles this with a small bootstrap path instead of making the whole HTTP surface public.

In src/host/daemon/api/shared.js, auth is bearer-token based. Data routes require Authorization: Bearer ... unless they are on a short allowlist. The important exception is /admin/web-token, which is intentionally unauthenticated only so the local admin bundle can bootstrap itself. The comments are explicit: /admin/web-token is for the same-origin admin panel, and that endpoint performs its own localhost checks.

The allowlist stays narrow on purpose:

/health stays public for liveness checks.
/pair/* stays open so a fresh device can bootstrap a token.
/admin/web-token stays open so the local browser can fetch its bearer.
Static assets and known SPA routes can load without a token, but data GETs do not.

That last point is the important hardening step.

Older daemon designs often used prefix denylists and accidentally leaked new data routes when somebody forgot to register them. APX goes the other direction. In the auth middleware, unknown extension-less GET routes are treated as protected by default. Only static files and known client-router paths pass before the token is present.

The tests make this concrete.

tests/health-auth.test.js checks that /projects rejects missing or wrong bearer tokens, while /assets/app-abc123.js and /settings can load without getting blocked by the auth wall. tests/security-hardening.test.js adds regression coverage for routes like /plugins and /skills, asserting that they now require a token even though they are GET endpoints.

So the web panel opens in two phases:

The browser loads the shell and assets.
The panel fetches /admin/web-token and uses that bearer for actual API calls.

The docs describe the same flow. On the local machine, the panel fetches its token automatically from /admin/web-token. On another device, apx pair web prints a URL with a #token=... fragment so the paired browser can authenticate without exposing the full daemon publicly by default.

That design fits the APC/APX split well.

APC should stay portable, reviewable, and repo-owned. It should not need to encode browser auth rules. APX should own runtime concerns such as daemon auth, paired devices, local sessions, and route protection. If those concerns leak back into APC, the project contract gets polluted with machine-local policy. If APX ignores them, the runtime becomes too trusting.

So the practical rule is simple:

APC defines project context.
APX exposes runtime surfaces.
Every runtime surface still needs an access boundary, even on localhost.

A local admin panel is still an admin panel.

APX gets that right by keeping the portable layer clean and putting authentication exactly where the runtime belongs.

APX Should Assemble Context, Not Dump APC Into Every Prompt

Manuel Bruña — Tue, 04 Aug 2026 12:04:23 +0000

APX Should Assemble Context, Not Dump APC Into Every Prompt

A portable context system becomes less useful the moment a runtime treats it like a blob.

That is the line APC and APX need to keep clear.

APC is the portable context layer. It gives a repository durable project meaning through AGENTS.md, .apc/, agent files, skills, and other committed artifacts. APX is the daily-use runtime and tooling layer. Its job is not to shovel all of that into every turn. Its job is to assemble the smallest useful prompt for the current surface and request.

That distinction matters because prompt assembly is a runtime problem, not a file-format problem.

If an agent runtime blindly dumps full project context into every prompt, three things usually go wrong:

prompt budgets get wasted on context that does not matter for this turn
the model gets nudged toward irrelevant instructions
the portable layer starts getting blamed for runtime bloat it did not cause

APX avoids that by treating APC as a source of durable context, then selecting pieces deliberately.

What APX actually assembles

In src/core/agent/prompt-builder.js, buildSuperAgentSystem() builds the final system prompt as layered blocks instead of one giant static file. The assembled prompt can include role, user context, memory, active threads, channel rules, project guidance, skills hints, lazy tools, voice mode, and final format directives.

That design matters because different turns need different slices.

A web-admin session can tolerate longer markdown guidance. A one-shot CLI call should stay tighter. Voice mode is not even treated as its own channel. APX keeps channels as surfaces and layers voice on top as a mode. That avoids fake channel duplication and keeps formatting rules narrower.

APC stays durable; APX stays selective

The useful APC lesson here is simple: durable context should exist in the repo, but runtime injection should stay selective.

APX even caps raw project guidance when it reads AGENTS.md into a prompt. The project guidance block is size-limited instead of assuming every repository rule file should enter every turn in full. That is exactly the right boundary.

APC preserves the contract. APX decides how much of that contract belongs in this specific interaction.

That same pattern shows up in skills.

buildSkillsHintBlock() does not preload every skill body. It exposes a catalog hint with slugs and explicitly tells the runtime to load details on demand through list_skills and load_skill({slug}). In other words, APC can hold durable skill files, but APX does not pay the full prompt cost unless the current request needs exact syntax.

That is a better use of both portability and tokens.

Why on-demand skill loading matters

This is also why the optional skill inspector in APX is interesting.

In src/core/agent/skills/inspector.js, inspectPromptForSkills() checks whether the feature is enabled, ignores prompts below a floor, refreshes stale indexes in the background, and only then tries to inject matching skill context. If the embedder does not match the saved index, it refuses to mix vector spaces and asks the operator to re-index instead.

That is not accidental complexity. It is runtime discipline.

The portable layer says, "These skills exist."

The runtime layer says, "For this turn, only these parts are worth paying for."

Without that separation, an APC-compatible project with many skills would quietly punish every request, even simple ones.

Practical takeaway

If you are building on APC, resist the urge to equate portability with maximum injection.

A good APC project should be rich enough that multiple tools can understand it. A good APX runtime should still be strict about what enters the prompt each turn.

That usually means:

keep durable project facts in APC
keep prompt assembly decisions in APX
load skill bodies only when exact detail matters
keep channel formatting scoped to the current surface
treat prompt budget as part of runtime architecture, not as an afterthought

That is the deeper reason the pair works well together.

APC gives the project one portable home for context.

APX makes that context usable every day by refusing to turn portability into prompt spam.

I Added ACP to APX Without Adding a Second Brain

Manuel Bruña — Mon, 03 Aug 2026 13:10:05 +0000

I Added ACP to APX Without Adding a Second Brain

The first time I looked at ACP support for APX, I felt the usual temptation: build a special path for the new protocol, give it its own session store, tune it for IDE behavior, and let it grow into a separate product-shaped thing.

That would have been a mistake.

The real lesson for me was simpler: ACP should be a thin adapter, not a second brain. If APX already has a daemon, a super-agent, and a stream of events that describes a turn, then the ACP surface should translate that work, not re-implement it.

That choice sounds small. It is not. It decides whether a new surface stays cheap to maintain or slowly becomes a fork with better branding.

What ACP is doing in APX

APX already knows how to talk to its own daemon. The ACP agent in src/interfaces/acp/index.js does not start a parallel reasoning engine. It opens a JSON-RPC 2.0 stream on stdio and maps ACP session calls onto the daemon's existing chat stream.

That is the important part.

A client calls session/new, session/prompt, or session/cancel. APX does the rest through the same runtime path it already uses elsewhere. The ACP layer is just a translator between one protocol and another.

In practice, that means:

initialize reports the ACP version and basic capabilities
authenticate is accepted as a no-op because daemon auth stays on the local bearer token
session/new resolves the project from the working directory
session/prompt streams the prompt into /projects/:pid/super-agent/chat/stream
session/cancel aborts the active turn

That is enough.

The protocol surface can be rich without becoming a second implementation. That distinction matters more than it looks.

Why I did not give ACP its own state machine

I have built enough agent tooling now to know what happens when a surface starts storing its own truth.

At first it feels convenient. The new client gets fast shortcuts. The code looks localized. You can add a field here, a cache there, maybe one special handler for the IDE case.

Then the drift begins.

One session store says the prompt happened.
Another store says it did not.
One adapter thinks cancellation means one thing.
Another adapter thinks it means something slightly different.
By the time you notice, the system is no longer one system.

So I kept ACP session state minimal. The adapter keeps just enough in memory to make the connection work: session id, conversation history, active turn, and a few counters for updates. No daemon-side ACP session database. No duplicate agent brain. No second source of truth.

That is boring. It is also easier to reason about.

The daemon already owns the real work. ACP should not compete with it.

The stream is the contract

The cleanest thing about this design is that ACP listens to the daemon's stream instead of inventing its own event language.

The mapping is plain:

assistant_text becomes agent_message_chunk
tool_start becomes tool_call
tool_result becomes tool_call_update
confirmation_required becomes an ACP permission round-trip
final becomes the session response

That one-to-one mapping matters because it keeps the adapter honest.

If the daemon says a tool started, ACP does not re-label it into something fancier. If the daemon ends with a final result, ACP does not hide it behind another layer of interpretation. The client sees the same work, only wrapped in ACP wire shapes.

I like that because it preserves debugging power. When something goes wrong, I can trace it through the same stream APX already uses. I do not need to ask whether ACP invented a separate failure mode.

Why history stays in the client connection

One subtle choice in the ACP code is that conversation history stays per connection, in memory.

That might sound like a compromise. For this surface, it is the right one.

The history exists so the ACP session can feed previousMessages on the next turn. That lets a client keep context without forcing the daemon to become a session database for every external protocol that touches it.

It also keeps the adapter narrow. The daemon still owns the real runtime. The ACP client owns its own conversation continuity. APX just bridges the turn.

That split is useful because ACP clients are not all the same. Some are IDEs. Some are editors. Some are automation surfaces. I do not want APX to guess their long-term memory model for them.

The real reason I wanted ACP at all

I did not add ACP because I wanted another badge on the README.

I added it because I want APX to reach more surfaces without changing its core shape.

The CLI is still the CLI.
The daemon is still the daemon.
The web admin is still a local window onto the same runtime.
ACP just lets other clients drive the same super-agent in a language they already speak.

That is the whole point of APC for me: one project context, many compatible tools. If APX is going to be the runtime layer for that idea, then protocol adapters should be cheap, local, and replaceable.

A thin ACP bridge gives me that.

A second brain would not.

What this changed in my thinking

This work changed how I judge new surfaces.

Now I ask a few blunt questions before I add anything:

Does this surface need its own state, or can it reuse the daemon?
Is this a translation layer, or am I sneaking in a fork?
Can I map events one-to-one, or am I inventing new semantics just because I can?

If the honest answer starts drifting toward "new brain," I stop and simplify.

That is not purity for its own sake. It is maintenance math.

Every extra brain creates another place where bugs can hide. Every thin adapter keeps the system closer to the contract I already trust.

The rule I kept

My rule for ACP ended up very close to the rule I keep for APC itself: preserve the contract, do not duplicate the contract.

APC says the project context should stay portable.
APX says the runtime should stay local.
ACP fits only if it stays a bridge between those ideas and another client, not a new center of gravity.

So I kept it thin.

That made the code easier to read.
It made cancellation simpler.
It made debugging less theatrical.
And it kept APX from growing the one thing I did not want to maintain: a second brain pretending to be just another adapter.

APC Migration Should Classify Context, Not Copy Folders

Manuel Bruña — Mon, 03 Aug 2026 12:04:37 +0000

APC Migration Should Classify Context, Not Copy Folders

A good APC migration is not a file move. It is a classification pass.

That distinction matters because most existing agent folders mix four different things: project rules, agent definitions, runtime state, and private configuration. If you copy all of that into .apc/, you do not get a portable project contract. You get a portable mess.

APC is the portable context layer. It answers one narrow question: what should a compatible agent know when it enters this repository? APX is the daily-use runtime and tooling layer. It reads that contract, installs APC-aware behavior into current tools, and keeps operational state local.

So when you migrate a project to APC, the job is not "copy .claude/ into .apc/" or "sync every tool folder into one neutral folder." The job is to separate durable project meaning from runtime residue.

What should move into APC

The APC side should contain information that stays useful across tools and across sessions:

AGENTS.md as the root compatibility and discovery contract
structured agent definitions under .apc/agents/<slug>.md
reusable instruction blocks under .apc/skills/
curated project memory in .apc/agents/<slug>/memory.md only when it is safe for the whole team
MCP hints in .apc/mcps.json without embedded secrets

This is the material another tool can read tomorrow and still understand.

What should stay out

The tempting mistake is to migrate everything that looks agent-related. That is exactly what APC tries to prevent.

Raw sessions, transcripts, conversations, message logs, tool traces, caches, and pasted credentials do not belong in .apc/. They are runtime-owned state. They are often private, noisy, or too temporary to commit.

That is where APX becomes useful. APX keeps runtime state under ~/.apx/projects/<project-id>/ and leaves the repository for durable context only. In other words, APC gives the project a clean contract; APX gives that contract an operational home without pushing local runtime data back into git.

A practical migration test

When you find a file during migration, ask one question:

Will this still help a different compatible tool, on a different machine, in a later session?

If the answer is yes, it probably belongs in APC after curation.

If the answer is no because it is private, local, ephemeral, or just the full history of one run, keep it out of APC.

That usually leads to a simple split:

keep repository-wide rules and stable agent summaries in AGENTS.md
move structured role detail into .apc/agents/
move reusable prompts or workflows into .apc/skills/
extract only durable facts into memory.md
leave raw runtime artifacts where the runtime owns them

Why this makes APX better too

APX works better when APC stays clean.

If .apc/ contains only durable project meaning, APX can safely teach Codex, Claude Code, and other tools to treat that directory as the context source. It does not need to guess which files are safe to project, commit, review, or share. It can read the project contract from the repo and keep sessions, messages, and machine-local preferences outside it.

That boundary is the whole point of the pair:

APC makes context portable
APX makes that portable context usable today

Migration succeeds when that boundary gets sharper, not blurrier.

So the next time you convert an agent project, do not ask, "Which folders should I copy?" Ask, "Which facts belong to the project, and which ones belong to the runtime?"

That is the difference between a neutral contract and another vendor-shaped dump.

Portable Context Does Not Mean Portable Runtimes

Manuel Bruña — Sun, 02 Aug 2026 12:02:11 +0000

Portable Context Does Not Mean Portable Runtimes

A portable agent project should not pretend every machine can run the same AI CLI.

That is the distinction APC and APX get right when used together.

APC is the portable context layer. It keeps the project contract in the repository: AGENTS.md, .apc/agents, .apc/project.json, skills, commands, and MCP hints. Clone the repo somewhere else and that meaning can travel with it.

APX is the daily-use runtime and tooling layer. It makes that context runnable through a local daemon, CLI, web admin, and bridges to external coding CLIs such as Claude Code, Codex, OpenCode, Aider, Cursor Agent, Gemini CLI, and Qwen Code.

But those runtimes are not part of APC.

That matters because a repo can be portable while the machine is not.

One laptop may have codex and claude installed. Another may only have gemini and ollama. A CI runner may have none of them. If a system treats runtime availability as if it were durable project context, it starts lying. The repo says one thing, the host can do another, and now every handoff becomes fragile.

APX avoids that by making runtime detection a local operation.

The APX runtime docs are explicit: before picking a runtime, run:

apx env detect

That command reports which runtime CLIs, engines, and tools are actually available on the current machine. In other words, APC defines the project, but APX checks the ground truth before execution.

That is a better boundary than storing runtime assumptions in the repo.

A practical flow looks like this:

apx env detect
apx run reviewer --runtime codex "Review the diff in src/ for regressions"

If codex is installed, APX can spawn it. If it is not installed, the runtime is missing on that host, regardless of how cleanly the APC files travel.

This is also why APX separates apx run from apx exec.

apx run delegates to an external runtime binary. APX builds the system prompt, spawns the CLI, captures the output, and stores a session record. The external tool performs the actual model interaction and shell work.

apx exec, by contrast, stays inside APX and calls a configured engine directly. Different path, different dependency surface, same APC project context.

That split is useful because it keeps portability honest.

You can move the same APC project between machines without editing the repository. Then APX can answer a local question:

which runtimes are installed here?
which engines are configured here?
which toolchain is available here right now?

Those are runtime questions, not project-contract questions.

The APX introduction docs make the broader design even clearer: the filesystem is the source of truth for durable project meaning, while sessions, conversations, messages, caches, and other runtime state live under ~/.apx/ and never belong in the repo. Runtime availability follows that same philosophy. Installed binaries and local engine setup are machine facts.

So the practical rule is simple:

APC should describe the project in a way that can survive clone, review, and handoff.
APX should discover what the current machine can actually execute.
The repo should not pretend local runtime binaries are portable artifacts.

That makes APC more trustworthy, not less. The project contract stays small and durable. APX handles the messy part: local capability, runtime invocation, and session tracking.

Portable context is valuable because it avoids vendor lock-in and repeated setup. But portability only works when it stops at the right boundary.

The project can travel.

The runtime must still be checked.

That is why apx env detect is not a convenience feature. It is the operational guardrail that keeps APC portable and APX honest.

Structured Agent Files Should Own Detail. `AGENTS.md` Should Stay Portable.

Manuel Bruña — Sat, 01 Aug 2026 12:03:00 +0000

Structured Agent Files Should Own Detail. `AGENTS.md` Should Stay Portable.

APC works best when it does two jobs at once without mixing them.

First job: give every tool one obvious project entrypoint. That is AGENTS.md at the repo root.

Second job: give APC-aware tools a cleaner place for structured detail. That is .apc/agents/<slug>.md next to .apc/project.json.

That split matters because compatibility and structure are not the same problem.

In the APC companion spec for AGENTS.md, the root file is defined as the compatibility-facing contract for agent discovery. It lives at the project root, next to .apc/, and many tools already know how to find and read it. The same spec also says that when .apc/agents/<slug>.md exists for the same slug, that structured file should be treated as the authoritative structured definition.

That is the right boundary.

If you try to put every detail into AGENTS.md, the root contract becomes noisy. Long descriptions, custom fields, memory overrides, skill lists, and formatting edge cases all end up in the one file every runtime has to scan first. Portable discovery gets harder exactly because the “simple entrypoint” started acting like a database.

If you go the other way and drop AGENTS.md entirely, portability gets worse. A lot of tools can walk up a repo and look for one familiar root file. Fewer tools know your internal structured layout on day one.

APC avoids that tradeoff by keeping both layers.

A small root contract can look like this:

# Agents

## reviewer
- **Role**: Code review
- **Model**: gpt-5
- **Skills**: documentation
- **Description**: Reviews risks, tests, and regressions.

That is enough for discovery, routing, and a first-pass understanding of the project.

Then the richer definition can live where APC-aware tooling expects it:

.apc/
  project.json
  agents/
    reviewer.md

This also matches how APX uses the project.

APX reads AGENTS.md as project guidance at runtime. In buildProjectAgentsBlock, it loads the root file, truncates it if needed, and injects it into the prompt as “Project guidance (AGENTS.md)”. That is a strong hint about intended size and purpose: useful startup rules, not an ever-growing dump of agent internals.

APX also has a dedicated parser for AGENTS.md sections. It looks for one # Agents heading, reads each ## <slug> block, and extracts bullet fields like Role, Model, Skills, and Description. That parser exists because the root contract needs to stay predictable and portable.

So the practical rule is simple:

Put cross-tool discovery in AGENTS.md.
Put structured per-agent detail in .apc/agents/.
Keep runtime sessions, conversations, and private state out of both; APX stores those under ~/.apx/.

That gives APC a durable portable layer and gives APX a clean daily-use runtime layer.

AGENTS.md stays readable by humans and broadly compatible tools. .apc/agents stays available for richer APC-native structure. APX can then bridge both without turning either one into the wrong kind of storage.

Portable projects usually fail from overloading the first file everybody touches. APC gets farther by keeping the index small and the detail where structure belongs.

Unknown Telegram Senders Should Stay Guests in APX

Manuel Bruña — Fri, 31 Jul 2026 12:04:21 +0000

Unknown Telegram Senders Should Stay Guests in APX

A Telegram bot should not treat every new message as trusted operator input.

That sounds obvious, but a lot of agent setups still blur identity, chat membership, and tool access. Someone writes to a bot, the bot answers, and before long the same person can trigger real actions because the runtime never drew a hard line between conversation and capability.

APX draws that line on purpose.

APC is the portable context layer. It keeps the project contract in the repo: AGENTS.md, .apc/, agent definitions, skills, commands, and MCP hints. APX is the daily-use runtime and tooling layer. It reads that project context, runs the agent loop, and handles runtime state such as sessions, messages, approvals, and channel identity outside the repository.

That trust decision belongs to APX, not APC.

Guest first, tools later

The APX Telegram identity logic is explicit.

A contact is keyed by the sender's stable Telegram user_id, not by chat_id. That matters because the same person may appear across different chats, while group chats can contain many people. APX stores the person globally and only uses owner_user_id to mark who owns one specific channel.

Then it applies a simple rule:

channel owner gets owner
configured contacts can get a custom role
unknown senders become guest

That last step is the important one.

In resolveAllowedTools(), APX gives the owner "*", reads tool allowlists from telegram.roles for known roles, and otherwise returns an empty list. In other words, guests fail closed. They can talk to the bot, but they do not get tool power just because they found the chat.

That is a better default than optimistic trust.

Why this split matters

A Telegram conversation has two separate questions:

who is this person?
what may this person trigger?

If a runtime collapses those into one step, it tends to over-grant. "Known enough to answer" quietly becomes "known enough to act."

APX does not do that.

The relationship block that feeds the model prompt is also strict. For a guest sender, APX tells the model it is talking to a guest with no permissions and instructs it to ask politely who they are. That keeps the social flow natural without pretending the model can grant access on its own.

So there are really three layers working together:

runtime identity resolution
prompt context about that identity
tool allowlist enforcement

That combination is what makes the behavior safe instead of merely friendly.

Small example

Imagine a fresh project bot pinned to one APX project.

The first private message on an owner-less channel can claim ownership. After that, another sender writing to the same bot is not promoted just because the conversation is private. APX records that person as a guest.

If you later want that contact to do more, you assign a role in APX config or through the web admin, where each role maps to a concrete tool list such as call_agent or list_tasks.

That means the trust upgrade is deliberate and reviewable.

Notably, APX does not grant power because a username looks familiar, because a user joined the chat, or because the model decided the person "seems legit." The runtime owns the permission boundary.

Why APC should stay out of it

This is not durable project context. It is live runtime policy.

APC should describe the project, its agents, its skills, and other repo-owned context that can travel across machines and runtimes. It should not commit transient channel trust or personal messaging access into the project contract.

Telegram roles, ownership claims, and sender registration depend on who is operating the bot right now. That is machine-local, runtime-managed state. APX is the right home for it.

This boundary is easy to miss, but it matters.

If APC stored this kind of messaging trust directly, portability would get worse and accidental exposure would get easier. By keeping APC portable and APX responsible for channel identity, the project contract stays clean while the runtime stays cautious.

That is the real design point: APC says what the project means. APX decides who, through Telegram, gets to do anything with it.

APX Keeps One Core So APC Can Reach Every Surface

Manuel Bruña — Thu, 30 Jul 2026 12:04:50 +0000

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.

Security Risk Grades Are Not Permission Modes in APX

Manuel Bruña — Thu, 30 Jul 2026 11:29:16 +0000

Security Risk Grades Are Not Permission Modes in APX

A permission toggle answers one question: may this tool run? It does not answer a second one that matters just as much: how dangerous is this exact action right now?

That is why APX keeps permission mode and security-risk grading as two separate runtime controls.

APC is the portable context layer. It gives the project one neutral contract in the repo: AGENTS.md, .apc/, agent files, MCP hints, skills, and other durable context. APX is the daily-use runtime and tooling layer. It reads that contract, runs the agent loop, and keeps runtime decisions like approvals, sessions, and message logs outside the repository.

This topic belongs on the APX side.

Two gates, two different jobs

APX supports three permission modes for the super-agent:

total: run tools without confirmation
automatico: APX decides automatically
permiso: only allow-listed tools run directly

That gate is about tool identity. A shell tool, file editor, Telegram sender, or MCP call can have a default trust policy before the model even decides what to do.

APX also has an optional security_risk layer. When enabled, APX injects a required security_risk field into each eligible tool schema, and the model must grade the action as LOW, MEDIUM, or HIGH as part of the tool call itself. No second model pass. No separate risk service.

That gate is about action severity.

Those are not the same thing.

A tool like run_shell might be harmless for ls src and dangerous for rm -rf build. A send tool might be fine for an internal note and risky for an outward message to a real user. Static permission mode cannot see that difference by itself. The risk grade can.

Why this split matters

If you collapse both ideas into one setting, you get a bad tradeoff.

If the system is too strict, the agent asks for approval on every non-trivial step and stops being useful. If the system is too loose, one trusted tool can do a much riskier action than the user expected.

APX avoids that by keeping both layers:

permission mode decides the baseline policy for a tool
security-risk grading decides whether this call should stop

The most interesting case is total mode. In APX, the risk gate still acts as a safety floor. Low-friction work runs freely, but a HIGH-graded action can still require confirmation. That is a better model than all-or-nothing trust, because "I trust this agent" should not mean "I want zero brakes on catastrophic actions."

Small example

Imagine the same project agent, the same runtime, and the same shell tool:

apx permission set total

Now compare two actions the model could take:

grep -R TODO src/
rm -rf ./tmp/generated-cache

Permission mode alone sees one tool: shell.
Risk grading sees two different severities.

That distinction lets APX stay fast on ordinary work without pretending every shell call carries the same blast radius.

Why APC should not own this

This is exactly the kind of state APC should not carry.

APC should travel cleanly between repos, machines, and runtimes. A committed project contract should not silently force the same approval behavior everywhere. Approval thresholds, confirmation surfaces, and action gating are runtime policy. They depend on who is running the work, where, and under what level of trust.

So the repo keeps the durable project context. APX keeps the live control plane.

That split is the real point: APC tells the runtime what the project is. APX decides how safely that runtime can act today.

Docs Are Part of the Contract in APC and APX

Manuel Bruña — Thu, 30 Jul 2026 11:28:18 +0000

Docs Are Part of the Contract in APC and APX

I used to treat docs like cleanup.

Code first. Fix behavior. Then, if time remained, explain what changed.

That habit works fine until a project gets enough surface area that the docs start acting like a second implementation. At that point, stale prose is not harmless. It is a bug with better grammar.

APC and APX pushed me into a different rule: docs are part of the contract. Not marketing. Not an afterthought. Contract.

That sounds obvious until you try to keep a real project honest across multiple surfaces. APC has its spec, its repo-owned context, and its compatibility layer. APX has the runtime, the CLI, the daemon, the web admin, and local state under ~/.apx/. The moment I let one surface drift from another, people and agents start learning two truths about the same system.

That is the wrong kind of flexibility.

Why I stopped seeing docs as separate work

The turning point was simple: I noticed that every time I let docs lag behind code, I was forcing future me to re-derive the same answer twice.

Once from the implementation.
Once from the text.

That is wasteful on a small repo and expensive on a growing one.

For APC/APX, the cost is worse because the audience is not just humans. Agents read these files too. If the README says one thing and the code does another, the model is not "being clever." It is being misled by my own stale contract.

So I changed the default.

If a change alters user-facing behavior, I update the docs in the same pass. If a page explains a workflow, I treat that page like code that can regress. If a command exists in the README, I expect the command to work. If an article says a file lives in .apc/, it should not actually live somewhere else.

That rule sounds strict. It is. It also saves time.

The mirrored-tree rule forced the issue

One of the clearest examples is APC's documentation structure.

The APX project rules require mirrored locale trees: src/pages/en/ and src/pages/es/ must stay structurally identical and semantically equivalent. Same page, same shape, same keys in _meta.js, locale-matched internal links.

That is not extra ceremony. It is a built-in drift detector.

If I add a page in English and forget the Spanish version, the build should complain. If I rename a section in one locale and leave the other behind, that mismatch is not a translation issue only. It is a contract break.

This changed how I think about documentation work.

Before, I thought of translation as a late-stage pass.
Now, I think of mirrored docs as a design constraint.

The constraint is useful because it makes the system honest. I cannot accidentally say, "the docs are updated," when only one audience got the change. I have to keep both views aligned, which is exactly what a project that talks to tools should demand.

Build output is not just packaging

I also stopped treating the build as a deployment chore.

A build is where drift gets caught early.

For APC, the rule is explicit: run npm run build before calling a docs task done. For APX docs, the same idea appears in a different shape: build the docs site and verify both locale trees render. That is not overhead. That is verification that the contract still compiles.

I like that framing because it keeps docs in the same mental bucket as code:

source changes happen in the repo
projections are rendered from that source
the build checks whether the projection still matches

That is the same logic I use elsewhere in the project.

APC is the repo-owned contract.
APX is the runtime that consumes it.
The rendered docs site is another projection.

If any projection starts inventing its own truth, the system gets harder to trust.

The real bug is not stale prose

The real bug is mismatched behavior.

A stale README can teach someone the wrong command.
A stale locale page can hide a feature from half the audience.
A stale spec can make an agent infer the wrong boundary between project state and runtime state.

In APC and APX, these mistakes matter more because the whole point of the project is to make boundaries obvious:

project vs. runtime
repo truth vs. local truth
contract vs. execution
source vs. projection

If docs blur those lines, they are not documenting the system. They are undoing it.

That is why I now write docs with the same question I use for code: what is the actual source of truth here?

If I cannot answer that clearly, I should not publish the sentence yet.

What changed in my workflow

The practical effect is boring, which is exactly why it works.

Now, when I touch APC or APX, I ask three things right away:

Did behavior change, or only implementation details?
If behavior changed, which docs need the same change now?
Does the build prove the docs still match the repo?

That keeps me from doing the usual "fix later" move that creates drift.

It also makes writing easier. I no longer try to write a polished explanation after the fact. I write the explanation while the change is still fresh, when I can still name the tradeoff that mattered.

That matters in a project like APX because a lot of the value is in decisions, not just features.

Why does ~/.apx/ exist? Because runtime state should stay local.
Why does AGENTS.md matter? Because tool-agnostic context needs one shared contract.
Why does the web admin exist? Because it is a window into the same runtime, not a separate product.

Those are not slogans. They are design decisions. Docs should preserve that exact shape.

The rule I keep now

My rule is simple:

If a sentence describes how APC or APX works, that sentence is part of the product.

That means I have to maintain it with the same care I give code.

Not because prose is sacred.
Not because docs are pretty.

Because the project only stays coherent if every surface tells the same story.

And once I started treating docs that way, APC and APX got easier to reason about.

Less drift.
Less rework.
Fewer fake truths.

That is the whole win.

Routine Memory Belongs in APX, Not APC

Manuel Bruña — Sat, 25 Jul 2026 12:04:30 +0000

Routine Memory Belongs in APX, Not APC

A scheduled routine needs memory sometimes.

Not project memory. Not agent memory. Not a giant prompt pasted back into itself.

Just a small durable note that helps the next run continue from the last one.

That is exactly why routine memory should live in APX runtime state, not in APC.

APC is the portable context layer. It should carry the project contract: agent definitions, rules, MCP expectations, and any repo-owned files another compatible tool can safely read after a clone.

APX is the daily-use runtime and tooling layer. It runs the scheduler, executes the routine, tracks timestamps, logs messages, and stores local operational state.

Routine memory is operational state.

The split already exists in APX

APX already treats the routine definition and the routine memory as two different things.

The routine definition lives in the repo. The daemon docs describe the scheduler flow clearly: when a routine fires, APX reads its definition from .apc/routines.json, resolves the handler, runs pre and post commands, and writes updated timestamps.

But the routine memory file is stored under APX runtime storage, not inside .apc/.

In the code, src/core/stores/routine-memory.js defines the path as:

<projectStoragePath>/routines/<routineId>/memory.md

And the APX project layout docs explain what projectStoragePath means in practice: runtime state lives under ~/.apx/projects/<apxId>/.

So the real split is intentional:

.apc/routines.json says what should run
~/.apx/projects/<apxId>/routines/<routineId>/memory.md stores what happened and what the next run should remember

That boundary is healthy.

Why APC is the wrong place

A routine memory file looks small, but it behaves like runtime residue.

It changes after execution. It may contain temporary observations, last-run facts, partial progress, or notes only useful on one machine at one moment in time.

If you commit that into APC, several problems show up fast:

routine runs start creating noisy git diffs
teammates inherit machine-local or time-local residue
CI and local runs can fight over the same memory file
the repo stops describing intent and starts storing execution leftovers

That is the same reason APC should not hold sessions, message logs, caches, or daemon state.

Portable context should tell another runtime how to understand the project.
It should not replay yesterday's routine scratchpad.

Why APX is the right place

APX owns the scheduler, so APX should own the scheduler's memory.

That keeps the lifecycle coherent.

The same runtime that decides when a routine is due can also keep the routine's notes close to its runs, history, messages, and local artifacts. That makes debugging simpler and keeps the repository clean.

APX also injects a bounded slice of that memory back into the routine prompt. In routine-memory.js, readRoutineMemoryForPrompt() trims the content and caps what enters the prompt. Then the routine runner passes that slice through channelMeta.routineMemory when a super_agent routine runs.

That detail matters.

The goal is not to turn memory into a second project spec. The goal is to give the routine just enough local continuity to behave well on the next execution.

A practical example

Imagine a morning standup routine.

The definition belongs in APC because the project should own the schedule and the prompt:

{
  "routines": [
    {
      "name": "morning-standup",
      "kind": "super_agent",
      "schedule": "0 9 * * *",
      "spec": { "prompt": "Summarize open work and send the update." }
    }
  ]
}

But the routine memory should stay local to APX:

# Routine memory - morning-standup

## 2026-07-25
- Yesterday's summary was already sent to Telegram.
- Skip duplicate reminder unless task count changed.

The first file is a portable contract.
The second file is runtime continuity.

Those are not the same category of data, so they should not live in the same layer.

Small rule, cleaner system

If APC is the repo-owned contract layer, keep routine definitions there.
If APX is the runtime layer, keep routine memory there.

That gives you a cleaner repository, safer automation, and fewer false assumptions when the same project moves across laptops, teammates, or compatible runtimes.

Routine definitions should travel.
Routine memory should stay with the runtime that earned it.

APC MCP Hints Should Name Secrets, Not Store Them

Manuel Bruña — Fri, 24 Jul 2026 12:03:35 +0000

APC MCP Hints Should Name Secrets, Not Store Them

A project can tell tools which MCP servers it expects.

That does not mean the repository should carry the credentials.

This is one of the clearest APC and APX boundaries: APC should name the MCP contract, while APX should supply and use secrets at runtime.

APC is the portable context layer. It gives a repository one stable place to declare project-owned agent context, rules, skills, and MCP expectations. For MCP, that place is .apc/mcps.json.

APX is the daily-use runtime and tooling layer. It reads APC files, merges them with local runtime config, audits conflicts, starts servers, and exposes tools through commands like apx mcp list, apx mcp run, and apx mcp check.

Once you keep those jobs separate, the rule gets simple:

.apc/mcps.json should describe what the project expects.
It should not contain the secret values needed to satisfy that expectation.

What belongs in `.apc/mcps.json`

The APC MCP config spec is specific about allowed content. The file may include:

server names
commands and non-secret arguments
remote MCP URLs when the endpoint itself is part of the project contract
environment variable names a user must provide locally
enabled or disabled state when a consumer supports it

That makes the file portable and reviewable.

A repository can say, "this project expects a GitHub MCP server" or "this project uses a filesystem MCP rooted here," without leaking anyone's account or machine-local state.

A safe example looks like this:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${env:GITHUB_TOKEN}"
      }
    }
  }
}

That tells every compatible consumer what to wire up, but leaves the actual credential outside the repository.

What should stay out

The same APC spec also draws a hard line around unsafe content. Do not commit:

API keys
bearer tokens
OAuth refresh tokens
personal account IDs
private headers
credentials embedded in URLs
generated session IDs
machine-local absolute paths unless the path itself is intentionally part of the contract

The reason is bigger than secret hygiene.

If a repository stores literal credentials in .apc/mcps.json, APC stops being portable context and starts becoming a private runtime dump. That breaks the whole point of APC.

A clone-safe contract should survive a new laptop, a new teammate, or a different compatible runtime. A real token does not travel safely across any of those boundaries.

Where APX fits

This is where APX becomes useful instead of redundant.

APX does not need APC to hold the secret itself. It needs APC to hold the portable hint. Then APX can merge that hint with local runtime state and do the operational work.

That is why the APX CLI has a dedicated MCP layer:

apx mcp list
apx mcp check
apx mcp run github search_repositories '{"query":"org:agentprojectcontext"}'

apx mcp check is especially relevant here because it audits MCP source files, merge order, and conflicts. In practice, that means APC can stay commit-safe while APX verifies whether the local machine has supplied the missing pieces correctly.

So the workflow becomes clean:

The repo declares the expected MCP server in .apc/mcps.json.
The user provides credentials locally through environment variables or runtime-owned config.
APX reads both layers, audits them, and runs the server.

That is a better split than pushing everything into one file.

Why naming env vars is enough

Teams sometimes assume that if the repo already names a secret like GITHUB_TOKEN, they may as well paste the value too.

That is the wrong conclusion.

Naming the variable is enough because it preserves the contract without hardcoding ownership.

The project can say:

which variable must exist
which server consumes it
which command uses that server

and still let each developer, CI runner, or local daemon provide the value in its own safe way.

That is exactly how portable context should behave.

APC keeps the shared project expectation visible in Git.
APX keeps runtime credentials and execution local.

Small rule, big payoff.

When .apc/mcps.json names secrets instead of storing them, the repository stays portable, review stays sane, and runtimes like APX can still wire the full MCP stack without leaking private state into the project.

DEV Community: Manuel Bruña

A Local Admin Panel Still Needs Auth in APX

A Local Admin Panel Still Needs Auth in APX

APX Should Assemble Context, Not Dump APC Into Every Prompt

APX Should Assemble Context, Not Dump APC Into Every Prompt

What APX actually assembles

APC stays durable; APX stays selective

Why on-demand skill loading matters

Practical takeaway

I Added ACP to APX Without Adding a Second Brain

I Added ACP to APX Without Adding a Second Brain

What ACP is doing in APX

Why I did not give ACP its own state machine

The stream is the contract

Why history stays in the client connection

The real reason I wanted ACP at all

What this changed in my thinking

The rule I kept

APC Migration Should Classify Context, Not Copy Folders

APC Migration Should Classify Context, Not Copy Folders

What should move into APC

What should stay out

A practical migration test

Why this makes APX better too

Portable Context Does Not Mean Portable Runtimes

Portable Context Does Not Mean Portable Runtimes

Structured Agent Files Should Own Detail. `AGENTS.md` Should Stay Portable.

Structured Agent Files Should Own Detail. AGENTS.md Should Stay Portable.

Unknown Telegram Senders Should Stay Guests in APX

Unknown Telegram Senders Should Stay Guests in APX

Guest first, tools later

Why this split matters

Small example

Why APC should stay out of it

APX Keeps One Core So APC Can Reach Every Surface

APX Keeps One Core So APC Can Reach Every Surface

Why this matters

Concrete example from APX

What thin surfaces buy you

Why APC depends on this discipline

Security Risk Grades Are Not Permission Modes in APX

Security Risk Grades Are Not Permission Modes in APX

Two gates, two different jobs

Why this split matters

Small example

Why APC should not own this

Docs Are Part of the Contract in APC and APX

Docs Are Part of the Contract in APC and APX

Why I stopped seeing docs as separate work

The mirrored-tree rule forced the issue

Build output is not just packaging

The real bug is not stale prose

What changed in my workflow

The rule I keep now

Routine Memory Belongs in APX, Not APC

Routine Memory Belongs in APX, Not APC

The split already exists in APX

Why APC is the wrong place

Why APX is the right place

A practical example

Small rule, cleaner system

APC MCP Hints Should Name Secrets, Not Store Them

APC MCP Hints Should Name Secrets, Not Store Them

What belongs in .apc/mcps.json

What should stay out

Where APX fits

Why naming env vars is enough

Structured Agent Files Should Own Detail. `AGENTS.md` Should Stay Portable.

What belongs in `.apc/mcps.json`