codescout 0.15.0

High-performance coding agent toolkit MCP server
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
132
133
134
135
136
137
138
139
140
141
142
143

//! Wire envelope for the peer-delegation protocol. Networked-ready: pure JSON,
//! no Unix-socket assumptions. A future TCP/TLS transport swaps only the
//! connect/listen layer, not this type.

use serde::{Deserialize, Serialize};
use serde_json::Value;

/// Bumped on any breaking change to the envelope or method set.
pub const PROTOCOL_VERSION: u32 = 1;

#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "lowercase")]
pub enum EnvelopeKind {
    Request,
    Response,
    Event,
    Error,
}

/// The single message type on the wire. `serde(skip_serializing_if)` keeps
/// frames minimal (null fields omitted).
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct PeerEnvelope {
    pub v: u32,
    pub id: String,
    pub kind: EnvelopeKind,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub method: Option<String>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub params: Option<Value>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub result: Option<Value>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub error: Option<PeerError>,
}

impl PeerEnvelope {
    pub fn request(id: impl Into<String>, method: &str, params: Value) -> Self {
        Self {
            v: PROTOCOL_VERSION,
            id: id.into(),
            kind: EnvelopeKind::Request,
            method: Some(method.into()),
            params: Some(params),
            result: None,
            error: None,
        }
    }

    pub fn response(id: impl Into<String>, result: Value) -> Self {
        Self {
            v: PROTOCOL_VERSION,
            id: id.into(),
            kind: EnvelopeKind::Response,
            method: None,
            params: None,
            result: Some(result),
            error: None,
        }
    }

    pub fn error(id: impl Into<String>, error: PeerError) -> Self {
        Self {
            v: PROTOCOL_VERSION,
            id: id.into(),
            kind: EnvelopeKind::Error,
            method: None,
            params: None,
            result: None,
            error: Some(error),
        }
    }
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct PeerError {
    pub code: ErrorCode,
    pub message: String,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub data: Option<Value>,
}

/// Closed taxonomy. Maps onto codescout's `RecoverableError` on the requester
/// side so a peer's bad-input failure does not abort sibling tool calls.
#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "snake_case")]
pub enum ErrorCode {
    VersionMismatch,
    UnknownMethod,
    UnknownTool,
    AccessDenied,
    ToolError,
    UnknownHandle,
    BadParams,
}

/// Advertised by `hello`. Lets the requester avoid sending a write tool to a
/// read-only peer (defence-in-depth on top of the peer-side wall).
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Capabilities {
    pub project: String,
    pub root: String,
    pub read_only: bool,
    pub tools: Vec<String>,
    pub executor_available: bool,
}

#[cfg(test)]
mod tests {
    use super::*;
    use serde_json::json;

    #[test]
    fn request_envelope_round_trips() {
        let env = PeerEnvelope::request(
            "a:1",
            "tool.call",
            json!({ "tool": "symbols", "args": { "path": "src" } }),
        );
        let wire = serde_json::to_value(&env).unwrap();
        assert_eq!(wire["kind"], "request");
        assert_eq!(wire["method"], "tool.call");
        assert!(wire.get("result").is_none());
        assert!(wire.get("error").is_none());
        let back: PeerEnvelope = serde_json::from_value(wire).unwrap();
        assert_eq!(back.method.as_deref(), Some("tool.call"));
    }

    #[test]
    fn error_envelope_carries_code() {
        let env = PeerEnvelope::error(
            "a:1",
            PeerError {
                code: ErrorCode::AccessDenied,
                message: "peer is read-only".into(),
                data: None,
            },
        );
        let wire = serde_json::to_value(&env).unwrap();
        assert_eq!(wire["kind"], "error");
        assert_eq!(wire["error"]["code"], "access_denied");
    }
}