Skip to content

armgit / agtx

Public Imported from GitHub
0

πŸ„πŸΌβ€β™‚οΈ The blackboard for coding agents - agentic development environment for claude code, codex, cursor, opencode, grok and more.

8.3 KB
Raw Blame
//! "What changed since I last looked" β€” the state behind `wait_for_board_change`.
//!
//! A caller supervising the board unattended pays for every turn it takes, and
//! the price of a turn is its whole context, re-read. Polling is two turns per
//! pass β€” a sleep, then a full listing β€” and most passes find nothing to do.
//! Measured on a 14-task run: 73 sleeps and 96 listings, with the listings alone
//! the largest share of every tool result the session re-read afterwards.
//!
//! So the wait blocks inside the server and answers once, when something needs
//! the caller, with only the tasks that differ from what it was last shown.
//!
//! Pure: no database, no tmux, no clock. The server feeds it one [`TaskMark`]
//! per task per poll.

use std::collections::{HashMap, HashSet};

use crate::db::TaskStatus;

/// The parts of a task a caller acts on. Two equal marks mean "nothing for the
/// caller here", so what goes in decides what can wake it.
///
/// `phase_age_secs` is deliberately absent: it changes on every refresh, and a
/// mark that always differs wakes nothing but reports everything.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct TaskMark {
    pub status: TaskStatus,
    /// The TUI's verdict, already withheld when it describes a previous status.
    pub phase_status: Option<String>,
    /// When the agent's hook last reported a turn boundary β€” `waiting`,
    /// `ended` or `blocked` β€” and `None` while it reports `working`.
    ///
    /// This is what tells two `idle`s apart. A caller nudges an idle agent, the
    /// agent works and stops again, and the board reads `idle` before and after:
    /// equal marks, and a caller that is never told its nudge was answered. The
    /// second `Stop` carries a new timestamp. `None` while working keeps a busy
    /// agent's heartbeat out of the mark, since every tool call bumps it.
    pub turn_ts: Option<i64>,
    pub deps_satisfied: bool,
    pub escalation_note: Option<String>,
}

impl TaskMark {
    /// Whether a task in this state is waiting on the caller.
    ///
    /// `working` and an absent status are not: they are what a task looks like
    /// between the caller's move and the outcome of it, and waking on them costs
    /// a turn per transition to learn nothing. A status change alone is not
    /// either β€” the caller asked for it β€” except into Done, which is where a
    /// merge landed and dependents may have come free.
    pub fn needs_attention(&self) -> bool {
        if self.escalation_note.is_some() {
            return true;
        }
        match self.status {
            TaskStatus::Done => true,
            // A research session runs in Backlog, so it has a phase of its own;
            // otherwise a Backlog task wants the caller once it can be started.
            TaskStatus::Backlog => self.deps_satisfied || self.phase_needs_attention(),
            TaskStatus::Planning | TaskStatus::Running | TaskStatus::Review => {
                self.phase_needs_attention()
            }
        }
    }

    fn phase_needs_attention(&self) -> bool {
        matches!(
            self.phase_status.as_deref(),
            Some("ready" | "idle" | "blocked" | "exited")
        )
    }
}

/// What one caller has been shown of one board.
///
/// Two maps, because "changed since the caller last saw it" and "changed since
/// the last poll" are different questions, and each misses a case the other
/// catches. Against `reported` alone, an agent nudged out of `idle` that works
/// and goes idle again inside one wait looks unchanged. Against `observed`
/// alone, a task that went `ready` while the caller was busy between two waits
/// is already `ready` at the first poll and looks unchanged too.
#[derive(Debug, Default)]
pub struct BoardView {
    /// The mark each task had when the caller was last shown it.
    reported: HashMap<String, TaskMark>,
    /// The mark each task had at the last poll.
    observed: HashMap<String, TaskMark>,
    /// Tasks that woke a wait while matching `reported` β€” see [`Self::poll`].
    woken: HashSet<String>,
    /// What the caller was last told about the TUI. `None` until it has been
    /// told anything, which is not a change to wake for.
    tui_connected: Option<bool>,
}

/// The answer to a wait: which tasks to show the caller.
#[derive(Debug, Default, PartialEq, Eq)]
pub struct BoardDiff {
    /// Tasks whose mark differs from what the caller was last shown, or that
    /// woke this wait. In board order.
    pub changed: Vec<String>,
    /// Tasks the caller was shown that no longer exist.
    pub removed: Vec<String>,
}

impl BoardView {
    /// Record that the caller was just shown these tasks β€” by `list_tasks` or
    /// `get_task` β€” so a wait does not wake to repeat them.
    ///
    /// A partial listing (one status, one task) records only what it showed;
    /// the rest of the board stays unseen, as it is. A task never shown wakes
    /// the next wait at once, which is also what makes a caller's first wait a
    /// baseline of the whole board.
    pub fn mark_seen<'a>(
        &mut self,
        tasks: impl IntoIterator<Item = (&'a str, &'a TaskMark)>,
        tui_connected: bool,
    ) {
        for (id, mark) in tasks {
            self.reported.insert(id.to_string(), mark.clone());
            self.observed.insert(id.to_string(), mark.clone());
            self.woken.remove(id);
        }
        self.tui_connected = Some(tui_connected);
    }

    /// One poll of the whole board. True when the caller should be woken.
    ///
    /// Wakes when a task is in a state that needs the caller *and* the caller
    /// has not seen it there β€” either it differs from what was reported, or it
    /// moved since the last poll. The second half is what catches a return to
    /// the same state; such a task matches `reported`, so it is remembered in
    /// `woken` to be included in the answer regardless.
    ///
    /// A task already reported in a state that needs attention does not wake
    /// again while it stays there. A caller that chooses to leave a `blocked`
    /// task alone must not be woken for it on every poll.
    pub fn poll(&mut self, board: &[(String, TaskMark)], tui_connected: bool) -> bool {
        let mut wake = false;
        if self.tui_connected.is_some_and(|t| t != tui_connected) {
            wake = true;
        }
        for (id, mark) in board {
            let unseen = self.reported.get(id) != Some(mark);
            let moved = self.observed.get(id) != Some(mark);
            if mark.needs_attention() && (unseen || moved) {
                wake = true;
                if !unseen {
                    self.woken.insert(id.clone());
                }
            }
            // A task the caller has never been shown is news in any state.
            if !self.reported.contains_key(id) {
                wake = true;
            }
            self.observed.insert(id.clone(), mark.clone());
        }
        let present: HashSet<&str> = board.iter().map(|(id, _)| id.as_str()).collect();
        if self
            .reported
            .keys()
            .any(|id| !present.contains(id.as_str()))
        {
            wake = true;
        }
        self.observed.retain(|id, _| present.contains(id.as_str()));
        wake
    }

    /// What to show the caller now, and record that it has been shown.
    ///
    /// Called when a wait answers, whether it woke or timed out: a timeout
    /// still reports the moves into non-actionable states it accumulated, so
    /// the next wait starts from what the caller actually knows.
    pub fn report(&mut self, board: &[(String, TaskMark)], tui_connected: bool) -> BoardDiff {
        let present: HashSet<&str> = board.iter().map(|(id, _)| id.as_str()).collect();
        let mut removed: Vec<String> = self
            .reported
            .keys()
            .filter(|id| !present.contains(id.as_str()))
            .cloned()
            .collect();
        removed.sort();
        for id in &removed {
            self.reported.remove(id);
        }

        let mut changed = Vec::new();
        for (id, mark) in board {
            if self.reported.get(id) != Some(mark) || self.woken.contains(id) {
                changed.push(id.clone());
                self.reported.insert(id.clone(), mark.clone());
            }
        }
        self.woken.clear();
        self.tui_connected = Some(tui_connected);
        BoardDiff { changed, removed }
    }
}