acp_adapter — Agent Communication Protocol

🎯 Why This Module Exists

Without the ACP adapter, Hermes Agent would be limited to CLI interactions and its own gateway protocol. Every editor or IDE wanting to integrate Hermes would need to implement a bespoke communication protocol, handle session management, and bridge approval workflows. The ACP (Agent Communication Protocol) is an emerging standard that editors like Cursor and VSCode already support — by implementing it, Hermes becomes instantly compatible with any ACP-aware client. The adapter bridges the gap between Hermes' synchronous, thread-based AIAgent and the async, event-driven world of ACP. It handles session persistence (conversations survive server restarts), permission callbacks (editor UI for approving sensitive operations), tool kind classification (semantic grouping for editor display), and MCP server registration (dynamic tool addition). Without this module, users would lose their conversation history on every restart, and editors would have no way to request approval for dangerous operations like terminal commands.

🚶 Step-by-Step Narrated Walkthrough

Follow a single editor session from connection through tool execution and permission approval as it flows through the entire acp_adapter pipeline:

1. Connection — An editor (e.g., Cursor) spawns the Hermes ACP server process. Communication happens over stdio: stdout carries ACP JSON-RPC frames, stderr is reserved for logging to prevent frame corruption.
2. Protocol Negotiation — The editor sends initialize(). HermesACPAgent detects the active runtime provider (e.g., OpenAI, Anthropic) and returns auth methods, supported capabilities (session load, fork, model switch), and protocol version.
3. Session Creation — create_session() generates a UUID, creates a fresh AIAgent instance, wraps it in a SessionState dataclass, and persists it to SessionDB (~/.hermes/state.db).
4. User Message — The editor sends a message() with the user's prompt. The text is extracted from ACP content blocks (TextContentBlock, ImageContentBlock, etc.) via _extract_text().
5. Agent Execution — AIAgent.run() executes in a ThreadPoolExecutor (4 workers) so the ACP event loop stays responsive. Callback factories (make_message_cb, make_step_cb, make_thinking_cb, make_tool_progress_cb) bridge agent events to ACP notifications.
6. Tool Execution — When the agent calls a tool, get_tool_kind() classifies it (read, edit, execute, fetch, think, other). The editor receives a ToolCallStart notification with the kind and arguments.
7. Permission Request — For sensitive operations (terminal commands, file writes), make_approval_callback() sends a request_permission to the editor with three options: Allow Once, Allow Always, or Deny. The editor shows a UI prompt to the user.
8. Permission Resolution — The callback uses asyncio.run_coroutine_threadsafe() to coordinate between the agent's worker thread and the ACP event loop. A 60-second timeout auto-denies if the editor doesn't respond.
9. Streaming Updates — As the agent produces output, make_message_cb() streams text chunks to the editor as ACP message notifications. The editor can display them progressively.
10. Completion — finish_message() signals the end of the agent's response. The full conversation history is persisted to SessionDB. If the editor reconnects later, load_session() restores from DB.

Thread-to-Async Bridge Pattern

The Problem: AIAgent is synchronous (blocking file I/O, subprocess calls, network requests). ACP is async (event-driven, non-blocking). Callbacks need to cross the thread/async boundary in both directions: agent thread pushing updates to ACP loop, and ACP loop sending permission responses to agent thread.

The Approach: Agent runs in a ThreadPoolExecutor. Outbound callbacks (agent to editor) use asyncio.run_coroutine_threadsafe(coro, loop) to schedule ACP notifications on the main event loop. Inbound responses (editor to agent) use the same mechanism with future.result(timeout=60) to block the agent thread until the editor responds.

Why This Algorithm: The alternative — rewriting AIAgent as async — would require overhauling the entire tool execution pipeline. The bridge pattern keeps both sides in their natural execution model and adds minimal overhead (one coroutine per callback invocation).

sequenceDiagram
    participant E as Editor
    participant L as ACP Event Loop
    participant T as Agent Worker Thread
    participant A as AIAgent
    E->>L: message(prompt)
    L->>T: submit AIAgent.run()
    T->>A: run(prompt)
    A->>T: tool_progress callback
    T->>L: run_coroutine_threadsafe(notify)
    L->>E: ToolCallStart notification
    A->>T: approval_callback(terminal, rm -rf)
    T->>L: run_coroutine_threadsafe(request_permission)
    L->>E: request_permission
    E->>L: AllowedOutcome(allow_once)
    L->>T: future.result() returns allow_once
    T->>A: return "once"
    A->>T: run complete
    T->>L: run_coroutine_threadsafe(finish_message)
    L->>E: message complete

Hot Paths

The most performance-sensitive code paths in this module:

• Callback bridge (thread to async): asyncio.run_coroutine_threadsafe() adds ~0.1ms overhead per call. For streaming responses with many chunks, this is the dominant overhead.
• Session persistence: SQLite write after each message. For long conversations, the serialized history can be 100+ KB. Writes are synchronous but fast (SQLite WAL mode).
• Permission round-trip: Blocking wait on future.result(). Latency depends entirely on user response time (0-60 seconds). Not optimizable.

Resource Usage

• Memory: Each session holds an AIAgent instance with full conversation history. Long conversations can consume 10-50 MB per session. Sessions are evicted from memory on server restart (restored lazily from DB).
• Threads: 4-thread pool for agent execution. 1 main thread for ACP event loop. Total: 5 threads per server process.
• Disk: SessionDB grows with conversation history. Each message adds ~1-5 KB. No automatic cleanup; users manage via session deletion.