1use std::collections::BTreeMap;
3
4use serde::{Deserialize, Serialize};
5use serde_json::{Value, json};
6
7pub const MAX_HARNESS_EVENTS: usize = 256;
8pub const MAX_OBSERVED_MODELS: usize = 32;
9type EventCounts = BTreeMap<HarnessEventKind, u64>;
10
11#[derive(Debug, Default, Clone, PartialEq, Eq, Serialize, Deserialize)]
13#[serde(deny_unknown_fields)]
14pub struct ObservationTotals {
15 pub event_counts: EventCounts,
16 pub models: BTreeMap<String, EventCounts>,
17 pub unattributed_event_counts: EventCounts,
18 pub omitted_model_event_counts: EventCounts,
19 pub models_truncated: bool,
20 pub discarded_inputs: u64,
21}
22
23impl ObservationTotals {
24 pub fn event_count(&self) -> u64 {
25 self.event_counts.values().sum()
26 }
27
28 pub fn observe(&mut self, event: &HarnessEvent) {
29 *self.event_counts.entry(event.kind).or_default() += 1;
30 let counts = if let Some(model) = &event.model {
31 if self.models.contains_key(model) || self.models.len() < MAX_OBSERVED_MODELS {
32 self.models.entry(model.clone()).or_default()
33 } else {
34 self.models_truncated = true;
35 &mut self.omitted_model_event_counts
36 }
37 } else {
38 &mut self.unattributed_event_counts
39 };
40 *counts.entry(event.kind).or_default() += 1;
41 if let Some(previous) = &event.previous_model {
42 if self.models.len() < MAX_OBSERVED_MODELS || self.models.contains_key(previous) {
43 self.models.entry(previous.clone()).or_default();
44 } else {
45 self.models_truncated = true;
46 }
47 }
48 }
49
50 pub fn validate(&self) -> Result<(), &'static str> {
51 const MAX_SAFE: u64 = 9_007_199_254_740_991;
52 if self.models.len() > MAX_OBSERVED_MODELS
53 || self.models.keys().any(|m| !valid_identifier(m))
54 || self.discarded_inputs > MAX_SAFE
55 {
56 return Err("invalid observation totals");
57 }
58 let mut attributed = self.unattributed_event_counts.clone();
59 for counts in self
60 .models
61 .values()
62 .chain(std::iter::once(&self.omitted_model_event_counts))
63 {
64 for (kind, count) in counts {
65 let sum = attributed.entry(*kind).or_default();
66 *sum = sum
67 .checked_add(*count)
68 .ok_or("observation count overflow")?;
69 }
70 }
71 let sum = self
72 .event_counts
73 .values()
74 .try_fold(0_u64, |n, v| n.checked_add(*v))
75 .ok_or("observation count overflow")?;
76 if sum > MAX_SAFE
77 || attributed != self.event_counts
78 || (!self.omitted_model_event_counts.is_empty() && !self.models_truncated)
79 {
80 return Err("inconsistent observation totals");
81 }
82 Ok(())
83 }
84}
85
86#[derive(Debug, Default, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
87#[serde(rename_all = "snake_case")]
88pub enum ObservationMode {
89 #[default]
90 Auto,
91 ClaudeHooks,
92 CodexHooks,
93 OpencodePlugin,
94 Off,
95}
96
97impl ObservationMode {
98 pub fn as_str(self) -> &'static str {
99 match self {
100 Self::Auto => "auto",
101 Self::ClaudeHooks => "claude_hooks",
102 Self::CodexHooks => "codex_hooks",
103 Self::OpencodePlugin => "opencode_plugin",
104 Self::Off => "off",
105 }
106 }
107}
108
109#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
110#[serde(rename_all = "snake_case")]
111pub enum ObservationStatus {
112 Unsupported,
113 Disabled,
114 Unavailable,
115 NoEvents,
116 Recorded,
117 Partial,
118}
119
120#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
121#[serde(rename_all = "snake_case")]
122pub enum ObservationSource {
123 ClaudeHooks,
124 CodexHooks,
125 OpencodePlugin,
126 Application,
128}
129
130#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize)]
131#[serde(rename_all = "snake_case")]
132pub enum HarnessEventKind {
133 SessionStarted,
134 SessionEnded,
135 TurnStarted,
136 TurnCompleted,
137 TurnFailed,
138 TurnInterrupted,
139 ToolCompleted,
141 ToolSucceeded,
142 ToolFailed,
143 TaskReportedComplete,
144 ModelChanged,
145 ModelObserved,
147 SubagentStarted,
148 SubagentStopped,
149}
150
151#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
152#[serde(deny_unknown_fields)]
153pub struct HarnessEvent {
154 pub kind: HarnessEventKind,
155 pub recorded_at_ms: u64,
156 #[serde(default, skip_serializing_if = "Option::is_none")]
157 pub session_id: Option<String>,
158 #[serde(default, skip_serializing_if = "Option::is_none")]
159 pub agent_id: Option<String>,
160 #[serde(default, skip_serializing_if = "Option::is_none")]
162 pub model: Option<String>,
163 #[serde(default, skip_serializing_if = "Option::is_none")]
164 pub previous_model: Option<String>,
165 #[serde(default, skip_serializing_if = "Option::is_none")]
166 pub tool_name: Option<String>,
167}
168
169impl HarnessEvent {
170 pub fn validate(&self) -> Result<(), &'static str> {
171 for value in [
172 &self.session_id,
173 &self.agent_id,
174 &self.model,
175 &self.previous_model,
176 &self.tool_name,
177 ]
178 .into_iter()
179 .flatten()
180 {
181 if !valid_identifier(value) {
182 return Err("invalid harness event identifier (value redacted)");
183 }
184 }
185 Ok(())
186 }
187}
188
189pub fn valid_identifier(value: &str) -> bool {
191 !value.is_empty()
192 && value.len() <= 256
193 && value
194 .bytes()
195 .all(|b| b.is_ascii_alphanumeric() || b"._:/@+-".contains(&b))
196}
197
198#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
199#[serde(try_from = "WireObservations")]
200pub struct HarnessObservations {
201 pub source: Option<ObservationSource>,
202 pub status: ObservationStatus,
203 pub events: Vec<HarnessEvent>,
204 #[serde(default, skip_serializing_if = "Option::is_none")]
205 pub totals: Option<ObservationTotals>,
206}
207
208#[derive(Deserialize)]
209struct WireObservations {
210 source: Option<ObservationSource>,
211 status: ObservationStatus,
212 events: Vec<HarnessEvent>,
213 #[serde(default)]
214 totals: Option<ObservationTotals>,
215}
216
217impl TryFrom<WireObservations> for HarnessObservations {
218 type Error = &'static str;
219 fn try_from(wire: WireObservations) -> Result<Self, Self::Error> {
220 if wire.events.len() > MAX_HARNESS_EVENTS {
221 return Err("too many harness events");
222 }
223 if (!wire.events.is_empty()
224 && (wire.source.is_none()
225 || !matches!(
226 wire.status,
227 ObservationStatus::Recorded | ObservationStatus::Partial
228 )))
229 || (wire.status == ObservationStatus::Recorded && wire.events.is_empty())
230 {
231 return Err("inconsistent harness observation status");
232 }
233 for event in &wire.events {
234 event.validate()?;
235 }
236 if let Some(totals) = &wire.totals {
237 totals.validate()?;
238 if totals.event_count() < wire.events.len() as u64
239 || (totals.event_count() > 0 && wire.events.is_empty())
240 || (totals.discarded_inputs > 0 && wire.status != ObservationStatus::Partial)
241 {
242 return Err("inconsistent observation sample");
243 }
244 let mut sample = ObservationTotals::default();
245 for event in &wire.events {
246 sample.observe(event);
247 }
248 if sample.event_counts.iter().any(|(kind, count)| {
249 *count > totals.event_counts.get(kind).copied().unwrap_or_default()
250 }) {
251 return Err("sample exceeds observation totals");
252 }
253 }
254 Ok(Self {
255 source: wire.source,
256 status: wire.status,
257 events: wire.events,
258 totals: wire.totals,
259 })
260 }
261}
262
263impl HarnessObservations {
264 pub fn event_count(&self) -> u64 {
265 self.totals
266 .as_ref()
267 .map_or(self.events.len() as u64, ObservationTotals::event_count)
268 }
269
270 pub fn counts(&self) -> ObservationTotals {
271 self.totals.clone().unwrap_or_else(|| {
272 let mut totals = ObservationTotals::default();
273 for event in &self.events {
274 totals.observe(event);
275 }
276 totals
277 })
278 }
279
280 pub fn observe(&mut self, event: HarnessEvent) {
281 let mut totals = self.counts();
282 totals.observe(&event);
283 if self.events.len() == MAX_HARNESS_EVENTS {
284 self.events.remove(0);
285 }
286 self.events.push(event);
287 self.totals = Some(totals);
288 if self.status != ObservationStatus::Partial {
289 self.status = ObservationStatus::Recorded;
290 }
291 }
292
293 pub fn routing_summary(&self) -> Value {
295 let mut changes = Vec::new();
296 for event in self.events.iter().rev() {
297 if event.kind == HarnessEventKind::ModelChanged && changes.len() < 16 {
298 changes.push(json!({"from": event.previous_model, "to": event.model}));
299 }
300 }
301 changes.reverse();
302 let totals = self.counts();
303 let summary_truncated = totals.models_truncated
304 || self.event_count() > self.events.len() as u64
305 || self
306 .events
307 .iter()
308 .filter(|e| e.kind == HarnessEventKind::ModelChanged)
309 .count()
310 > 16;
311 json!({"source": self.source, "status": self.status, "event_counts": totals.event_counts,
312 "observed_models": totals.models.keys().collect::<Vec<_>>(),
313 "model_event_counts": totals.models, "unattributed_event_counts": totals.unattributed_event_counts,
314 "omitted_model_event_counts": totals.omitted_model_event_counts, "discarded_inputs": totals.discarded_inputs,
315 "total_events": self.event_count(), "sampled_events": self.events.len(),
316 "model_switches": changes,
317 "summary_truncated": summary_truncated})
318 }
319}
320
321#[cfg(test)]
322mod tests {
323 use super::*;
324 #[test]
325 fn whole_session_counts_survive_sampling_and_model_cardinality_limits() {
326 let mut observations = HarnessObservations {
327 source: Some(ObservationSource::ClaudeHooks),
328 status: ObservationStatus::NoEvents,
329 events: vec![],
330 totals: None,
331 };
332 for i in 0..1000 {
333 observations.observe(HarnessEvent {
334 kind: HarnessEventKind::ToolSucceeded,
335 recorded_at_ms: i,
336 session_id: None,
337 agent_id: None,
338 model: (i % 3 != 0).then(|| format!("model-{}", i % 40)),
339 previous_model: None,
340 tool_name: None,
341 });
342 }
343 assert_eq!(observations.event_count(), 1000);
344 assert_eq!(observations.events.len(), 256);
345 assert_eq!(observations.events[0].recorded_at_ms, 744);
346 let totals = observations.counts();
347 totals.validate().unwrap();
348 assert_eq!(totals.models.len(), MAX_OBSERVED_MODELS);
349 assert!(totals.models_truncated);
350 assert_eq!(
351 totals.unattributed_event_counts[&HarnessEventKind::ToolSucceeded],
352 334
353 );
354 assert!(!totals.omitted_model_event_counts.is_empty());
355 assert_eq!(
356 serde_json::from_value::<HarnessObservations>(
357 serde_json::to_value(&observations).unwrap()
358 )
359 .unwrap(),
360 observations
361 );
362 let mut invalid = serde_json::to_value(&observations).unwrap();
363 invalid["totals"]["event_counts"]["tool_succeeded"] = json!(999);
364 assert!(serde_json::from_value::<HarnessObservations>(invalid).is_err());
365 assert_eq!(observations.routing_summary()["total_events"], 1000);
366 assert_eq!(observations.routing_summary()["sampled_events"], 256);
367 }
368 #[test]
369 fn bounded_deserialization_rejects_free_text_without_echoing_it() {
370 let event =
371 json!({"kind": "model_changed", "recorded_at_ms": 1, "model": "private content\n"});
372 let wire = json!({"source": "claude_hooks", "status": "recorded", "events": [event]});
373 let error = serde_json::from_value::<HarnessObservations>(wire).unwrap_err();
374 assert!(!error.to_string().contains("private content"));
375 let event = json!({"kind": "turn_completed", "recorded_at_ms": 1});
376 assert!(serde_json::from_value::<HarnessObservations>(json!({"source": "claude_hooks", "status": "recorded", "events": vec![event; MAX_HARNESS_EVENTS + 1]})).is_err());
377 }
378}