ππΌββοΈ The blackboard for coding agents - agentic development environment for claude code, codex, cursor, opencode, grok and more.
Rust adeai-agentsclaudeclaude-codecodexcursorgeminigrokopencodespec-driven-developmentvibe-codingvim
use crate::tmux::safe_session_name;
use chrono::{DateTime, Utc};
use serde::{Deserialize, Serialize};
/// Task status in the kanban board
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
pub enum TaskStatus {
Backlog,
Planning,
Running,
Review,
Done,
}
impl TaskStatus {
pub fn as_str(&self) -> &'static str {
match self {
TaskStatus::Backlog => "backlog",
TaskStatus::Planning => "planning",
TaskStatus::Running => "running",
TaskStatus::Review => "review",
TaskStatus::Done => "done",
}
}
pub fn display_name(&self) -> &'static str {
match self {
TaskStatus::Backlog => "backlog/research",
TaskStatus::Planning => "planning",
TaskStatus::Running => "running",
TaskStatus::Review => "review",
TaskStatus::Done => "done",
}
}
pub fn from_str(s: &str) -> Option<Self> {
match s {
"backlog" => Some(TaskStatus::Backlog),
"planning" => Some(TaskStatus::Planning),
"running" => Some(TaskStatus::Running),
"review" => Some(TaskStatus::Review),
"done" => Some(TaskStatus::Done),
_ => None,
}
}
pub fn columns() -> &'static [TaskStatus] {
&[
TaskStatus::Backlog,
TaskStatus::Planning,
TaskStatus::Running,
TaskStatus::Review,
TaskStatus::Done,
]
}
}
/// A task on the kanban board
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Task {
pub id: String,
pub title: String,
pub description: Option<String>,
pub status: TaskStatus,
/// The agent running in the task's window now. A phase with its own agent
/// in `[agents]` switches the task over and rewrites this, which is why it
/// cannot also carry the task's own pick β see `base_agent`.
pub agent: String,
/// The agent this task runs on in any phase without a per-phase override:
/// the task wizard's pick, or the configured default at creation. Stands in
/// for `default_agent` when a phase's agent is resolved, so a task picked to
/// run on another agent stays on it. `None` for a task stored before the
/// column existed, which falls back to the configured default.
pub base_agent: Option<String>,
pub project_id: String,
pub session_name: Option<String>,
pub worktree_path: Option<String>,
pub branch_name: Option<String>,
pub pr_number: Option<i32>,
pub pr_url: Option<String>,
pub plugin: Option<String>,
pub cycle: i32,
pub referenced_tasks: Option<String>,
pub escalation_note: Option<String>,
pub base_branch: Option<String>,
/// When the task last changed status. An artifact counts toward the phase it
/// is in only if it was written after this, so a previous cycle's
/// `execute.md` cannot make a resumed task read as done before it has run.
/// Stamped by `Database::update_task` on any status change. `None` for a task
/// stored before the column existed: unknown, so no freshness check applies,
/// rather than failing every artifact that predates the upgrade.
pub phase_entered_at: Option<DateTime<Utc>>,
pub created_at: DateTime<Utc>,
pub updated_at: DateTime<Utc>,
}
impl Task {
pub fn new(
title: impl Into<String>,
agent: impl Into<String>,
project_id: impl Into<String>,
) -> Self {
let id = uuid::Uuid::new_v4().to_string();
let now = Utc::now();
let agent = agent.into();
Self {
id,
title: title.into(),
description: None,
status: TaskStatus::Backlog,
base_agent: Some(agent.clone()),
agent,
project_id: project_id.into(),
session_name: None,
worktree_path: None,
branch_name: None,
pr_number: None,
pr_url: None,
plugin: None,
cycle: 1,
referenced_tasks: None,
escalation_note: None,
base_branch: None,
phase_entered_at: Some(now),
created_at: now,
updated_at: now,
}
}
/// Returns the task description if present, otherwise the title.
pub fn content_text(&self) -> String {
self.description
.as_deref()
.unwrap_or(&self.title)
.to_string()
}
/// Generate tmux session name: task-{id}--{project}--{slug}
pub fn generate_session_name(&self, project_name: &str) -> String {
let project_name = safe_session_name(project_name);
let slug = self
.title
.to_lowercase()
.chars()
.map(|c| if c.is_alphanumeric() { c } else { '-' })
.collect::<String>();
let slug = slug.trim_matches('-');
// Truncate slug to keep session name reasonable
let slug: String = slug.chars().take(20).collect();
format!("task-{}--{}--{}", &self.id[..8], project_name, slug)
}
}
/// A project tracked by agtx
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Project {
pub id: String,
pub name: String,
pub path: String,
pub github_url: Option<String>,
pub default_agent: Option<String>,
pub last_opened: DateTime<Utc>,
}
impl Project {
pub fn new(name: impl Into<String>, path: impl Into<String>) -> Self {
Self {
id: uuid::Uuid::new_v4().to_string(),
name: name.into(),
path: path.into(),
github_url: None,
default_agent: None,
last_opened: Utc::now(),
}
}
}
/// A queued request for a task state transition (used by MCP server).
/// The TUI polls this table and executes transitions with full side effects.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct TransitionRequest {
pub id: String,
pub task_id: String,
pub action: String,
pub reason: Option<String>,
pub requested_at: DateTime<Utc>,
pub processed_at: Option<DateTime<Utc>>,
pub error: Option<String>,
}
impl TransitionRequest {
pub fn new(task_id: impl Into<String>, action: impl Into<String>) -> Self {
Self {
id: uuid::Uuid::new_v4().to_string(),
task_id: task_id.into(),
action: action.into(),
reason: None,
requested_at: Utc::now(),
processed_at: None,
error: None,
}
}
}
/// Represents a running agent session
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct RunningAgent {
pub session_name: String,
pub project_id: String,
pub task_id: String,
pub agent_name: String,
pub started_at: DateTime<Utc>,
pub status: AgentStatus,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
pub enum AgentStatus {
Running,
Waiting,
Completed,
}
impl AgentStatus {
pub fn as_str(&self) -> &'static str {
match self {
AgentStatus::Running => "running",
AgentStatus::Waiting => "waiting",
AgentStatus::Completed => "completed",
}
}
}
/// A notification for the orchestrator agent (pull-based).
/// Events are written to the DB by the TUI and fetched by the orchestrator via MCP.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Notification {
pub id: String,
pub message: String,
pub created_at: DateTime<Utc>,
/// The task this is about. `None` only for rows written before the column
/// existed β every producer sets it.
pub task_id: Option<String>,
/// What kind of event this is. Separate from `message` because a consumer
/// outside the TUI filters on the event, not on prose: a chat bridge that
/// wakes someone for [`TaskStuck`](NotificationKind::TaskStuck) but not for
/// [`PhaseCompleted`](NotificationKind::PhaseCompleted) cannot express that
/// against a formatted string.
pub kind: Option<NotificationKind>,
}
/// Why a [`Notification`] was raised.
///
/// The serde spellings match [`as_str`](Self::as_str) so the stored value and
/// the wire value cannot drift β a consumer reading the DB directly and one
/// reading serialised output must agree on the name.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum NotificationKind {
/// A task's phase artifact appeared β it can move forward.
PhaseCompleted,
/// A task has stopped making progress and may need a human.
TaskStuck,
}
impl NotificationKind {
pub fn as_str(&self) -> &'static str {
match self {
NotificationKind::PhaseCompleted => "phase_completed",
NotificationKind::TaskStuck => "task_stuck",
}
}
pub fn from_str(s: &str) -> Option<Self> {
match s {
"phase_completed" => Some(NotificationKind::PhaseCompleted),
"task_stuck" => Some(NotificationKind::TaskStuck),
_ => None,
}
}
}
impl Notification {
pub fn new(message: impl Into<String>) -> Self {
Self {
id: uuid::Uuid::new_v4().to_string(),
message: message.into(),
created_at: Utc::now(),
task_id: None,
kind: None,
}
}
/// The form every producer should use: a notification is always *about* a
/// task, and a consumer outside this process needs both halves to route it.
pub fn for_task(
kind: NotificationKind,
task_id: impl Into<String>,
message: impl Into<String>,
) -> Self {
Self {
task_id: Some(task_id.into()),
kind: Some(kind),
..Self::new(message)
}
}
}
/// Phase completion status.
///
/// The TUI computes this on its own thread and reads its in-memory copy; the
/// `task_runtime` table is a *published* mirror for readers in other processes,
/// which cannot recompute it without duplicating the artifact-check and
/// pane-hash pipeline. A reader must treat a row as a snapshot and check
/// `updated_at`: with no TUI running nothing refreshes it, and a frozen
/// [`Working`](Self::Working) must not be presented as live.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum PhaseStatus {
/// Agent is still working, no artifact yet
Working,
/// Agent is stopped waiting on a permission prompt or a question.
///
/// Set from an agent-reported hook event, or from a match against that
/// agent's own `security` dialogs in the pane (`visible_security_dialog`,
/// which runs only while `auto_trust` is off). Never from silence: "no output
/// for 15s" is [`Idle`](Self::Idle), which guesses, where this names what the
/// task is waiting on.
Blocked,
/// Agent output hasn't changed for 15s β may need user input
Idle,
/// Phase artifact detected, ready to advance
Ready,
/// Tmux window gone (process exited)
Exited,
}
impl PhaseStatus {
pub fn as_str(&self) -> &'static str {
match self {
PhaseStatus::Working => "working",
PhaseStatus::Blocked => "blocked",
PhaseStatus::Idle => "idle",
PhaseStatus::Ready => "ready",
PhaseStatus::Exited => "exited",
}
}
pub fn from_str(s: &str) -> Option<Self> {
match s {
"working" => Some(PhaseStatus::Working),
"blocked" => Some(PhaseStatus::Blocked),
"idle" => Some(PhaseStatus::Idle),
"ready" => Some(PhaseStatus::Ready),
"exited" => Some(PhaseStatus::Exited),
_ => None,
}
}
}
/// A published snapshot of one task's runtime state, for readers outside the
/// TUI process. Written by the session refresh; never read back by the TUI,
/// which has the live values.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct TaskRuntime {
pub task_id: String,
pub phase_status: PhaseStatus,
/// The task status this verdict was computed for. A reader must not apply
/// it to a task that has since moved: the refresh snapshots tasks before it
/// runs, so a pass in flight across a transition returns the *previous*
/// phase's verdict stamped with a fresh `updated_at`. `None` for a row
/// written before the column existed.
pub status: Option<TaskStatus>,
/// Hash of the last pane capture, and when it last changed. Carried so a
/// reader can distinguish "idle because the agent is quiet" from "idle
/// because nothing has refreshed this row".
pub pane_hash: Option<String>,
pub pane_changed_at: Option<DateTime<Utc>>,
pub updated_at: DateTime<Utc>,
}
/// A phone (or anything else) paired with `agtx serve`.
///
/// One row per device rather than one shared secret, so a lost phone can be
/// revoked without re-pairing everything else β which is the whole reason this
/// exists rather than the single token it replaced.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct MobileDevice {
pub id: String,
/// What the user calls it. Free text from the pairing request, so it is
/// shown but never trusted or matched on.
pub label: String,
/// SHA-256 of the token, hex. The token itself is shown once, at pairing,
/// and never stored.
pub token_hash: String,
pub created_at: DateTime<Utc>,
pub last_seen: Option<DateTime<Utc>>,
/// The serve session that paired it.
///
/// Provenance, not a lifetime β a pairing persists until revoked. It is
/// what a future expiry or forget-on-exit policy would delete by, and the
/// reason such a policy can be safe: `mobile_devices` is global, so a
/// second agtx serving another project must keep its own devices.
///
/// `None` for a row written before this column existed, and in tests.
pub session_id: Option<String>,
}
impl MobileDevice {
pub fn new(label: impl Into<String>, token_hash: impl Into<String>) -> Self {
Self {
id: uuid::Uuid::new_v4().to_string(),
label: label.into(),
token_hash: token_hash.into(),
created_at: Utc::now(),
last_seen: None,
session_id: None,
}
}
/// Bind this device to the serve session that paired it.
pub fn in_session(mut self, session_id: impl Into<String>) -> Self {
self.session_id = Some(session_id.into());
self
}
}