Skip to content

Commit f942fff

Browse files
nikomatsakisclaude
nikomatsakis
and
claude
committed
docs(acp): add RFC and implementation documentation
Add comprehensive documentation for the ACP server implementation: - RFC document (agent-client-protocol-rfc.md) with detailed technical specification including: - Complete motivation and architectural design - Protocol mapping between ACP and Q CLI systems - Implementation decisions and deferred features - Session lifecycle and authentication flow - Implementation tracking document (PR_PLAN.md) showing: - Phase-by-phase development progress - Current implementation status (functionally complete for basic chat) - Remaining work items for advanced features This documentation provides reviewers with complete context for the ACP integration design and implementation approach. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
1 parent 48ce0ac commit f942fff

File tree

2 files changed

+478
-0
lines changed

2 files changed

+478
-0
lines changed

‎PR_PLAN.md‎

Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
# ACP Server Implementation Plan
2+
3+
This document tracks implementation progress for the Agent Client Protocol (ACP) server integration. It will be removed before the PR lands.
4+
5+
## Implementation Plan
6+
7+
The implementation uses an actor-based pattern for clean message passing instead of shared state with RwLocks. Implementation proceeds in commit-sized units:
8+
9+
### Phase 1: Actor Foundation
10+
1. **Actor pattern foundation** - Implement `AcpAgentForward`, `AcpServerHandle`, and `AcpSessionHandle` with message types
11+
- *Test*: Actor handles can be created, messages can be sent (stub responses)
12+
- *Note*: Uses `mpsc::channel(32)` for bounded message passing, `oneshot::channel()` for responses
13+
2. **Basic command structure** - Add `q acp` subcommand with feature gating and actor system integration
14+
- *Test*: `q acp` command spawns actor system, handles `initialize` requests
15+
- *Note*: Uses `LocalSet` for !Send ACP futures, stdio transport with `AgentSideConnection`
16+
3. **Server actor implementation** - Implement server actor loop with session management
17+
- *Test*: Can handle multiple ACP method calls, routes to appropriate handlers
18+
- *Note*: Server actor maintains `HashMap<SessionId, AcpSessionHandle>` for session routing
19+
20+
### Phase 2: Session Management
21+
4. **Session lifecycle** - Implement `new_session` and `load_session` with session actor spawning
22+
- *Test*: Can create sessions, spawn session actors, store session IDs
23+
- *Note*: Each session actor owns its `ConversationState` and `ToolManager` instance
24+
5. **Basic prompt handling** - Implement session actor prompt processing (stub LLM responses)
25+
- *Test*: Can send prompts to sessions, session actors receive and respond
26+
6. **Response streaming** - Wire up real LLM integration with ACP streaming notifications
27+
- *Test*: Prompts return actual AI responses, streaming works through actor system
28+
29+
### Phase 2.5: Test Infrastructure
30+
7. **Actor test harness** - Adapt existing test harness to work with new actor system
31+
- *Test*: Can test actor system with mock LLMs, conversational test scripts work
32+
- *Note*: Test harness creates actors in-process, injects mock LLM responses
33+
8. **Mock LLM integration** - Ensure mock LLM system works with session actors
34+
- *Test*: Mock LLM scripts can control session actor responses deterministically
35+
36+
### Phase 3: Advanced Features
37+
9. **Tool system integration** - Implement ACP tool permissions and execution through actors
38+
- *Test*: Tools work through session actors, permission requests flow correctly
39+
- *Note*: Session actors handle tool execution, report via ACP `ToolCall` messages
40+
10. **File operation routing** - Replace builtin file tools with ACP versions in session actors
41+
- *Test*: `fs_read`/`fs_write` work through editor, session actors route file operations
42+
- *Note*: Session actors use ACP file operations instead of direct filesystem access
43+
44+
**Architecture Benefits:**
45+
- **Eliminates RwLocks**: No shared mutable state, each actor owns its data
46+
- **Natural backpressure**: Bounded channels prevent memory issues under load
47+
- **Clean testing**: Each actor can be tested in isolation with message injection
48+
- **Incremental development**: Can implement and test each actor independently
49+
50+
## Current Implementation Status
51+
52+
**✅ COMPLETED - Phase 1: Actor Foundation**
53+
1. ✅ **Actor pattern foundation** - Complete actor system with message types
54+
- `AcpAgentForward`, `AcpServerHandle`, `AcpSessionHandle` implemented
55+
- Bounded channels (`mpsc::channel(32)`) with `oneshot` responses
56+
- Proper error propagation (`eyre::Result` internal, `acp::Error` protocol)
57+
2. ✅ **Basic command structure** - `q acp` subcommand with actor integration
58+
- Feature gating, `LocalSet` for !Send futures, stdio transport
59+
- `AgentSideConnection` integration working
60+
3. ✅ **Server actor implementation** - Complete server actor with session routing
61+
- Session management with `HashMap<SessionId, AcpSessionHandle>`
62+
- Method routing for `initialize`, `new_session`, `load_session`, etc.
63+
64+
**✅ COMPLETED - Phase 2: Session Management**
65+
4. ✅ **Session lifecycle** - Session creation and actor spawning working
66+
- `new_session` creates session actors with unique IDs
67+
- Each session actor owns its `ConversationState` and `ToolManager`
68+
5. ✅ **Basic prompt handling** - Session actors process prompts correctly
69+
- Convert ACP prompts to Q CLI format, set in conversation state
70+
6. ✅ **Response streaming** - Full LLM integration with streaming notifications
71+
- Real `SendMessageStream` integration, `ResponseEvent` → ACP conversion
72+
- Streaming `AssistantText`, `ToolUseStart`, `ToolUse` events via transport
73+
74+
**🚧 REMAINING WORK**
75+
76+
**Phase 2.5: Test Infrastructure**
77+
7. ⚠️ **Actor test harness** - Need to adapt existing test infrastructure
78+
8. ⚠️ **Mock LLM integration** - Ensure mock LLM works with session actors
79+
80+
**Phase 3: Advanced Features**
81+
9. ⚠️ **Tool system integration** - Basic tool execution works, need ACP permissions
82+
- Current: Tool use shows as `[Tool execution]` placeholder
83+
- Missing: ACP `session/request_permission` flow, proper `ToolCall` messages
84+
10. ⚠️ **File operation routing** - Need ACP file operations instead of direct filesystem
85+
- Current: Uses direct filesystem access
86+
- Missing: Route `fs_read`/`fs_write` through ACP protocol
87+
88+
**Minor TODOs:**
89+
- Session configuration from ACP (currently uses defaults)
90+
- Cancel operations implementation (currently no-op)
91+
- Set session mode implementation (currently returns method not found)
92+
93+
**Current State:** The ACP server is **functionally complete** for basic chat functionality. Users can connect editors, create sessions, send prompts, and receive streaming AI responses. The actor architecture is solid and ready for the remaining advanced features.

0 commit comments

Comments
 (0)