Skip to main content

jevia_core/
observations.rs

1//! Bounded, allowlisted harness facts. None of these events asserts task correctness.
2use 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/// Whole-session counters, independent of the bounded recent event sample.
12#[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    /// Caller-reported SDK facts, not independently observed native hooks.
127    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    /// A tool returned; its result does not establish success or failure.
140    ToolCompleted,
141    ToolSucceeded,
142    ToolFailed,
143    TaskReportedComplete,
144    ModelChanged,
145    /// The harness reported a model for a request, not proof of provider execution.
146    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    /// Only a model explicitly reported in this event, never the configured model.
161    #[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
189/// Identifiers only: never free text, tool arguments, transcript paths, or output.
190pub 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    /// Routing gets bounded aggregates, not local session identifiers or an event transcript.
294    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}