docs: add missing #[must_use], # Errors, # Panics across public api

hive-ag3nt/src/events.rs

@@ -222,6 +222,7 @@ pub struct TokenUsage {
 
 impl TokenUsage {
     /// Total context consumed this turn (input + cache reads + cache writes).
+    #[must_use]
     pub fn context_tokens(&self) -> u64 {
         self.input_tokens + self.cache_read_input_tokens + self.cache_creation_input_tokens
     }
@@ -230,6 +231,7 @@ impl TokenUsage {
     /// **cumulative** sum across every inference in the turn — useful as a
     /// cost signal, but NOT the current context size (a tool-heavy turn
     /// sums per-call cached prompts and easily exceeds the model window).
+    #[must_use]
     pub fn from_stream_event(v: &serde_json::Value) -> Option<Self> {
         if v.get("type").and_then(|t| t.as_str()) != Some("result") {
             return None;
@@ -241,6 +243,7 @@ impl TokenUsage {
     /// `.message.usage` block. Each turn fires one of these for every
     /// model call; tracking the LAST one over the turn gives the actual
     /// conversation context size — the number to watch for compaction.
+    #[must_use]
     pub fn from_assistant_event(v: &serde_json::Value) -> Option<Self> {
         if v.get("type").and_then(|t| t.as_str()) != Some("assistant") {
             return None;
@@ -443,12 +446,17 @@ impl Bus {
 
     /// Take + clear the one-shot. Returns true iff the caller should
     /// run claude without `--continue` for this turn.
+    #[must_use]
     pub fn take_skip_continue(&self) -> bool {
         self.skip_continue_once.swap(false, Ordering::SeqCst)
     }
 
     /// Currently-selected claude model name. Read on every turn so a
     /// `/model <name>` flip takes effect on the next turn.
+    ///
+    /// # Panics
+    ///
+    /// Panics if the internal lock is poisoned.
     #[must_use]
     pub fn model(&self) -> String {
         self.model.lock().unwrap().clone()
@@ -459,6 +467,10 @@ impl Bus {
     /// state dir (`hyperhive-model`) so the override survives harness
     /// restart and container rebuild (gone on `--purge`, matching
     /// every other piece of agent state).
+    ///
+    /// # Panics
+    ///
+    /// Panics if the internal lock is poisoned.
     pub fn set_model(&self, name: impl Into<String>) {
         let value: String = name.into();
         self.model.lock().unwrap().clone_from(&value);
@@ -472,6 +484,10 @@ impl Bus {
     /// emitting a SSE event. Used by the bin entrypoints to backfill
     /// from the most recent `turn_stats` row so the per-agent web UI's
     /// ctx + cost badges paint real numbers on cold load.
+    ///
+    /// # Panics
+    ///
+    /// Panics if an internal lock is poisoned.
     pub fn seed_usage(&self, ctx: Option<TokenUsage>, cost: Option<TokenUsage>) {
         if ctx.is_some() {
             *self.last_ctx_usage.lock().unwrap() = ctx;
@@ -485,6 +501,10 @@ impl Bus {
     /// usage (current context size); `cost` is the cumulative across
     /// every inference in the turn (cost signal). One SSE event fires
     /// per turn carrying both.
+    ///
+    /// # Panics
+    ///
+    /// Panics if an internal lock is poisoned.
     pub fn record_turn_usage(&self, ctx: TokenUsage, cost: TokenUsage) {
         *self.last_ctx_usage.lock().unwrap() = Some(ctx);
         *self.last_cost_usage.lock().unwrap() = Some(cost);
@@ -503,6 +523,10 @@ impl Bus {
     /// per-turn counter for each one we find. Called by the stdout
     /// pump on every parsed line. Cheap when the line isn't an
     /// assistant message — the field-check short-circuits.
+    ///
+    /// # Panics
+    ///
+    /// Panics if the internal lock is poisoned.
     pub fn observe_stream(&self, v: &serde_json::Value) {
         if v.get("type").and_then(|t| t.as_str()) != Some("assistant") {
             return;
@@ -531,6 +555,10 @@ impl Bus {
     /// Snapshot + clear the per-turn tool-call counter. The harness
     /// calls this between turns to fold the breakdown into a
     /// `turn_stats` row, then start the next turn with an empty map.
+    ///
+    /// # Panics
+    ///
+    /// Panics if the internal lock is poisoned.
     #[must_use]
     pub fn take_tool_calls(&self) -> std::collections::HashMap<String, u64> {
         std::mem::take(&mut *self.tool_calls.lock().unwrap())
@@ -538,6 +566,10 @@ impl Bus {
 
     /// Last context-size snapshot (last inference of the most recent
     /// turn), or `None` if no turn has completed yet.
+    ///
+    /// # Panics
+    ///
+    /// Panics if the internal lock is poisoned.
     #[must_use]
     pub fn last_ctx_usage(&self) -> Option<TokenUsage> {
         *self.last_ctx_usage.lock().unwrap()
@@ -545,6 +577,10 @@ impl Bus {
 
     /// Last cumulative cost snapshot (sum across the most recent turn's
     /// inferences), or `None` if no turn has completed yet.
+    ///
+    /// # Panics
+    ///
+    /// Panics if the internal lock is poisoned.
     #[must_use]
     pub fn last_cost_usage(&self) -> Option<TokenUsage> {
         *self.last_cost_usage.lock().unwrap()
@@ -552,6 +588,10 @@ impl Bus {
 
     /// Update the harness's authoritative turn-loop state. Records
     /// the transition time so `state_snapshot` can return a since-age.
+    ///
+    /// # Panics
+    ///
+    /// Panics if the internal lock is poisoned.
     pub fn set_state(&self, next: TurnState) {
         let since;
         {
@@ -598,6 +638,10 @@ impl Bus {
     }
 
     /// Current state + since-when (unix seconds). Snapshot copy, no lock held.
+    ///
+    /// # Panics
+    ///
+    /// Panics if the internal lock is poisoned.
     #[must_use]
     pub fn state_snapshot(&self) -> (TurnState, i64) {
         *self.state.lock().unwrap()
@@ -617,6 +661,7 @@ impl Bus {
         let _ = self.tx.send(envelope);
     }
 
+    #[must_use]
     pub fn subscribe(&self) -> broadcast::Receiver<BusEvent> {
         self.tx.subscribe()
     }