adk-acp 0.8.2

Agent Client Protocol (ACP) integration for ADK-Rust — connect to Claude Code, Codex, and other ACP agents
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131

//! Server-specific error types for the ACP Server.
//!
//! These errors represent conditions that can occur during server operation,
//! from session management failures to transport issues.

use std::fmt;

/// Server-specific errors for the ACP Server.
///
/// Each variant maps to a specific error condition with a machine-readable
/// `error_code` and human-readable message. Internal details are logged
/// via `tracing` but never exposed to clients.
#[derive(Debug)]
pub enum AcpServerError {
    /// Session not found in the registry.
    SessionNotFound(String),

    /// Maximum concurrent sessions reached.
    MaxSessionsReached(usize),

    /// Server is shutting down, not accepting new requests.
    ShuttingDown,

    /// Protocol version not supported.
    UnsupportedVersion {
        /// The version requested by the client.
        requested: String,
        /// The versions supported by this server.
        supported: Vec<String>,
    },

    /// Malformed protocol message received.
    MalformedMessage(String),

    /// Internal server error (details logged, not exposed to client).
    Internal(String),

    /// Transport-level error.
    Transport(String),

    /// Agent execution error.
    Execution(String),
}

impl AcpServerError {
    /// Returns the machine-readable error code for this error.
    ///
    /// # Example
    ///
    /// ```rust,ignore
    /// let err = AcpServerError::SessionNotFound("sess-123".into());
    /// assert_eq!(err.error_code(), "session_not_found");
    /// ```
    pub fn error_code(&self) -> &'static str {
        match self {
            Self::SessionNotFound(_) => "session_not_found",
            Self::MaxSessionsReached(_) => "max_sessions_reached",
            Self::ShuttingDown => "shutting_down",
            Self::UnsupportedVersion { .. } => "unsupported_version",
            Self::MalformedMessage(_) => "malformed_message",
            Self::Internal(_) => "internal_error",
            Self::Transport(_) => "transport_error",
            Self::Execution(_) => "execution_error",
        }
    }

    /// Returns a client-safe message that does not expose internal details.
    ///
    /// For `Internal` errors, a generic message is returned. For all other
    /// variants, the descriptive message is returned.
    pub fn client_message(&self) -> String {
        match self {
            Self::SessionNotFound(id) => format!("session not found: {id}"),
            Self::MaxSessionsReached(limit) => {
                format!("max sessions reached (limit: {limit})")
            }
            Self::ShuttingDown => "server is shutting down".to_string(),
            Self::UnsupportedVersion { requested, supported } => {
                format!("unsupported protocol version: {requested}, supported: {supported:?}")
            }
            Self::MalformedMessage(msg) => format!("malformed message: {msg}"),
            Self::Internal(_) => "internal server error".to_string(),
            Self::Transport(msg) => format!("transport error: {msg}"),
            Self::Execution(msg) => format!("execution error: {msg}"),
        }
    }

    /// Formats the error as a JSON-compatible error response.
    pub fn to_error_response(&self) -> ErrorResponse {
        ErrorResponse { error_code: self.error_code().to_string(), message: self.client_message() }
    }
}

impl fmt::Display for AcpServerError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::SessionNotFound(id) => write!(f, "session not found: {id}"),
            Self::MaxSessionsReached(limit) => {
                write!(f, "max sessions reached (limit: {limit})")
            }
            Self::ShuttingDown => write!(f, "server is shutting down"),
            Self::UnsupportedVersion { requested, supported } => {
                write!(f, "unsupported protocol version: {requested}, supported: {supported:?}")
            }
            Self::MalformedMessage(msg) => write!(f, "malformed message: {msg}"),
            Self::Internal(msg) => write!(f, "internal server error: {msg}"),
            Self::Transport(msg) => write!(f, "transport error: {msg}"),
            Self::Execution(msg) => write!(f, "execution error: {msg}"),
        }
    }
}

impl std::error::Error for AcpServerError {}

impl From<AcpServerError> for crate::AcpError {
    fn from(err: AcpServerError) -> Self {
        crate::AcpError::Protocol(err.to_string())
    }
}

/// A structured error response sent to ACP clients.
///
/// Contains a machine-readable `error_code` and a human-readable `message`.
/// Internal details (stack traces, file paths) are never included.
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
pub struct ErrorResponse {
    /// Machine-readable error code (e.g., "session_not_found").
    pub error_code: String,
    /// Human-readable error description.
    pub message: String,
}