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.

6.7 KB
Raw Blame
//! What a task is allowed to do next, and who is asking.
//!
//! Shared by the MCP server and the web API so the phone and the orchestrator
//! cannot drift apart on what a task permits.

use crate::db::{Task, TaskStatus};

/// Who is asking what a task may do.
///
/// The answer genuinely differs, and collapsing the two is a bug in both
/// directions. The orchestrator does not manage Backlog β€” a human triages it β€”
/// so offering it `research` would have it starting work the user has not
/// looked at. A person opening the board has the opposite need: Backlog triage
/// is most of what they came to do, and a Backlog card with no actions is a
/// dead end.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum CallerKind {
    /// The orchestrator agent, driving the board unattended.
    Orchestrator,
    /// A person, through a UI.
    Human,
}

/// Every `move_task` verb, in one place so the MCP tool and the web API cannot
/// disagree about what a valid action is even called.
pub const ACTIONS: &[&str] = &[
    "research",
    "move_forward",
    "move_to_planning",
    "move_to_running",
    "move_to_review",
    "move_to_done",
    "move_to_done_and_merge",
    "resume",
    "escalate_to_user",
];

/// Whether a task's agent can be sent a message through `send_to_task`.
///
/// Planning, Running and Review all have a live agent in their window. Review is
/// included so a reviewer can be handed a small fix in place, with no board
/// transition made just to deliver a message. `resume` sends the task round a
/// whole execute cycle, and is for going back to implement more.
///
/// Backlog has no agent unless it is researching, and Done has none at all.
pub fn accepts_task_input(status: TaskStatus) -> bool {
    matches!(
        status,
        TaskStatus::Planning | TaskStatus::Running | TaskStatus::Review
    )
}

/// The longest a task title may be. Mirrors the wizard's own cap, so a task
/// created from a phone cannot be one the desktop refuses to edit.
pub const MAX_TASK_TITLE_CHARS: usize = 120;

/// The actions `task` currently permits, named as the MCP `move_task` verbs.
///
/// `deps_satisfied` comes from [`crate::db::Database::deps_satisfied`]: a task
/// whose referenced tasks are not yet in Review or Done cannot leave Backlog.
pub fn allowed_actions(task: &Task, deps_satisfied: bool, caller: CallerKind) -> Vec<String> {
    let mut actions: Vec<String> = Vec::new();

    match task.status {
        TaskStatus::Backlog => {
            // The orchestrator is a coordinator, not a triager: it moves work
            // that a person has already decided to start. Everything a human
            // can do from Backlog is what the board's `R`, `m` and `M` keys do.
            if caller == CallerKind::Human {
                actions.push("research".to_string());
                actions.push("move_to_planning".to_string());
                actions.push("move_to_running".to_string());
            }
        }
        TaskStatus::Planning | TaskStatus::Running => {
            actions.push("move_forward".to_string());
            // `escalate_to_user` means "stop and ask the person". Offering it to
            // the person is incoherent β€” they are already looking at the task β€”
            // so it belongs to the orchestrator alone.
            if caller == CallerKind::Orchestrator {
                actions.push("escalate_to_user".to_string());
            }
        }
        TaskStatus::Review => {
            actions.push("move_to_done".to_string());
            actions.push("resume".to_string());
            // Integrating locally is the unattended caller's problem alone. A
            // person reaches Done through a PR merged on the remote, and
            // offering them a button that merges into their own checkout
            // instead would be a second, conflicting way to land the same work.
            if caller == CallerKind::Orchestrator {
                actions.push("move_to_done_and_merge".to_string());
            }
        }
        TaskStatus::Done => {}
    }

    // Block forward transitions out of Backlog when dependencies are not
    // satisfied. Reachable only for `Human`, since the orchestrator is offered
    // nothing from Backlog to retain β€” but it belongs here rather than inside
    // the arm above, because the rule is about the transition, not the caller.
    if !deps_satisfied && task.status == TaskStatus::Backlog {
        actions.retain(|a| {
            !matches!(
                a.as_str(),
                "move_forward" | "move_to_planning" | "move_to_running"
            )
        });
    }

    actions
}

/// Why an action was refused.
///
/// The two cases are different kinds of wrong and a caller should treat them
/// differently: an unknown verb is a malformed request that will never work,
/// while a verb the task does not currently permit may succeed once the board
/// moves. Collapsing them tells a client to give up on something it should
/// retry, or to retry something it should fix.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum ActionRefusal {
    /// Not a verb agtx knows.
    UnknownAction(String),
    /// A real verb, not available in this task's current state.
    NotPermitted(String),
}

impl ActionRefusal {
    pub fn message(&self) -> &str {
        match self {
            ActionRefusal::UnknownAction(m) | ActionRefusal::NotPermitted(m) => m,
        }
    }
}

/// Whether `caller` may ask for `action` on `task` right now.
pub fn validate_action(
    task: &Task,
    deps_satisfied: bool,
    caller: CallerKind,
    action: &str,
) -> Result<(), ActionRefusal> {
    if !ACTIONS.contains(&action) {
        return Err(ActionRefusal::UnknownAction(format!(
            "unknown action {action:?}; valid actions are {}",
            ACTIONS.join(", ")
        )));
    }

    let allowed = allowed_actions(task, deps_satisfied, caller);
    if allowed.iter().any(|a| a == action) {
        return Ok(());
    }

    // Separate "not yet" from "not ever": a dependency clears on its own, and
    // telling someone their tap was invalid when it was merely early sends them
    // looking for a bug in the wrong place.
    if !deps_satisfied
        && task.status == TaskStatus::Backlog
        && matches!(
            action,
            "move_forward" | "move_to_planning" | "move_to_running"
        )
    {
        return Err(ActionRefusal::NotPermitted(format!(
            "{action} is blocked: this task's dependencies are not all in Review or Done yet"
        )));
    }

    Err(ActionRefusal::NotPermitted(format!(
        "{action} is not available for a task in {}{}",
        task.status.as_str(),
        if allowed.is_empty() {
            String::new()
        } else {
            format!("; try one of {}", allowed.join(", "))
        }
    )))
}