Some thoughts on where HAPI might evolve to, in the broader agent ecosystem

[heavygee]

@tiann , @swear01 - collabs and fellow users, truly this tool is my "HAPI" Place 😄

I'm using it extensively in my own personal life and my work life, dogfooding all day everyday, and I got to thinking over a cup of tea this afternoon, and after a lengthy chat with (first cursor Auto, then gpt5.6 sol high) brought forth this 15-25m treatise, a bit like a "what-if" - to stir the pot a little and see what y'all thought of it...

I'm just a user - a passionate one, for sure, but sometimes I like to play this game. So if you wanted to grab a cup of tea and have a read - I can confidently say that at least 90% of it is decent enough to warrant your time - i.e. not slop formed from a one-liner and a few thousand tokens. I stand by it, and I wrote this intro myself 💯 (these are dew-fresh hand-picked emoji, I swear).

https://github.com/heavygee/hapi/blob/ff290e0fab52abe8ce9ecae0ab9f76f6b0dd5cd3/docs/plans/2026-07-30-hapi-agent-ecosystem-thesis.md

[tiann]

Thank you so much for this brilliant and deeply thoughtful manifesto. Your analysis of vendor vertical integration and HAPI's role as a horizontal fabric is spot on. I also really appreciate your pragmatic engineering red lines—especially around multi-user isolation and prompt security.

I completely agree with the long-term vision and the Phase 0–5 path. To make this actionable, I think starting with Agent-to-Agent (A2A) collaboration is the perfect pragmatic first step.

Following your principles:

Artifact-based handoffs: No endless model chatter; use state-driven handoffs (e.g., Claude Code outputs a diff, HAPI passes structured context to a local Qwen for review/tests).

"One Boss" architecture: Route all interactions through HAPI (the proto-Overseer) to maintain human audit and interruption control.

Unified work advertisements: Standardize control-plane protocols to smooth over vendor differences.

If you're open to it, I'd love for you to submit this (or a refined version) as an RFC or VISION.md in our GitHub Discussions so the whole community can dive into it.

Thanks again for the incredible contribution—let's build this!

[heavygee]

Follow-up as requested: drafted the A2A control-plane RFC as a first-class Ideas proposal:

➡️ RFC: HAPI Agent-to-Agent (A2A) Control Plane

It canonizes Layer 0 (inspect_peer / ping_peer / session citations), proposes the hub events ledger for typed handoffs + work ads + receipts, and elevates AGENT_NOTIFY_SUMMARY from optional FCM enrichment to a best-effort status feed. No manager UI in this RFC - looking for feedback on sequencing and the smallest useful P1/P2 slice.

[KorenKrita]

Thanks for sharing this. As a HAPI user, I see its role a little differently.

1. HAPI's web and mobile UI will probably never match the full features and experience of the official clients or TUIs it supports. I think that is fine.
2. I mainly use HAPI for remote control and continuity: checking or continuing work that I started on my PC. I do not expect HAPI to replace the official clients as my main workspace.
3. Different machines and environments naturally have different MCPs, skills, and CLI tools. One of HAPI's strongest advantages is that it uses the local agents I have already configured. I would be careful about turning HAPI into a central layer that must manage and inject every capability again.
4. I strongly agree with the A2A direction. Sessions running different CLIs should be able to discover each other, exchange messages and artifacts, and coordinate or delegate work. This feels like a core architecture capability that HAPI should provide.

My preferred direction is simple: keep native agents native, let each environment keep its own capabilities, and make HAPI the connection and coordination layer between them.

[heavygee]

Cheers for the reply 🙏
I confess I'm now very biased - I am 99% only using HAPI at this point, the native tools now feel like working with one hand tied behind my back 😂 couldn't explain why that is...

Looking forward to getting that A2A stuff out the door, a good step forward, I agree!

[KorenKrita]

Interesting — my desktop workflow is almost the inverse, although my mobile workflow is very close to yours.

I still spend most of my desktop time in the official TUI or GUI. For Codex, the official app is genuinely excellent. For Pi, I have built quite a few plugins to adapt both the TUI functionality and its visual presentation to the way I work. HAPI, by contrast, is a purely conversational experience: on the Web it naturally lacks some of the terminal's information density, rendering richness, and operational convenience.

That said, probably 99% of my mobile agent time is spent in HAPI. Apart from debugging HAPI itself, I almost never use the Web UI or launch HAPI from the CLI on my PC.

For A2A, the more mature implementations I currently know of are Paseo, CCB, and the closed-source Lody.

I did notice that HAPI already implements part of the A2A foundation, although I had barely used it before today. After trying it, I ran into a couple of usability questions:

1. When I copy a session reference such as:

   See session "Coding" (/sessions/7ee03698-0fe7-4f76-b8a8-d84f4eddbf5c) for context
   

   my agent generally does not infer that it should call the corresponding HAPI MCP tool to inspect or communicate with that session. Instead, it tends to search locally. Because I use a self-hosted Hub as the broker, there is no corresponding session data available in the local filesystem.

2. Session listing also behaves differently across the Hub boundary in my setup. hapi ping-peer --list did not work from the runner-side context, but it did work when executed directly on the Hub host. In practice, this means I currently need to explicitly tell the agent which MCP tool to use and paste the complete session reference before the interaction can begin.

I am genuinely excited about HAPI's A2A direction and would be very happy to help test, refine, and continue building it together. Cheers! 🍻

[heavygee]

Very much appreciate those links 🙏 will have a read.

On the A2A foundation, fair catches - thank you for actually dogfooding the Layer 0 path.

You're right on both counts: pasted session references do not reliably steer agents to inspect_peer (they fall back to local search), and ping-peer --list is fragile off the hub host / missing as an MCP affordance. That's on the current foundation being too "exists in the tool list" and not enough "agents actually do the right thing."

Tracked:

• feat(a2a): steer agents from session citations to inspect_peer #1370 - citation → inspect_peer steering
• feat(a2a): list peers from runner context (MCP + CLI auth) #1371 - list peers from runner context (MCP + CLI auth)

Very happy to have you poke at those once they land. Cheers 🍻

[heavygee]

Posted a landscape companion as a General discussion, for people coming from Happy / T3 Code / vendor IDE comparisons:

➡️ HAPI in the agent control-plane landscape (Happy, T3 Code, vendor IDEs)

It stays anchored on upstream today, then only folds in what is already agreed in Discussions (#1258 / #1332 A2A, and the attention/event-layer note from #691). Feedback welcome there.

[tiann]

Here's a fun A2A scenario I recently encountered:

I recently developed a tool (https://github.com/tiann/freedrop) for P2P file transfer using MQTT + WebRTC. To maximize bandwidth utilization, I needed to perform end-to-end testing on two public network machines. So, I started codex on both machines using HAPI, and then used @session to have the two agents start transferring files to each other to pinpoint the bottleneck. Ultimately, their combined performance improved the transfer speed by 1.9 times!

[KorenKrita]

I’ve also been experimenting with Paseo’s A2A recently, and ran into something interesting.

Paseo exposes its A2A functionality through three layers: CLI, MCP, and skills. For an agent connected to Paseo, the A2A-related MCP tools can be injected selectively; the skills are also optional, as is installing the CLI. The smallest setup is usually MCP-only. If you want the agent to receive guidance on how to use those tools, adding the skill is recommended. The CLI acts as an escape hatch when MCP is unavailable, since MCP depends on the daemon being up and reachable.

All of this worked exactly as expected until I tested Prime Agent today. I use both Codex and Pi, and they share ~/.agents/skills/, so I had placed Paseo’s skill there. Prime Agent is forked from Pi, which means it also discovered that skill—even though Prime Agent itself had no Paseo integration and therefore no Paseo MCP tools injected.

Prime Agent is also a harness that strongly encourages subagent use. Before I noticed what was happening, it had already used the Paseo CLI to create and work with dozens of Codex instances. Even more interestingly, it developed a clear functional division of labor between the Codex agents created through Paseo and its own built-in subagents.

This changed my understanding of Paseo’s A2A model. In practice, the skill + CLI combination means that any Paseo-supported harness can become a callable backend for an external harness that has no native Paseo integration at all. It effectively creates a one-way invocation path without requiring both sides to integrate the same MCP layer.

This is not directly related to HAPI’s A2A implementation or design philosophy. It is just an observation that projects aggregating agent capabilities or information behind a single CLI + skill seem to be becoming more common lately—perhaps because more of us are routinely working across multiple agents and harnesses.

Another similar project I tried recently is Obelisk, which uses a single CLI to aggregate and parse session logs from multiple harnesses.

[bobleer]

That Prime Agent/Paseo path is kind of wild. It also convinced me that ‘skill discovered’ and ‘capability granted’ have to be two different runtime facts. In BitFun, a skill can describe how to use something, but it doesn't register the corresponding tool/CLI or grant it permission. Otherwise a shared ~/.agents/skills quietly becomes authority for every harness that scans it.

[tiann]

I believe skills + CLI is a better solution than MCP. I mentioned this during the PR merge, suggesting that skills could be used in conjunction. MCP infiltrates the system prompt and occupies a fixed context window, while skills load progressively. For sessions that don't require A2A, skills have virtually no overhead, while MCP incurs a fixed cost.

In fact, some of our current flavors don't implement MCP injection, so features like ping_peer are practically unavailable.

[heavygee]

@tiann on skills vs MCP (this comment and the note on #1195):

The shared goal looks unchanged: A2A as a first-class HAPI affordance, with the first pragmatic slice already underway. First-class, as I read it, means as deterministic as the product can reasonably be: the same create / inspect / ping (and spawn-with-remit) behavior across flavors, fail-closed, permission-gated, same hub and namespace.

Skills are the wrong layer for that contract. They are context. They might be loaded. They might be followed. That is a maybe, not an affordance. A collaboration path that exists only as prompt text is non-deterministic by construction (the #1370 shape: agents infer a contract from prose and then miss it). The create-side version showed up the same way: putting message on POST /api/machines/:id/spawn is stripped, spawn returns a session id, and the new session is empty. Tracking: #1509.

What I think gets there:

• Hub + CLI own create / inspect / ping (and spawn-with-remit). That is the HAPI affordance.
• MCP is one invocation path for flavors that already inject HAPI tools. A flavor missing that wiring is a coverage gap, not a reason to relocate the contract into SKILL.md.
• Skills can document "call spawn_peer / hapi spawn-peer." They cannot be the implementation.

MCP's fixed context cost is a real constraint. It may make sense to confirm making ping_peer / spawn_peer opt-in per session (#1401) so sessions that are not doing A2A do not pay the tool-list tax.

If the contract moves out of HAPI into skills, the non-determinism stays: empty peers, JWT+curl archaeology, and A2A that works only when a given session happened to load the right markdown. On my reading of the goal, I don't think that is something one can really consider a first-class affordance; that approach would not get us there.

[KorenKrita]

Mcp inject is different in each harness, for pi even don't own mcp itself, the Paseo require the pi install and use the most popular mcp package for it's inject, but it's easy to see not every pi uesr use that package, so Paseo give all mcp skill cli for every kind of use. But the mcp is good for server side update in the othe hand.

[bobleer]

That makes sense. I’d treat skill + CLI as the portable baseline and MCP as an optional fast path, rather than forcing one interface everywhere. The skill could start with a cheap hapi capabilities --json probe, then pick CLI, injected MCP, or no-op based on what that harness actually exposes.

That keeps the server-side-update advantage too: the hub can version the capability manifest while each harness only needs one tiny stable command. Most importantly, discovering the skill still does not silently grant the CLI permission.

[swear01]

I finally caught up with the discussion. I think I’m strongly aligned with the A2A direction, but somewhat more conservative about how far HAPI itself should expand above that layer.

I agree that A2A should be a first-class HAPI capability. In particular, I also agree with the recent point that the deterministic contract should live in the HAPI Hub/Runner/CLI rather than in prompt text.

Where I differ slightly is on the agent-facing integration. I strongly prefer Skill + CLI as the baseline rather than MCP. The actual capability still belongs to HAPI — the CLI implements inspect, ping, spawn, handoff, etc. — while the skill only teaches an agent when and how to use those primitives.

That keeps the integration lightweight and portable across agentic tools without injecting a fixed MCP tool surface/context into every session.

One thing I would especially like us to prioritize in A2A is inspect first, interact second.

A common use case for me is session migration: I may exhaust the quota of one agent and want to continue that session using another agentic tool. In exactly that situation, an A2A mechanism that requires the old agent to respond is unreliable — the old agent may no longer be able to run at all.

What I want is roughly:

new agent -> inspect old HAPI session -> recover context/state/artifacts -> continue

without requiring the old agent to participate. Live peer interaction can then be an additional capability when both sides are available.

Where I’m more hesitant about the larger thesis is HAPI owning higher-level capability management and orchestration itself: centrally managing/distributing skills, normalizing all agent capabilities, or introducing a central Overseer that routes work across every agent.

Those ideas are useful, but I’m not convinced they need to live in HAPI core. For example, tools such as [skillshare](https://github.com/runkids/skillshare) already do a good job of managing skills across many agentic tools.

Given HAPI’s relatively small maintainer base, I would rather keep that boundary narrow and spend the maintenance budget on supporting more native agents well.

My preferred layering would be:

• HAPI core: sessions, discovery, inspect, handoff, messaging, spawning, permissions, events
• Agent integration: Skill + HAPI CLI
• Higher-level orchestration / capability management: optional tools built on top of HAPI

So I’m very much in favor of first-class A2A — I’m also working on improving that path myself. I just think first-class A2A does not necessarily require first-class orchestration to live in HAPI itself.

[bobleer]

The A2A direction makes sense as long as HAPI stays the coordinator, not the accidental owner of every runtime’s filesystem, credentials, or MCP state. The handoff probably needs more than a prompt: authoritative workspace identity, agent/session id, pending approvals, and an artifact digest. Otherwise the “one boss” view can look coherent while two machines are acting on different state.