dirigent/crates/dirigent_acp_api/CLAUDE.md

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

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:

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