Skip to content

feat: add ACP (Agent Client Protocol) server for VS Code / Zed / JetBrains integration#837

Open
teknium1 wants to merge 2 commits intomainfrom
hermes/hermes-1a683351
Open

feat: add ACP (Agent Client Protocol) server for VS Code / Zed / JetBrains integration#837
teknium1 wants to merge 2 commits intomainfrom
hermes/hermes-1a683351

Conversation

@teknium1
Copy link
Contributor

@teknium1 teknium1 commented Mar 10, 2026 •
edited
Loading

Summary

Adds full ACP (Agent Client Protocol) support, enabling hermes-agent to work as a coding agent inside VS Code (via vscode-acp extension), Zed (native), JetBrains IDEs, and any ACP-compatible editor.

Also adds the jupyter-live-kernel skill for data science workflows.

ACP is the industry standard for agent-editor communication, co-developed by Zed and JetBrains. 30+ agents already support it.

User Flow

1. hermes is already installed (install.sh)
2. Install 'ACP Client' extension in VS Code
3. Add to settings: "acp.agents": { "hermes": { "command": "hermes", "args": ["acp"] } }
4. Open ACP panel → Select hermes → Start chatting

ACP Implementation (acp_adapter/, ~1000 lines)

File Purpose
server.py HermesACPAgent — all 15 Agent protocol methods
session.py Thread-safe SessionManager with per-session AIAgent
events.py Callback → ACP notification translation
tools.py Tool kind mapping (20+ tools) + content builders
permissions.py Approval bridging → editor permission dialogs
auth.py Provider credential verification
entry.py CLI entry point

Features

  • ✅ Full session lifecycle (new, load, list, fork, resume)
  • ✅ Tool call events with kinds (read/edit/execute/search/fetch/think)
  • ✅ Diff content for file edits
  • ✅ Terminal output content
  • ✅ Permission bridging (dangerous commands → editor approval dialog)
  • ✅ Reasoning/thinking streaming
  • ✅ Token usage tracking
  • ✅ Cancel/interrupt + Model switching

Integration

  • run_agent.py: ACP tool bridge hook
  • hermes_cli/main.py: hermes acp subcommand
  • pyproject.toml: [acp] extra (auto-installed via install.sh)
  • docs/acp-setup.md: User setup guide

Also includes: jupyter-live-kernel skill

New data-science skill category with hamelnb integration for stateful Jupyter REPL.

Tests

  • 41 new ACP tests + full suite: 2901 passed, 0 failures

teknium1 added 2 commits March 10, 2026 08:07
@teknium1
feat(skills): add jupyter-live-kernel skill for stateful Python REPL
cfc3ccb 
Adds a new data-science skill category with jupyter-live-kernel, which
uses hamelnb (https://github.com/hamelsmu/hamelnb) to give the agent
a live Jupyter kernel for stateful, iterative Python execution.

Key features:
- Variables persist across executions (unlike execute_code which is stateless)
- Inspect live variables, edit notebook cells, restart-and-run-all
- Clear trigger conditions and distinction from execute_code/terminal
- Practical tips based on hands-on testing
- No new tools required — uses terminal to run CLI commands

Prerequisites: uv, jupyterlab, hamelnb cloned to ~/.agent-skills/hamelnb
@teknium1
feat: add ACP (Agent Client Protocol) server for editor integration
e80786c 
Adds full ACP support enabling hermes-agent to work as a coding agent
inside VS Code (via vscode-acp extension), Zed, JetBrains IDEs, and
any ACP-compatible editor.

## New module: acp_adapter/

- server.py: HermesACPAgent implementing all 15 Agent protocol methods
  (initialize, authenticate, new/load/list/fork/resume session, prompt,
  cancel, set mode/model/config, on_connect)
- session.py: Thread-safe SessionManager with per-session AIAgent lifecycle
- events.py: Callback factories translating hermes callbacks to ACP
  session_update notifications (tool_call, agent_thought, agent_message)
- tools.py: Tool kind mapping (20+ tools → read/edit/execute/search/fetch/think)
  and content builders (diffs for file edits, terminal output, text previews)
- permissions.py: Bridges hermes approval_callback to ACP requestPermission
  RPC for dangerous command approval dialogs in the editor
- auth.py: Provider credential verification
- entry.py: CLI entry point with .env loading and stderr logging

## Integration points

- run_agent.py: ACP tool bridge hook in _execute_tool_calls() for
  delegating file/terminal operations to the editor
- hermes_cli/main.py: 'hermes acp' subcommand
- pyproject.toml: [acp] optional dependency, hermes-acp entry point,
  included in [all] extras (auto-installed via install.sh)

## Supporting files

- acp_registry/agent.json: ACP Registry manifest
- acp_registry/icon.svg: Hermes caduceus icon
- docs/acp-setup.md: User-facing setup guide for VS Code, Zed, JetBrains

## Tests

- 41 new tests across 5 test files covering tools, sessions, permissions,
  server lifecycle, and auth
- Full test suite: 2901 passed, 0 failures

## User flow

1. hermes is already installed (install.sh)
2. Install 'ACP Client' extension in VS Code
3. Configure: command='hermes', args=['acp']
4. Chat with Hermes in the editor — diffs, terminals, approval
   dialogs, thinking blocks all rendered natively
@teknium1 teknium1 force-pushed the hermes/hermes-1a683351 branch from 0d42731 to e80786c Compare March 10, 2026 15:41
@teknium1 teknium1 changed the title feat(skills): add jupyter-live-kernel skill for stateful Python REPL feat: add ACP (Agent Client Protocol) server for VS Code / Zed / JetBrains integration Mar 10, 2026
@teknium1 teknium1 mentioned this pull request Mar 10, 2026
Closed
18 tasks
teknium1 added a commit that referenced this pull request Mar 11, 2026
@teknium1
feat: add ACP (Agent Client Protocol) server for editor integration
cc61f54 
Complete ACP implementation enabling hermes-agent to work as a coding
agent inside VS Code, Zed, JetBrains IDEs, and any ACP-compatible editor.

Based on PR #837 by teknium1, with full implementation of the prompt flow
and fixes for broken event bridging.

## ACP Adapter (acp_adapter/, ~1200 lines)

server.py — HermesACPAgent with all 15 Agent protocol methods:
  - Full session lifecycle (new, load, resume, list, fork, cancel)
  - prompt() runs AIAgent in thread executor, streams tool events,
    thinking, and agent messages back to the editor in real-time
  - Permission bridging for dangerous command approval dialogs
  - Model switching support

session.py — Thread-safe SessionManager with per-session AIAgent,
  conversation history, and model tracking

events.py — Callback factories bridging AIAgent's sync callbacks to
  ACP's async notifications via run_coroutine_threadsafe()

tools.py — Tool kind mapping (25+ tools) with human-readable titles,
  diff content for file edits, and result truncation

permissions.py — Maps ACP permission dialogs to hermes approval flow
auth.py — Provider credential detection
entry.py — CLI entry point with stderr logging

## Key Design Decisions

- No modifications to run_agent.py — ACP works entirely through
  AIAgent's existing callback system (tool_progress_callback,
  thinking_callback, step_callback)
- File edits shown as diffs in the editor (FileEditToolCallContent)
- Terminal commands shown with $ prefix
- Large tool outputs truncated for the UI (5000 char limit)
- Approval for dangerous commands routed to editor permission dialog

## Also includes
- jupyter-live-kernel skill for data science workflows
- acp_registry/ with agent.json for editor auto-discovery
- docs/acp-setup.md with VS Code, Zed, JetBrains setup guides
- hermes acp CLI subcommand

## Tests
- 81 new ACP tests covering server, session, events, tools, auth,
  permissions
- Full suite: 3330 passed, 16 skipped

Closes #837
@teknium1 teknium1 mentioned this pull request Mar 11, 2026
Merged
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@teknium1