codewhale_runtime/model_context/
fragment.rs1use std::collections::hash_map::DefaultHasher;
11use std::hash::{Hash, Hasher};
12
13pub use codewhale_core::fragments::{
15 DEFAULT_FRAGMENT_MAX_BYTES, MAX_FRAGMENT_BYTES, MAX_FRAGMENT_TOKENS, MAX_FRAGMENTS_PER_CONTEXT,
16};
17
18#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
21pub enum FragmentId {
22 Workspace,
23 Permissions,
24 Route,
25 AgentTopology,
26 SkillsTools,
27 TokenBudget,
28 ProjectInstructions,
29 Constitution,
30}
31
32impl FragmentId {
33 #[must_use]
34 #[allow(dead_code)] pub fn as_str(self) -> &'static str {
36 match self {
37 Self::Workspace => "workspace",
38 Self::Permissions => "permissions",
39 Self::Route => "route",
40 Self::AgentTopology => "agent_topology",
41 Self::SkillsTools => "skills_tools",
42 Self::TokenBudget => "token_budget",
43 Self::ProjectInstructions => "project_instructions",
44 Self::Constitution => "constitution",
45 }
46 }
47
48 #[must_use]
50 pub fn marker(self) -> &'static str {
51 match self {
52 Self::Workspace => "<!-- cw:ctx:workspace -->",
53 Self::Permissions => "<!-- cw:ctx:permissions -->",
54 Self::Route => "<!-- cw:ctx:route -->",
55 Self::AgentTopology => "<!-- cw:ctx:agent_topology -->",
56 Self::SkillsTools => "<!-- cw:ctx:skills_tools -->",
57 Self::TokenBudget => "<!-- cw:ctx:token_budget -->",
58 Self::ProjectInstructions => "<!-- cw:ctx:project_instructions -->",
59 Self::Constitution => "<!-- cw:ctx:constitution -->",
60 }
61 }
62
63 #[must_use]
64 #[allow(dead_code)] pub fn role(self) -> FragmentRole {
66 match self {
67 Self::Workspace => FragmentRole::Workspace,
68 Self::Permissions => FragmentRole::Permissions,
69 Self::Route => FragmentRole::Route,
70 Self::AgentTopology => FragmentRole::AgentTopology,
71 Self::SkillsTools => FragmentRole::SkillsTools,
72 Self::TokenBudget => FragmentRole::TokenBudget,
73 Self::ProjectInstructions => FragmentRole::ProjectInstructions,
74 Self::Constitution => FragmentRole::Constitution,
75 }
76 }
77
78 #[must_use]
79 #[allow(dead_code)] pub fn all() -> &'static [FragmentId] {
81 &[
82 Self::Workspace,
83 Self::Permissions,
84 Self::Route,
85 Self::AgentTopology,
86 Self::SkillsTools,
87 Self::TokenBudget,
88 Self::ProjectInstructions,
89 Self::Constitution,
90 ]
91 }
92}
93
94#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
96pub enum FragmentRole {
97 Workspace,
99 Permissions,
101 Route,
103 AgentTopology,
105 SkillsTools,
107 TokenBudget,
109 ProjectInstructions,
111 Constitution,
113}
114
115impl FragmentRole {
116 #[must_use]
117 #[allow(dead_code)] pub fn as_str(self) -> &'static str {
119 match self {
120 Self::Workspace => "workspace",
121 Self::Permissions => "permissions",
122 Self::Route => "route",
123 Self::AgentTopology => "agent_topology",
124 Self::SkillsTools => "skills_tools",
125 Self::TokenBudget => "token_budget",
126 Self::ProjectInstructions => "project_instructions",
127 Self::Constitution => "constitution",
128 }
129 }
130}
131
132#[derive(Debug, Clone, PartialEq, Eq)]
134pub enum FragmentRender {
135 Unchanged { marker: String, content_hash: u64 },
137 Updated { fragment: ModelContextFragment },
139 #[allow(dead_code)] Cleared { marker: String },
142}
143
144#[derive(Debug, Clone, PartialEq, Eq)]
146pub struct ModelContextFragment {
147 pub id: FragmentId,
148 pub role: FragmentRole,
149 pub marker: &'static str,
150 pub max_bytes: usize,
151 pub content: String,
152 pub content_hash: u64,
153}
154
155impl ModelContextFragment {
156 #[must_use]
157 pub fn new(id: FragmentId, role: FragmentRole, raw: impl Into<String>) -> Self {
158 Self::with_max_bytes(id, role, raw, DEFAULT_FRAGMENT_MAX_BYTES)
159 }
160
161 #[must_use]
162 pub fn with_max_bytes(
163 id: FragmentId,
164 role: FragmentRole,
165 raw: impl Into<String>,
166 max_bytes: usize,
167 ) -> Self {
168 let clamped_max = max_bytes.min(MAX_FRAGMENT_BYTES);
170 let mut content = enforce_byte_cap(raw.into(), clamped_max);
171 if content.len().div_ceil(4) > MAX_FRAGMENT_TOKENS {
173 content = enforce_byte_cap(content, MAX_FRAGMENT_BYTES);
174 }
175 let content_hash = hash_content(&content);
176 Self {
177 id,
178 role,
179 marker: id.marker(),
180 max_bytes: clamped_max,
181 content,
182 content_hash,
183 }
184 }
185
186 #[must_use]
188 pub fn matches_text(&self, haystack: &str) -> bool {
189 haystack.contains(self.marker)
190 }
191
192 #[must_use]
194 pub fn render_diff(&self, previous: Option<&Self>) -> FragmentRender {
195 match previous {
196 Some(prev) if prev.content_hash == self.content_hash && prev.marker == self.marker => {
197 FragmentRender::Unchanged {
198 marker: self.marker.to_string(),
199 content_hash: self.content_hash,
200 }
201 }
202 _ => FragmentRender::Updated {
203 fragment: self.clone(),
204 },
205 }
206 }
207
208 #[must_use]
210 pub fn render_marked(&self) -> String {
211 let rendered = format!("{}\n{}", self.marker, self.content.trim_end());
212 debug_assert!(self.matches_text(&rendered));
213 rendered
214 }
215}
216
217fn hash_content(content: &str) -> u64 {
218 let mut hasher = DefaultHasher::new();
219 content.hash(&mut hasher);
220 hasher.finish()
221}
222
223fn enforce_byte_cap(raw: String, max_bytes: usize) -> String {
224 if max_bytes == 0 {
225 return String::new();
226 }
227 if raw.len() <= max_bytes {
228 return raw;
229 }
230 let omitted = raw.len().saturating_sub(max_bytes);
231 let marker = format!("\n[…truncated: {omitted} bytes omitted]");
232 if marker.len() >= max_bytes {
233 return marker.chars().take(max_bytes).collect();
234 }
235 let keep = max_bytes.saturating_sub(marker.len());
236 let mut end = keep;
238 while end > 0 && !raw.is_char_boundary(end) {
239 end -= 1;
240 }
241 let mut out = raw[..end].to_string();
242 out.push_str(&marker);
243 out
244}
245
246#[cfg(test)]
247mod tests {
248 use super::*;
249
250 #[test]
251 fn render_diff_detects_change_and_retain() {
252 let a = ModelContextFragment::new(FragmentId::Route, FragmentRole::Route, "m=a");
253 let b = ModelContextFragment::new(FragmentId::Route, FragmentRole::Route, "m=a");
254 let c = ModelContextFragment::new(FragmentId::Route, FragmentRole::Route, "m=b");
255 assert!(matches!(
256 b.render_diff(Some(&a)),
257 FragmentRender::Unchanged { .. }
258 ));
259 assert!(matches!(
260 c.render_diff(Some(&a)),
261 FragmentRender::Updated { .. }
262 ));
263 assert!(matches!(
264 a.render_diff(None),
265 FragmentRender::Updated { .. }
266 ));
267 }
268}