docs(adr): ACP Server with WebSocket Transport

[chaodu-agent]

Summary

Proposes implementing an ACP (Agent Client Protocol) compliant server endpoint in OpenAB with WebSocket as the primary transport.

Architecture

┌─────────────────────────────────────────────────────────────┐
│                      ACP Clients                            │
├─────────────┬──────────────┬────────────┬───────┬──────────┤
│ IDE Plugin  │ Desktop App  │  Web App   │  CLI  │  Mobile  │
│ (Zed, JB)  │(AniCompanion)│ (Browser)  │       │          │
└──────┬──────┴──────┬───────┴─────┬──────┴───┬───┴────┬─────┘
       │             │             │          │        │
       └─────────────┴──────┬──────┴──────────┴────────┘
                            │
                   WSS  GET /acp  (JSON-RPC 2.0)
                            │
┌───────────────────────────┼─────────────────────────────────┐
│                    OpenAB Unified Binary                     │
│                           │                                 │
│  ┌────────────────────────▼────────────────────────────┐    │
│  │              ACP Server Adapter                      │    │
│  │  initialize / session/new / session/prompt           │    │
│  │  AgentMessageChunk / ToolCall / requestPermission    │    │
│  └────────────────────────┬────────────────────────────┘    │
│                           │                                 │
│  ┌────────────────────────▼────────────────────────────┐    │
│  │              Internal Dispatcher                     │    │
│  │         GatewayEvent / GatewayReply                  │    │
│  └───────┬────────────────┼────────────────┬───────────┘    │
│          │                │                │                │
│  ┌───────▼──────┐ ┌──────▼───────┐ ┌──────▼───────┐       │
│  │ Claude Agent │ │ Codex Agent  │ │  Kiro Agent  │       │
│  │  Container   │ │  Container   │ │  Container   │       │
│  └──────────────┘ └──────────────┘ └──────────────┘       │
│                                                             │
│  Existing adapters (Discord, Telegram, LINE, etc.)          │
│  continue to work in parallel                               │
└─────────────────────────────────────────────────────────────┘

Why ACP?

• Industry standard — backed by Zed, JetBrains, GitHub, Block (3.5k★ spec repo)
• Bidirectional — agent can request permission, push tool status, initiate messages
• Any client connects — IDE, desktop app, web app, CLI — no bespoke adapters needed
• Official SDKs — Rust, TypeScript, Python, Kotlin, Java

OAB's Unique Position

Existing ACP servers (Anvil, Goose, codex-acp):
  Local machine → stdio pipe → 1 agent process

OAB as ACP server:
  Remote clients → WebSocket → Multi-agent platform
                                 ├── Agent routing
                                 ├── Fan-out & aggregate
                                 ├── Session persistence
                                 ├── MCP bridging
                                 └── Tool policy engine

No one is building a remote multi-agent ACP server yet. This is OAB's differentiation.

What's in this PR

• docs/adr/acp-server-websocket.md — full ADR with context, decision, consequences, alternatives considered, and phased implementation plan

Implementation Phases

1. Core ACP Server (MVP) — WebSocket upgrade, initialize/session/prompt, streaming replies
2. Tool Calls & Permissions — ToolCall notifications, requestPermission flow
3. Multi-Session & Resume — multiple sessions per connection, session/load
4. Multi-Agent Fan-Out — one prompt → multiple agents → aggregated result
5. Streamable HTTP — POST+SSE fallback for serverless environments

References

• ACP Spec
• ACP WebSocket Transport RFD
• Official Rust SDK
• Discussion context: VTuber adapter PR feat(vtuber): add OpenAI-compatible adapter #1234 and AniCompanion integration analysis

cc @pahud

[chaodu-agent]

LGTM ✅ — Well-structured ADR with solid technical grounding for adopting ACP as the standard client protocol.

What This PR Does

Proposes adding an ACP (Agent Client Protocol) compliant server endpoint to OpenAB with WebSocket transport, replacing the need for bespoke per-frontend adapters with a single industry-standard protocol.

How It Works

A new GET /acp endpoint with WebSocket upgrade is added to the existing axum HTTP listener, using the official agent-client-protocol Rust crate for JSON-RPC dispatch. ACP lifecycle methods (initialize, session/new, session/prompt) map to OAB's internal GatewayEvent/GatewayReply flow, with agent routing via the model field. Feature-gated behind acp with Bearer token auth on upgrade.

Findings

#	Severity	Finding	Location
1	🟢	Excellent strategic positioning — correctly identifies OAB's unique value as a remote multi-agent ACP server vs. existing local single-agent implementations	§1 Context
2	🟢	Related ADR references (unified-binary.md, multi-platform-adapters.md) both exist on main — cross-references are valid	§1 Related
3	🟢	Phased implementation plan is pragmatic — MVP first with progressive enhancement, deferring optional HTTP transport to Phase 5	§5 Implementation
4	🟢	Alternatives section is thorough — each rejected option (custom WS, OpenAI Realtime, MCP Streamable HTTP, per-frontend adapters) has clear justification	§4 Alternatives
5	🟢	Correctly notes WebSocket transport RFD is in Draft status, honestly acknowledging spec dependency risk	§3 Consequences
6	🟢	Clean feature-flag design with OPENAB_ACP_ENABLED and OPENAB_ACP_AUTH_KEY — non-invasive to existing adapters	§2 Decision

What's Good (🟢)

• Strategic clarity: The ADR identifies a genuine gap — no remote multi-agent ACP server exists — and positions OAB to fill it
• Spec alignment: The proposed GET /acp with WebSocket upgrade matches ACP transport RFD conventions
• Practical scope: Feature-gated, auth-gated, with graceful coexistence alongside existing adapters and the VTuber endpoint
• Accurate cross-references: Both related ADRs (unified-binary.md, multi-platform-adapters.md) exist in docs/adr/ on main
• Good risk acknowledgment: Honestly states spec dependency risk and current client adoption gap
• Clean ADR structure: Follows standard Context → Decision → Consequences → Alternatives → Implementation format
• Multi-agent fan-out vision: The ensemble dispatch concept (openab::ensemble) leverages OAB's existing multi-agent infrastructure in a novel way

Baseline Check

• PR opened: 2026-06-30
• Main already has: docs/adr/ directory with 20 existing ADRs (including referenced unified-binary.md and multi-platform-adapters.md)
• Main does NOT have: any ACP-related code or documentation
• Net-new value: First ADR establishing the architectural direction for ACP adoption — entirely new content, consistent with existing ADR corpus