Hermes Agent implements the Agent Client Protocol (ACP), a standardized communication layer that allows the agent to function as a backend for AI-native editors and IDEs. By running as an ACP server, Hermes provides its full suite of self-improvement capabilities, toolsets, and persistent memory to environments like VS Code and Zed.
The ACP integration is centered around the HermesACPAgent class acp_adapter/server.py41 which implements the acp.Agent interface. This server translates ACP lifecycle events (initialization, authentication, session management) into internal AIAgent operations.
When an IDE connects to Hermes via ACP, the following flow occurs:
initialize request. Hermes responds with its capabilities, including session forking, listing, and resumption acp_adapter/server.py94-130new_session, load_session, or resume_session, providing a working directory (cwd) acp_adapter/server.py282-358HermesACPAgent extracts text from ACP content blocks, retrieves or restores the SessionState acp_adapter/session.py159-173 and executes the agent loop in a ThreadPoolExecutor acp_adapter/server.py198acp_adapter.events capture tool progress, thinking blocks, and assistant messages, sending them back to the IDE as ACP session updates via asyncio.run_coroutine_threadsafe acp_adapter/events.py94-108The following diagram bridges the Agent Client Protocol concepts to the specific Python entities in the codebase.
Diagram: ACP to Code Entity Mapping
Sources: acp_adapter/server.py41 acp_adapter/session.py175-195 acp_adapter/events.py114-182 acp_adapter/session.py199-215 acp_adapter/tools.py24-59 acp_adapter/server.py198
ACP sessions are managed by a thread-safe SessionManager acp_adapter/session.py175-195 Unlike standard CLI sessions, ACP sessions are explicitly tied to an editor's working directory (cwd) and are persisted to the shared SessionDB (~/.hermes/state.db) so they survive process restarts acp_adapter/session.py3-8
When a session is created, its cwd is registered with the terminal tool via _register_task_cwd acp_adapter/session.py112-127 to ensure environment overrides are applied to sub-processes. This is particularly important for Windows Subsystem for Linux (WSL) environments, where Windows drive paths need to be translated to WSL mount paths (e.g., E:\Projects to /mnt/e/Projects) acp_adapter/session.py29-41
| Function | File:Line | Description |
|---|---|---|
create_session | acp_adapter/session.py199-215 | Initializes a new SessionState, fresh AIAgent, and persists to DB. |
fork_session | acp_adapter/session.py233-267 | Deep-copies a session's history into a new ID with a fresh agent instance. |
list_sessions | acp_adapter/session.py269-304 | Merges in-memory and persisted sessions into a unified list. |
_translate_acp_cwd | acp_adapter/session.py29-41 | Converts Windows drive paths to WSL mount paths if Hermes is running in WSL. |
_register_task_cwd | acp_adapter/session.py112-127 | Binds a task/session ID to the editor's working directory for tools. |
Sources: acp_adapter/session.py175-304 acp_adapter/session.py29-41 acp_adapter/session.py112-127
Diagram: IDE Integration Sequence
Sources: acp_adapter/server.py94-130 acp_adapter/session.py199-215 acp_adapter/events.py66-72 acp_adapter/events.py114-121
Hermes tool names are mapped to ACP ToolKind (e.g., read_file -> read, terminal -> execute) using TOOL_KIND_MAP acp_adapter/tools.py24-59 During execution, make_tool_progress_cb acp_adapter/events.py114 creates a callback that generates unique tool call IDs via make_tool_call_id acp_adapter/tools.py89-91 and emits ToolCallStart events acp_adapter/events.py134-182
The ACP server implements a pre-execution approval mechanism for file mutations.
make_approval_callback acp_adapter/permissions.py73 is wired into the agent to gate sensitive tool calls.set_hermes_interactive_context acp_adapter/server.py83 to ensure the agent blocks correctly during tool execution turns.HermesACPAgent exposes approval policies as session modes (e.g., accept_edits, dont_ask) rather than flat configuration options tests/acp/test_server.py61-72Hermes supports registering ACP-provided MCP servers during session initialization. In new_session, mcp_servers are passed to the SessionManager acp_adapter/session.py129-144 which uses _expand_acp_enabled_toolsets to include these as toolsets. This allows IDEs to dynamically extend the agent's capabilities with their own local tools acp_adapter/session.py129-144
Since ACP reserves stdout for JSON-RPC frames, incidental output is redirected to stderr via _acp_stderr_print acp_adapter/session.py101-109 Tool titles are dynamically built to provide human-readable summaries (e.g., terminal: ls -la) acp_adapter/tools.py94-183
The server utilizes detect_provider() acp_adapter/auth.py65 to identify existing runtime credentials. If Hermes is not yet configured, it advertises a terminal auth method (TERMINAL_SETUP_AUTH_METHOD_ID) that allows the user to run the setup wizard directly from the IDE terminal acp_adapter/auth.py65
ACP supports sending image and file resources as part of the prompt. HermesACPAgent converts ImageContentBlock and ResourceContentBlock into OpenAI-compatible multimodal content tests/acp_adapter/test_acp_images.py16-28 Text resources are inlined with their URI and metadata to provide context to the agent tests/acp_adapter/test_acp_images.py39-59
Sources: acp_adapter/tools.py24-59 acp_adapter/session.py129-144 acp_adapter/session.py101-109 acp_adapter/tools.py94-183 acp_adapter/auth.py65 tests/acp_adapter/test_acp_images.py16-59
Refresh this wiki
This wiki was recently refreshed. Please wait 3 days to refresh again.