Skip to main content

byob_protocol/
usage.rs

1//! Context usage of a chat and its compactions.
2//!
3//! When a conversation nears the model's context window, the engine asks the model for a
4//! dense summary and continues from that summary plus the newest turns ("compaction"). The
5//! transcript keeps every message; clients show a divider where a compaction happened.
6
7use serde::{Deserialize, Serialize};
8
9/// One compaction of the chat in view.
10#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
11pub struct Compaction {
12    pub id: u64,
13    /// The summary stands in for every entry up to and including this one (0: it was made
14    /// before the chat's first entry finished). Clients draw the divider after it.
15    pub after_entry: u64,
16    /// Estimated tokens of the request before and after.
17    pub tokens_before: u64,
18    pub tokens_after: u64,
19    /// The summary the model wrote (markdown).
20    pub summary: String,
21    /// The user asked for it (`/compact`), rather than the context threshold.
22    #[serde(default)]
23    pub manual: bool,
24    /// What the user asked the summary to keep.
25    #[serde(default, skip_serializing_if = "Option::is_none")]
26    pub focus: Option<String>,
27    /// Milliseconds since the Unix epoch.
28    pub created_at: i64,
29}
30
31impl Compaction {
32    /// "Context compacted · 182k → 9k tokens".
33    pub fn label(&self) -> String {
34        format!("Context compacted · {} → {} tokens", short_tokens(self.tokens_before), short_tokens(self.tokens_after))
35    }
36}
37
38/// Token use of one chat, for the header meter.
39#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
40pub struct ChatUsage {
41    pub chat: String,
42    /// Tokens the conversation takes in the context now (the last request's prompt and reply
43    /// as the server counted them, or an estimate of the next request).
44    pub context_used: u64,
45    /// `context_used` is the engine's estimate, not the server's count.
46    #[serde(default)]
47    pub estimated: bool,
48    /// The context window in tokens (a default when the server doesn't say).
49    pub context_window: u64,
50    /// Requests bigger than this are compacted first (0: never automatically).
51    pub compact_at: u64,
52    /// Prompt and completion tokens of the most recent model request.
53    #[serde(default)]
54    pub last_prompt_tokens: u64,
55    #[serde(default)]
56    pub last_completion_tokens: u64,
57    /// Totals over the whole chat, as reported by the server.
58    #[serde(default)]
59    pub prompt_tokens: u64,
60    #[serde(default)]
61    pub completion_tokens: u64,
62    /// Model requests, tool rounds and compactions included.
63    #[serde(default)]
64    pub model_calls: u64,
65    #[serde(default)]
66    pub compactions: u64,
67    /// Time spent in replies and compactions.
68    #[serde(default)]
69    pub elapsed_ms: u64,
70    /// A compaction is running in this chat.
71    #[serde(default)]
72    pub compacting: bool,
73    /// Tokens subagents used (not in the chat's context; not in the totals above).
74    #[serde(default)]
75    pub agent_prompt_tokens: u64,
76    #[serde(default)]
77    pub agent_completion_tokens: u64,
78    /// Model requests subagents made.
79    #[serde(default)]
80    pub agent_calls: u64,
81}
82
83impl ChatUsage {
84    /// `context_used` as a fraction of the window, 0..=1.
85    pub fn fraction(&self) -> f32 {
86        ratio(self.context_used, self.context_window)
87    }
88
89    /// `context_used` as a fraction of the compaction threshold (1 = compacts next).
90    pub fn pressure(&self) -> f32 {
91        if self.compact_at == 0 { self.fraction() } else { ratio(self.context_used, self.compact_at) }
92    }
93
94    /// "34k / 262k".
95    pub fn label(&self) -> String {
96        format!("{}{} / {}", if self.estimated { "~" } else { "" }, short_tokens(self.context_used), short_tokens(self.context_window))
97    }
98
99    /// "main 34k · agents 120k" (tokens in and out), or `None` if no subagent ran.
100    pub fn split_label(&self) -> Option<String> {
101        let agents = self.agent_prompt_tokens.saturating_add(self.agent_completion_tokens);
102        if agents == 0 && self.agent_calls == 0 {
103            return None;
104        }
105        let main = self.prompt_tokens.saturating_add(self.completion_tokens);
106        Some(format!("main {} · agents {}", short_tokens(main), short_tokens(agents)))
107    }
108}
109
110#[allow(clippy::cast_precision_loss)] // display only
111fn ratio(a: u64, b: u64) -> f32 {
112    if b == 0 { 0.0 } else { (a as f64 / b as f64).clamp(0.0, 1.0) as f32 }
113}
114
115/// "950", "9.4k", "9k", "34k", "1.2M".
116pub fn short_tokens(n: u64) -> String {
117    #[allow(clippy::cast_precision_loss)] // display only
118    let f = n as f64;
119    match n {
120        0..1_000 => n.to_string(),
121        1_000..10_000 => format!("{:.1}k", f / 1_000.0).replace(".0k", "k"),
122        10_000..1_000_000 => format!("{}k", n / 1_000),
123        _ => format!("{:.1}M", f / 1_000_000.0),
124    }
125}
126
127#[cfg(test)]
128mod tests {
129    use super::*;
130
131    #[test]
132    fn labels_read_naturally() {
133        assert_eq!(short_tokens(950), "950");
134        assert_eq!(short_tokens(9_400), "9.4k");
135        assert_eq!(short_tokens(262_144), "262k");
136        assert_eq!(short_tokens(1_200_000), "1.2M");
137        let u = ChatUsage { context_used: 34_000, context_window: 262_144, compact_at: 200_000, ..Default::default() };
138        assert_eq!(u.label(), "34k / 262k");
139        assert!((u.pressure() - 0.17).abs() < 0.001);
140        assert_eq!(ChatUsage { estimated: true, ..u.clone() }.label(), "~34k / 262k");
141        assert_eq!(ChatUsage::default().fraction(), 0.0);
142        assert_eq!(u.split_label(), None);
143        let split = ChatUsage { prompt_tokens: 30_000, completion_tokens: 4_000, agent_prompt_tokens: 110_000, agent_completion_tokens: 10_000, ..u.clone() };
144        assert_eq!(split.split_label().as_deref(), Some("main 34k · agents 120k"));
145        let c = Compaction {
146            id: 1,
147            after_entry: 4,
148            tokens_before: 182_000,
149            tokens_after: 9_000,
150            summary: String::new(),
151            manual: false,
152            focus: None,
153            created_at: 0,
154        };
155        assert_eq!(c.label(), "Context compacted · 182k → 9k tokens");
156    }
157}