Skip to main content

kernel_apis/
goal.rs

1//! The session goal (`/goal`, port of `ultron/goal.ts` GoalDriver): a person sets one objective and a background job
2//! (its own REPL, under the usage root `goal:<id>`) works on it until the goal ends.
3//!
4//! - Only a person sets, edits, pauses, resumes or clears the goal ([`GoalDriver::command`], the worker's
5//!   `goal.command` request). The model reads it (`goal.get`), tests with the host's check (`goal.check`) and ends it
6//!   (`goal.complete`, `goal.blocked`), naming the revision it worked on.
7//! - `goal.complete` with a check command completes only if the host's own run of it exits 0; without one the
8//!   completion is recorded as unverified. `goal.blocked` needs BLOCK_MIN_CHECKS checks when there is a check command.
9//!   STUCK_CHECKS identical failing checks in a row pause the goal (and stop its job shortly after the reply).
10//! - A job that ends while the goal is active starts again only if its run changed the check result
11//!   ([`GoalDriver::task_ended`]); otherwise the goal pauses.
12//! - Durable (Rust): a goal's job is a task on the task journal, started with the idempotent key `<goal id>:<run>`.
13//!   When the worker reopens ([`GoalDriver::recover`]) the goal is reconciled with the journal through
14//!   [`GoalJobs::job_state`] and [`GoalJobs::job_with_key`]: a run admitted but not yet recorded is adopted, a job
15//!   still running is kept, a job the restart interrupted is followed by the next run (the goal stays active), and a
16//!   job that ended while no worker ran is settled as [`GoalDriver::task_ended`] would have. Checks, the stuck count
17//!   and progress are in the goal document, written with every change. A worker whose `GoalJobs` keeps no journal
18//!   (`job_state` is `None`) behaves as TypeScript: an active goal whose job was running loads as paused.
19//!
20//! The document `{version: 1, goal}` is the session value `ultron.module/goal`; a failed write is the error of the
21//! command, request or task end that made it. Each change of the goal is made under one lock, and the job calls it
22//! decides (start, stop) and a check's run are made with the lock released: stopping a job ends it on the calling
23//! thread and its end comes back through [`GoalDriver::task_ended`]. A start in flight is named by its run key; a
24//! job whose goal moved on meanwhile is stopped, and a job that ended before its start returned is settled then.
25
26use crate::store::read_versioned;
27use crate::util::Clock;
28use crate::{ApiModule, Request, TaskHost};
29use fancy_regex::Regex;
30use kernel::Signal;
31use kernel::store::DocumentStore;
32use serde_json::{Map, Value, json};
33use std::sync::{Arc, Mutex, OnceLock};
34use std::time::Duration;
35
36/// Failing checks in a row with the same result that pause the goal.
37pub const STUCK_CHECKS: i64 = 10;
38/// Checks needed before the model may declare the goal blocked (when there is a check command).
39pub const BLOCK_MIN_CHECKS: i64 = 3;
40/// A hanging check command is stopped after this long.
41pub const CHECK_TIMEOUT_SECONDS: u64 = 600;
42const CHECK_OUTPUT_CHARS: usize = 2000;
43const TEXT_MAX_CHARS: usize = 4000;
44const EVIDENCE_MAX: usize = 20;
45/// Usage root prefix of goal jobs (`GOAL_USAGE_ROOT_PREFIX` of usage.ts).
46pub const GOAL_USAGE_ROOT_PREFIX: &str = "goal:";
47
48#[derive(Debug, Clone, PartialEq, Eq)]
49pub struct GoalCheckResult {
50    pub exit_code: Option<i64>,
51    pub timed_out: bool,
52    pub output: String,
53}
54
55/// What the task journal says about a goal job.
56#[derive(Clone, Debug, PartialEq)]
57pub enum JobState {
58    /// Admitted and not ended (it runs under this worker).
59    Running,
60    /// Ended, with its durable result (`NativeResult`; `status: "interrupted"` when a restart cut it off).
61    Ended(Value),
62}
63
64/// The task host's error for work it stopped because it closed (`HOST_CLOSED` of native-host.ts).
65pub const HOST_CLOSED: &str = "Ultron task host closed";
66
67/// A job result that says the worker went away under the run (a restart interrupted it, or its host closed), not
68/// that the run itself ended.
69fn cut_off(result: &Value) -> bool {
70    result["status"] == "interrupted" || (result["status"] == "cancelled" && result["error"] == HOST_CLOSED)
71}
72
73/// What the driver needs from its worker: run the check in the session's working directory, start and stop the
74/// goal's background job, and name the lane a job runs on.
75pub trait GoalJobs: Send + Sync {
76    fn run_check(&self, command: &str, timeout_seconds: u64) -> Result<GoalCheckResult, String>;
77    /// Starts the goal's background job with `prompt`; returns its task id.
78    fn start_job(&self, prompt: &str, key: &str, usage_root: &str) -> Result<String, String>;
79    fn stop_job(&self, task_id: &str, reason: &str) -> Result<(), String>;
80    fn lane_of_job(&self, task_id: &str) -> Option<String>;
81    /// The journal's state of a job task; `None` when the worker keeps no task journal.
82    fn job_state(&self, _task_id: &str) -> Option<JobState> {
83        None
84    }
85    /// The task admitted with `key`, if any.
86    fn job_with_key(&self, _key: &str) -> Option<String> {
87        None
88    }
89}
90
91fn regexes() -> &'static [(Regex, &'static str); 3] {
92    static CELL: OnceLock<[(Regex, &'static str); 3]> = OnceLock::new();
93    CELL.get_or_init(|| {
94        [
95            (Regex::new(r"(?i)0x[0-9a-f]+").expect("regex"), "0x"),
96            (
97                Regex::new(r"(?<![A-Za-z0-9_])[0-9]+(?:\.[0-9]+)?\s?(?:ms|s|sec|secs|seconds)(?![A-Za-z0-9_])")
98                    .expect("regex"),
99                "<t>",
100            ),
101            (Regex::new(r"\s+").expect("regex"), " "),
102        ]
103    })
104}
105
106/// A check result's fingerprint: exit status and output, with durations and addresses left out.
107pub fn check_signature(result: &GoalCheckResult) -> String {
108    let mut output = jsrt::utf16::tail(&result.output, CHECK_OUTPUT_CHARS).to_string();
109    for (pattern, replacement) in regexes() {
110        output = pattern.replace_all(&output, *replacement).into_owned();
111    }
112    let status = if result.timed_out {
113        "timeout".to_string()
114    } else {
115        result.exit_code.map_or("null".to_string(), |code| code.to_string())
116    };
117    jsrt::hash::sha256_hex(format!("{status}\n{}", jsrt::string::trim(&output)).as_bytes())[..16].to_string()
118}
119
120fn text_of(goal: &Value, key: &str) -> String {
121    goal[key].as_str().unwrap_or_default().to_string()
122}
123
124fn int_of(goal: &Value, key: &str) -> i64 {
125    goal[key].as_i64().unwrap_or(0)
126}
127
128/// The brief of the goal's background job.
129pub fn goal_brief(goal: &Value) -> String {
130    let revision = &goal["revision"];
131    let check = match goal["check"].as_str() {
132        None => "There is no check command: when you call goal.complete, give concrete evidence (it is recorded as unverified).".to_string(),
133        Some(command) => format!(
134            "Check: `{command}`. `await goal.check()` runs it on the host and returns {{passed, exit_code, output}}; goal.complete runs it again and succeeds only if it exits 0."
135        ),
136    };
137    let mut parts = vec![
138        format!(
139            "You are working on the session goal (revision {revision}) on your own, as a background job: nobody is waiting on your turns, and nothing limits your time."
140        ),
141        format!("Objective: {}", text_of(goal, "objective")),
142        check,
143        "Work in your REPL: keep what you tried and learned in Python (`state['goal']`), change the code, test, and use the result to choose the next step. Delegate independent attempts with `rlm.spawn(brief, name=..., worktree=True)` and `await rlm.merge(...)` the one that works.".to_string(),
144        format!(
145            "Keep going until `await goal.complete({revision}, summary, evidence=[...])` succeeds. Only if something outside you blocks the goal after real attempts: `await goal.blocked({revision}, reason)`. Ten identical failing checks in a row pause the goal, so change your approach when a check keeps failing the same way. The user may change the goal: `await goal.get()` shows the current revision."
146        ),
147    ];
148    if let Some(answer) = goal["last_answer"].as_str() {
149        parts.push(format!("The previous run on this goal ended with: {answer}"));
150    }
151    parts.join("\n\n")
152}
153
154/// A short status for `/goal`.
155pub fn goal_status_text(goal: Option<&Value>) -> String {
156    let Some(goal) = goal else {
157        return "No goal. Set one with /goal <objective>.".into();
158    };
159    let reason = goal["reason"]
160        .as_str()
161        .filter(|r| !r.is_empty())
162        .map(|r| format!(": {r}"))
163        .unwrap_or_default();
164    let stuck = int_of(goal, "stuck");
165    let mut lines = vec![
166        format!(
167            "Goal (revision {}, {}{reason}): {}",
168            goal["revision"],
169            text_of(goal, "status"),
170            text_of(goal, "objective")
171        ),
172        format!(
173            "Check: {}. Runs: {}. Checks: {}{}.",
174            goal["check"].as_str().unwrap_or("none (completion is unverified)"),
175            goal["runs"],
176            goal["checks"],
177            if stuck > 1 {
178                format!(" ({stuck} identical failures in a row)")
179            } else {
180                String::new()
181            }
182        ),
183    ];
184    if let Some(job) = goal["job"].as_str() {
185        lines.push(format!("Job: {job} (running)."));
186    }
187    let last = &goal["last_check"];
188    if last.is_object() {
189        let outcome = if last["passed"] == true {
190            "passed".to_string()
191        } else if last["timed_out"] == true {
192            "timed out".to_string()
193        } else {
194            format!("exit {}", last["exit_code"])
195        };
196        lines.push(format!("Last check: {outcome} ({}).", text_of(last, "command")));
197    }
198    let completion = &goal["completion"];
199    if completion.is_object() {
200        lines.push(format!(
201            "Completed{}: {}",
202            if completion["verified"] == true {
203                " (check passed)"
204            } else {
205                " (unverified)"
206            },
207            text_of(completion, "summary")
208        ));
209    }
210    lines.join("\n")
211}
212
213fn public_goal(goal: &Value) -> Value {
214    let mut out = Map::new();
215    for key in [
216        "id",
217        "revision",
218        "objective",
219        "check",
220        "status",
221        "reason",
222        "runs",
223        "checks",
224        "stuck",
225        "last_check",
226        "completion",
227    ] {
228        out.insert(key.into(), goal[key].clone());
229    }
230    Value::Object(out)
231}
232
233fn text(value: Option<&Value>, name: &str) -> Result<String, String> {
234    match value.and_then(Value::as_str) {
235        Some(text) if !jsrt::string::trim(text).is_empty() => Ok(jsrt::utf16::head(text, TEXT_MAX_CHARS).to_string()),
236        _ => Err(format!("{name} must be a non-empty string")),
237    }
238}
239
240fn evidence_list(value: Option<&Value>) -> Result<Vec<Value>, String> {
241    let items = value.and_then(Value::as_array).filter(|items| !items.is_empty()).ok_or(
242        "evidence must be a non-empty list of strings: commands with their outcome (\"npm test: exit 0\") or files with lines",
243    )?;
244    if !items
245        .iter()
246        .all(|item| item.as_str().is_some_and(|text| !jsrt::string::trim(text).is_empty()))
247    {
248        return Err("every evidence item must be a non-empty string".into());
249    }
250    Ok(items
251        .iter()
252        .take(EVIDENCE_MAX)
253        .map(|item| Value::from(jsrt::utf16::head(item.as_str().unwrap_or_default(), TEXT_MAX_CHARS)))
254        .collect())
255}
256
257fn tail(output: &str) -> String {
258    if jsrt::utf16::len(output) > CHECK_OUTPUT_CHARS {
259        format!("…{}", jsrt::utf16::tail(output, CHECK_OUTPUT_CHARS - 1))
260    } else {
261        output.to_string()
262    }
263}
264
265/// A [`GoalJobs`] call decided under the driver's lock and made after it is released: stopping a running job ends it
266/// on the calling thread, and its end comes back through [`GoalDriver::task_ended`], which takes the lock.
267enum Effect {
268    Stop {
269        job: String,
270        reason: String,
271    },
272    Start {
273        key: String,
274        brief: String,
275        usage_root: String,
276    },
277}
278
279struct State {
280    goal: Option<Value>,
281    loaded: bool,
282    closed: bool,
283    /// Calls to make once the lock is released.
284    effects: Vec<Effect>,
285    /// Run keys (`<goal id>:<run>`) whose job is being started, outside the lock.
286    starting: Vec<String>,
287    /// Task ends that arrived while a start was in flight: one may be the job being started, which ended before its
288    /// id was recorded.
289    early_ends: Vec<(String, Option<Value>)>,
290}
291
292/// What `/goal` shows: a fixed text, or the goal's status (after the calls it made), with a note.
293enum Reply {
294    Text(String),
295    Status(&'static str),
296}
297
298/// A `goal.*` request that needs the check run: what it was decided against, re-checked once the run returns.
299struct PendingCheck {
300    id: String,
301    command: String,
302}
303
304fn run_key(goal: &Value) -> String {
305    format!("{}:{}", text_of(goal, "id"), goal["runs"])
306}
307
308/// Takes the goal's job and stops it after the lock is released.
309fn stop_job(goal: &mut Value, effects: &mut Vec<Effect>, reason: &str) {
310    if let Some(job) = goal["job"].as_str().map(str::to_string) {
311        effects.push(Effect::Stop {
312            job,
313            reason: reason.into(),
314        });
315    }
316    goal["job"] = Value::Null;
317}
318
319pub struct GoalDriver {
320    store: Arc<dyn DocumentStore>,
321    jobs: Arc<dyn GoalJobs>,
322    now: Clock,
323    state: Mutex<State>,
324}
325
326impl GoalDriver {
327    pub fn new(store: Arc<dyn DocumentStore>, jobs: Arc<dyn GoalJobs>, now: Clock) -> Self {
328        Self {
329            store,
330            jobs,
331            now,
332            state: Mutex::new(State {
333                goal: None,
334                loaded: false,
335                closed: false,
336                effects: Vec::new(),
337                starting: Vec::new(),
338                early_ends: Vec::new(),
339            }),
340        }
341    }
342
343    fn now(&self) -> i64 {
344        (self.now)()
345    }
346
347    /// Runs `step` on the loaded goal under the lock, then makes the [`GoalJobs`] calls it decided with the lock
348    /// released. A failed write of the document is the call's error, even when the step itself succeeded.
349    fn locked<R>(&self, step: impl FnOnce(&Self, &mut State) -> Result<R, String>) -> Result<R, String> {
350        let (result, effects) = {
351            let mut state = jsrt::sync::lock(&self.state);
352            let result = self.load(&mut state).and_then(|()| step(self, &mut state));
353            (result, std::mem::take(&mut state.effects))
354        };
355        let applied = self.apply(effects);
356        let result = result?;
357        applied.map(|()| result)
358    }
359
360    /// Makes the calls, then records what each start returned (which may decide more calls).
361    fn apply(&self, mut effects: Vec<Effect>) -> Result<(), String> {
362        let mut outcome = Ok(());
363        while !effects.is_empty() {
364            for effect in std::mem::take(&mut effects) {
365                match effect {
366                    Effect::Stop { job, reason } => {
367                        let _ = self.jobs.stop_job(&job, &reason);
368                    }
369                    Effect::Start { key, brief, usage_root } => {
370                        let started = self.jobs.start_job(&brief, &key, &usage_root);
371                        let mut state = jsrt::sync::lock(&self.state);
372                        let recorded = self.started(&mut state, &key, started);
373                        effects.extend(std::mem::take(&mut state.effects));
374                        outcome = outcome.and(recorded);
375                    }
376                }
377            }
378        }
379        outcome
380    }
381
382    /// A start returned: its job is the goal's when the goal still waits on that run, and is stopped otherwise (the
383    /// goal was paused, cleared or replaced while it started).
384    fn started(&self, state: &mut State, key: &str, started: Result<String, String>) -> Result<(), String> {
385        state.starting.retain(|starting| starting != key);
386        let mut early = if state.starting.is_empty() {
387            std::mem::take(&mut state.early_ends)
388        } else {
389            Vec::new()
390        };
391        let waiting = state
392            .goal
393            .as_ref()
394            .is_some_and(|goal| goal["status"] == "active" && goal["job"].is_null() && run_key(goal) == key);
395        let result = match started {
396            Ok(job) if !waiting => {
397                state.effects.push(Effect::Stop {
398                    job,
399                    reason: "goal changed".into(),
400                });
401                Ok(())
402            }
403            Ok(job) => {
404                state.goal.as_mut().expect("a goal")["job"] = job.as_str().into();
405                let persisted = self.persist(state);
406                let ended = early.iter().position(|(id, _)| *id == job).map(|at| early.remove(at));
407                match ended {
408                    Some((id, result)) => persisted.and(self.job_ended(state, &id, result.as_ref())),
409                    None => persisted,
410                }
411            }
412            Err(error) if waiting => {
413                let goal = state.goal.as_mut().expect("a goal");
414                goal["status"] = "paused".into();
415                goal["reason"] = format!("the goal job could not start: {error}").into();
416                self.persist(state)
417            }
418            Err(_) => Ok(()),
419        };
420        if !state.starting.is_empty() {
421            // Kept for the starts still in flight.
422            state.early_ends.extend(early);
423        }
424        result
425    }
426
427    fn load(&self, state: &mut State) -> Result<(), String> {
428        if state.loaded {
429            return Ok(());
430        }
431        state.loaded = true;
432        let saved = read_versioned("ultron.module/goal", self.store.read()?, "version")?;
433        let goal = saved.and_then(|saved| saved.get("goal").filter(|goal| goal.is_object()).cloned());
434        if state.goal.is_none() {
435            state.goal = goal;
436        }
437        self.reconcile(state)
438    }
439
440    /// Reconciles an active goal with the task journal after a reopen (see the module docs). The journal lookups
441    /// only read it and never call back into the driver, so they run under the lock.
442    fn reconcile(&self, state: &mut State) -> Result<(), String> {
443        let Some(goal) = state.goal.as_mut().filter(|goal| goal["status"] == "active") else {
444            return Ok(());
445        };
446        let mut changed = false;
447        if goal["job"].is_null() {
448            // An active goal without a job was starting a run when the worker died: the run is written before it is
449            // admitted, so its key names the task if the admission happened.
450            match self.jobs.job_with_key(&run_key(goal)) {
451                Some(task) => {
452                    goal["job"] = task.into();
453                    changed = true;
454                }
455                None => return self.start_job(state),
456            }
457        }
458        let Some(job) = goal["job"].as_str().map(str::to_string) else {
459            return Ok(());
460        };
461        match self.jobs.job_state(&job) {
462            Some(JobState::Running) if changed => self.persist(state),
463            Some(JobState::Running) => Ok(()),
464            Some(JobState::Ended(result)) if cut_off(&result) => {
465                // The worker going away cut the run off, not the job's own work: the goal goes on with its next run.
466                goal["job"] = Value::Null;
467                goal["last_answer"] = "The previous run was interrupted when Ultron restarted; continue from the goal's state and the files.".into();
468                self.start_job(state)
469            }
470            Some(JobState::Ended(result)) => self.job_ended(state, &job, Some(&result)),
471            None => {
472                // No journal: a job does not outlive the worker that ran it, so the goal pauses (TypeScript).
473                goal["job"] = Value::Null;
474                goal["status"] = "paused".into();
475                goal["reason"] = "Ultron restarted while the goal job ran; /goal resume continues".into();
476                Ok(())
477            }
478        }
479    }
480
481    /// Loads the goal and reconciles it with the task journal (the worker's open); returns it.
482    pub fn recover(&self) -> Result<Option<Value>, String> {
483        self.get()
484    }
485
486    /// Writes the document.
487    fn persist(&self, state: &State) -> Result<(), String> {
488        self.store
489            .write(&json!({"version": 1, "goal": state.goal}))
490            .map_err(|error| format!("the session goal could not be saved: {error}"))
491    }
492
493    /// The goal now (a copy), after the document loads.
494    pub fn get(&self) -> Result<Option<Value>, String> {
495        self.locked(|_, _| Ok(()))?;
496        Ok(jsrt::sync::lock(&self.state).goal.clone())
497    }
498
499    /// Stops starting jobs (shutdown).
500    pub fn close(&self) {
501        jsrt::sync::lock(&self.state).closed = true;
502    }
503
504    /// Writes the goal's next run, then has its job started once the lock is released.
505    fn start_job(&self, state: &mut State) -> Result<(), String> {
506        if state.closed {
507            return Ok(());
508        }
509        let now = self.now();
510        let goal = state.goal.as_mut().expect("a goal");
511        goal["runs"] = (int_of(goal, "runs") + 1).into();
512        goal["run_progress"] = false.into();
513        goal["updated_at"] = now.into();
514        goal["job"] = Value::Null;
515        let key = run_key(goal);
516        // The run is durable before its task is admitted, so a reopen finds the task by this key; a run that could
517        // not be written is not started.
518        if let Err(error) = self.persist(state) {
519            let goal = state.goal.as_mut().expect("a goal");
520            goal["status"] = "paused".into();
521            goal["reason"] = format!("{error}; /goal resume retries").into();
522            return Err(error);
523        }
524        let goal = state.goal.as_ref().expect("a goal");
525        let effect = Effect::Start {
526            key: key.clone(),
527            brief: goal_brief(goal),
528            usage_root: format!("{GOAL_USAGE_ROOT_PREFIX}{}", text_of(goal, "id")),
529        };
530        state.starting.push(key);
531        state.effects.push(effect);
532        Ok(())
533    }
534
535    fn set_status(&self, state: &mut State, status: &str, reason: Option<&str>) -> Result<(), String> {
536        let now = self.now();
537        let goal = state.goal.as_mut().expect("a goal");
538        goal["status"] = status.into();
539        goal["reason"] = reason.map_or(Value::Null, Value::from);
540        goal["updated_at"] = now.into();
541        self.persist(state)
542    }
543
544    /// `/goal [objective | pause | resume | clear | check [command] | status]`; returns the text to show.
545    pub fn command(&self, args: &str) -> Result<String, String> {
546        let text = jsrt::string::trim(args);
547        let reply = self.locked(|this, state| this.command_step(state, text))?;
548        Ok(match reply {
549            Reply::Text(text) => text,
550            Reply::Status(note) => goal_status_text(jsrt::sync::lock(&self.state).goal.as_ref()) + note,
551        })
552    }
553
554    fn command_step(&self, state: &mut State, text: &str) -> Result<Reply, String> {
555        if text.is_empty() || text == "status" {
556            return Ok(Reply::Status(""));
557        }
558        if text == "clear" {
559            let Some(goal) = state.goal.as_mut() else {
560                return Ok(Reply::Text("No goal to clear.".into()));
561            };
562            stop_job(goal, &mut state.effects, "goal cleared");
563            state.goal = None;
564            self.persist(state)?;
565            return Ok(Reply::Text("Goal cleared.".into()));
566        }
567        if text == "pause" {
568            match state.goal.as_mut() {
569                Some(goal) if goal["status"] == "active" => stop_job(goal, &mut state.effects, "goal paused"),
570                _ => return Ok(Reply::Status("")),
571            }
572            self.set_status(state, "paused", Some("paused by you; /goal resume continues"))?;
573            return Ok(Reply::Status(""));
574        }
575        if text == "resume" {
576            match state.goal.as_ref() {
577                Some(goal) if goal["status"] != "complete" && goal["status"] != "active" => {}
578                _ => return Ok(Reply::Status("")),
579            }
580            self.set_status(state, "active", None)?;
581            state.goal.as_mut().expect("a goal")["stuck"] = 0.into();
582            self.start_job(state)?;
583            return Ok(Reply::Status(""));
584        }
585        if text == "check" || text.starts_with("check ") {
586            let now = self.now();
587            let Some(goal) = state.goal.as_mut() else {
588                return Ok(Reply::Text("Set a goal first: /goal <objective>.".into()));
589            };
590            let command = jsrt::string::trim(&text["check".len()..]);
591            goal["check"] = if command.is_empty() {
592                Value::Null
593            } else {
594                jsrt::utf16::head(command, TEXT_MAX_CHARS).into()
595            };
596            goal["revision"] = (int_of(goal, "revision") + 1).into();
597            goal["stuck"] = 0.into();
598            goal["last_signature"] = Value::Null;
599            goal["updated_at"] = now.into();
600            self.persist(state)?;
601            return Ok(Reply::Status(""));
602        }
603        let mut revision = 1;
604        if let Some(goal) = state.goal.as_mut() {
605            stop_job(goal, &mut state.effects, "goal replaced");
606            revision = int_of(goal, "revision") + 1;
607        }
608        let now = self.now();
609        state.goal = Some(json!({
610            "id": format!("goal-{}", &jsrt::random::uuid_v4()[..8]),
611            "revision": revision,
612            "objective": jsrt::utf16::head(text, TEXT_MAX_CHARS),
613            "check": null,
614            "status": "active",
615            "reason": null,
616            "job": null,
617            "runs": 0,
618            "checks": 0,
619            "stuck": 0,
620            "last_signature": null,
621            "run_progress": false,
622            "last_check": null,
623            "last_answer": null,
624            "created_at": now,
625            "updated_at": now,
626            "completion": null,
627        }));
628        self.start_job(state)?;
629        Ok(Reply::Status(
630            "\nAdd the check that decides when it is done: /goal check <command>.",
631        ))
632    }
633
634    /// A task ended (the worker's task-end observer; `result` is its `NativeResult`): a goal job that ended early is
635    /// started again when its run made progress, otherwise the goal pauses.
636    pub fn task_ended(&self, task_id: &str, result: Option<&Value>) -> Result<(), String> {
637        self.locked(|this, state| this.job_ended(state, task_id, result))
638    }
639
640    fn job_ended(&self, state: &mut State, task_id: &str, result: Option<&Value>) -> Result<(), String> {
641        let now = self.now();
642        let Some(goal) = state.goal.as_mut() else {
643            return Ok(());
644        };
645        if state.closed {
646            return Ok(());
647        }
648        if goal["job"] != task_id {
649            if !state.starting.is_empty() {
650                state.early_ends.push((task_id.to_string(), result.cloned()));
651            }
652            return Ok(());
653        }
654        goal["job"] = Value::Null;
655        let answer = match result.map(|result| (&result["value"], result.get("error"))) {
656            Some((Value::String(value), _)) => value.clone(),
657            Some((_, Some(error))) if !error.is_null() => jsrt::value::string(Some(error)),
658            _ => String::new(),
659        };
660        goal["last_answer"] = if jsrt::utf16::len(&answer) > 1000 {
661            format!("{}…", jsrt::utf16::head(&answer, 999)).into()
662        } else if answer.is_empty() {
663            Value::Null
664        } else {
665            answer.into()
666        };
667        goal["updated_at"] = now.into();
668        if goal["status"] != "active" {
669            return self.persist(state);
670        }
671        if goal["run_progress"] == true {
672            return self.start_job(state);
673        }
674        self.set_status(
675            state,
676            "paused",
677            Some("the goal job ended without progress; /goal resume continues"),
678        )
679    }
680
681    /// Records a check's result on the goal it ran for.
682    fn record_check(&self, state: &mut State, command: String, result: GoalCheckResult) -> Result<Value, String> {
683        let goal = state.goal.as_mut().expect("a goal");
684        let passed = result.exit_code == Some(0) && !result.timed_out;
685        let signature = check_signature(&result);
686        let same = goal["last_signature"] == signature.as_str();
687        if !same {
688            goal["run_progress"] = true.into();
689        }
690        goal["stuck"] = (if passed {
691            0
692        } else if same {
693            int_of(goal, "stuck") + 1
694        } else {
695            1
696        })
697        .into();
698        goal["last_signature"] = signature.into();
699        goal["checks"] = (int_of(goal, "checks") + 1).into();
700        let now = self.now();
701        goal["last_check"] = json!({
702            "command": command,
703            "passed": passed,
704            "exit_code": result.exit_code,
705            "timed_out": result.timed_out,
706            "output": tail(&result.output),
707            "at": now,
708        });
709        goal["updated_at"] = now.into();
710        let run = goal["last_check"].clone();
711        self.persist(state)?;
712        Ok(run)
713    }
714
715    /// The model's call must name the active goal's current revision.
716    fn current(goal: &Value, revision: Option<&Value>) -> Result<(), String> {
717        if goal["status"] != "active" {
718            return Err(format!("The session goal is {}, not active", text_of(goal, "status")));
719        }
720        let matches = revision
721            .and_then(Value::as_f64)
722            .zip(goal["revision"].as_f64())
723            .is_some_and(|(a, b)| a == b);
724        if !matches {
725            return Err(format!(
726                "The goal is at revision {} (the user changed it): read it with goal.get() and work on that",
727                goal["revision"]
728            ));
729        }
730        Ok(())
731    }
732
733    /// One `goal.*` request from `lane`. A check runs with the lock released (it can take CHECK_TIMEOUT_SECONDS),
734    /// and its result is recorded only on the goal it ran for.
735    pub fn handle_request(&self, kind: &str, payload: &Map<String, Value>, lane: &str) -> Result<Value, String> {
736        let check = match self.locked(|this, state| this.request_step(state, kind, payload, lane))? {
737            Ok(done) => return Ok(done),
738            Err(check) => check,
739        };
740        let result = self.jobs.run_check(&check.command, CHECK_TIMEOUT_SECONDS)?;
741        self.locked(|this, state| {
742            let same = state
743                .goal
744                .as_ref()
745                .is_some_and(|goal| text_of(goal, "id") == check.id && goal["check"] == check.command.as_str());
746            if !same {
747                return Err("The session goal changed while its check ran: read it with goal.get()".into());
748            }
749            if kind == "goal.complete" {
750                Self::current(state.goal.as_ref().expect("a goal"), payload.get("revision"))?;
751            }
752            let run = this.record_check(state, check.command, result)?;
753            this.checked(state, kind, payload, run)
754        })
755    }
756
757    /// The part of a request before its check: `Ok` is the reply when no check is needed.
758    fn request_step(
759        &self,
760        state: &mut State,
761        kind: &str,
762        payload: &Map<String, Value>,
763        lane: &str,
764    ) -> Result<Result<Value, PendingCheck>, String> {
765        if kind == "goal.get" {
766            kernel::ops::fields("goal.get", payload)?;
767            return Ok(Ok(state.goal.as_ref().map_or(Value::Null, public_goal)));
768        }
769        let goal = state.goal.as_ref().ok_or("There is no session goal")?;
770        let job = goal["job"].as_str().and_then(|job| self.jobs.lane_of_job(job));
771        if lane != kernel::ROOT_LANE && Some(lane) != job.as_deref() {
772            return Err("Only the goal's job or the root agent works the session goal; subagents report to it".into());
773        }
774        let pending = || PendingCheck {
775            id: text_of(goal, "id"),
776            command: text_of(goal, "check"),
777        };
778        match kind {
779            "goal.check" => {
780                kernel::ops::fields("goal.check", payload)?;
781                if goal["check"].is_null() {
782                    return Err("This goal has no check command (the user sets one with /goal check)".into());
783                }
784                Ok(Err(pending()))
785            }
786            "goal.complete" => {
787                kernel::ops::fields("goal.complete", payload)?;
788                Self::current(goal, payload.get("revision"))?;
789                text(payload.get("summary"), "summary")?;
790                evidence_list(payload.get("evidence"))?;
791                if goal["check"].is_null() {
792                    return self.complete(state, payload, false).map(Ok);
793                }
794                Ok(Err(pending()))
795            }
796            "goal.blocked" => {
797                kernel::ops::fields("goal.blocked", payload)?;
798                Self::current(goal, payload.get("revision"))?;
799                let reason = text(payload.get("reason"), "reason")?;
800                let checks = int_of(goal, "checks");
801                if !goal["check"].is_null() && checks < BLOCK_MIN_CHECKS {
802                    return Err(format!(
803                        "goal.blocked is accepted after {BLOCK_MIN_CHECKS} checks ({checks} so far): keep working, test with goal.check(), and try another approach"
804                    ));
805                }
806                self.set_status(state, "blocked", Some(&reason))?;
807                Ok(Ok(json!({"status": "blocked", "reason": reason})))
808            }
809            _ => Err(kernel::ops::not_wired(kind)),
810        }
811    }
812
813    /// The part of a request after its check ran (`run` is the recorded check).
814    fn checked(
815        &self,
816        state: &mut State,
817        kind: &str,
818        payload: &Map<String, Value>,
819        mut run: Value,
820    ) -> Result<Value, String> {
821        if kind == "goal.complete" {
822            if run["passed"] != true {
823                return Ok(json!({
824                    "complete": false,
825                    "status": state.goal.as_ref().expect("a goal")["status"],
826                    "check": run,
827                    "message": "The check failed, so the goal is not complete: fix the cause and call goal.complete again.",
828                }));
829            }
830            return self.complete(state, payload, true);
831        }
832        let goal = state.goal.as_ref().expect("a goal");
833        if goal["status"] == "active" && int_of(goal, "stuck") >= STUCK_CHECKS {
834            let stuck = int_of(goal, "stuck");
835            self.set_status(
836                state,
837                "paused",
838                Some(&format!(
839                    "{stuck} failing checks in a row gave the same result; /goal resume continues"
840                )),
841            )?;
842            let goal = state.goal.as_mut().expect("a goal");
843            // Stopped after this reply reaches the job's cell.
844            if let Some(stopping) = goal["job"].as_str().map(str::to_string) {
845                let jobs = self.jobs.clone();
846                std::thread::spawn(move || {
847                    std::thread::sleep(Duration::from_millis(100));
848                    let _ = jobs.stop_job(&stopping, "goal stuck");
849                });
850            }
851            goal["job"] = Value::Null;
852            run["paused"] = true.into();
853            run["reason"] = goal["reason"].clone();
854            return Ok(run);
855        }
856        run["paused"] = false.into();
857        Ok(run)
858    }
859
860    fn complete(&self, state: &mut State, payload: &Map<String, Value>, verified: bool) -> Result<Value, String> {
861        let summary = text(payload.get("summary"), "summary")?;
862        let evidence = evidence_list(payload.get("evidence"))?;
863        let now = self.now();
864        state.goal.as_mut().expect("a goal")["completion"] =
865            json!({"summary": summary, "evidence": evidence, "verified": verified, "at": now});
866        self.set_status(state, "complete", None)?;
867        let goal = state.goal.as_ref().expect("a goal");
868        Ok(json!({"complete": true, "status": goal["status"], "verified": verified, "check": goal["last_check"]}))
869    }
870}
871
872impl ApiModule for GoalDriver {
873    fn prefixes(&self) -> &[&str] {
874        &["goal."]
875    }
876
877    fn start(&self, _host: &dyn TaskHost) -> Result<(), String> {
878        self.locked(|_, _| Ok(()))
879    }
880
881    fn handle(&self, request: &Request<'_>) -> Result<Value, String> {
882        self.handle_request(request.kind, request.payload, request.lane)
883    }
884}
885
886/// [`GoalJobs`] over the worker's task journal and shell: a goal job is a `background-job@1` task admitted through
887/// [`TaskHost::spawn`] with the goal's run key, and a check is the host's blocking `bash`.
888pub struct TaskGoalJobs {
889    tasks: Arc<dyn crate::TaskHost>,
890    shell: Arc<dyn kernel::HostHandler>,
891}
892
893impl TaskGoalJobs {
894    pub fn new(tasks: Arc<dyn crate::TaskHost>, shell: Arc<dyn kernel::HostHandler>) -> TaskGoalJobs {
895        TaskGoalJobs { tasks, shell }
896    }
897
898    fn task(&self, matches: impl Fn(&Value) -> bool) -> Option<Value> {
899        self.tasks.tasks().ok()?.into_iter().find(matches)
900    }
901}
902
903impl GoalJobs for TaskGoalJobs {
904    fn run_check(&self, command: &str, timeout_seconds: u64) -> Result<GoalCheckResult, String> {
905        let mut payload = Map::new();
906        payload.insert("command".into(), command.into());
907        payload.insert("timeout".into(), timeout_seconds.into());
908        let reply = self.shell.handle("bash", payload, &Signal::new())?;
909        Ok(GoalCheckResult {
910            exit_code: reply["exit_code"].as_i64(),
911            timed_out: reply["timed_out"] == true,
912            output: reply["output"].as_str().unwrap_or_default().to_string(),
913        })
914    }
915
916    /// The usage root is not passed: [`TaskHost::spawn`] charges the job to its admission root.
917    fn start_job(&self, prompt: &str, key: &str, _usage_root: &str) -> Result<String, String> {
918        let request = json!({"definition": "background-job@1", "input": {"prompt": prompt}, "key": key});
919        let task = self.tasks.spawn(&request, None)?;
920        task["id"]
921            .as_str()
922            .map(str::to_string)
923            .ok_or_else(|| "the task host returned no task id".into())
924    }
925
926    fn stop_job(&self, task_id: &str, reason: &str) -> Result<(), String> {
927        self.tasks.cancel(task_id, reason).map(|_| ())
928    }
929
930    fn lane_of_job(&self, task_id: &str) -> Option<String> {
931        self.tasks.task_lane(task_id)
932    }
933
934    fn job_state(&self, task_id: &str) -> Option<JobState> {
935        let task = self.task(|task| task["id"] == task_id)?;
936        Some(match task.get("result").filter(|result| !result.is_null()) {
937            Some(result) => JobState::Ended(result.clone()),
938            None => JobState::Running,
939        })
940    }
941
942    fn job_with_key(&self, key: &str) -> Option<String> {
943        self.task(|task| task["key"] == key)
944            .and_then(|task| task["id"].as_str().map(str::to_string))
945    }
946}