Skip to main content

ocp_types/
capability.rs

1//! Handshake and capability negotiation types
2//! (`docs/specs/stella-rust-cli/06-context-protocol.md` §3.2). `DataFlow` is
3//! the security-critical field: hosts surface it at install/consent time,
4//! and `egress: true` providers must never be auto-enabled (§3.5).
5
6use serde::{Deserialize, Serialize};
7
8/// Declares what a provider does with data, so a host can gate consent
9/// before ever sending it a query.
10#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)]
11pub struct DataFlow {
12    /// Can see workspace content via query payloads.
13    #[serde(default)]
14    pub reads: bool,
15    /// Persists `context/upsert` writes.
16    #[serde(default)]
17    pub writes: bool,
18    /// Sends anything off the local machine. A host MUST require explicit,
19    /// one-time consent before enabling a provider with `egress: true`.
20    #[serde(default)]
21    pub egress: bool,
22}
23
24/// Provider identity reported at `initialize`.
25#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
26pub struct ProviderInfo {
27    pub name: String,
28    pub version: String,
29    pub data_flow: DataFlow,
30}
31
32/// What a provider can do, negotiated at handshake time.
33#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
34pub struct Capabilities {
35    #[serde(default)]
36    pub query: QueryCapability,
37    #[serde(default)]
38    pub upsert: bool,
39    #[serde(default)]
40    pub graph: bool,
41    #[serde(default, skip_serializing_if = "Option::is_none")]
42    pub embeddings_fingerprint: Option<String>,
43    #[serde(default)]
44    pub subscribe: bool,
45}
46
47#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
48pub struct QueryCapability {
49    #[serde(default)]
50    pub kinds: Vec<String>,
51    #[serde(default)]
52    pub filters: Vec<String>,
53}
54
55#[cfg(test)]
56mod tests {
57    use super::*;
58
59    #[test]
60    fn egress_provider_data_flow_roundtrips() {
61        let flow = DataFlow {
62            reads: true,
63            writes: false,
64            egress: true,
65        };
66        let json = serde_json::to_string(&flow).unwrap();
67        let back: DataFlow = serde_json::from_str(&json).unwrap();
68        assert_eq!(back, flow);
69        assert!(
70            back.egress,
71            "egress providers must be inspectable by hosts before consent"
72        );
73    }
74
75    #[test]
76    fn provider_info_defaults_data_flow_to_no_egress() {
77        let flow = DataFlow::default();
78        assert!(
79            !flow.egress,
80            "default DataFlow must never imply egress consent"
81        );
82    }
83
84    #[test]
85    fn capabilities_roundtrip_with_defaults() {
86        let caps = Capabilities {
87            query: QueryCapability {
88                kinds: vec!["snippet".into()],
89                filters: vec![],
90            },
91            upsert: true,
92            graph: false,
93            embeddings_fingerprint: Some("bge-small-v1".into()),
94            subscribe: false,
95        };
96        let json = serde_json::to_string(&caps).unwrap();
97        let back: Capabilities = serde_json::from_str(&json).unwrap();
98        assert_eq!(back, caps);
99    }
100}