mirror of
https://github.com/NousResearch/hermes-agent.git
synced 2026-05-18 04:41:56 +00:00
fef1a41248
Cross-checked 75 docs pages under user-guide/messaging/, developer-guide/,
guides/, and integrations/ against the live registries and gateway code.
messaging/
- index.md: API Server toolset is hermes-api-server (was 'hermes (default)');
Google Chat slug is hermes-google_chat (underscore — plugin name uses _).
- google_chat.md: drop bogus 'pip install hermes-agent[google_chat]' (no such
extra); list the actual deps (google-cloud-pubsub, google-api-python-client,
google-auth, google-auth-oauthlib).
- qqbot.md: config namespace is platforms.qqbot (was platforms.qq, which is
silently ignored by the adapter); QQ_STT_BASE_URL is not read directly —
baseUrl lives under platforms.qqbot.extra.stt.
- teams-meetings.md: 'hermes teams-pipeline' is plugin-gated (teams_pipeline
plugin must be enabled), not a built-in subcommand.
- sms.md: example log line 0.0.0.0:8080 -> 127.0.0.1:8080 (default
SMS_WEBHOOK_HOST).
- open-webui.md: API_SERVER_* are env vars, not YAML keys — write them to
per-profile .env, not 'hermes config set' (same pattern fixed in
api-server.md last round). Also bumped example ports to 8650+ to dodge the
default webhook (8644)/wecom-callback (8645)/msgraph-webhook (8646)
collision.
developer-guide/
- architecture.md: tool/toolset counts (61/52 -> 70+/~28); LOC stamps for
run_agent.py, cli.py, hermes_cli/main.py, setup.py, mcp_tool.py,
gateway/run.py replaced with 'large file' to stop drifting.
- agent-loop.md: same LOC drift (~13,700 -> 'a large file (15k+ lines)').
- gateway-internals.md: '14+ external messaging platforms' -> '20+'; gateway
platform tree updated (qqbot is a sub-package, not qqbot.py; added
yuanbao.py, feishu_comment.py, msgraph_webhook.py); 'gateway/builtin_hooks/
(always active)' was wrong — it's an empty extension point and
_register_builtin_hooks() is a no-op stub.
- acp-internals.md: drop fictional 'message_callback' from the bridged-
callbacks list; clarify thinking_callback is currently set to None.
- provider-runtime.md: provider list was missing AWS Bedrock, Azure Foundry,
NVIDIA NIM, xAI, Arcee, GMI Cloud, StepFun, Qwen OAuth, Xiaomi, Ollama
Cloud, LM Studio, Tencent TokenHub. Fallback section described only the
legacy single-pair model — corrected to the canonical list-form
fallback_providers chain.
- environments.md: parsers list missing llama4_json and the deepseek_v31
alias; both register via @register_parser.
- browser-supervisor.md: drop reference to scripts/browser_supervisor_e2e.py
which doesn't exist in-repo.
- contributing.md: tinker-atropos is a git submodule — note that
'git submodule update --init' is required if cloning without
--recurse-submodules.
guides/
- operate-teams-meeting-pipeline.md: cron flags were all wrong — schedule is
positional (not --schedule), the script-only flag is --no-agent (not
--script-only), and there's no --command flag. Replaced with a real example
that creates the script under ~/.hermes/scripts/ and uses the actual flags.
Also replaced fictional 'hermes cron show <name>' with 'hermes cron status'.
- automation-templates.md: 'cron create --skills "a,b"' doesn't work —
the flag is --skill (singular, repeatable). Fixed all 5 occurrences via AST
rewrite.
- minimax-oauth.md: 'hermes auth add minimax-oauth --region cn' silently
fails because --region isn't registered on the auth-add argparse spec.
Pointed users at the minimax-cn provider (or MINIMAX_CN_API_KEY env) for
China-region access.
- cron-script-only.md: 'hermes send' is fictional — replaced the comparison-
table mention with a webhook-subscription pointer; also fixed the dead link
to /guides/pipe-script-output (page doesn't exist).
- cron-troubleshooting.md: 'hermes serve' isn't a real subcommand. Pointed
at 'hermes gateway' (foreground) / 'hermes gateway start' (service).
- local-ollama-setup.md: 'agent.api_timeout' is not a config key. The right
knob is the HERMES_API_TIMEOUT env var.
- python-library.md: run_conversation() return dict has only final_response
and messages — task_id is stored on the agent instance, not echoed back.
- use-mcp-with-hermes.md: '--args /c "npx -y …"' wraps the npx command in
one quoted string, so cmd.exe gets a single arg instead of the multi-token
command line it needs. Removed the surrounding quotes — argparse nargs='*'
collects each token correctly.
integrations/
- providers.md: Bedrock guardrail YAML keys were 'id'/'version' (don't exist);
actual keys are guardrail_identifier/guardrail_version (matches DEFAULT_CONFIG
and the run_agent.py reader). GMI default base URL (api.gmi.ai/v1 ->
api.gmi-serving.com/v1) and portal URL (inference.gmi.ai -> www.gmicloud.ai)
refreshed. Fallback section rewritten to lead with the canonical
fallback_providers list form (was leading with the legacy fallback_model
single dict); supported-providers list extended to include azure-foundry,
alibaba-coding-plan, lmstudio.
index.md
- '68 built-in tools' -> '70+'; '15+ platforms' was both inconsistent with
integrations/index.md ('19+') and undercounted — bumped to 20+ and added
Weixin/QQ Bot/Yuanbao/Google Chat to the list.
Validation: 'npm run build' clean (exit 0); broken-link count unchanged at
155 (same as round-1 post-skill-regen baseline). 24 files, +132/-89.
181 lines
4.7 KiB
Markdown
181 lines
4.7 KiB
Markdown
---
|
|
sidebar_position: 2
|
|
title: "ACP Internals"
|
|
description: "How the ACP adapter works: lifecycle, sessions, event bridge, approvals, and tool rendering"
|
|
---
|
|
|
|
# ACP Internals
|
|
|
|
The ACP adapter wraps Hermes' synchronous `AIAgent` in an async JSON-RPC stdio server.
|
|
|
|
Key implementation files:
|
|
|
|
- `acp_adapter/entry.py`
|
|
- `acp_adapter/server.py`
|
|
- `acp_adapter/session.py`
|
|
- `acp_adapter/events.py`
|
|
- `acp_adapter/permissions.py`
|
|
- `acp_adapter/tools.py`
|
|
- `acp_adapter/auth.py`
|
|
- `acp_registry/agent.json`
|
|
|
|
## Boot flow
|
|
|
|
```text
|
|
hermes acp / hermes-acp / python -m acp_adapter
|
|
-> acp_adapter.entry.main()
|
|
-> load ~/.hermes/.env
|
|
-> configure stderr logging
|
|
-> construct HermesACPAgent
|
|
-> acp.run_agent(agent, use_unstable_protocol=True)
|
|
```
|
|
|
|
Stdout is reserved for ACP JSON-RPC transport. Human-readable logs go to stderr.
|
|
|
|
## Major components
|
|
|
|
### `HermesACPAgent`
|
|
|
|
`acp_adapter/server.py` implements the ACP agent protocol.
|
|
|
|
Responsibilities:
|
|
|
|
- initialize / authenticate
|
|
- new/load/resume/fork/list/cancel session methods
|
|
- prompt execution
|
|
- session model switching
|
|
- wiring sync AIAgent callbacks into ACP async notifications
|
|
|
|
### `SessionManager`
|
|
|
|
`acp_adapter/session.py` tracks live ACP sessions.
|
|
|
|
Each session stores:
|
|
|
|
- `session_id`
|
|
- `agent`
|
|
- `cwd`
|
|
- `model`
|
|
- `history`
|
|
- `cancel_event`
|
|
|
|
The manager is thread-safe and supports:
|
|
|
|
- create
|
|
- get
|
|
- remove
|
|
- fork
|
|
- list
|
|
- cleanup
|
|
- cwd updates
|
|
|
|
### Event bridge
|
|
|
|
`acp_adapter/events.py` converts AIAgent callbacks into ACP `session_update` events.
|
|
|
|
Bridged callbacks:
|
|
|
|
- `tool_progress_callback`
|
|
- `thinking_callback` (currently set to `None` in the ACP bridge — reasoning is forwarded through `step_callback` instead)
|
|
- `step_callback`
|
|
|
|
Because `AIAgent` runs in a worker thread while ACP I/O lives on the main event loop, the bridge uses:
|
|
|
|
```python
|
|
asyncio.run_coroutine_threadsafe(...)
|
|
```
|
|
|
|
### Permission bridge
|
|
|
|
`acp_adapter/permissions.py` adapts dangerous terminal approval prompts into ACP permission requests.
|
|
|
|
Mapping:
|
|
|
|
- `allow_once` -> Hermes `once`
|
|
- `allow_always` -> Hermes `always`
|
|
- reject options -> Hermes `deny`
|
|
|
|
Timeouts and bridge failures deny by default.
|
|
|
|
### Tool rendering helpers
|
|
|
|
`acp_adapter/tools.py` maps Hermes tools to ACP tool kinds and builds editor-facing content.
|
|
|
|
Examples:
|
|
|
|
- `patch` / `write_file` -> file diffs
|
|
- `terminal` -> shell command text
|
|
- `read_file` / `search_files` -> text previews
|
|
- large results -> truncated text blocks for UI safety
|
|
|
|
## Session lifecycle
|
|
|
|
```text
|
|
new_session(cwd)
|
|
-> create SessionState
|
|
-> create AIAgent(platform="acp", enabled_toolsets=["hermes-acp"])
|
|
-> bind task_id/session_id to cwd override
|
|
|
|
prompt(..., session_id)
|
|
-> extract text from ACP content blocks
|
|
-> reset cancel event
|
|
-> install callbacks + approval bridge
|
|
-> run AIAgent in ThreadPoolExecutor
|
|
-> update session history
|
|
-> emit final agent message chunk
|
|
```
|
|
|
|
### Cancelation
|
|
|
|
`cancel(session_id)`:
|
|
|
|
- sets the session cancel event
|
|
- calls `agent.interrupt()` when available
|
|
- causes the prompt response to return `stop_reason="cancelled"`
|
|
|
|
### Forking
|
|
|
|
`fork_session()` deep-copies message history into a new live session, preserving conversation state while giving the fork its own session ID and cwd.
|
|
|
|
## Provider/auth behavior
|
|
|
|
ACP does not implement its own auth store.
|
|
|
|
Instead it reuses Hermes' runtime resolver:
|
|
|
|
- `acp_adapter/auth.py`
|
|
- `hermes_cli/runtime_provider.py`
|
|
|
|
So ACP advertises and uses the currently configured Hermes provider/credentials.
|
|
|
|
## Working directory binding
|
|
|
|
ACP sessions carry an editor cwd.
|
|
|
|
The session manager binds that cwd to the ACP session ID via task-scoped terminal/file overrides, so file and terminal tools operate relative to the editor workspace.
|
|
|
|
## Duplicate same-name tool calls
|
|
|
|
The event bridge tracks tool IDs FIFO per tool name, not just one ID per name. This is important for:
|
|
|
|
- parallel same-name calls
|
|
- repeated same-name calls in one step
|
|
|
|
Without FIFO queues, completion events would attach to the wrong tool invocation.
|
|
|
|
## Approval callback restoration
|
|
|
|
ACP temporarily installs an approval callback on the terminal tool during prompt execution, then restores the previous callback afterward. This avoids leaving ACP session-specific approval handlers installed globally forever.
|
|
|
|
## Current limitations
|
|
|
|
- ACP sessions are persisted to the shared `~/.hermes/state.db` (SessionDB) and transparently restored across process restarts; they appear in `session_search`
|
|
- non-text prompt blocks are currently ignored for request text extraction
|
|
- editor-specific UX varies by ACP client implementation
|
|
|
|
## Related files
|
|
|
|
- `tests/acp/` — ACP test suite
|
|
- `toolsets.py` — `hermes-acp` toolset definition
|
|
- `hermes_cli/main.py` — `hermes acp` CLI subcommand
|
|
- `pyproject.toml` — `[acp]` optional dependency + `hermes-acp` script
|