1use serde_json::{Value, json};
18use services::{Branch, BranchSource, LocalServices};
19use std::sync::{Arc, Mutex, PoisonError};
20use std::time::{Duration, Instant};
21
22use protocol::custom_types::REFINEMENTS;
23const TARGET_PREFIX: &str = "instruction:main.";
25pub const COOLDOWN: Duration = Duration::from_secs(20 * 60);
27pub const MAX_PROPOSALS: usize = 3;
29pub const MAX_TEXT: usize = 1024;
31const MIN_QUOTE_CHARS: usize = 16;
33pub const MESSAGE_LIMIT: usize = 12;
35const HISTORY_LIMIT: usize = 10;
37
38const SYSTEM: &str = "You review a coding agent's compaction summary and propose small, durable instructions the agent \
39should follow for the rest of this session. Answer with JSON only.";
40
41#[derive(Clone)]
43pub struct Ledger {
44 pub services: Arc<LocalServices>,
45 pub branch: Option<BranchSource>,
46}
47
48impl Ledger {
49 fn branch(&self) -> Option<Branch> {
50 self.branch.as_ref().map(|source| source())
51 }
52
53 fn records(&self, branch: Option<&Branch>) -> Vec<Value> {
55 let listed = self.services.handle("refinements.list", &json!({}), branch);
56 let records = listed
57 .ok()
58 .and_then(|value| value.as_array().cloned())
59 .unwrap_or_default();
60 records
61 .into_iter()
62 .filter(|record| record["kind"] == "instruction")
63 .filter(|record| record["target"].as_str().is_some_and(|t| t.starts_with(TARGET_PREFIX)))
64 .collect()
65 }
66
67 pub fn active(&self) -> Vec<Value> {
69 active(&self.records(self.branch().as_ref()))
70 }
71}
72
73fn active(records: &[Value]) -> Vec<Value> {
74 records
75 .iter()
76 .filter(|record| record["state"] == "active")
77 .map(services::refinement_view)
78 .collect()
79}
80
81pub struct AutoRefine {
83 pub on: bool,
84 last_pass: Mutex<Option<Instant>>,
85}
86
87impl AutoRefine {
88 pub fn new(settings: &Value, env: Option<&str>) -> AutoRefine {
90 let env_off = crate::flag_off(env);
91 AutoRefine {
92 on: !env_off && settings["refine"]["auto"].as_bool().unwrap_or(true),
93 last_pass: Mutex::new(None),
94 }
95 }
96
97 pub fn start_pass(&self) -> bool {
99 let mut last = self.last_pass.lock().unwrap_or_else(PoisonError::into_inner);
100 if !self.on || last.is_some_and(|at| at.elapsed() < COOLDOWN) {
101 return false;
102 }
103 *last = Some(Instant::now());
104 true
105 }
106}
107
108pub fn shown(entries: &[Value]) -> Option<Vec<String>> {
110 let details = *session_journal::context::custom_details_since_compaction(entries, REFINEMENTS).last()?;
111 let ids = details["ids"].as_array().into_iter().flatten();
112 Some(ids.filter_map(|id| id.as_str().map(str::to_string)).collect())
113}
114
115pub fn message(active: &[Value], shown: Option<&[String]>, timestamp: u64) -> Option<Value> {
117 let active = &active[..active.len().min(MESSAGE_LIMIT)];
118 let ids: Vec<String> = active
119 .iter()
120 .filter_map(|r| r["id"].as_str().map(str::to_string))
121 .collect();
122 if ids.as_slice() == shown.unwrap_or_default() {
123 return None;
124 }
125 let mut content = if active.is_empty() {
126 "[refinements] No instruction refinements are active now; disregard the ones listed earlier.".to_string()
127 } else {
128 "[refinements] Instructions this session learned from its own compaction summaries, each backed by a quote \
129 from one. Follow them unless the user says otherwise; `refinements.rollback` with an id retires a wrong one."
130 .to_string()
131 };
132 for refinement in active {
133 let text = refinement["text"].as_str().unwrap_or_default();
134 let cut = text.char_indices().take_while(|(at, _)| *at < MAX_TEXT).map(|(_, c)| c);
135 content.push_str(&format!(
136 "\n- [{} v{}] {}",
137 refinement["id"].as_str().unwrap_or_default(),
138 refinement["version"],
139 cut.collect::<String>()
140 ));
141 }
142 Some(json!({
143 "role": "custom",
144 "customType": REFINEMENTS,
145 "content": content,
146 "display": true,
147 "details": {"ids": ids},
148 "timestamp": timestamp,
149 }))
150}
151
152#[derive(Debug, PartialEq)]
154pub struct Proposal {
155 pub text: String,
156 pub quote: String,
157 pub rationale: String,
158 pub expected_outcome: String,
159}
160
161#[derive(Debug, Default, PartialEq)]
163pub struct Plan {
164 pub proposals: Vec<Proposal>,
165 pub rollback: Vec<String>,
166}
167
168pub fn plan(reply: &str, summary: &str) -> Plan {
172 let json = match (reply.find('{'), reply.rfind('}')) {
173 (Some(start), Some(end)) if start < end => &reply[start..=end],
174 _ => return Plan::default(),
175 };
176 let Ok(value) = serde_json::from_str::<Value>(json) else {
177 return Plan::default();
178 };
179 let field = |item: &Value, key: &str| {
180 item[key]
181 .as_str()
182 .map(str::trim)
183 .filter(|text| !text.is_empty())
184 .map(str::to_string)
185 };
186 let proposals = value["proposals"].as_array().into_iter().flatten().take(MAX_PROPOSALS);
187 Plan {
188 proposals: proposals
189 .filter_map(|item| {
190 let proposal = Proposal {
191 text: field(item, "text")?,
192 quote: item["quote"].as_str()?.to_string(),
193 rationale: field(item, "rationale")?,
194 expected_outcome: field(item, "expectedOutcome")?,
195 };
196 (proposal.text.len() <= MAX_TEXT
197 && proposal.quote.trim().chars().count() >= MIN_QUOTE_CHARS
198 && summary.contains(&proposal.quote))
199 .then_some(proposal)
200 })
201 .collect(),
202 rollback: value["rollback"]
203 .as_array()
204 .into_iter()
205 .flatten()
206 .filter_map(|id| id.as_str().map(str::to_string))
207 .collect(),
208 }
209}
210
211fn prompt(summary: &str, records: &[Value]) -> String {
212 let active = serde_json::to_string_pretty(&active(records)).unwrap_or_default();
213 let history: Vec<Value> = records[records.len().saturating_sub(HISTORY_LIMIT)..]
214 .iter()
215 .map(|r| {
216 let view = services::refinement_view(r);
217 json!({"id": view["id"], "state": r["state"], "text": view["text"]})
218 })
219 .collect();
220 let history = serde_json::to_string_pretty(&history).unwrap_or_default();
221 format!(
222 "<summary>\n{summary}\n</summary>\n\n<active-refinements>\n{active}\n</active-refinements>\n\n\
223 <refinement-history>\n{history}\n</refinement-history>\n\n\
224 Propose at most {MAX_PROPOSALS} short instructions (each under {MAX_TEXT} bytes) the agent should follow for \
225 the rest of this session. Prefer none over speculative ones: only repeated failures, user corrections or \
226 reusable tactics the summary shows. Each needs `quote`, an excerpt copied character for character from the \
227 summary that shows why; a proposal whose quote is not in the summary is discarded. Do not repeat an active \
228 refinement. List in `rollback` the ids of active refinements the summary shows to be wrong or harmful.\n\n\
229 Answer with JSON only: {{\"proposals\": [{{\"text\": \"...\", \"quote\": \"...\", \"rationale\": \"...\", \
230 \"expectedOutcome\": \"...\"}}], \"rollback\": []}}"
231 )
232}
233
234pub fn propose(
237 ledger: Ledger,
238 compaction_id: String,
239 summary: String,
240 ask: impl FnOnce(&str, &str) -> Result<String, String> + Send + 'static,
241) {
242 std::thread::spawn(move || {
243 let records = ledger.records(ledger.branch().as_ref());
244 let Ok(reply) = ask(SYSTEM, &prompt(&summary, &records)) else {
245 return;
246 };
247 apply(&ledger, &plan(&reply, &summary), &compaction_id);
248 });
249}
250
251fn apply(ledger: &Ledger, plan: &Plan, compaction_id: &str) {
253 let branch = ledger.branch();
254 let records = ledger.records(branch.as_ref());
255 let current = active(&records);
256 for id in &plan.rollback {
257 if current.iter().any(|r| r["id"] == id.as_str()) {
258 let _ = ledger
259 .services
260 .handle("refinements.rollback", &json!({"id": id}), branch.as_ref());
261 }
262 }
263 let mut next = records.len();
264 for proposal in &plan.proposals {
265 if current.iter().any(|r| r["text"] == proposal.text.as_str()) {
266 continue;
267 }
268 next += 1;
269 let request = json!({
270 "kind": "instruction",
271 "target": format!("{TARGET_PREFIX}r{next}"),
272 "baseVersion": 0,
273 "content": proposal.text,
274 "evidence": [{
275 "ref": format!("compaction:{compaction_id}"),
276 "quote": proposal.quote,
277 "rationale": proposal.rationale,
278 "expectedOutcome": proposal.expected_outcome,
279 }],
280 "scope": "session",
281 });
282 if let Ok(record) = ledger.services.handle("refinements.propose", &request, branch.as_ref()) {
283 let _ = ledger
284 .services
285 .handle("refinements.activate", &json!({"id": record["id"]}), branch.as_ref());
286 }
287 }
288}
289
290#[cfg(test)]
291mod tests {
292 use super::*;
293
294 const SUMMARY: &str =
295 "## Progress\nThe user corrected the agent twice: run tests with scripts/nextest.sh, not cargo test.";
296
297 fn reply(proposals: Value) -> String {
298 json!({"proposals": proposals, "rollback": ["r-old"]}).to_string()
299 }
300
301 fn proposal(text: &str, quote: &str) -> Value {
302 json!({"text": text, "quote": quote, "rationale": "user corrected it", "expectedOutcome": "no reruns"})
303 }
304
305 #[test]
306 fn auto_refine_plan_keeps_proposals_quoted_from_the_summary() {
307 let fenced = format!(
308 "```json\n{}\n```",
309 reply(json!([proposal(
310 "Run tests with scripts/nextest.sh.",
311 "run tests with scripts/nextest.sh"
312 )]))
313 );
314 assert_eq!(
315 plan(&fenced, SUMMARY),
316 Plan {
317 proposals: vec![Proposal {
318 text: "Run tests with scripts/nextest.sh.".into(),
319 quote: "run tests with scripts/nextest.sh".into(),
320 rationale: "user corrected it".into(),
321 expected_outcome: "no reruns".into(),
322 }],
323 rollback: vec!["r-old".into()],
324 }
325 );
326 }
327
328 #[test]
329 fn auto_refine_plan_drops_invented_quotes_oversized_text_and_extras() {
330 let quote = "run tests with scripts/nextest.sh";
331 let kept = plan(
332 &reply(json!([
333 proposal("Invented.", "the agent deleted the database twice"),
334 proposal("Paraphrased.", "run the tests with scripts/nextest.sh"),
335 proposal("Too short a quote.", "nextest"),
336 proposal(&"x".repeat(MAX_TEXT + 1), quote),
337 proposal("Fourth.", quote),
338 ])),
339 SUMMARY,
340 );
341 assert_eq!(
342 kept.proposals,
343 Vec::new(),
344 "only the first three are read, and none of them holds"
345 );
346 let three = plan(
347 &reply(json!([
348 proposal("a", quote),
349 proposal("b", quote),
350 proposal("c", quote),
351 proposal("d", quote)
352 ])),
353 SUMMARY,
354 );
355 assert_eq!(
356 three.proposals.iter().map(|p| p.text.as_str()).collect::<Vec<_>>(),
357 ["a", "b", "c"]
358 );
359 }
360
361 #[test]
362 fn auto_refine_plan_of_a_malformed_reply_is_empty() {
363 for reply in ["", "no json here", "{\"proposals\": [", "[1, 2]", "{\"proposals\": 3}"] {
364 assert_eq!(plan(reply, SUMMARY), Plan::default(), "{reply}");
365 }
366 }
367
368 #[test]
369 fn auto_refine_message_follows_what_the_context_shows() {
370 let active = [json!({"id": "r1", "version": 1, "text": "Use nextest."})];
371 let message = message(&active, None, 7).unwrap();
372 assert!(message["content"].as_str().unwrap().contains("[r1 v1] Use nextest."));
373 let entries = [json!({"type": "message", "message": message})];
374 let shown = shown(&entries);
375 assert_eq!(shown.as_deref(), Some(&["r1".to_string()][..]));
376 assert!(super::message(&active, shown.as_deref(), 8).is_none(), "already shown");
377 let none = super::message(&[], shown.as_deref(), 9).unwrap();
378 assert!(
379 none["content"]
380 .as_str()
381 .unwrap()
382 .contains("No instruction refinements are active")
383 );
384 assert!(super::message(&[], None, 9).is_none(), "nothing to say");
385 let compacted = [entries[0].clone(), json!({"type": "compaction"})];
386 assert_eq!(super::shown(&compacted), None, "a compaction shows them again");
387 }
388
389 #[test]
390 fn auto_refine_follows_the_setting_and_cools_down() {
391 assert!(!AutoRefine::new(&json!({"refine": {"auto": false}}), None).start_pass());
392 assert!(!AutoRefine::new(&json!({}), Some("off")).on);
393 let auto = AutoRefine::new(&json!({}), Some("1"));
394 assert!(auto.on);
395 assert!(auto.start_pass());
396 assert!(!auto.start_pass(), "one pass per cooldown");
397 }
398}