Adapter Architecture — Graph vs Packages Deep Dive

The Atlas graph defines **9 canonical muxes** as the bridging abstractions of the a5c agent stack. Each adapter normalizes one concern across all supported agent products. This document maps each graph adapter to its implementing package(s) and identifies concrete gaps.

The 9 Canonical Muxes (from `extensions/muxes/canonical-muxes.yaml`)

---

Adapter-to-Package Detailed Mapping

1. agent-launch-adapter → `adapters-cli/src/commands/launch.ts`

**Graph description:** Spawns and supervises Invocations across all supported agent products. Owns the 9-state Invocation lifecycle (spawned → running → paused → interrupted → aborted | timed-out | completed | crashed | killed).

**Bridging concerns (from graph):**

• spawn args per agent (positional prompt vs --prompt, model flag formats)
• env-var conventions per agent (ANTHROPIC_API_KEY vs OPENAI_API_KEY)
• working-directory mapping
• subprocess management (Unix pgroups vs Windows Job Objects)
• signal propagation
• retry policy and lifecycle hooks
• min-version enforcement (semver gate)
• execution-mode dispatch (local / docker / ssh / k8s / cloud)

**Implementation reality:**

• launch.ts is ~1600 lines handling spawn, proxy, PTY, bridge modes
• Adapter-specific args come from agent-catalog graph data (getYoloLaunchArgs, getLaunchConfig)
• Subprocess management: Unix pgroups ✅, Windows Job Objects ❌ (uses taskkill)
• Signal propagation: basic SIGTERM/SIGKILL ✅, SSH/docker/k8s ❌
• Retry policy: not implemented
• Min-version enforcement: not implemented
• Execution-mode dispatch: local only, no docker/ssh/k8s

**Gaps:**

---

2. agent-comm-adapter → `agent-comm-adapter/src/client.ts`

**Graph description:** Bridges every in-flight event shape. Channels are absorbed here because the underlying primitive is a structured communication channel between two participants.

**Implementation reality:**

• AgentMuxClient in agent-comm-adapter handles event streaming
• Events are normalized to a common shape across harnesses
• Session-flow projections in adapters-ui consume these events

**Gaps:**

---

3. agent-config-adapter → `adapters-cli` + `adapters-adapters`

**Graph description:** Wraps each agent's idiosyncratic config/auth/install conventions into one set of operations callable from orchestrator or user.

**Implementation reality:**

• install.ts handles install/uninstall/update/detect per adapter
• Each adapter in adapters-adapters defines install methods, config paths
• agent-catalog provides install metadata from the graph

**Gaps:**

---

4. hooks-adapter → `hooks-adapter-cli` + `hooks-adapter-core` + `hooks-adapter-adapter-*`

**Graph description:** Bridges per-product native hook names to the canonical hook taxonomy + applies per-axis merge policies.

**Implementation reality:**

• hooks-adapter-core: canonical hook taxonomy, merge policies
• hooks-adapter-cli: CLI binary (a5c-hooks-adapter invoke)
• 10 adapter packages: claude, codex, gemini, copilot, cursor, pi, oh-my-pi, opencode, openclaw, hermes

**Gaps:**

---

5. transport-adapter → `transport-adapter`

**Graph description:** Bridges between concrete LLM wire protocols and one canonical inference request/response shape. Adding a new native impl is a Catalog edit.

**Implementation reality:**

• HTTP proxy translating between exposed transport (what harness speaks) and target transport (what provider expects)
• Supports: OpenAI Chat, OpenAI Responses, Anthropic, Google, Bedrock
• Codec architecture planned but incomplete

**Gaps:**

---

6. extensions-adapter → `extensions-adapter`

**Graph description:** Compiles one Portable Extension manifest into per-agent native formats via per-target generators.

**Implementation reality:**

• Mature compiler: plugin.json → 10 target formats (claude-code, codex, gemini, etc.)
• Handles hooks, skills, commands, agents, settings per target
• sharedSets for per-harness overrides

**Gaps:**

---

7. session-storage-adapter → `babysitter-sdk` (session module)

**Graph description:** Unified abstraction for reading and writing session files at rest.

**Implementation reality:**

• packages/babysitter-sdk/src/session/ handles init, associate, resume, update, state
• YAML frontmatter session state management
• Tied to .a5c/ state directory

**Gaps:**

---

8. tasks-adapter → `tasks-adapter`

**Graph description:** The lone live Trust Chain primitive — ProvenBreakpointAnswer signs decision answers with the named Authority of the responder. Bridges every backend (Linear, GitHub, Slack, etc.)

**Implementation reality:**

• tasks-adapter: pluggable backends, cryptographic signing
• Server-backed breakpoint routing
• MCP integration for remote approval

**Gaps:**

---

9. tools-adapter → **No dedicated package**

**Graph description:** CLI→MCP gateway, CLI→MCP gateway, and tool-level hooks layered on hooks-adapter PreToolUse / PostToolUse.

**Implementation reality:**

• Tool dispatch is embedded in agent-comm-adapter and agent-platform
• MCP tool serving is in babysitter-sdk (mcp module)
• No unified tools-adapter abstraction

**Gaps:**

---

Agent Stack Implementation Layers (L4-L6)

agent-core vs agent-comm-adapter vs agent-platform

The graph defines three implementation node kinds for the agent stack:

But agent-comm-adapter also implements L4-L5 concerns (event dispatch, session management, adapter registry) without being an "AgentCoreImpl" in the graph.

**Gap:** agent-comm-adapter is the de facto agent core for harness-mediated scenarios but isn't represented as an AgentCoreImpl in the graph. The graph has agent:adapters as an AgentProduct but its internal decomposition (core/cli/adapters/gateway/tui/ui) isn't modeled.

Package Decomposition vs Graph Model

**Gap:** 4 of 7 adapters packages have no corresponding adapter in the graph. They implement presentation (L11) and observability concerns that the adapter model doesn't cover.

---

Summary of Critical Gaps