Skip to main content

session_core/
auto_refine.rs

1//! Automatic instruction refinements (Rust-only): the session learns from its own compaction summaries, with
2//! evidence it cannot invent.
3//!
4//! - Propose: after a completed compaction, in the background, one side request with the new summary, the active
5//!   refinements and the recent ledger history asks for at most [`MAX_PROPOSALS`] small instructions. [`plan`] keeps
6//!   only proposals whose `quote` is a verbatim substring of the summary (no invented failures); each kept one is
7//!   proposed and activated in the session's refinements ledger (kind `instruction`, target `instruction:main.r<n>`,
8//!   branch-anchored, checked by the ledger's own validator), and listed rollbacks of active ones are rolled back.
9//!   At most one pass per [`COOLDOWN`]; every failure is silent.
10//! - Deliver: before a root run of a user message, when the active `instruction:main.*` refinements differ from what
11//!   the context shows since its last compaction, the run opens with one `ultron.refinements` custom message listing
12//!   them (on the branch, like recalled memory, so the prompt cache holds). The summarizer never sees it (compaction
13//!   `convert_for_summary`).
14//! - Both run only while the `refine.auto` setting is on (default on) and `ULTRON_AUTO_REFINE` is not `off` (tests
15//!   that count requests turn it off); off, the session runs the unmodified harness.
16
17use 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;
23/// Targets of main-lane refinements: `instruction:main.r<n>` (the ledger keeps one active record per target).
24const TARGET_PREFIX: &str = "instruction:main.";
25/// The least time between two proposal passes.
26pub const COOLDOWN: Duration = Duration::from_secs(20 * 60);
27/// The most proposals one pass keeps.
28pub const MAX_PROPOSALS: usize = 3;
29/// The longest refinement text, in bytes.
30pub const MAX_TEXT: usize = 1024;
31/// The shortest quote accepted as evidence: a word or two of the summary proves nothing.
32const MIN_QUOTE_CHARS: usize = 16;
33/// The most refinements one message lists.
34pub const MESSAGE_LIMIT: usize = 12;
35/// Ledger history the proposal request shows.
36const 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/// The session's refinements ledger and the branch its changes follow (compose builds it).
42#[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    /// Every main-lane instruction record on the branch, oldest first.
54    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    /// The active main-lane refinements on the current branch: `{id, version, text}`, oldest first.
68    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
81/// Whether automatic refinement is on for a session (`refine.auto`, default on), and when it last proposed.
82pub struct AutoRefine {
83    pub on: bool,
84    last_pass: Mutex<Option<Instant>>,
85}
86
87impl AutoRefine {
88    /// From the merged `settings` (`refine.auto`) and `ULTRON_AUTO_REFINE` (`off`, `0`, `false`: off).
89    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    /// Whether a proposal pass may start now (on, and past the cooldown); starting one restarts the cooldown.
98    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
108/// The refinement ids the context shows since its last compaction (`None`: no refinements message since).
109pub 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
115/// The message that tells the context which refinements are active, when that differs from what it `shown`.
116pub 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/// One proposed refinement, its quote already found verbatim in the summary.
153#[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/// What a proposal reply asks for.
162#[derive(Debug, Default, PartialEq)]
163pub struct Plan {
164    pub proposals: Vec<Proposal>,
165    pub rollback: Vec<String>,
166}
167
168/// The plan in a proposal `reply` (`{"proposals": [{text, quote, rationale, expectedOutcome}], "rollback": [ids]}`,
169/// fenced or not): at most [`MAX_PROPOSALS`], each with text of at most [`MAX_TEXT`] bytes and a quote that is a
170/// verbatim substring of `summary`; the rest are dropped. A reply that is not such JSON plans nothing.
171pub 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
234/// One proposal pass over the compaction `compaction_id`'s `summary`, in the background: `ask(system, prompt)` is
235/// the side request; its plan is applied to `ledger`. Failures are not reported.
236pub 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
251/// Rolls back the plan's active rollbacks, then proposes and activates its proposals (each under a new target).
252fn 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}