mirror of
https://github.com/NousResearch/hermes-agent.git
synced 2026-05-18 04:41:56 +00:00
97 lines
5.5 KiB
Markdown
97 lines
5.5 KiB
Markdown
# Hermes Agent ACP Registry + Zed Integration Implementation Plan
|
|
|
|
> For Hermes: Use subagent-driven-development skill to implement this plan task-by-task.
|
|
|
|
Goal: Make Hermes Agent installable from Zed's official ACP Registry, so users can add Hermes from Zed's agent panel without manual custom `agent_servers` settings.
|
|
|
|
Architecture: Use the official `agentclientprotocol/registry` flow instead of the deprecated Zed Agent Server Extension path. Ship a registry-compatible launcher distribution, advertise valid ACP auth methods during every handshake, validate against official registry schema and auth CI, then submit a registry PR for `hermes-agent`.
|
|
|
|
Tech Stack: Hermes Agent Python package, ACP adapter (`hermes acp` / `hermes-acp`), npm launcher package, official ACP Registry JSON schema, Zed external agent UI.
|
|
|
|
---
|
|
|
|
## Compliance constraints
|
|
|
|
- Zed v0.221.x+ prefers the ACP Registry for external agents; do not use Zed Agent Server Extensions for distribution.
|
|
- Registry repo layout is top-level `hermes-agent/agent.json` and `hermes-agent/icon.svg`, not `agents/hermes-agent/`.
|
|
- Registry metadata must use the official schema: `id`, `name`, `version`, `description`, `distribution`, optional `repository`, `website`, `authors`, `license`.
|
|
- Distribution must be exactly one supported type unless intentionally adding another: `binary`, `npx`, or `uvx`.
|
|
- Hermes must advertise at least one valid `authMethods` entry on a clean first-run handshake. No-provider/no-auth is not compliant.
|
|
- Terminal Auth must be explicit and deterministic: `id: hermes-setup`, `type: terminal`, `args: ["--setup"]`.
|
|
- `icon.svg` must be 16x16, square, monochrome, and use only `currentColor` / `none` for fill/stroke; no gradients, hardcoded colors, or `url(#...)` paints.
|
|
- ACP server mode must reserve stdout for JSON-RPC only. Diagnostics/logs go to stderr. `--version`, `--check`, and `--setup` are not server mode and may print normally.
|
|
- Published npm package must exist and be runnable before the upstream registry PR references it.
|
|
|
|
---
|
|
|
|
## Tasks
|
|
|
|
1. Verify/implement ACP auth methods.
|
|
- Always return terminal setup auth from `initialize()`.
|
|
- Return configured provider auth in addition when provider credentials are resolvable.
|
|
- Add tests for provider auth, terminal fallback auth, and authenticate behavior before/after provider setup.
|
|
|
|
2. Add non-interactive ACP commands.
|
|
- `hermes acp --version`
|
|
- `hermes acp --check`
|
|
- `hermes acp --setup`
|
|
- Same behavior through `hermes-acp`.
|
|
|
|
3. Build npm launcher package.
|
|
- Package: `@nousresearch/hermes-agent-acp@<version>`.
|
|
- Command: `uvx --from 'hermes-agent[acp]==<version>' hermes-acp ...args`.
|
|
- Fallback: `uv tool run --from ...` when only `uv` exists.
|
|
- Forward all args, including `--setup`, `--version`, and `--check`.
|
|
- Preserve stdio in server mode.
|
|
- Print actionable stderr error when `uv`/`uvx` is missing.
|
|
|
|
4. Replace local registry metadata.
|
|
- Convert `acp_registry/agent.json` from old command-style local format to official registry schema.
|
|
- Replace `acp_registry/icon.svg` with compliant 16x16 currentColor icon.
|
|
- Add tests rejecting old fields (`schema_version`, `display_name`, `distribution.type`, `distribution.command`) and unknown distribution keys.
|
|
|
|
5. Update docs.
|
|
- Zed docs show official ACP Registry install first: Add Agent / `zed: acp registry` -> search Hermes Agent -> install.
|
|
- Manual `agent_servers` JSON remains only as local-development fallback.
|
|
- Docs include `uv` prerequisite and `hermes acp --check` troubleshooting.
|
|
- Developer internals mention npm launcher and terminal setup auth.
|
|
|
|
6. Validate locally.
|
|
- `python -m pytest tests/acp/test_auth.py tests/acp/test_server.py tests/acp/test_entry.py tests/acp/test_registry_manifest.py -q`
|
|
- `(cd packages/hermes-agent-acp && npm test)`
|
|
- `(cd packages/hermes-agent-acp && npm pack --dry-run)`
|
|
- `hermes acp --version`
|
|
- `hermes acp --check`
|
|
|
|
7. Validate against official registry tooling before PR.
|
|
- In a clone/fork of `agentclientprotocol/registry`, copy files into top-level `hermes-agent/`.
|
|
- Run official dry-run build, e.g. `uv run --with jsonschema .github/workflows/build_registry.py --dry-run`.
|
|
- Run official auth check if available, e.g. `.github/workflows/scripts/run-registry-docker.sh python3 .github/workflows/verify_agents.py --auth-check`.
|
|
- Fix any schema/auth issues before submitting.
|
|
|
|
8. Publish and submit.
|
|
- Publish `@nousresearch/hermes-agent-acp@<version>`.
|
|
- Verify published package:
|
|
- `npx @nousresearch/hermes-agent-acp@<version> --version`
|
|
- `npx @nousresearch/hermes-agent-acp@<version> --check`
|
|
- ACP initialize/authMethods smoke test through the published package.
|
|
- Open PR to `agentclientprotocol/registry` adding `hermes-agent/agent.json` and `hermes-agent/icon.svg`.
|
|
|
|
9. End-to-end Zed verification.
|
|
- Install Hermes Agent through Zed's ACP Registry.
|
|
- Start a Hermes thread.
|
|
- Verify workspace cwd, file tools, terminal tools, tool rendering, and approval prompts.
|
|
|
|
---
|
|
|
|
## Acceptance criteria
|
|
|
|
- Hermes appears in Zed's official ACP Registry UI.
|
|
- Install starts Hermes without custom Zed settings.
|
|
- Registry CI passes schema and auth validation.
|
|
- ACP stdout remains JSON-RPC only; all logs go to stderr.
|
|
- `authMethods` are present and valid on clean first run.
|
|
- Terminal Auth can launch Hermes provider/model setup with `--setup`.
|
|
- Zed workspace cwd is honored by Hermes file and terminal tools.
|
|
- Docs describe registry install first and manual custom config second.
|
|
- Package/release automation prevents registry entries from pointing at unpublished versions.
|