1use serde::{Deserialize, Serialize};
8
9use wist_contracts::capability_report::{InvestigationCapabilities, LogsCapabilities};
10
11use super::{AgentLocalWork, AgentUplinkState, HostProfile};
12
13pub const API_VERSION: &str = wist_contracts::API_VERSION_V1;
15
16#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
17#[serde(rename_all = "snake_case")]
18pub enum AgentWorkState {
19 Paused,
20 Resumed,
21}
22
23#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
25#[serde(deny_unknown_fields)]
26pub struct AgentWorkStateChange {
27 pub input_id: String,
28 pub state: AgentWorkState,
29 pub reason: String,
30 pub at: String,
31}
32
33#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
34#[serde(deny_unknown_fields)]
35pub struct AgentStatusReport {
36 pub agent_id: String,
37 pub instance_id: String,
38 pub version: String,
39 #[serde(default)]
41 pub memory_bytes: Option<u64>,
42 #[serde(default)]
46 pub cpu_percent: Option<f64>,
47 #[serde(default)]
58 pub cpu_cores: Option<u32>,
59 #[serde(default)]
61 pub admin_latency_ms: Option<u64>,
62 #[serde(default)]
64 pub work_state_changes: Option<Vec<AgentWorkStateChange>>,
65 #[serde(default)]
71 pub discovery_policy_version: Option<i64>,
72 #[serde(default)]
79 pub local_work: Option<AgentLocalWork>,
80 #[serde(default)]
89 pub uplink_state: Option<AgentUplinkState>,
90 #[serde(default)]
98 pub certificate_status: Option<AgentCertificateStatus>,
99 #[serde(default)]
107 pub machine_profile: Option<HostProfile>,
108 #[serde(default)]
118 pub logs_capabilities: Option<LogsCapabilities>,
119 #[serde(default)]
128 pub investigation_capabilities: Option<InvestigationCapabilities>,
129 #[serde(default, skip_serializing_if = "Vec::is_empty")]
135 pub command_acks: Vec<AgentCommandAck>,
136}
137
138#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
140#[serde(deny_unknown_fields)]
141pub struct AgentCertificateStatus {
142 pub not_after: String,
144 pub remaining_seconds: i64,
146 pub state: String,
148 #[serde(default)]
153 pub last_renewal: Option<AgentCredentialRenewal>,
154}
155
156#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
161#[serde(deny_unknown_fields)]
162pub struct AgentCredentialRenewal {
163 pub outcome: String,
165 pub checked_at: String,
167 pub detail: String,
169 pub not_after: String,
171}
172
173#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
175#[serde(deny_unknown_fields)]
176pub struct AgentStatusAck {
177 pub agent_id: String,
178 pub instance_id: String,
179 pub acknowledged_at: String,
180 #[serde(default, skip_serializing_if = "Vec::is_empty")]
186 pub commands: Vec<AgentCommand>,
187}
188
189#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
197#[serde(deny_unknown_fields)]
198pub struct AgentCommand {
199 pub command_id: String,
200 pub requested_at_ms: i64,
202 pub kind: String,
205 #[serde(default, skip_serializing_if = "String::is_empty")]
207 pub params: String,
208}
209
210#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
212#[serde(deny_unknown_fields)]
213pub struct AgentCommandAck {
214 pub command_id: String,
215 pub outcome: String,
217 #[serde(default, skip_serializing_if = "String::is_empty")]
219 pub detail: String,
220}
221
222pub mod command_kind {
224 pub const REFRESH_FACTS: &str = "refresh_facts";
226 pub const INVESTIGATE: &str = "investigate";
231}
232
233pub mod command_outcome {
235 pub const SUCCEEDED: &str = "succeeded";
237 pub const FAILED: &str = "failed";
239 pub const NO_UPLINK: &str = "no_uplink";
241 pub const THROTTLED: &str = "throttled";
243 pub const STALE: &str = "stale";
245 pub const UNSUPPORTED: &str = "unsupported";
247 pub const SUPERSEDED: &str = "superseded";
249 pub const EXPIRED: &str = "expired";
251}
252
253#[cfg(test)]
254mod tests {
255 use super::{
256 AgentCertificateStatus, AgentCommandAck, AgentStatusAck, AgentStatusReport, AgentWorkState,
257 AgentWorkStateChange, command_outcome,
258 };
259
260 #[test]
261 fn agent_work_state_uses_snake_case_on_the_wire() {
262 assert_eq!(
263 serde_json::to_string(&AgentWorkState::Paused).unwrap(),
264 "\"paused\""
265 );
266 assert_eq!(
267 serde_json::to_string(&AgentWorkState::Resumed).unwrap(),
268 "\"resumed\""
269 );
270 let change = AgentWorkStateChange {
271 input_id: "app".to_string(),
272 state: AgentWorkState::Paused,
273 reason: "spool_over_limit".to_string(),
274 at: "2026-09-27T00:00:00Z".to_string(),
275 };
276 let json = serde_json::to_string(&change).expect("encode");
277 let back: AgentWorkStateChange = serde_json::from_str(&json).expect("decode");
278 assert_eq!(back, change);
279
280 let mutated = json.replacen('{', "{\"extra\":1,", 1);
282 assert!(serde_json::from_str::<AgentWorkStateChange>(&mutated).is_err());
283 }
284
285 #[test]
286 fn a_minimal_agent_status_report_decodes_and_extra_keys_fail() {
287 let json = r#"{"agent_id":"a","instance_id":"i","version":"0.1.5"}"#;
289 let report: AgentStatusReport = serde_json::from_str(json).expect("decode");
290 assert_eq!(report.memory_bytes, None);
291 assert_eq!(report.cpu_percent, None);
292 assert_eq!(report.work_state_changes, None);
293 assert_eq!(report.discovery_policy_version, None);
294 assert!(report.local_work.is_none());
295 assert!(report.uplink_state.is_none());
296 assert!(report.certificate_status.is_none());
297 assert!(report.machine_profile.is_none());
299 assert!(report.command_acks.is_empty());
301
302 assert!(
303 serde_json::from_str::<AgentStatusReport>(
304 r#"{"agent_id":"a","instance_id":"i","version":"v","nope":1}"#
305 )
306 .is_err()
307 );
308 }
309
310 #[test]
312 fn an_agent_status_report_carries_the_machine_profile() {
313 let json = r#"{
314 "agent_id":"a","instance_id":"i","version":"0.1.24",
315 "machine_profile":{
316 "node_id":"node-1","hostname":"host-1","os":"linux","arch":"x86_64",
317 "machine_id":"mid-1","cloud_instance_id":null,"k8s_node_uid":null,
318 "ip_addresses":["en0 192.168.1.5/24","10.8.0.2"]
319 }
320 }"#;
321 let report: AgentStatusReport = serde_json::from_str(json).expect("decode");
322 let profile = report.machine_profile.expect("machine_profile present");
323 assert_eq!(profile.hostname, "host-1");
324 assert_eq!(profile.node_id, "node-1");
325 assert_eq!(profile.machine_id, "mid-1");
326 assert_eq!(
327 profile.ip_addresses,
328 vec!["en0 192.168.1.5/24".to_string(), "10.8.0.2".to_string()]
329 );
330 }
331
332 #[test]
335 fn certificate_status_last_renewal_is_optional_and_round_trips() {
336 let legacy =
337 r#"{"not_after":"2026-11-04T00:00:00Z","remaining_seconds":100,"state":"valid"}"#;
338 let status: AgentCertificateStatus = serde_json::from_str(legacy).expect("decode");
339 assert!(status.last_renewal.is_none());
340
341 let json = r#"{"not_after":"2026-11-04T00:00:00Z","remaining_seconds":100,"state":"valid",
342 "last_renewal":{"outcome":"renewed","checked_at":"2026-10-08T00:00:00Z",
343 "detail":"credential renewed","not_after":"2026-11-04T00:00:00Z"}}"#;
344 let status: AgentCertificateStatus = serde_json::from_str(json).expect("decode");
345 assert_eq!(
346 status.last_renewal.as_ref().expect("renewal").outcome,
347 "renewed"
348 );
349
350 let encoded = serde_json::to_string(&status).expect("encode");
351 let back: AgentCertificateStatus = serde_json::from_str(&encoded).expect("decode");
352 assert_eq!(back, status);
353
354 let drifted = r#"{"not_after":"x","remaining_seconds":0,"state":"valid",
356 "last_renewal":{"outcome":"renewed","checked_at":"t","detail":"","not_after":"",
357 "extra":1}}"#;
358 assert!(serde_json::from_str::<AgentCertificateStatus>(drifted).is_err());
359 }
360
361 #[test]
363 fn logs_capabilities_are_optional_and_round_trip() {
364 let legacy = r#"{"agent_id":"a","instance_id":"i","version":"0.8.0"}"#;
365 let report: AgentStatusReport = serde_json::from_str(legacy).expect("decode");
366 assert!(report.logs_capabilities.is_none());
367
368 let json = r#"{"agent_id":"a","instance_id":"i","version":"0.9.0",
369 "logs_capabilities":{
370 "file_inputs":["absolute-path","glob"],
371 "multiline_modes":["none","indented"],
372 "exporters":["journalctl-kernel"]
373 }}"#;
374 let report: AgentStatusReport = serde_json::from_str(json).expect("decode");
375 let logs = report.logs_capabilities.expect("logs_capabilities");
376 assert_eq!(logs.exporters, vec!["journalctl-kernel".to_string()]);
377 assert!(logs.file_inputs.contains(&"glob".to_string()));
378
379 let drifted = r#"{"agent_id":"a","instance_id":"i","version":"v",
381 "logs_capabilities":{"file_inputs":[],"nope":1}}"#;
382 assert!(serde_json::from_str::<AgentStatusReport>(drifted).is_err());
383 }
384
385 #[test]
387 fn a_status_ack_carries_optional_commands() {
388 let legacy = r#"{"agent_id":"a","instance_id":"i","acknowledged_at":"t"}"#;
389 let ack: AgentStatusAck = serde_json::from_str(legacy).expect("decode");
390 assert!(ack.commands.is_empty());
391
392 let json = r#"{"agent_id":"a","instance_id":"i","acknowledged_at":"t",
393 "commands":[{"command_id":"c-1","requested_at_ms":1700000000000,
394 "kind":"refresh_facts"}]}"#;
395 let ack: AgentStatusAck = serde_json::from_str(json).expect("decode");
396 assert_eq!(ack.commands.len(), 1);
397 let command = &ack.commands[0];
398 assert_eq!(command.command_id, "c-1");
399 assert_eq!(command.requested_at_ms, 1_700_000_000_000);
400 assert_eq!(command.kind, "refresh_facts");
401 assert!(command.params.is_empty());
402
403 let encoded = serde_json::to_string(&AgentStatusAck {
405 agent_id: "a".to_string(),
406 instance_id: "i".to_string(),
407 acknowledged_at: "t".to_string(),
408 commands: Vec::new(),
409 })
410 .expect("encode");
411 assert!(!encoded.contains("commands"));
412
413 let drifted = r#"{"agent_id":"a","instance_id":"i","acknowledged_at":"t",
415 "commands":[{"command_id":"c-1","requested_at_ms":1,
416 "kind":"refresh_facts","nope":1}]}"#;
417 assert!(serde_json::from_str::<AgentStatusAck>(drifted).is_err());
418 }
419
420 #[test]
422 fn an_unknown_command_kind_still_decodes() {
423 let json = r#"{"agent_id":"a","instance_id":"i","acknowledged_at":"t",
424 "commands":[{"command_id":"c-9","requested_at_ms":1,"kind":"future_command"}]}"#;
425 let ack: AgentStatusAck = serde_json::from_str(json).expect("decode");
426 assert_eq!(ack.commands[0].kind, "future_command");
427 }
428
429 #[test]
431 fn an_agent_status_report_can_carry_command_results() {
432 let legacy = r#"{"agent_id":"a","instance_id":"i","version":"0.9.0"}"#;
433 let report: AgentStatusReport = serde_json::from_str(legacy).expect("decode");
434 assert!(report.command_acks.is_empty());
435
436 let json = r#"{"agent_id":"a","instance_id":"i","version":"0.9.11",
437 "command_acks":[{"command_id":"c-1","outcome":"succeeded",
438 "detail":"probes=6 failed=0"}]}"#;
439 let report: AgentStatusReport = serde_json::from_str(json).expect("decode");
440 assert_eq!(
441 report.command_acks,
442 vec![AgentCommandAck {
443 command_id: "c-1".to_string(),
444 outcome: command_outcome::SUCCEEDED.to_string(),
445 detail: "probes=6 failed=0".to_string(),
446 }]
447 );
448 }
449}