sync from monorepo @ 2452e92e

2026-05-08 01:59:04 +02:00
commit b03dc15371
459 changed files with 129586 additions and 0 deletions
@@ -0,0 +1,124 @@
+# Package: dirigent_acp_api
+
+ACP Server implementation for accepting incoming ACP connections from external agents.
+
+## Quick Facts
+- **Type**: Library
+- **Main Entry**: src/lib.rs
+- **Dependencies**: axum, tokio, serde, tracing, uuid, async-trait, dirigent_protocol
+- **Status**: Core structure complete, integration with CoreRuntime pending
+
+## Overview
+
+The `dirigent_acp_api` package implements an ACP (Agent-Client Protocol) server that allows Dirigent to accept incoming connections from external ACP clients like Claude Code or custom agents. This enables session sharing, remote orchestration, and multi-client collaboration.
+
+## Architecture
+
+### Core Components
+
+- **config.rs** - Server configuration types (`AcpServerConfig`)
+- **error.rs** - Error types (`AcpServerError`, `JsonRpcErrorObject`)
+- **jsonrpc.rs** - JSON-RPC 2.0 types and parsing
+- **rpc.rs** - RPC handler and method dispatch
+- **session_manager.rs** - Session/client tracking (TODO)
+- **sse.rs** - SSE notification system (TODO)
+- **event_bridge.rs** - Event translation (TODO)
+
+### Key Types
+
+```rust
+pub struct AcpServerConfig {
+    pub enabled: bool,           // Enable/disable server
+    pub port: u16,               // Listen port (default: 3001)
+    pub allowed_origins: Option<Vec<String>>,  // CORS origins
+    pub max_connections: usize,  // Connection limit (default: 100)
+}
+```
+
+### ConnectorOperations Trait
+
+The RPC handler uses a trait abstraction to avoid circular dependencies with dirigent_core:
+
+```rust
+#[async_trait]
+pub trait ConnectorOperations: Send + Sync {
+    async fn create_session(&self, connector_id: &str) -> Result<String>;
+    async fn load_session(&self, connector_id: &str, session_id: &str) -> Result<Session>;
+    async fn send_prompt(&self, connector_id: &str, session_id: &str, prompt: &str) -> Result<String>;
+    // ... more methods
+}
+```
+
+## API Endpoints
+
+### POST `/rpc`
+
+JSON-RPC 2.0 endpoint supporting:
+- `initialize` - Client handshake
+- `session/new` - Create session
+- `session/load` - Load existing session
+- `session/prompt` - Send prompt
+- `session/cancel` - Cancel generation
+- `session/close` - Close session
+
+### GET `/events`
+
+Server-Sent Events for streaming notifications:
+- `acp/messageChunk` - Streaming content
+- `acp/messageComplete` - Generation complete
+- `acp/sessionIdle` - Ready for input
+
+### GET `/health`
+
+Health check endpoint.
+
+## Configuration UI
+
+The ACP Server is configured via the web UI at **Configuration > ACP Server**:
+
+- Enable/disable toggle
+- Port configuration
+- Max connections limit
+- Allowed origins (CORS)
+- Default connector selection
+- Connected clients management
+
+Server functions in `crates/api/src/acp_server.rs` bridge the UI and this package.
+
+## Implementation Status
+
+**Completed:**
+- Configuration types (`AcpServerConfig`)
+- Error types (`AcpServerError`)
+- JSON-RPC types and parsing
+- RPC handler structure with ConnectorOperations trait
+
+**Pending:**
+- Session Manager implementation
+- SSE Notifier implementation
+- Event Bridge implementation
+- Axum router integration
+- Web server integration
+
+## Key Files
+
+| File | Description |
+|------|-------------|
+| `src/lib.rs` | Module exports and router creation |
+| `src/config.rs` | AcpServerConfig with validation |
+| `src/error.rs` | Error types and codes |
+| `src/jsonrpc.rs` | JSON-RPC 2.0 implementation |
+| `src/rpc.rs` | RPC handler and method dispatch |
+
+## Related Packages
+
+- **dirigent_core** - Provides CoreHandle implementation of ConnectorOperations
+- **dirigent_protocol** - Shared event and message types
+- **api** - Server functions for UI configuration
+- **web** - Configuration UI components
+
+## Documentation
+
+- **Architecture**: `docs/architecture/acp_server.md`
+- **Configuration**: `docs/configuration/acp-connectors.md`
+- **Tasks**: `docs/building/07_acp_serve/02_acp_server_tasks.md`