# 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`