{
  "id": "page:docs-hermes-research-raw-acp-internals",
  "_kind": "Page",
  "_file": "wiki/docs/hermes-research/raw/acp-internals.md",
  "_cluster": "wiki",
  "attributes": {
    "nodeKind": "Page",
    "sourcePath": "docs/hermes-research/raw/acp-internals.md",
    "sourceKind": "repo-docs",
    "title": "ACP Internals",
    "displayName": "ACP Internals",
    "slug": "docs/hermes-research/raw/acp-internals",
    "articlePath": "wiki/docs/hermes-research/raw/acp-internals.md",
    "article": "\n# ACP Internals\n\n> Source: https://hermes-agent.nousresearch.com/docs/developer-guide/acp-internals\n\n## Architecture Overview\n\nThe ACP adapter implements a wrapper layer that \"converts Hermes' synchronous `AIAgent` into an async JSON-RPC stdio server.\" This enables editor integration through a standardized protocol.\n\n## Boot Sequence\n\nThe startup flow progresses through:\n- Entry point invocation (`acp_adapter.entry.main()`)\n- Version/configuration parsing\n- Environment loading from `~/.hermes/.env`\n- `HermesACPAgent` construction\n- Server initialization with `acp.run_agent()`\n\nNotably, \"stdout is reserved for ACP JSON-RPC transport\" while human-readable diagnostics route to stderr.\n\n## Core Components\n\n**HermesACPAgent** (`acp_adapter/server.py`)\nManages protocol implementation with responsibilities including session creation, prompt execution, and model switching. It bridges synchronous AI callbacks to asynchronous ACP notifications.\n\n**SessionManager** (`acp_adapter/session.py`)\nMaintains thread-safe session state including:\n- Session identifiers and agent instances\n- Working directory and model configuration\n- Message history and cancellation signals\n\n**Event Bridge** (`acp_adapter/events.py`)\nTranslates three callback types into ACP updates:\n- Tool progress notifications\n- Step execution events\n- Reasoning/thinking signals\n\nThe bridge uses `asyncio.run_coroutine_threadsafe()` to coordinate between the worker thread running the AI agent and the main event loop.\n\n**Permission System** (`acp_adapter/permissions.py`)\nMaps approval prompts to ACP permission requests: `allow_once` -> once, `allow_always` -> always, with timeout/failure defaulting to denial.\n\n## Session Management\n\nSessions persist to `~/.hermes/state.db` and restore across process restarts. The system supports:\n- Creating new sessions with specified working directories\n- Forking sessions by deep-copying message history\n- Cancellation via interrupt signals\n- FIFO tool tracking for parallel identical-name calls\n\n**Working Directory Binding**: Sessions carry editor workspace context through task-scoped terminal/file overrides.\n\n## Authentication\n\nRather than implementing custom auth, the adapter \"reuses Hermes' runtime resolver,\" advertising the currently configured provider credentials and offering an interactive setup method for first-run registry clients.\n\n## Implementation Files\n\nCore modules: `entry.py`, `server.py`, `session.py`, `events.py`, `permissions.py`, `tools.py`, `auth.py`, plus test suite at `tests/acp/` and toolset definition in `toolsets.py`.\n",
    "documents": []
  },
  "outgoingEdges": [],
  "incomingEdges": [
    {
      "from": "page:docs-hermes-research",
      "to": "page:docs-hermes-research-raw-acp-internals",
      "kind": "contains_page"
    }
  ]
}