[PR #5] [MERGED] feat(acp): Add ACP (Agent Communication Protocol) adapter for CLI agents #82

New issue

Closed

opened 2026-02-27 10:22:09 +03:00 by kerem · 0 comments

kerem commented

2026-02-27 10:22:09 +03:00

Owner

📋 Pull Request Information

Original PR: https://github.com/mikeyobrien/ralph-orchestrator/pull/5
Author: @mikeyobrien
Created: 12/14/2025
Status: ✅ Merged
Merged: 12/14/2025
Merged by: @mikeyobrien

Base: main ← Head: feature/acp-support

📝 Commits (10+)

9878b7b feat(acp): add ACPProtocol class for JSON-RPC 2.0 handling
9dbbf74 feat(acp): add ACPMessage data models for typed message handling
640b984 docs: update progress tracking for ACP Step 2 completion
b44c95a feat(acp): add ACPClient subprocess manager
a1afdf9 docs: update progress tracking for ACP Step 3 completion
6ffdce3 feat(acp): implement basic ACPAdapter with initialize/session flow
2549553 feat(acp): implement session/prompt and streaming update handling
c98fcbd docs: update progress tracking for ACP Step 5 completion
4e05d46 Ralph checkpoint 5
099ac0d feat(acp): implement permission handler with four modes

📊 Changes

30 files changed (+9040 additions, -43 deletions)

View changed files

➕ .agent/scratchpad.md (+12 -0)
📝 .gitignore (+1 -0)
📝 PROMPT.md (+457 -1)
📝 README.md (+118 -8)
📝 docs/api/cli.md (+26 -3)
📝 docs/changelog.md (+45 -0)
📝 docs/guide/agents.md (+214 -10)
📝 docs/guide/configuration.md (+73 -1)
📝 docs/index.md (+8 -5)
📝 docs/quick-start.md (+13 -1)
📝 src/ralph_orchestrator/__main__.py (+33 -2)
📝 src/ralph_orchestrator/adapters/__init__.py (+9 -2)
➕ src/ralph_orchestrator/adapters/acp.py (+750 -0)
➕ src/ralph_orchestrator/adapters/acp_client.py (+328 -0)
➕ src/ralph_orchestrator/adapters/acp_handlers.py (+890 -0)
➕ src/ralph_orchestrator/adapters/acp_models.py (+522 -0)
➕ src/ralph_orchestrator/adapters/acp_protocol.py (+214 -0)
📝 src/ralph_orchestrator/main.py (+2 -1)
📝 src/ralph_orchestrator/metrics.py (+4 -0)
📝 src/ralph_orchestrator/orchestrator.py (+36 -9)

...and 10 more files

📄 Description

Summary

Implements a complete ACP (Agent Communication Protocol) adapter enabling integration with any ACP-compliant CLI agent (e.g., Gemini CLI)
Adds JSON-RPC 2.0 protocol handling, subprocess lifecycle management, and streaming update support
Provides four permission modes: auto_approve, deny_all, allowlist, and interactive
Includes file and terminal operation handlers per ACP specification
Integrates with CLI (-a acp, --acp-agent, --acp-permission-mode) and configuration (ralph.yml)

Changes

New Files (6 source, 9 test):

src/ralph_orchestrator/adapters/acp.py - Main ACPAdapter class
src/ralph_orchestrator/adapters/acp_protocol.py - JSON-RPC 2.0 message handling
src/ralph_orchestrator/adapters/acp_client.py - Subprocess manager with async I/O
src/ralph_orchestrator/adapters/acp_models.py - Typed data models for ACP messages
src/ralph_orchestrator/adapters/acp_handlers.py - Permission, file, and terminal handlers
tests/test_acp_*.py - 305 unit tests covering all functionality

Modified Files:

src/ralph_orchestrator/__main__.py - CLI argument parsing for ACP options
src/ralph_orchestrator/main.py - Added ACP to AgentType enum
src/ralph_orchestrator/orchestrator.py - ACPAdapter initialization
src/ralph_orchestrator/metrics.py - ACP cost tracking entry (zero cost - billing via underlying agent)
README.md - Updated documentation with ACP usage

Features

JSON-RPC 2.0 Protocol - Full request/response/notification handling
Subprocess Management - Async read/write with graceful shutdown
ACP Handshake - initialize → session/new → session/prompt flow
Streaming Updates - Accumulates agent_message_chunk, agent_thought_chunk, tool_call notifications
Permission Handling - Four modes with allowlist pattern matching (exact, glob, regex)
File Operations - fs/read_text_file, fs/write_text_file with security validation
Terminal Operations - terminal/create, terminal/output, terminal/wait_for_exit, terminal/kill, terminal/release
Configuration - Via ralph.yml and environment variables (RALPH_ACP_AGENT, RALPH_ACP_PERMISSION_MODE, RALPH_ACP_TIMEOUT)

Usage

# Run with Gemini CLI (default ACP agent)
ralph run -a acp -p "Your prompt here"

# Specify a different ACP agent
ralph run -a acp --acp-agent myagent -p "Your prompt"

# Use deny_all permission mode
ralph run -a acp --acp-permission-mode deny_all -p "Your prompt"

Test plan

Unit tests: 305 passing, 8 skipped (integration tests require GOOGLE_API_KEY)
Protocol tests: JSON-RPC 2.0 message creation/parsing
Model tests: Dataclass validation and serialization
Handler tests: Permission modes, file ops, terminal ops
CLI tests: Argument parsing and orchestrator integration
E2E tests with Gemini CLI (manual verification documented in PROMPT.md)

Breaking Changes

None - this is an additive feature.

🤖 Generated with Claude Code

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/mikeyobrien/ralph-orchestrator/pull/5 **Author:** [@mikeyobrien](https://github.com/mikeyobrien) **Created:** 12/14/2025 **Status:** ✅ Merged **Merged:** 12/14/2025 **Merged by:** [@mikeyobrien](https://github.com/mikeyobrien) **Base:** `main` ← **Head:** `feature/acp-support` --- ### 📝 Commits (10+) - [`9878b7b`](https://github.com/mikeyobrien/ralph-orchestrator/commit/9878b7beda44f5e3bd323c4749fd37d8dfaa3f83) feat(acp): add ACPProtocol class for JSON-RPC 2.0 handling - [`9dbbf74`](https://github.com/mikeyobrien/ralph-orchestrator/commit/9dbbf74c109717731d219c9d4dd2280e07f866c7) feat(acp): add ACPMessage data models for typed message handling - [`640b984`](https://github.com/mikeyobrien/ralph-orchestrator/commit/640b9842b4ab77ee7948e75a4ab8e487cd9167d5) docs: update progress tracking for ACP Step 2 completion - [`b44c95a`](https://github.com/mikeyobrien/ralph-orchestrator/commit/b44c95a7689ff50ac75059cc9b29de37facfbe37) feat(acp): add ACPClient subprocess manager - [`a1afdf9`](https://github.com/mikeyobrien/ralph-orchestrator/commit/a1afdf97de3037c8f9606031ef70770c7b60fa07) docs: update progress tracking for ACP Step 3 completion - [`6ffdce3`](https://github.com/mikeyobrien/ralph-orchestrator/commit/6ffdce3b60400cf9eb13892c6734babb3247adbb) feat(acp): implement basic ACPAdapter with initialize/session flow - [`2549553`](https://github.com/mikeyobrien/ralph-orchestrator/commit/2549553bdfcd8a5cb3e819c0014974b9c49b2389) feat(acp): implement session/prompt and streaming update handling - [`c98fcbd`](https://github.com/mikeyobrien/ralph-orchestrator/commit/c98fcbd9f952a2e6e13d00cb940c6b28e7805eff) docs: update progress tracking for ACP Step 5 completion - [`4e05d46`](https://github.com/mikeyobrien/ralph-orchestrator/commit/4e05d463810eeb5d4f1e01dc64ef0d8e93fb6971) Ralph checkpoint 5 - [`099ac0d`](https://github.com/mikeyobrien/ralph-orchestrator/commit/099ac0d110ea7cee71ce30be20b6907acda0649c) feat(acp): implement permission handler with four modes ### 📊 Changes **30 files changed** (+9040 additions, -43 deletions) <details> <summary>View changed files</summary> ➕ `.agent/scratchpad.md` (+12 -0) 📝 `.gitignore` (+1 -0) 📝 `PROMPT.md` (+457 -1) 📝 `README.md` (+118 -8) 📝 `docs/api/cli.md` (+26 -3) 📝 `docs/changelog.md` (+45 -0) 📝 `docs/guide/agents.md` (+214 -10) 📝 `docs/guide/configuration.md` (+73 -1) 📝 `docs/index.md` (+8 -5) 📝 `docs/quick-start.md` (+13 -1) 📝 `src/ralph_orchestrator/__main__.py` (+33 -2) 📝 `src/ralph_orchestrator/adapters/__init__.py` (+9 -2) ➕ `src/ralph_orchestrator/adapters/acp.py` (+750 -0) ➕ `src/ralph_orchestrator/adapters/acp_client.py` (+328 -0) ➕ `src/ralph_orchestrator/adapters/acp_handlers.py` (+890 -0) ➕ `src/ralph_orchestrator/adapters/acp_models.py` (+522 -0) ➕ `src/ralph_orchestrator/adapters/acp_protocol.py` (+214 -0) 📝 `src/ralph_orchestrator/main.py` (+2 -1) 📝 `src/ralph_orchestrator/metrics.py` (+4 -0) 📝 `src/ralph_orchestrator/orchestrator.py` (+36 -9) _...and 10 more files_ </details> ### 📄 Description ## Summary - Implements a complete ACP (Agent Communication Protocol) adapter enabling integration with any ACP-compliant CLI agent (e.g., Gemini CLI) - Adds JSON-RPC 2.0 protocol handling, subprocess lifecycle management, and streaming update support - Provides four permission modes: `auto_approve`, `deny_all`, `allowlist`, and `interactive` - Includes file and terminal operation handlers per ACP specification - Integrates with CLI (`-a acp`, `--acp-agent`, `--acp-permission-mode`) and configuration (`ralph.yml`) ## Changes **New Files (6 source, 9 test):** - `src/ralph_orchestrator/adapters/acp.py` - Main ACPAdapter class - `src/ralph_orchestrator/adapters/acp_protocol.py` - JSON-RPC 2.0 message handling - `src/ralph_orchestrator/adapters/acp_client.py` - Subprocess manager with async I/O - `src/ralph_orchestrator/adapters/acp_models.py` - Typed data models for ACP messages - `src/ralph_orchestrator/adapters/acp_handlers.py` - Permission, file, and terminal handlers - `tests/test_acp_*.py` - 305 unit tests covering all functionality **Modified Files:** - `src/ralph_orchestrator/__main__.py` - CLI argument parsing for ACP options - `src/ralph_orchestrator/main.py` - Added ACP to AgentType enum - `src/ralph_orchestrator/orchestrator.py` - ACPAdapter initialization - `src/ralph_orchestrator/metrics.py` - ACP cost tracking entry (zero cost - billing via underlying agent) - `README.md` - Updated documentation with ACP usage ## Features 1. **JSON-RPC 2.0 Protocol** - Full request/response/notification handling 2. **Subprocess Management** - Async read/write with graceful shutdown 3. **ACP Handshake** - `initialize` → `session/new` → `session/prompt` flow 4. **Streaming Updates** - Accumulates `agent_message_chunk`, `agent_thought_chunk`, `tool_call` notifications 5. **Permission Handling** - Four modes with allowlist pattern matching (exact, glob, regex) 6. **File Operations** - `fs/read_text_file`, `fs/write_text_file` with security validation 7. **Terminal Operations** - `terminal/create`, `terminal/output`, `terminal/wait_for_exit`, `terminal/kill`, `terminal/release` 8. **Configuration** - Via `ralph.yml` and environment variables (`RALPH_ACP_AGENT`, `RALPH_ACP_PERMISSION_MODE`, `RALPH_ACP_TIMEOUT`) ## Usage ```bash # Run with Gemini CLI (default ACP agent) ralph run -a acp -p "Your prompt here" # Specify a different ACP agent ralph run -a acp --acp-agent myagent -p "Your prompt" # Use deny_all permission mode ralph run -a acp --acp-permission-mode deny_all -p "Your prompt" ``` ## Test plan - [x] Unit tests: 305 passing, 8 skipped (integration tests require GOOGLE_API_KEY) - [x] Protocol tests: JSON-RPC 2.0 message creation/parsing - [x] Model tests: Dataclass validation and serialization - [x] Handler tests: Permission modes, file ops, terminal ops - [x] CLI tests: Argument parsing and orchestrator integration - [x] E2E tests with Gemini CLI (manual verification documented in PROMPT.md) ## Breaking Changes None - this is an additive feature. 🤖 Generated with [Claude Code](https://claude.com/claude-code) --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>