Skip to main content

cccc_sdk/
protocol.rs

1use serde::{Deserialize, Serialize};
2use serde_json::{Map, Value};
3
4use crate::DaemonError;
5
6/// Group-wide current awaiting Mail, evaluated at one observation time.
7#[derive(Clone, Debug, Deserialize)]
8pub struct InboxSummaryResult {
9    pub group_id: String,
10    pub observed_at: String,
11    pub cutoff: String,
12    pub actors: Vec<InboxSummaryActor>,
13}
14
15#[derive(Clone, Debug, Deserialize)]
16pub struct InboxSummaryActor {
17    pub actor_id: String,
18    pub awaiting_count: u64,
19    pub overdue_count: u64,
20    pub oldest_awaiting_at: Option<String>,
21    pub oldest_age_seconds: Option<u64>,
22}
23
24/// Daemon IPC v1 request envelope.
25#[derive(Clone, Debug, Serialize)]
26pub struct DaemonRequest<'a> {
27    pub v: u32,
28    pub op: &'a str,
29    pub args: &'a Map<String, Value>,
30}
31
32/// Daemon IPC v1 response envelope.
33#[derive(Clone, Debug, Deserialize)]
34pub struct DaemonResponse {
35    pub v: u32,
36    pub ok: bool,
37    #[serde(default)]
38    pub result: Map<String, Value>,
39    #[serde(default)]
40    pub error: Option<DaemonError>,
41}
42
43/// Stable fields returned by `ping`; unknown fields remain available through
44/// [`CCCCClient::call`](crate::CCCCClient::call).
45#[derive(Clone, Debug, Deserialize)]
46pub struct PingResult {
47    #[serde(default)]
48    pub version: String,
49    #[serde(default)]
50    pub pid: u64,
51    #[serde(default)]
52    pub ts: String,
53    #[serde(default)]
54    pub ipc_v: u32,
55    #[serde(default)]
56    pub capabilities: Map<String, Value>,
57    pub implementation: String,
58    #[serde(default)]
59    pub compatibility: Option<String>,
60}
61
62/// Delivery policy for a newly stored chat message.
63#[derive(Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
64#[serde(rename_all = "snake_case")]
65pub enum MessageMode {
66    Send,
67    RequestReply,
68    Mail,
69}
70
71/// Delivery policy for a reply. Replies cannot create another reply obligation.
72#[derive(Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
73#[serde(rename_all = "snake_case")]
74pub enum ReplyMessageMode {
75    Send,
76    Mail,
77}
78
79impl ReplyMessageMode {
80    pub const fn as_str(self) -> &'static str {
81        match self {
82            Self::Send => "send",
83            Self::Mail => "mail",
84        }
85    }
86}
87
88/// Projection requested from `context_get`.
89#[derive(Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
90#[serde(rename_all = "snake_case")]
91pub enum ContextDetail {
92    Overview,
93    Summary,
94    Full,
95}
96
97impl ContextDetail {
98    pub const fn as_str(self) -> &'static str {
99        match self {
100            Self::Overview => "overview",
101            Self::Summary => "summary",
102            Self::Full => "full",
103        }
104    }
105}
106
107/// Optional mode filter for non-consuming message history reads.
108#[derive(Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
109#[serde(rename_all = "snake_case")]
110pub enum MessageHistoryMode {
111    All,
112    Send,
113    RequestReply,
114    Mail,
115}
116
117impl MessageHistoryMode {
118    pub const fn as_str(self) -> &'static str {
119        match self {
120            Self::All => "all",
121            Self::Send => "send",
122            Self::RequestReply => "request_reply",
123            Self::Mail => "mail",
124        }
125    }
126}
127
128/// Filters for a non-consuming history read.
129#[derive(Clone, Debug, Default)]
130pub struct MessageHistoryOptions {
131    pub mode: Option<MessageHistoryMode>,
132    pub query: Option<String>,
133    /// Requires CCCC 0.4.50 or later; older daemons silently ignore this filter.
134    pub sender: Option<String>,
135    pub before_event_id: Option<String>,
136    pub limit: Option<u32>,
137}
138
139/// Team-review leads; counts do not measure a member's value.
140#[derive(Clone, Debug, Deserialize)]
141pub struct GroupActivityCounts {
142    pub messages_sent: u64,
143    pub messages_to_user: u64,
144    /// Scheduled ledger notices, not confirmed delivery or model turns.
145    pub scheduled_notices: u64,
146    pub last_message_at: String,
147}
148
149#[derive(Clone, Debug, Deserialize)]
150pub struct GroupActivityMember {
151    pub actor_id: String,
152    pub tasks_open: u64,
153    #[serde(flatten)]
154    pub counts: GroupActivityCounts,
155}
156
157#[derive(Clone, Debug, Deserialize)]
158pub struct GroupActivityResult {
159    pub days: u32,
160    pub since: String,
161    pub user: GroupActivityCounts,
162    pub members: Vec<GroupActivityMember>,
163}
164
165impl MessageMode {
166    pub const fn as_str(self) -> &'static str {
167        match self {
168            Self::Send => "send",
169            Self::RequestReply => "request_reply",
170            Self::Mail => "mail",
171        }
172    }
173}
174
175/// Optional arguments for `terminal_history`.
176#[derive(Clone, Debug, Default)]
177pub struct TerminalHistoryOptions {
178    pub render_before: Option<u64>,
179    pub before: Option<u64>,
180    pub limit_bytes: Option<u64>,
181    pub strip_ansi: Option<bool>,
182    pub compact: Option<bool>,
183    pub by: Option<String>,
184}
185
186/// Optional arguments for `terminal_since`.
187#[derive(Clone, Debug, Default)]
188pub struct TerminalSinceOptions {
189    pub limit_bytes: Option<u64>,
190    pub by: Option<String>,
191}
192
193/// Optional arguments for `terminal_snapshot`.
194#[derive(Clone, Debug, Default)]
195pub struct TerminalSnapshotOptions {
196    pub limit_bytes: Option<u64>,
197    pub by: Option<String>,
198}
199
200#[derive(Clone, Debug, Deserialize)]
201pub struct TerminalSnapshotResult {
202    pub data: String,
203    pub start_cursor: u64,
204    pub end_cursor: u64,
205}
206
207#[derive(Clone, Debug, Deserialize)]
208pub struct TerminalHistoryResult {
209    pub group_id: String,
210    pub actor_id: String,
211    pub warning: String,
212    pub hint: String,
213    pub text: String,
214    pub start_cursor: u64,
215    pub end_cursor: u64,
216    pub has_more: bool,
217    pub cursor_expired: bool,
218}
219
220#[derive(Clone, Debug, Deserialize)]
221pub struct TerminalSinceHistory {
222    pub data: String,
223    pub start_cursor: u64,
224    pub end_cursor: u64,
225    pub has_more: bool,
226    pub cursor_expired: bool,
227}
228
229#[derive(Clone, Debug, Deserialize)]
230pub struct TerminalSinceResult {
231    pub history: TerminalSinceHistory,
232}
233
234#[derive(Clone, Debug, Deserialize)]
235pub struct TerminalResizeResult {
236    pub group_id: String,
237    pub actor_id: String,
238    pub cols: u32,
239    pub rows: u32,
240}
241
242#[derive(Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
243#[serde(rename_all = "snake_case")]
244pub enum WebModelDeliveryMode {
245    Standard,
246    ImageCompat,
247}
248
249#[derive(Clone, Debug, Deserialize)]
250pub struct WebModelDeliveryPreference {
251    pub mode: WebModelDeliveryMode,
252    pub updated_at: String,
253    pub updated_by: String,
254}
255
256#[derive(Clone, Debug, Deserialize)]
257pub struct WebModelDeliveryPreferencesResult {
258    pub group_id: String,
259    pub actor_id: String,
260    pub preference: WebModelDeliveryPreference,
261}
262
263#[derive(Clone, Debug, Deserialize)]
264pub struct WebModelRecoveredTurnDelivery {
265    pub mode: String,
266    pub cursor_committed: bool,
267    pub web_model_mode: WebModelDeliveryMode,
268}
269
270#[derive(Clone, Debug, Deserialize)]
271pub struct WebModelRecoveredTurn {
272    pub turn_id: String,
273    pub group_id: String,
274    pub actor_id: String,
275    pub event_ids: Vec<String>,
276    pub latest_event_id: String,
277    pub latest_ts: String,
278    pub messages: Vec<Value>,
279    pub coalesced_text: String,
280    pub system_prompt: String,
281    pub delivery: WebModelRecoveredTurnDelivery,
282}
283
284#[derive(Clone, Debug, Deserialize)]
285pub struct WebModelRuntimeRecoverTurnResult {
286    pub status: String,
287    pub turn: WebModelRecoveredTurn,
288}