Skip to main content

session_core/
nudge.rs

1//! The root agent's research-loop brake and procedural-memory hint (`ultron/tool-round-nudge.ts`), as session-worker.ts
2//! wires them on `main`'s `turn_end`: after `ULTRON_TOOL_ROUNDS_NUDGE` consecutive tool rounds the root is steered to
3//! answer (again, more firmly, at twice that); while subagents or tasks it started run, busy rounds are steered to wait
4//! instead; after `ULTRON_SKILL_NUDGE` successful rounds it is told once to save the procedure as a code skill. The
5//! steers are queued as steering messages; nothing is ever aborted.
6
7use std::collections::{HashMap, HashSet};
8
9pub const SKILL_NUDGE_ENV: &str = "ULTRON_SKILL_NUDGE";
10pub const TOOL_ROUNDS_NUDGE_ENV: &str = "ULTRON_TOOL_ROUNDS_NUDGE";
11
12pub const DEFAULT_TOOL_ROUNDS_NUDGE: u64 = 10;
13pub const DEFAULT_WAIT_ROUNDS: u64 = 3;
14pub const DEFAULT_SKILL_NUDGE: u64 = 8;
15
16/// `nudgeThreshold`: unset or off is 0 (disabled), `on` is `enabled`, a whole number is itself.
17fn nudge_threshold(value: Option<&str>, enabled: u64) -> u64 {
18    let raw = value.map(|v| v.trim().to_lowercase()).unwrap_or_default();
19    if raw.is_empty() || ["off", "false", "no"].contains(&raw.as_str()) {
20        return 0;
21    }
22    if ["on", "true", "yes"].contains(&raw.as_str()) {
23        return enabled;
24    }
25    match raw.parse::<f64>() {
26        Ok(n) if n.is_finite() && n >= 0.0 && n.fract() == 0.0 => n as u64,
27        _ => 0,
28    }
29}
30
31/// `toolRoundsNudgeFromEnv` (`ULTRON_TOOL_ROUNDS_NUDGE`).
32pub fn tool_rounds_nudge_from_env(value: Option<&str>) -> u64 {
33    nudge_threshold(value, DEFAULT_TOOL_ROUNDS_NUDGE)
34}
35
36/// `skillNudgeFromEnv` (`ULTRON_SKILL_NUDGE`).
37pub fn skill_nudge_from_env(value: Option<&str>) -> u64 {
38    nudge_threshold(value, DEFAULT_SKILL_NUDGE)
39}
40
41pub fn nudge_message(rounds: u64, last: bool) -> String {
42    if last {
43        format!(
44            "[Ultron] You have now used {rounds} rounds of tool calls in this turn. Stop calling tools and write your answer now from what you already have. List anything still unknown instead of searching further."
45        )
46    } else {
47        format!(
48            "[Ultron] You have used {rounds} rounds of tool calls in this turn without answering. Unless one more specific call is essential, stop gathering and answer now with what you have, noting what remains unknown."
49        )
50    }
51}
52
53/// `waitNudgeMessage`. Woken (`async_events` without `next_call`), the root's `rlm.collect` never waits
54/// (crate::wake): it is told to end its turn; otherwise to await the results.
55pub fn wait_nudge_message(running: u64, async_events: bool, next_call: bool) -> String {
56    let what = if running == 1 {
57        "1 subagent or task you started is".to_string()
58    } else {
59        format!("{running} subagents or tasks you started are")
60    };
61    if async_events && next_call {
62        return format!(
63            "[Ultron] {what} still running; each end is reported as a `child_done` (or `task_done`) event at the top of a later rlm result. Do only separate work of your own and do not check on them through their files, logs or progress. If nothing of your own is left, wait for free: `await rlm.collect(handles)` (nothing wakes you after you reply)."
64        );
65    }
66    if async_events {
67        format!(
68            "[Ultron] {what} still running; each result comes to you as a `child_done` (or `task_done`) event. Do only separate work of your own and do not check on them through their files, logs or progress. If nothing of your own is left, end your turn: the events wake you, and `await rlm.collect(handles)` then returns the results (it does not wait while they run)."
69        )
70    } else {
71        format!(
72            "[Ultron] {what} still running. Do only separate work of your own and do not check on them through their files, logs or progress. If nothing of your own is left, wait for free with `await rlm.collect(handles)` (or `await agents.result(id)`)."
73        )
74    }
75}
76
77pub fn skill_nudge_message(rounds: u64) -> String {
78    format!(
79        "[Ultron] {rounds} tool rounds in a row succeeded. If this procedure will recur, once it works save it as a tested skill with `await skills.propose_code(name, source, test_source, evidence)`; otherwise carry on."
80    )
81}
82
83#[derive(Default)]
84struct RunRounds {
85    rounds: u64,
86    waiting: u64,
87    was_running: bool,
88    wait_nudged: bool,
89}
90
91/// `ToolRoundNudger`: [`ToolRoundNudger::turn_ended`] answers the steer to send, if any.
92pub struct ToolRoundNudger {
93    threshold: u64,
94    async_events: bool,
95    wait_rounds: u64,
96    next_call: bool,
97    runs: HashMap<String, RunRounds>,
98}
99
100impl ToolRoundNudger {
101    pub fn new(threshold: u64, async_events: bool) -> ToolRoundNudger {
102        ToolRoundNudger {
103            threshold,
104            async_events,
105            wait_rounds: DEFAULT_WAIT_ROUNDS,
106            next_call: false,
107            runs: HashMap::new(),
108        }
109    }
110
111    /// `nextCall: true`: the wait steer says events arrive at the top of a later rlm result (an external root, whose
112    /// runs nothing can start).
113    pub fn with_next_call(mut self) -> ToolRoundNudger {
114        self.next_call = true;
115        self
116    }
117
118    /// [`ToolRoundNudger::with_next_call`] on or off: off for an external root whose host wakes it (`ultron claude`'s
119    /// asyncRewake waiter).
120    pub fn set_next_call(&mut self, on: bool) {
121        self.next_call = on;
122    }
123
124    /// One model turn of `run` ended with `tool_calls` calls while `running` root-started subagents or tasks run.
125    pub fn turn_ended(&mut self, run: &str, tool_calls: usize, running: u64) -> Option<String> {
126        if self.threshold == 0 {
127            return None;
128        }
129        let state = self.runs.entry(run.to_string()).or_default();
130        // A turn that answers without tools ends the streak, and so does the end of the last running child.
131        state.rounds = if tool_calls == 0 {
132            0
133        } else if state.was_running && running == 0 {
134            1
135        } else {
136            state.rounds + 1
137        };
138        if running == 0 {
139            state.wait_nudged = false;
140        }
141        state.waiting = if running > 0 && tool_calls > 0 {
142            state.waiting + 1
143        } else {
144            0
145        };
146        state.was_running = running > 0;
147        let brake = state.rounds == self.threshold || state.rounds == self.threshold * 2;
148        let wait = running > 0 && !state.wait_nudged && self.wait_rounds > 0 && state.waiting >= self.wait_rounds;
149        if running > 0 && (brake || wait) {
150            state.wait_nudged = true;
151            return Some(wait_nudge_message(running, self.async_events, self.next_call));
152        }
153        brake.then(|| nudge_message(state.rounds, state.rounds == self.threshold * 2))
154    }
155
156    pub fn run_ended(&mut self, run: &str) {
157        self.runs.remove(run);
158    }
159}
160
161pub struct SkillExtractionNudger {
162    threshold: u64,
163    streaks: HashMap<String, u64>,
164    nudged: HashSet<String>,
165}
166
167impl SkillExtractionNudger {
168    pub fn new(threshold: u64) -> SkillExtractionNudger {
169        SkillExtractionNudger {
170            threshold,
171            streaks: HashMap::new(),
172            nudged: HashSet::new(),
173        }
174    }
175
176    /// `tool_calls` made in the turn, `failed` of whose results were errors; `running` root-started work still running.
177    pub fn turn_ended(&mut self, run: &str, tool_calls: usize, failed: usize, running: u64) -> Option<String> {
178        if self.threshold == 0 || self.nudged.contains(run) {
179            return None;
180        }
181        let streak = if tool_calls > 0 && failed == 0 && running == 0 {
182            self.streaks.get(run).copied().unwrap_or(0) + 1
183        } else {
184            0
185        };
186        self.streaks.insert(run.to_string(), streak);
187        if streak < self.threshold {
188            return None;
189        }
190        self.nudged.insert(run.to_string());
191        self.streaks.remove(run);
192        Some(skill_nudge_message(streak))
193    }
194
195    pub fn run_ended(&mut self, run: &str) {
196        self.streaks.remove(run);
197        self.nudged.remove(run);
198    }
199}