DEV Community: Manuel Bruña

Why I Made APX Forward a Message as a Quote, Not a Paste

Manuel Bruña — Mon, 05 Oct 2026 13:04:48 +0000

I kept hitting the same small failure while building APX: a useful message existed, but it lived in the wrong conversation.

A person would receive a detail in one thread, open another agent session, copy the text, and paste it there. The new agent could read the words, but not their meaning in context. Was this something the owner had just typed? Was it an agent's conclusion? Which project or conversation produced it? Could anyone reopen the original exchange next week?

Copy-paste is fast, but it quietly destroys the facts that make a handoff trustworthy.

So I made forwarding in APX a quote with provenance, not a convenience paste.

The thesis: context needs an address

A forwarded message now carries where it came from, who said it, and when it was said. In the web surface, a message can move to another session in the same project or a different project. The destination receives a quote card rather than an anonymous paragraph.

That is deliberately modest. I did not add a new message channel, a separate forwarding database, or an opaque cross-project synchronization layer. A forwarded item is still an ordinary user turn. It is stored in the same places other turns are stored, so existing conversation views, ledgers, inboxes, and later re-reads do not need a special alternate history.

The turn's metadata holds the structured provenance. The text delivered to the model holds an explicit quote marker containing the source label, speaker, and timestamp. The model and the human therefore get the same important distinction: these are quoted words, not a fresh instruction from the owner.

That dual representation matters. Metadata lets the UI render a readable quote card and navigate back toward its source. The explicit marker lets an agent reason about the quote without guessing where it came from. If I kept only metadata, the model would lose the boundary. If I kept only a magic text prefix, every client would need to parse presentation details from prose.

The small details were the feature

Most of the work was not the forward button. It was deciding what a forward may carry and what it must not pretend to be.

First, the quote is bounded. APX caps forwarded text at 4,000 characters and marks it as truncated when needed. A forward is context, not a back door for injecting a giant transcript or binary-looking tool output into another model's context window. The destination still has room to answer.

Second, the source has a real address. Depending on where the message began, APX records enough information to identify a thread, conversation, or live session. It also records the originating project. That last part is essential when a forward crosses projects: an ID only makes sense inside its own project. Without project identity, a card may point at the wrong conversation or nowhere at all.

Third, author identity stays intentionally simple. The forwarded payload distinguishes the owner from an agent and may include an agent display name. That is enough to prevent the worst ambiguity without inventing a complicated hierarchy of new message types.

Finally, I put the quote before the note the person adds at forwarding time. A message such as “review this and extract risks” is useful only if the agent can first see what “this” is. The quote also uses blockquote lines and a closing marker, so multi-paragraph content does not blur into a new instruction.

Why an ordinary turn was better than a transport feature

I was tempted to treat forwarding as a transport concern: copy a payload from one chat object to another and call it done. That would have created a strange exception. It might work in one panel, yet disappear from a ledger, fail to survive a refresh, or become unreadable on another APX surface.

Making it an ordinary user turn with extra provenance has a calmer result. The destination session owns the new turn. The source remains unchanged. The destination can reply naturally. Existing storage and message shaping keep doing their jobs.

This also avoids an important false promise: forwarding is not shared memory. It does not merge two sessions, make their histories identical, or grant one project access to another project's entire conversation. It carries one bounded quotation, visibly labeled, because a person chose to hand it over.

That boundary is useful for daily work. I can send an agent's investigation from one session to a reviewer in another and ask a focused question. I can move a customer detail from a channel conversation to a project session without presenting it as something I personally wrote. I can revisit the destination later and see both the quote and the instruction that accompanied it.

What I learned

Agent products often make moving text look trivial. But when an agent acts on text, provenance is part of the input. Losing it changes the meaning of the handoff.

The practical rule I am keeping is simple: when context crosses a conversation boundary, preserve the boundary in the artifact. Keep the quote bounded. Name its source. Name its speaker. Keep the original available to reopen. Do not turn a handoff into a silent copy.

That is a smaller feature than “cross-agent collaboration” sounds like. It is also more honest. APX does not need every conversation to become one giant memory. It needs a reliable way for a human to carry one useful piece of context into the next room.

A Project Needs Two Memories—But Only One Should Travel With Git

Manuel Bruña — Mon, 05 Oct 2026 12:03:57 +0000

A Project Needs Two Memories—But Only One Should Travel With Git

Agent projects collect facts quickly: a deployment detail mentioned in a chat, a local preference discovered during a run, a decision that belongs in the repository. Treating all of them as one memory creates a bad choice: either private runtime details leak into Git, or durable project knowledge remains trapped on one machine.

APX and APC avoid that choice by giving a project two memories with different jobs. The practical rule is simple: let APX retain newly captured project notes locally; promote only reviewed, team-safe facts into APC.

The memory that stays local

APX keeps local project memory under its own runtime state, outside the repository. This is the right destination for facts gathered while operating: a note from a conversation, a temporary constraint found during a task, or a detail that may include information not meant for every future clone.

That separation is deliberate. A note captured automatically can contain material supplied through a chat or session. Committing it immediately makes it durable, shared, and hard to retract. Local runtime memory lets APX use the fact during daily work without silently turning it into project policy.

For example, an agent may record that a current task depends on a local service configuration. That can help the next APX turn on the same machine. It does not automatically mean every contributor should inherit it.

The memory that travels

APC's .apc/memory.md has a stricter role: curated project facts safe for the team. It lives in the repository, so Git carries it through clones, reviews, and history. That makes it useful for decisions that should outlast a runtime session: an architectural boundary, a durable convention, or a confirmed operational constraint.

The important boundary is authorship. APX does not treat a newly captured runtime note as permission to write the curated APC file. A person reviews the fact and decides whether it belongs in the shared project contract. The Memories surface can show both halves, but their visibility does not erase their different trust levels.

Why two memories improve daily work

A single memory store forces every note to be either too private to share or too easy to commit. The two-part design gives each fact a safe first home:

Capture working context locally in APX.
Keep using it while the local runtime needs it.
Review whether it is durable and safe for the team.
Promote only that smaller set into .apc/memory.md.

This also keeps APC portable. A fresh clone receives the decisions needed to understand the project, not another operator's conversations or machine-specific residue. Meanwhile, APX remains useful as the local runtime that can retain short-lived operational context.

The thesis is not that local notes are lesser knowledge. They are knowledge with a different audience and lifetime. APC makes shared context explicit; APX makes daily context usable without confusing it for a Git artifact. Keep both, but promote deliberately.

A Local Agent Panel Should Not Need a Cloud Project Mirror

Manuel Bruña — Sat, 03 Oct 2026 12:03:44 +0000

A Local Agent Panel Should Not Need a Cloud Project Mirror

A browser panel can make an agent system feel like a hosted product. That does not mean the project must be copied to a hosted product. APX takes a different boundary: the panel is a local interface to a local daemon, while APC keeps durable project context in the repository.

That distinction is practical. A project needs rules, agent definitions, reusable skills, and curated memory that can travel with its Git history. A running system needs sessions, conversation threads, logs, a scheduler, and active connections that should stay on the machine operating them. Treating both as one cloud-shaped data store weakens both jobs.

APC is the portable context layer. Its project contract lives in AGENTS.md and .apc/: files a teammate can review, version, and clone. APX is the daily-use runtime layer. It reads that context, runs agents, and keeps runtime state under ~/.apx/ instead of turning the repository into a session database.

The panel is a surface, not another source of truth

APX's web admin is served by the local daemon. By default, that daemon listens on 127.0.0.1:7430; the CLI, web panel, desktop window, TUI, and MCP bridge communicate with the same local process over HTTP. One runtime can therefore expose several interfaces without making each interface own a separate copy of projects, agents, or conversations.

Start with a normal status check:

apx status

If needed, APX starts its daemon. Opening http://127.0.0.1:7430 then shows the panel backed by that same daemon. The browser is useful because it is a good surface for browsing projects, sessions, messages, MCPs, and routines—not because it becomes a new project backend.

This design avoids a common drift problem. Imagine editing an agent role in a dashboard while the repository still has an older agent definition. Now a reviewer must ask which source an agent will actually follow. APC avoids that ambiguity by keeping durable project meaning in ordinary files. APX can index and use those files, but its live state remains runtime-owned.

Local by default, explicit when shared

A local panel is not automatically a network service. APX binds the daemon to loopback by default. To open the panel from another device on a LAN, the operator must opt in and pair that client. That is a meaningful boundary: browser access can expand deliberately without silently exposing the daemon on every network.

The same separation helps with recovery. Removing a project from APX's registered-project list does not delete project files. Cloning the repository elsewhere still brings the APC contract; it does not bring someone else's local conversations, tokens, or daemon process.

There is no claim that local runtime state eliminates every external dependency. An agent may call a configured model provider or an MCP server. The point is narrower: APX does not require a public server merely to give a local project a usable agent dashboard.

Use the boundary as a design test. If a fact should survive a clone and code review, put it in APC. If it only exists because an agent is running right now, let APX keep it local. The panel can be rich without becoming a cloud mirror of your project.

Read Your Own AGENTS.md Whole; Bound Foreign Context

Manuel Bruña — Fri, 02 Oct 2026 12:03:01 +0000

Read Your Own AGENTS.md Whole; Bound Foreign Context

An agent runtime has two conflicting duties when it loads project instructions: preserve the rules that govern its own work, and keep an arbitrary external file from consuming the entire prompt. Treating both files the same creates a bad trade-off. A small universal limit can silently remove a project’s own critical rules; no limit lets any referenced repository take over the context window.

APX makes the distinction explicit. It treats APC as the portable context layer: AGENTS.md and the defined .apc/ files carry project-owned guidance. APX is the daily-use runtime and tooling layer that assembles this guidance into a live prompt, along with runtime state that remains local.

The practical rule is simple: APX reads the AGENTS.md for the project it is running inside in full. A foreign project’s file has a configurable budget.

Why one cap fails

Imagine a project’s AGENTS.md starts with code conventions and ends with a release safety rule:

## Release

Never publish before the integration suite passes.

A fixed cap can preserve the first section and cut the last one. The agent then receives a partial contract while believing it received project guidance. That is worse than a visible absence: it can follow some rules and violate rules it never saw.

APX had exactly this failure mode. Its prompt-builder regression test records that an earlier 6,000-character cap sliced the owning project’s contract mid-rule. The current implementation does not cap the project matching the runtime’s working directory. The project’s own contract reaches the prompt whole.

That is not a claim that every instruction file should be unlimited everywhere. It is an ownership decision. The repository running the agent owns its contract and should be able to review its full effect.

Foreign context needs a different policy

APX can also receive a project path that is not its own working project. That file might be useful context, but it is not safe to assume its size is reasonable for the current turn. APX therefore applies a default foreign-contract budget of 24,000 characters.

When it must shorten a file, it does two important things:

It cuts on a line boundary instead of breaking a rule mid-sentence.
It states that the result is truncated and reports how much was omitted.

The resulting prompt tells the agent to read the file directly before relying on rules not shown. This preserves an important fact: partial context is partial.

The foreign cap is also configurable through super_agent.project_agents_max_chars. A positive value changes the budget; 0 disables it. That makes prompt size a deliberate local runtime choice, not a hidden change to APC’s portable contract.

Keep the boundary clear

This division helps answer a common design question: should a project shorten its own instructions to fit a runtime? Sometimes, yes—but that should be a project authoring decision, made in the repository and reviewed like any other change. It should not be an invisible runtime truncation.

Likewise, a runtime may need to bound external context for cost and reliability. That safeguard belongs in APX, where prompt assembly happens. It does not redefine what APC files mean or what a project is allowed to document.

A useful test follows: when an agent acts inside your repository, can you show exactly which project rules reached it? If the answer is “only the first part, silently,” the boundary is wrong. Read the owning contract whole; bound foreign context visibly.

APC keeps the contract portable. APX applies it in a live runtime without pretending every source of context has the same ownership or budget.

Why APX Rejects Invalid Agent Autonomy Instead of Guessing

Manuel Bruña — Wed, 30 Sep 2026 12:03:19 +0000

An agent autonomy setting looks like small metadata. It is not. It can decide whether a tool runs now or pauses for a human. That makes guessing the wrong response to invalid input.

APC provides portable project context: agent files, roles, skills, and project metadata travel with the repository. APX is the local runtime that reads that context, runs agents, and enforces tool permissions on the machine. The boundary matters here: a portable agent declaration may request an autonomy mode, but APX must turn that declaration into a real, local permission decision.

APX has three permission modes:

total: tools run without confirmation.
automatico: safe work can proceed; destructive, outbound, runtime, MCP, and filesystem-mutating work can require confirmation.
permiso: only allowed_tools run directly; every other tool asks.

A project has a baseline mode in its runtime configuration. An individual agent can declare Autonomy: to override that baseline for its own turn. An agent with no declaration inherits the project setting.

The bad shortcut

Imagine a project whose normal setting is automatico, and a review agent should be more constrained:

---
name: reviewer
role: Review pull requests
Autonomy: permiso
---

Now imagine someone edits the card and writes Autonomy: permissive. A permissive parser might map that to total, choose the nearest known word, or silently save a value that later means something else. Each path turns a typo into an authorization decision.

APX does not invent a mode. When it reads a stored autonomy field, an unrecognized value is dropped and the agent inherits the project baseline. That protects the runtime from treating garbage as a new, wider permission setting. It also keeps the effective policy explainable: either a recognized agent override applies, or the project policy applies.

There is an important nuance. Inheritance is not a substitute for validation. If the project baseline is broader than the author intended for that agent, a malformed stored value will not magically preserve the intended restriction. That is why APX handles direct CLI input differently: apx agent ... --autonomy rejects an invalid value and tells the user the accepted modes, including inherit. A person at a terminal gets a visible error instead of a plausible-looking success message.

A practical rule

Use these meanings consistently:

no --autonomy flag     keep current agent setting
--autonomy inherit     clear agent override; follow project mode
--autonomy automatico  set explicit agent override
--autonomy permiso     set explicit agent override
--autonomy total       set explicit agent override

Then verify the result in the agent file and test an action that should pause. Configuration text alone is not evidence that the tool loop uses it. APX applies a valid agent override to the active turn configuration before its permission guard and risk handling run.

Keep the contract small

The portable side should say who the agent is and, when useful, its intended operating boundary. The runtime side must decide what the current machine can actually execute, prompt on, or deny. APC does not become a hidden authorization database; APX does not treat a typo as authority.

That division makes agent behavior safer to review. A teammate can inspect the declared agent contract in the repository. The local runtime can enforce it without copying private runtime state back into APC. And when an autonomy value is wrong, the system has one honest answer: stop guessing and fix the value.

A Portable Agent Contract Cannot Link to a Local Plan

Manuel Bruña — Tue, 29 Sep 2026 21:45:16 +0000

A Portable Agent Contract Cannot Link to a Local Plan

An AGENTS.md file can tell every compatible agent how a repository should be handled. That promise breaks when a rule links to a planning file that exists only on one developer's machine. The link works for its author, then becomes a dead end in a fresh clone.

This is a small boundary, but it is a useful test for portable context. If a future contributor cannot read an instruction and every document it depends on, the instruction is not yet a project contract.

APC is the portable context layer. It keeps repository-owned rules, agent definitions, skills, and non-secret MCP expectations in AGENTS.md and .apc/. APX is the daily-use runtime and tooling layer. It runs agents and keeps local operational material—sessions, private runtime memory, caches, and machine-specific state—outside the repository.

A local plan belongs on the APX side of that boundary unless it has been deliberately promoted into a shareable project artifact.

A link is an ownership claim

Consider this root instruction:

Read `spec/release-notes.md` before changing the deployment flow.

If spec/ is ignored because it holds exploratory notes or raw QA evidence, a new clone has neither the file nor its reasoning. The root contract now asks an agent to follow unavailable context. Worse, a reviewer can miss the error because the author's working tree resolves the link perfectly.

The same problem appears with absolute paths, private issue exports, temporary design notes, and runtime logs. They may be useful during one task. They cannot be prerequisites for portable behavior.

Treat every link from AGENTS.md, .apc/, or tracked documentation as a claim: this target is durable, safe to share, and available to a clean checkout. If that claim is false, change the contract.

Promote the decision, not the scratchpad

A local plan often contains valuable thinking mixed with temporary material. Do not copy the whole file into APC merely to repair a broken link. Extract the part that survives review.

For example, a local release investigation might establish one lasting rule: generated assets must be checked before publishing. That rule can live directly in AGENTS.md, or a concise explanation can become a tracked decision document. The raw command output, incomplete alternatives, and machine paths remain local.

A practical promotion flow is:

Keep the working plan and raw evidence local while the task is active.
Identify the decision that future contributors actually need.
Rewrite it as a short, self-contained project rule or tracked document.
Link only to that tracked artifact from APC context.

This gives a clean clone enough guidance to act without importing private or stale task history.

Use the smallest durable surface

Not every note needs a new document. A repository-wide instruction belongs in AGENTS.md. A reusable procedure can become an APC skill. A rule for only one folder belongs in .apc/rules/. A longer, reviewable rationale can live in ordinary tracked project documentation.

The important part is not the filename. It is whether the content remains true, readable, and useful beyond the machine that produced it.

APX helps keep the other category useful without pretending it is portable. Its local runtime can retain sessions, messages, task state, and private working material under its own storage. That lets an active task keep detail without leaking that detail into the repository contract.

Fresh-clone test

Before adding a context link, ask one question: would this still help an agent that cloned the repository today on another machine?

If yes, keep it tracked and make the target self-contained. If no, leave it in the local plan or runtime state, then promote only the verified conclusion when it becomes a real project constraint.

Portable context is not a directory full of references. It is a contract that can stand on its own. APC carries that contract; APX carries the local work around it.

Why I Made APX Confirmations Refuse a Group Vote

Manuel Bruña — Mon, 28 Sep 2026 13:03:32 +0000

When I added confirmation prompts to APX, the obvious implementation was almost enough: show Yes and No, wait for a callback, then continue the tool call.

That works in a direct chat. It fails in a group.

A confirmation message can be visible to several people, but visibility is not authority. If one person asks an agent to send a quote, create a file, or perform another gated action, a nearby button must not let a bystander authorize it. The hard part was not making a button. It was preserving the identity behind the request.

My thesis is simple: a confirmation should belong to the person who initiated the action, not to the chat where the button happens to appear.

The tempting shortcut

A Telegram confirmation is asynchronous. An agent is midway through a tool call, decides that an action needs approval, sends an inline keyboard, and waits. Later, Telegram delivers a callback query when somebody taps a button.

The shortcut is to store only a random confirmation ID and resolve it when any matching callback arrives. It is concise, and it looks correct in a one-person conversation. In a group, it silently changes the question from “did the initiator approve?” to “did anyone with access to the chat press Yes?”

Those are not equivalent questions.

The second question is especially dangerous because the interface gives it an air of legitimacy. Everyone sees the same card. Everyone can reach the same button. Without an explicit actor check, a colleague trying to help, a curious participant, or the wrong person tapping by mistake can turn someone else’s request into an authorized action.

Bind the pending request to an actor

APX keeps pending confirmations in memory. Each entry has a correlation ID, a promise waiting for a boolean answer, an expiry timer, and optionally a guardActorId. Telegram passes the ID of the person who started the turn as that guard.

When a callback arrives, APX checks the presser before it resolves anything:

confirmation belongs to initiator 111
bystander 999 taps Yes
→ reject callback
→ keep confirmation pending
initiator 111 taps Yes
→ resolve confirmation
→ tool may execute

The detail I care about most is the middle line: rejection does not consume the request. The bystander gets a “Not your confirmation” response, but the original person can still decide. A failed authorization attempt is not the same thing as a decline.

That distinction keeps the state machine small and truthful. There are three outcomes that matter: approved by the right actor, declined by the right actor, or still waiting. “Someone else pressed a button” belongs outside that set.

Make silence safe

A confirmation cannot wait forever. An agent loop suspended forever is not safer; it is merely harder to reason about. APX gives Telegram confirmations a 60-second lifetime. If nobody answers, the promise resolves to false. The tool does not run.

This is deliberate. A missing answer should never become permission through a retry, a timeout handler, or a later reconnect. Defaulting to cancellation makes the system’s behavior legible: no explicit approval, no action.

The same rule matters after a restart. Pending confirmations live only in the daemon process because the agent turn that created them lives there too. If APX restarts, there is no valid suspended turn to resume. A later tap on the old button is shown as expired rather than treated as a fresh approval.

I prefer that small inconvenience to reviving an action after its surrounding context has disappeared. A quote request might have been edited, a file operation might no longer be relevant, and the person who asked might have changed their mind. An expired button says exactly what happened: this decision window is gone.

Confirmation still is not execution

There is another boundary worth keeping explicit. A successful confirmation means the gate is open; it does not prove that the tool succeeded. The handler still has to run, and it can still fail. Conversely, a declined or expired confirmation means the handler never ran.

APX tests that separation. Its security-risk tests assert that a declined confirmation leaves the tool’s execution count at zero. The actor-guard test asserts that a different user cannot resolve a guarded confirmation, while the original initiator still can. These are boring tests, but that is exactly the point: a safety promise should be precise enough to test without interpretation.

What I learned building it

I used to think of confirmation as a UI feature. It is really a small authorization protocol crossing time and a chat transport. It needs an identity, a one-time correlation key, an expiration rule, and a clear answer for stale state.

The practical checklist I now use is short:

Bind approval to an actor when the transport is shared.
Reject unauthorized responses without destroying the real request.
Treat no answer as cancellation.
Treat post-restart buttons as expired.
Never report a request as pending when the current surface cannot actually ask.

That last point matters outside Telegram too. Some APX surfaces have a confirmation adapter; some execution contexts do not. Where APX cannot present a real confirmation, it refuses the action and says that no request was sent. Pretending otherwise would turn a missing capability into a false promise.

Agents become useful when they can act. They stay trustworthy when every boundary around that action remains explicit. A group chat is a shared place, not shared authority—and a confirmation button should make that true in code, not just in the copy around it.

A WhatsApp Capability Should Capture, Not Execute

Manuel Bruña — Mon, 28 Sep 2026 12:03:50 +0000

A WhatsApp Capability Should Capture, Not Execute

A contact asks a WhatsApp agent for an appointment. The dangerous interpretation is: the agent now has permission to book one. APX uses a narrower interpretation: the agent may capture the request for its owner to confirm.

That difference keeps a conversational convenience from quietly becoming an execution path.

APC is the portable context layer. It keeps durable project material in the repository: AGENTS.md, .apc/, agent definitions, skills, commands, and MCP hints. APX is the daily-use runtime and tooling layer. It handles local channels, runtime state, identity, and the live decisions around an inbound message.

A WhatsApp request is runtime work. It should not turn into a portable project instruction—or an automatic external action.

Capabilities are deliberately small

APX's WhatsApp configuration recognizes three capabilities: appointments, errands, and facts. All start off by default.

The names can be misleading if read too quickly. They are not tool grants. A non-owner WhatsApp turn has no tools. Enabling appointments or errands lets APX extract a request into a pending suggestion; it does not let the conversation book, send, promise, or decide anything.

The split matters because answering someone and acting for them are different kinds of authority. A natural reply can say, “I’ll pass that along for confirmation.” It must not say a time is agreed, a slot is free, or an errand will happen.

facts is the other deliberate boundary. When an owner has written approved facts for a contact, APX may answer from those facts. Anything outside them remains unknown. A friendly contact-specific rule can adjust tone, but it cannot create facts or tools that the runtime did not supply.

Capture runs beside the reply

For enabled appointment or errand capture, APX reads the inbound message separately and records a structured pending suggestion. It preserves the sender, request summary, requested work, urgency, and the sender's timing words.

That last detail is important. If somebody says “tomorrow afternoon,” APX stores those words rather than resolving them into a timestamp. The capture layer is not allowed to make a calendar decision merely because it understood the phrase.

APX also keeps capture separate from the reply text. Hiding machine-readable request data inside a reply would require stripping it before delivery. A failed strip could expose internal machinery to the contact. With a separate capture pass, the reply stays plain text and a capture failure only loses a suggestion; it does not corrupt the conversation.

A practical flow

Imagine a plumber writes:

Can I come by tomorrow afternoon to check the leak?

With appointment capture enabled, APX can create a pending request containing the contact, purpose, and exact timing language. The owner receives something to review. The agent's reply can acknowledge the request and say it will be passed on.

It cannot confirm the visit. It cannot claim the owner is available. It cannot turn “tomorrow afternoon” into a booking.

This is less flashy than an agent that acts immediately, but it is more truthful. The system knows it has captured intent, not completed the work.

Why APC stays out of it

The project may travel between repositories, machines, and compatible tools. WhatsApp contacts, owner approval, pending requests, and channel-specific capabilities should not travel with it as committed project truth. They depend on a particular account, operator, and moment.

So APC describes what the project is. APX handles what a local messaging surface may safely do today.

The useful rule is simple: when a message asks for real-world action, first capture intent. Then let a responsible human—or an explicitly authorized execution path—confirm the action.

A channel capability should make a request visible. It should not silently make that request true.

A Conversation ID Is Not Project Context

Manuel Bruña — Sun, 27 Sep 2026 12:02:59 +0000

A Conversation ID Is Not Project Context

A conversation ID can feel like the fastest way to give an agent continuity: save it in the repository, pass it to the next machine, and resume where the last prompt stopped. It is also the wrong boundary. A conversation is runtime state. Project context is a contract. They should not be stored together.

APC is the portable context layer. Its AGENTS.md and .apc/ tree describe the project: agent roles, reusable skills, project metadata, and MCP hints without credentials. APX is the daily-use runtime and tooling layer. It runs agents and keeps the local operational record: sessions, conversations, messages, caches, and task logs.

That split is not a limitation. It makes a clone predictable.

A conversation belongs to one local runtime

When APX registers a project, its committed definition remains in the repository. Its runtime data lives under ~/.apx/projects/<apx_id>/. Per-agent folders include sessions/ and conversations/; those files reflect a particular machine, engine, account, model context window, and moment in time.

A saved conversation ID may depend on all of those conditions. Another machine might not have the underlying conversation, might use a different runtime, or might not have permission to read it. Committing the ID makes the repository imply a guarantee it cannot provide.

The same mistake appears in a subtler form: copying a raw transcript into AGENTS.md or .apc/memory.md so the next agent can “continue.” Raw turns include temporary questions, stale tool output, and often sensitive operational detail. They grow quickly while teaching future agents what happened once, rather than what must remain true.

Keep the durable decision, not the handle

Suppose an agent investigated a deployment failure and found a durable rule:

The deploy command needs a clean generated-assets directory; run the project check before publishing.

That rule can become a reviewed project instruction or a concise curated memory fact. It can travel in APC because it explains an ongoing constraint. The conversation ID that led to it should remain local to APX, where an operator can inspect or summarize it when needed.

The resulting workflow is small:

Run work through APX; it records the local session and conversation.
Extract only stable, reviewable decisions.
Add those decisions to APC-owned instructions when they apply to the project.
Let a new machine register the repository and start a new local runtime history.

For a short-lived task, the durable output may be nothing. That is healthy. Not every discussion earns a permanent place in project context.

Portability needs a clean restart point

A clone should be able to answer: Which agents exist? Which rules apply? Which skills can run? Which project ID connects this repository to local APX state? APC provides those answers without importing one machine’s chat history.

APX then supplies the operational continuity appropriate to that machine: apx conversations list can inspect stored conversations, and apx session summary <id> can turn a completed session into a concise explanation. Those are runtime tools, not repository format requirements.

This separation also makes cleanup safer. Removing local runtime state does not erase repository rules. Sharing a repository does not publish chat transcripts. Switching from one supported runtime to another does not require pretending that an opaque conversation handle is a portable artifact.

Use APC to preserve what collaborators need to know before work begins. Use APX to retain the local evidence of work already done. A conversation ID can help one runtime resume a thread; it should never become the project’s memory contract.

A Routine Result Is Not a Delivery

Manuel Bruña — Sat, 26 Sep 2026 22:16:39 +0000

A Routine Result Is Not a Delivery

A scheduled agent can finish its work and still fail the person who asked for it. The model produced text. The shell command exited. The routine history says it ran. But its result never reached a human.

That is why APX treats routine output and routine delivery as separate steps. A result is what the routine produced. Delivery is where that result actually goes—and whether that route accepted it.

APC is the portable context layer: repository-owned rules, agent definitions, and skills that travel with a project. APX is the daily-use runtime and tooling layer. It runs a scheduled job, chooses its local delivery channels, and records the operational outcome. This is runtime behavior, so it belongs in APX, not in APC.

Delivery is opt-in

APX resolves delivery in a deliberate order:

The routine's own deliver_to setting.
The runtime default at config.routines.deliver_to.
No delivery.

That final default is intentional. A newly introduced delivery feature should not change where older routines send output. A routine must opt in before its result becomes a message on a channel.

For example, a routine can calculate a daily status and produce a useful answer. Without a configured delivery target, it has completed computation—not communication. The distinction prevents a misleading green checkmark.

One output, one owner

A second failure mode is double delivery. A routine can send a Telegram message itself, run a post_commands shell hook that sends the same text, and also have configured delivery. One logical report then becomes several notifications.

APX checks for channels already served by the routine handler, its post-command sinks, or an agent tool call. It suppresses the redundant path rather than assuming every configured route should fire.

This changes how to design a routine. Pick one delivery owner for each channel:

{
  "kind": "exec_agent",
  "spec": {
    "agent": "default",
    "no_tools": true,
    "prompt": "Summarize today's status in one short paragraph."
  },
  "deliver_to": ["telegram"]
}

The routine creates the text; configured delivery owns the Telegram send. Alternatively, a hand-written apx telegram send "$APX_LLM_OUTPUT" post-command can own that send. Do not configure both as independent paths for the same message.

A failed route should look failed

APX records a result for each delivery channel: ok, held, or error. An unknown channel is reported as an error rather than silently ignored. If delivery was requested but no channel accepted the message—and no earlier path already served it—the routine ends in an error state with a direct explanation: it produced an answer and no one received it.

held is different from failure. It means an interruption or notification budget deliberately withheld the message. The result remains available in the run log and routine memory instead of being discarded or mislabeled as sent.

That distinction is useful operationally:

ok: result reached configured channel.
held: runtime deliberately delayed or withheld a notification.
error: route did not accept delivery; investigate configuration or service state.

Ordinary reports need less noise

For ordinary Telegram-bound routine reports, APX can record a pending delivery first. The daemon gives the owner a short grace period to open the agent chat and reply. If that happens, the delivery becomes answered and the extra notification is canceled. If it remains pending, a later sweep notifies the owner. Priority or anchor deliveries notify immediately.

This is a small product rule with a practical effect: a user who already saw the report does not receive an unnecessary second ping, while an unseen report does not vanish inside a routine log.

The useful test for a scheduled agent is therefore not only “did it run?” Ask:

Did it produce the intended result?
Which channel owned delivery?
Was that channel ok, held, or error?
Could another path have sent the same report twice?

Let APC carry the portable instructions that define the work. Let APX own the local execution and delivery record. A routine becomes useful only when its result reaches the right person exactly once.

A Routine Name Is Not Its Memory Key

Manuel Bruña — Fri, 25 Sep 2026 12:02:14 +0000

A Routine Name Is Not Its Memory Key

A scheduled agent task needs two kinds of identity. One is for people: a name such as daily-review. The other is for stored runtime state: a stable identifier that survives normal edits. Treating those as the same thing creates a subtle failure: edit a routine, and its history silently becomes someone else's problem.

APC and APX divide this responsibility deliberately. APC is the portable context layer: versioned rules, agent definitions, skills, and other project facts that can travel with a repository. APX is the daily-use runtime and tooling layer. It runs routines and keeps their local operational state outside the repository.

That division makes routine identity an APX concern.

Display names change; runtime state should not

In APX, a routine record has a human-readable name and a generated id. The name is how the CLI and a person find the routine. The ID is what APX uses for the routine's private memory path:

~/.apx/projects/<project-id>/routines/<routine-id>/memory.md

This is more than implementation detail. Routine memory can hold short, durable operational notes that help the next run. If an ordinary edit assigned a new identity, the routine would no longer read its old notes. The old directory would remain behind, and the newly edited routine would start with an empty memory as if it were new.

APX avoids that by carrying the existing ID forward when upsertRoutine rebuilds a routine record. The record may receive a new schedule, prompt, delivery target, or tool boundary, but its runtime identity remains stable. The same applies to created_at: editing a routine is not creating a second one.

The boundary prevents a common confusion

It can be tempting to put this state in APC because both systems are project-aware. But routine memory answers a runtime question: what should this specific scheduled task remember locally between runs? It is not automatically a team-wide project rule.

For example, a routine named daily-review might accumulate a short note about an unresolved local inspection. That note belongs to the APX runtime store. It should not appear in a clone just because someone copied the repository, and it should not become a committed instruction without review.

If the project eventually needs a durable rule—perhaps a verified deployment constraint—a human can promote that fact into APC through the normal review path. Until then, the local note stays local.

This boundary also keeps the two systems understandable:

APC names portable, reviewable project context.
APX names local execution state and connects it to a live routine.

A practical edit test

When changing a routine, verify more than its visible fields. Ask four questions:

Does the routine still have the same ID?
Does its existing memory path still resolve?
Did the edit preserve its creation time and prior run state?
If the name changes, is that an intentional new routine or a migration with an explicit state decision?

The last question matters because a display name is often the lookup key on a command line, while the runtime ID anchors data that should outlive routine edits. Renaming therefore deserves a deliberate product decision, not an accidental side effect of rewriting a JSON record.

Keep identity boring

Stable identifiers are rarely exciting. Their value appears when a routine changes over weeks: scheduled work keeps its own bounded history, local state does not leak into APC, and a harmless edit does not erase operational continuity.

Let APC carry portable project truth. Let APX keep routine state local. And when a routine changes, preserve the identity that its memory depends on.

Agent Memory Should Propose Before It Writes

Manuel Bruña — Thu, 24 Sep 2026 12:03:52 +0000

Agent Memory Should Propose Before It Writes

An agent can turn a busy day into a plausible list of facts. That does not mean it should silently rewrite the memory that shapes its next prompt.

That is why APX makes apx memory consolidate propose by default. It accepts candidate facts from standard input, evaluates them, and prints what it would keep or skip. Nothing is written until you add --apply.

This is a small CLI choice with a larger lesson: memory needs an explicit boundary between suggestion and authority.

APC is the portable project-context layer: committed agent definitions, rules, skills, and other reviewable project facts. APX is the daily-use runtime and tooling layer. It runs agents, keeps local runtime state, and provides the operational commands around it. The consolidation command belongs on the APX side because it works with runtime notebook memory, not repository context.

Candidate facts are not trusted facts

A routine, a model, or a person can send one candidate per line to the command:

printf '%s\n' \
  'Use pnpm, never npm' \
  'The owner may change the deployment plan next week' \
  'Review API changes before merging' | \
  apx memory consolidate

The important part is what does not happen: APX does not treat every line as memory. The command proposes a kept set and reports skipped candidates. Its implementation separates distilling candidate text from judging what survives, so the same rules apply whether candidates came from an automated routine or from a human at a terminal.

That protects against a common failure mode. Runtime activity is full of tentative language, stale details, copied text, and one-off task facts. If every summary automatically became long-term memory, the next prompt would inherit guesses as if they were instructions.

Preview is a real safety feature

When the proposed output looks right, write it deliberately:

printf '%s\n' \
  'Use pnpm, never npm' \
  'Review API changes before merging' | \
  apx memory consolidate --apply

The extra flag is not ceremony. Agent memory is injected into future prompts, so changing it changes future behavior. A background job that silently edits what an agent believes about itself can create hard-to-see drift: the job succeeded, but the agent is now operating from an unreviewed premise.

--apply makes that change visible at the point of action. It also gives operators a useful review loop: generate candidates, inspect the proposed keep/skip decision, then authorize the write only when the surviving facts deserve repeated prompt space.

Keep the scope honest

This command does not promote notes into APC automatically. APX per-agent memory lives under ~/.apx/projects/<apx_id>/agents/<slug>/memory.md, outside the repository. It is local runtime state. APC still holds the committed project contract, such as .apc/agents/<slug>.md and other portable context.

That distinction matters. A local notebook can help an agent work today without claiming that every note belongs in version control or should travel to every clone. If a fact later becomes stable, safe, and useful for the whole project, a human can curate it into APC through the normal review process.

APX also keeps reversal narrow. apx memory revert removes entries written by consolidation while leaving hand-written notes alone. That makes experimentation less risky: automated consolidation has a bounded undo path instead of treating the whole notebook as disposable.

Practical rule

Use automated processes to collect and compress candidate facts. Use explicit review and --apply to grant those facts long-term influence.

APC keeps portable project truth reviewable. APX makes local runtime memory useful without pretending that every observation is already truth.

For agent memory, that order matters: propose first, write second.