use serde_json::{Value, json};
use services::{Branch, BranchSource, LocalServices};
use std::sync::{Arc, Mutex, PoisonError};
use std::time::{Duration, Instant};
use protocol::custom_types::REFINEMENTS;
const TARGET_PREFIX: &str = "instruction:main.";
pub const COOLDOWN: Duration = Duration::from_secs(20 * 60);
pub const MAX_PROPOSALS: usize = 3;
pub const MAX_TEXT: usize = 1024;
const MIN_QUOTE_CHARS: usize = 16;
pub const MESSAGE_LIMIT: usize = 12;
const HISTORY_LIMIT: usize = 10;
const SYSTEM: &str = "You review a coding agent's compaction summary and propose small, durable instructions the agent \
should follow for the rest of this session. Answer with JSON only.";
#[derive(Clone)]
pub struct Ledger {
pub services: Arc<LocalServices>,
pub branch: Option<BranchSource>,
}
impl Ledger {
fn branch(&self) -> Option<Branch> {
self.branch.as_ref().map(|source| source())
}
fn records(&self, branch: Option<&Branch>) -> Vec<Value> {
let listed = self.services.handle("refinements.list", &json!({}), branch);
let records = listed
.ok()
.and_then(|value| value.as_array().cloned())
.unwrap_or_default();
records
.into_iter()
.filter(|record| record["kind"] == "instruction")
.filter(|record| record["target"].as_str().is_some_and(|t| t.starts_with(TARGET_PREFIX)))
.collect()
}
pub fn active(&self) -> Vec<Value> {
active(&self.records(self.branch().as_ref()))
}
}
fn active(records: &[Value]) -> Vec<Value> {
records
.iter()
.filter(|record| record["state"] == "active")
.map(services::refinement_view)
.collect()
}
pub struct AutoRefine {
pub on: bool,
last_pass: Mutex<Option<Instant>>,
}
impl AutoRefine {
pub fn new(settings: &Value, env: Option<&str>) -> AutoRefine {
let env_off = crate::flag_off(env);
AutoRefine {
on: !env_off && settings["refine"]["auto"].as_bool().unwrap_or(true),
last_pass: Mutex::new(None),
}
}
pub fn start_pass(&self) -> bool {
let mut last = self.last_pass.lock().unwrap_or_else(PoisonError::into_inner);
if !self.on || last.is_some_and(|at| at.elapsed() < COOLDOWN) {
return false;
}
*last = Some(Instant::now());
true
}
}
pub fn shown(entries: &[Value]) -> Option<Vec<String>> {
let details = *session_journal::context::custom_details_since_compaction(entries, REFINEMENTS).last()?;
let ids = details["ids"].as_array().into_iter().flatten();
Some(ids.filter_map(|id| id.as_str().map(str::to_string)).collect())
}
pub fn message(active: &[Value], shown: Option<&[String]>, timestamp: u64) -> Option<Value> {
let active = &active[..active.len().min(MESSAGE_LIMIT)];
let ids: Vec<String> = active
.iter()
.filter_map(|r| r["id"].as_str().map(str::to_string))
.collect();
if ids.as_slice() == shown.unwrap_or_default() {
return None;
}
let mut content = if active.is_empty() {
"[refinements] No instruction refinements are active now; disregard the ones listed earlier.".to_string()
} else {
"[refinements] Instructions this session learned from its own compaction summaries, each backed by a quote \
from one. Follow them unless the user says otherwise; `refinements.rollback` with an id retires a wrong one."
.to_string()
};
for refinement in active {
let text = refinement["text"].as_str().unwrap_or_default();
let cut = text.char_indices().take_while(|(at, _)| *at < MAX_TEXT).map(|(_, c)| c);
content.push_str(&format!(
"\n- [{} v{}] {}",
refinement["id"].as_str().unwrap_or_default(),
refinement["version"],
cut.collect::<String>()
));
}
Some(json!({
"role": "custom",
"customType": REFINEMENTS,
"content": content,
"display": true,
"details": {"ids": ids},
"timestamp": timestamp,
}))
}
#[derive(Debug, PartialEq)]
pub struct Proposal {
pub text: String,
pub quote: String,
pub rationale: String,
pub expected_outcome: String,
}
#[derive(Debug, Default, PartialEq)]
pub struct Plan {
pub proposals: Vec<Proposal>,
pub rollback: Vec<String>,
}
pub fn plan(reply: &str, summary: &str) -> Plan {
let json = match (reply.find('{'), reply.rfind('}')) {
(Some(start), Some(end)) if start < end => &reply[start..=end],
_ => return Plan::default(),
};
let Ok(value) = serde_json::from_str::<Value>(json) else {
return Plan::default();
};
let field = |item: &Value, key: &str| {
item[key]
.as_str()
.map(str::trim)
.filter(|text| !text.is_empty())
.map(str::to_string)
};
let proposals = value["proposals"].as_array().into_iter().flatten().take(MAX_PROPOSALS);
Plan {
proposals: proposals
.filter_map(|item| {
let proposal = Proposal {
text: field(item, "text")?,
quote: item["quote"].as_str()?.to_string(),
rationale: field(item, "rationale")?,
expected_outcome: field(item, "expectedOutcome")?,
};
(proposal.text.len() <= MAX_TEXT
&& proposal.quote.trim().chars().count() >= MIN_QUOTE_CHARS
&& summary.contains(&proposal.quote))
.then_some(proposal)
})
.collect(),
rollback: value["rollback"]
.as_array()
.into_iter()
.flatten()
.filter_map(|id| id.as_str().map(str::to_string))
.collect(),
}
}
fn prompt(summary: &str, records: &[Value]) -> String {
let active = serde_json::to_string_pretty(&active(records)).unwrap_or_default();
let history: Vec<Value> = records[records.len().saturating_sub(HISTORY_LIMIT)..]
.iter()
.map(|r| {
let view = services::refinement_view(r);
json!({"id": view["id"], "state": r["state"], "text": view["text"]})
})
.collect();
let history = serde_json::to_string_pretty(&history).unwrap_or_default();
format!(
"<summary>\n{summary}\n</summary>\n\n<active-refinements>\n{active}\n</active-refinements>\n\n\
<refinement-history>\n{history}\n</refinement-history>\n\n\
Propose at most {MAX_PROPOSALS} short instructions (each under {MAX_TEXT} bytes) the agent should follow for \
the rest of this session. Prefer none over speculative ones: only repeated failures, user corrections or \
reusable tactics the summary shows. Each needs `quote`, an excerpt copied character for character from the \
summary that shows why; a proposal whose quote is not in the summary is discarded. Do not repeat an active \
refinement. List in `rollback` the ids of active refinements the summary shows to be wrong or harmful.\n\n\
Answer with JSON only: {{\"proposals\": [{{\"text\": \"...\", \"quote\": \"...\", \"rationale\": \"...\", \
\"expectedOutcome\": \"...\"}}], \"rollback\": []}}"
)
}
pub fn propose(
ledger: Ledger,
compaction_id: String,
summary: String,
ask: impl FnOnce(&str, &str) -> Result<String, String> + Send + 'static,
) {
std::thread::spawn(move || {
let records = ledger.records(ledger.branch().as_ref());
let Ok(reply) = ask(SYSTEM, &prompt(&summary, &records)) else {
return;
};
apply(&ledger, &plan(&reply, &summary), &compaction_id);
});
}
fn apply(ledger: &Ledger, plan: &Plan, compaction_id: &str) {
let branch = ledger.branch();
let records = ledger.records(branch.as_ref());
let current = active(&records);
for id in &plan.rollback {
if current.iter().any(|r| r["id"] == id.as_str()) {
let _ = ledger
.services
.handle("refinements.rollback", &json!({"id": id}), branch.as_ref());
}
}
let mut next = records.len();
for proposal in &plan.proposals {
if current.iter().any(|r| r["text"] == proposal.text.as_str()) {
continue;
}
next += 1;
let request = json!({
"kind": "instruction",
"target": format!("{TARGET_PREFIX}r{next}"),
"baseVersion": 0,
"content": proposal.text,
"evidence": [{
"ref": format!("compaction:{compaction_id}"),
"quote": proposal.quote,
"rationale": proposal.rationale,
"expectedOutcome": proposal.expected_outcome,
}],
"scope": "session",
});
if let Ok(record) = ledger.services.handle("refinements.propose", &request, branch.as_ref()) {
let _ = ledger
.services
.handle("refinements.activate", &json!({"id": record["id"]}), branch.as_ref());
}
}
}
#[cfg(test)]
mod tests {
use super::*;
const SUMMARY: &str =
"## Progress\nThe user corrected the agent twice: run tests with scripts/nextest.sh, not cargo test.";
fn reply(proposals: Value) -> String {
json!({"proposals": proposals, "rollback": ["r-old"]}).to_string()
}
fn proposal(text: &str, quote: &str) -> Value {
json!({"text": text, "quote": quote, "rationale": "user corrected it", "expectedOutcome": "no reruns"})
}
#[test]
fn auto_refine_plan_keeps_proposals_quoted_from_the_summary() {
let fenced = format!(
"```json\n{}\n```",
reply(json!([proposal(
"Run tests with scripts/nextest.sh.",
"run tests with scripts/nextest.sh"
)]))
);
assert_eq!(
plan(&fenced, SUMMARY),
Plan {
proposals: vec![Proposal {
text: "Run tests with scripts/nextest.sh.".into(),
quote: "run tests with scripts/nextest.sh".into(),
rationale: "user corrected it".into(),
expected_outcome: "no reruns".into(),
}],
rollback: vec!["r-old".into()],
}
);
}
#[test]
fn auto_refine_plan_drops_invented_quotes_oversized_text_and_extras() {
let quote = "run tests with scripts/nextest.sh";
let kept = plan(
&reply(json!([
proposal("Invented.", "the agent deleted the database twice"),
proposal("Paraphrased.", "run the tests with scripts/nextest.sh"),
proposal("Too short a quote.", "nextest"),
proposal(&"x".repeat(MAX_TEXT + 1), quote),
proposal("Fourth.", quote),
])),
SUMMARY,
);
assert_eq!(
kept.proposals,
Vec::new(),
"only the first three are read, and none of them holds"
);
let three = plan(
&reply(json!([
proposal("a", quote),
proposal("b", quote),
proposal("c", quote),
proposal("d", quote)
])),
SUMMARY,
);
assert_eq!(
three.proposals.iter().map(|p| p.text.as_str()).collect::<Vec<_>>(),
["a", "b", "c"]
);
}
#[test]
fn auto_refine_plan_of_a_malformed_reply_is_empty() {
for reply in ["", "no json here", "{\"proposals\": [", "[1, 2]", "{\"proposals\": 3}"] {
assert_eq!(plan(reply, SUMMARY), Plan::default(), "{reply}");
}
}
#[test]
fn auto_refine_message_follows_what_the_context_shows() {
let active = [json!({"id": "r1", "version": 1, "text": "Use nextest."})];
let message = message(&active, None, 7).unwrap();
assert!(message["content"].as_str().unwrap().contains("[r1 v1] Use nextest."));
let entries = [json!({"type": "message", "message": message})];
let shown = shown(&entries);
assert_eq!(shown.as_deref(), Some(&["r1".to_string()][..]));
assert!(super::message(&active, shown.as_deref(), 8).is_none(), "already shown");
let none = super::message(&[], shown.as_deref(), 9).unwrap();
assert!(
none["content"]
.as_str()
.unwrap()
.contains("No instruction refinements are active")
);
assert!(super::message(&[], None, 9).is_none(), "nothing to say");
let compacted = [entries[0].clone(), json!({"type": "compaction"})];
assert_eq!(super::shown(&compacted), None, "a compaction shows them again");
}
#[test]
fn auto_refine_follows_the_setting_and_cools_down() {
assert!(!AutoRefine::new(&json!({"refine": {"auto": false}}), None).start_pass());
assert!(!AutoRefine::new(&json!({}), Some("off")).on);
let auto = AutoRefine::new(&json!({}), Some("1"));
assert!(auto.on);
assert!(auto.start_pass());
assert!(!auto.start_pass(), "one pass per cooldown");
}
}