use std::sync::Arc;
use agentstategraph::{CommitOptions, RepoError, Repository};
use agentstategraph_core::IntentCategory;
use chrono::Utc;
use once_cell::sync::Lazy;
use regex::Regex;
static BLOCKER_ID_RE: Lazy<Regex> =
Lazy::new(|| Regex::new(r"^t-\d{1,9}$").expect("static blocker-id regex must compile"));
fn validate_blocker_ids(blockers: &[TaskId]) -> Result<(), TaskStoreError> {
for b in blockers {
if !BLOCKER_ID_RE.is_match(&b.0) {
return Err(TaskStoreError::InvalidBlockerId(b.0.clone()));
}
}
Ok(())
}
use crate::error::TaskStoreError;
use crate::paths;
use crate::state::{Transition, check_transition};
use crate::types::{OnCompleteHook, Plan, PlanStatus, Priority, Proof, Task, TaskId, TaskStatus};
use crate::verifier::{Verifier, VerifyEntry, VerifyReport};
#[derive(Default)]
pub struct AddTaskOptions {
pub payload: Option<serde_json::Value>,
pub parent_change: Option<String>,
pub on_complete: Option<OnCompleteHook>,
}
pub struct TaskStore {
repo: Arc<Repository>,
prefix: String,
agent_id: String,
}
impl TaskStore {
pub fn new(
repo: Arc<Repository>,
prefix: impl Into<String>,
agent_id: impl Into<String>,
) -> Self {
let mut prefix = prefix.into();
if prefix.ends_with('/') {
prefix.pop();
}
Self {
repo,
prefix,
agent_id: agent_id.into(),
}
}
pub fn prefix(&self) -> &str {
&self.prefix
}
pub fn agent_id(&self) -> &str {
&self.agent_id
}
const MAX_CAS_RETRIES: u32 = 32;
pub fn create_plan(
&self,
ref_name: &str,
name: &str,
description: Option<String>,
) -> Result<Plan, TaskStoreError> {
for _ in 0..Self::MAX_CAS_RETRIES {
let head = self.repo.head(ref_name)?;
if self.plan_exists(ref_name, name)? {
return Err(TaskStoreError::PlanAlreadyExists(name.to_string()));
}
let plan = Plan {
name: name.to_string(),
description: description.clone(),
status: PlanStatus::Active,
created_at: Utc::now(),
created_by: self.agent_id.clone(),
archived_at: None,
summary: None,
closed_at: None,
closed_by: None,
};
let meta_path = paths::plan_meta(&self.prefix, name);
let value = serde_json::to_value(&plan)?;
match self.repo.set_json_cas(
ref_name,
head,
&meta_path,
&value,
self.commit_opts(format!("Create plan {}", name)),
) {
Ok(_) => return Ok(plan),
Err(RepoError::WriteConflict) => continue,
Err(e) => return Err(e.into()),
}
}
Err(TaskStoreError::WriteConflict)
}
pub fn list_plans(&self, ref_name: &str) -> Result<Vec<Plan>, TaskStoreError> {
let root = match self.repo.get_json(ref_name, &self.prefix) {
Ok(v) => v,
Err(e) if is_path_not_found(&e) => return Ok(Vec::new()),
Err(e) => return Err(e.into()),
};
let serde_json::Value::Object(map) = root else {
return Ok(Vec::new());
};
map.iter()
.map(|(name, plan)| plan_from_tree(name, plan))
.collect()
}
pub fn list_plans_with_tasks(
&self,
ref_name: &str,
) -> Result<Vec<(Plan, Vec<Task>)>, TaskStoreError> {
let root = match self.repo.get_json(ref_name, &self.prefix) {
Ok(v) => v,
Err(e) if is_path_not_found(&e) => return Ok(Vec::new()),
Err(e) => return Err(e.into()),
};
let serde_json::Value::Object(map) = root else {
return Ok(Vec::new());
};
map.iter()
.map(|(name, plan)| Ok((plan_from_tree(name, plan)?, tasks_from_tree(plan)?)))
.collect()
}
pub fn get_plan(&self, ref_name: &str, name: &str) -> Result<Plan, TaskStoreError> {
let meta_path = paths::plan_meta(&self.prefix, name);
let value = self
.repo
.get_json(ref_name, &meta_path)
.map_err(|e| map_not_found(e, || TaskStoreError::PlanNotFound(name.to_string())))?;
Ok(serde_json::from_value(value)?)
}
pub fn archive_plan(&self, ref_name: &str, name: &str) -> Result<Plan, TaskStoreError> {
let meta_path = paths::plan_meta(&self.prefix, name);
for _ in 0..Self::MAX_CAS_RETRIES {
let head = self.repo.head(ref_name)?;
let mut plan = self.get_plan(ref_name, name)?;
plan.status = PlanStatus::Archived;
plan.archived_at = Some(Utc::now());
let value = serde_json::to_value(&plan)?;
match self.repo.set_json_cas(
ref_name,
head,
&meta_path,
&value,
self.commit_opts(format!("Archive plan {}", name)),
) {
Ok(_) => return Ok(plan),
Err(RepoError::WriteConflict) => continue,
Err(e) => return Err(e.into()),
}
}
Err(TaskStoreError::WriteConflict)
}
pub fn close_plan(
&self,
ref_name: &str,
name: &str,
summary: &str,
) -> Result<Plan, TaskStoreError> {
if summary.trim().is_empty() {
return Err(TaskStoreError::SummaryRequired);
}
let meta_path = paths::plan_meta(&self.prefix, name);
for _ in 0..Self::MAX_CAS_RETRIES {
let head = self.repo.head(ref_name)?;
let mut plan = self.get_plan(ref_name, name)?;
match plan.status {
PlanStatus::Completed => return Ok(plan),
PlanStatus::Archived => {
return Err(TaskStoreError::CannotClose {
plan: name.to_string(),
reason: "plan is archived".to_string(),
});
}
PlanStatus::Active => {}
}
let tasks = self.list_tasks(ref_name, name)?;
if tasks.is_empty() {
return Err(TaskStoreError::CannotClose {
plan: name.to_string(),
reason: "plan has no tasks".to_string(),
});
}
if let Some(open) = tasks.iter().find(|t| !t.status.is_terminal()) {
return Err(TaskStoreError::CannotClose {
plan: name.to_string(),
reason: format!(
"task {} is still {:?}; every task must be done or abandoned first",
open.id.0, open.status
),
});
}
plan.status = PlanStatus::Completed;
plan.summary = Some(summary.trim().to_string());
plan.closed_at = Some(Utc::now());
plan.closed_by = Some(self.agent_id.clone());
let value = serde_json::to_value(&plan)?;
match self.repo.set_json_cas(
ref_name,
head,
&meta_path,
&value,
self.commit_opts(format!("Close plan {}", name)),
) {
Ok(_) => return Ok(plan),
Err(RepoError::WriteConflict) => continue,
Err(e) => return Err(e.into()),
}
}
Err(TaskStoreError::WriteConflict)
}
pub fn delete_plan(&self, ref_name: &str, name: &str) -> Result<(), TaskStoreError> {
if !self.plan_exists(ref_name, name)? {
return Err(TaskStoreError::PlanNotFound(name.to_string()));
}
let root = paths::plan_root(&self.prefix, name);
self.repo.delete(
ref_name,
&root,
self.commit_opts(format!("Delete plan {}", name)),
)?;
Ok(())
}
pub fn add_task(
&self,
ref_name: &str,
plan: &str,
title: &str,
priority: Priority,
parent_id: Option<TaskId>,
blocked_by: Vec<TaskId>,
assigned_to: Option<String>,
) -> Result<Task, TaskStoreError> {
self.add_task_with_extensions(
ref_name,
plan,
title,
priority,
parent_id,
blocked_by,
assigned_to,
AddTaskOptions::default(),
)
}
pub fn add_task_with_extensions(
&self,
ref_name: &str,
plan: &str,
title: &str,
priority: Priority,
parent_id: Option<TaskId>,
blocked_by: Vec<TaskId>,
assigned_to: Option<String>,
opts: AddTaskOptions,
) -> Result<Task, TaskStoreError> {
let AddTaskOptions {
payload,
parent_change,
on_complete,
} = opts;
if !self.plan_exists(ref_name, plan)? {
return Err(TaskStoreError::PlanNotFound(plan.to_string()));
}
if let Some(ref parent) = parent_id {
let parent_task = self.get_task(ref_name, plan, parent)?;
if parent_task.parent_id.is_some() {
return Err(TaskStoreError::ParentIsSubtask(parent.clone()));
}
}
validate_blocker_ids(&blocked_by)?;
for blocker in &blocked_by {
self.get_task(ref_name, plan, blocker)?;
}
for _ in 0..Self::MAX_CAS_RETRIES {
let head = self.repo.head(ref_name)?;
let next_num = self.next_task_number(ref_name, plan)?;
let id = TaskId::new(next_num);
let task = Task {
id: id.clone(),
title: title.to_string(),
status: TaskStatus::Pending,
priority,
parent_id: parent_id.clone(),
blocked_by: blocked_by.clone(),
created_at: Utc::now(),
created_by: self.agent_id.clone(),
started_at: None,
started_by: None,
completed_at: None,
completed_by: None,
proof: None,
abandoned_at: None,
abandoned_reason: None,
assigned_to: assigned_to.clone(),
payload: payload.clone(),
parent_change: parent_change.clone(),
on_complete: on_complete.clone(),
};
let task_path = paths::task(&self.prefix, plan, &id);
let value = serde_json::to_value(&task)?;
match self.repo.set_json_cas(
ref_name,
head,
&task_path,
&value,
self.commit_opts(format!("Add task {}/{}", plan, id)),
) {
Ok(_) => return Ok(task),
Err(RepoError::WriteConflict) => continue,
Err(e) => return Err(e.into()),
}
}
Err(TaskStoreError::WriteConflict)
}
pub fn task_ids(&self, ref_name: &str, plan: &str) -> Result<Vec<TaskId>, TaskStoreError> {
let root_path = paths::plan_root(&self.prefix, plan);
let leaves = match self.repo.list_paths(ref_name, &root_path, None) {
Ok(v) => v,
Err(e) if is_path_not_found(&e) => {
return Err(TaskStoreError::PlanNotFound(plan.to_string()));
}
Err(e) => return Err(e.into()),
};
let prefix_with_slash = format!("{}/", root_path);
let mut ids: std::collections::BTreeSet<TaskId> = std::collections::BTreeSet::new();
for leaf in leaves {
let Some(suffix) = leaf.strip_prefix(&prefix_with_slash) else {
continue;
};
let first = suffix.split('/').next().unwrap_or("");
if first.is_empty() || first == paths::META_KEY {
continue;
}
ids.insert(TaskId(first.to_string()));
}
Ok(ids.into_iter().collect())
}
pub fn list_tasks(&self, ref_name: &str, plan: &str) -> Result<Vec<Task>, TaskStoreError> {
let root_path = paths::plan_root(&self.prefix, plan);
let root = self
.repo
.get_json(ref_name, &root_path)
.map_err(|e| map_not_found(e, || TaskStoreError::PlanNotFound(plan.to_string())))?;
if root.get(paths::META_KEY).is_none() {
return Err(TaskStoreError::PlanNotFound(plan.to_string()));
}
tasks_from_tree(&root)
}
pub fn get_task(
&self,
ref_name: &str,
plan: &str,
id: &TaskId,
) -> Result<Task, TaskStoreError> {
let path = paths::task(&self.prefix, plan, id);
let value = self.repo.get_json(ref_name, &path).map_err(|e| {
map_not_found(e, || TaskStoreError::TaskNotFound {
plan: plan.to_string(),
id: id.clone(),
})
})?;
Ok(serde_json::from_value(value)?)
}
pub fn start_task(
&self,
ref_name: &str,
plan: &str,
id: &TaskId,
) -> Result<Task, TaskStoreError> {
self.update_task(
ref_name,
plan,
id,
format!("Start {}/{}", plan, id),
|task| {
check_transition(task.status, Transition::Start)?;
let BlockerCheck { missing, pending } =
self.classify_blockers(ref_name, plan, &task.blocked_by)?;
if !missing.is_empty() {
return Err(TaskStoreError::BlockerNotFound { blockers: missing });
}
if !pending.is_empty() {
return Err(TaskStoreError::Blocked { blockers: pending });
}
task.status = TaskStatus::InProgress;
task.started_at = Some(Utc::now());
task.started_by = Some(self.agent_id.clone());
Ok(())
},
)
}
pub fn complete_task(
&self,
ref_name: &str,
plan: &str,
id: &TaskId,
proof: Proof,
) -> Result<Task, TaskStoreError> {
self.update_task(
ref_name,
plan,
id,
format!("Complete {}/{}", plan, id),
|task| {
check_transition(task.status, Transition::Complete)?;
task.status = TaskStatus::Done;
task.proof = Some(proof.clone());
task.completed_at = Some(Utc::now());
task.completed_by = Some(self.agent_id.clone());
Ok(())
},
)
}
pub fn abandon_task(
&self,
ref_name: &str,
plan: &str,
id: &TaskId,
reason: &str,
) -> Result<Task, TaskStoreError> {
if reason.trim().is_empty() {
return Err(TaskStoreError::ReasonRequired);
}
self.update_task(
ref_name,
plan,
id,
format!("Abandon {}/{}", plan, id),
|task| {
check_transition(task.status, Transition::Abandon)?;
task.status = TaskStatus::Abandoned;
task.abandoned_at = Some(Utc::now());
task.abandoned_reason = Some(reason.to_string());
Ok(())
},
)
}
pub fn set_priority(
&self,
ref_name: &str,
plan: &str,
id: &TaskId,
priority: Priority,
) -> Result<Task, TaskStoreError> {
let desc = format!("Set priority {:?} on {}/{}", priority, plan, id);
self.update_task(ref_name, plan, id, desc, |task| {
task.priority = priority;
Ok(())
})
}
pub fn set_blockers(
&self,
ref_name: &str,
plan: &str,
id: &TaskId,
blockers: Vec<TaskId>,
) -> Result<Task, TaskStoreError> {
validate_blocker_ids(&blockers)?;
let desc = format!("Update blockers on {}/{}", plan, id);
self.update_task(ref_name, plan, id, desc, |task| {
for blocker in &blockers {
self.get_task(ref_name, plan, blocker)?;
}
task.blocked_by = blockers.clone();
Ok(())
})
}
pub fn assign_task(
&self,
ref_name: &str,
plan: &str,
id: &TaskId,
agent: &str,
) -> Result<Task, TaskStoreError> {
let desc = format!("Assign {}/{} to {}", plan, id, agent);
self.update_task(ref_name, plan, id, desc, |task| {
task.assigned_to = Some(agent.to_string());
Ok(())
})
}
pub fn unassign_task(
&self,
ref_name: &str,
plan: &str,
id: &TaskId,
) -> Result<Task, TaskStoreError> {
self.update_task(
ref_name,
plan,
id,
format!("Unassign {}/{}", plan, id),
|task| {
task.assigned_to = None;
Ok(())
},
)
}
pub fn next_task(&self, ref_name: &str, plan: &str) -> Result<Option<Task>, TaskStoreError> {
self.next_task_for(ref_name, plan, None, true)
}
pub fn next_task_for(
&self,
ref_name: &str,
plan: &str,
assigned_to: Option<&str>,
include_unassigned: bool,
) -> Result<Option<Task>, TaskStoreError> {
let tasks = self.list_tasks(ref_name, plan)?;
let mut candidates: Vec<&Task> = tasks
.iter()
.filter(|t| t.status == TaskStatus::Pending)
.filter(|t| t.blocked_by.iter().all(|b| blocker_satisfied(&tasks, b)))
.filter(|t| match assigned_to {
None => true,
Some(agent) => match &t.assigned_to {
Some(a) => a == agent,
None => include_unassigned,
},
})
.collect();
candidates.sort_by(|a, b| b.priority.cmp(&a.priority).then(a.id.cmp(&b.id)));
Ok(candidates.first().map(|t| (*t).clone()))
}
pub fn list_plans_by_status(
&self,
ref_name: &str,
status: Option<PlanStatus>,
) -> Result<Vec<Plan>, TaskStoreError> {
let plans = self.list_plans(ref_name)?;
match status {
None => Ok(plans),
Some(s) => Ok(plans.into_iter().filter(|p| p.status == s).collect()),
}
}
pub fn derived_status(
&self,
ref_name: &str,
plan: &str,
parent_id: &TaskId,
) -> Result<TaskStatus, TaskStoreError> {
let tasks = self.list_tasks(ref_name, plan)?;
let parent = tasks.iter().find(|t| &t.id == parent_id).ok_or_else(|| {
TaskStoreError::TaskNotFound {
plan: plan.to_string(),
id: parent_id.clone(),
}
})?;
let subtasks: Vec<&Task> = tasks
.iter()
.filter(|t| t.parent_id.as_ref() == Some(parent_id))
.collect();
if subtasks.is_empty() {
return Ok(parent.status);
}
if subtasks.iter().any(|t| t.status == TaskStatus::InProgress) {
return Ok(TaskStatus::InProgress);
}
let non_abandoned: Vec<&&Task> = subtasks
.iter()
.filter(|t| t.status != TaskStatus::Abandoned)
.collect();
if !non_abandoned.is_empty() && non_abandoned.iter().all(|t| t.status == TaskStatus::Done) {
return Ok(TaskStatus::Done);
}
Ok(TaskStatus::Pending)
}
pub fn verify_plan(
&self,
ref_name: &str,
plan: &str,
verifier: &dyn Verifier,
) -> Result<VerifyReport, TaskStoreError> {
let tasks = self.list_tasks(ref_name, plan)?;
let mut results = Vec::new();
for task in tasks.iter().filter(|t| t.status == TaskStatus::Done) {
let proof = task.proof.as_ref().ok_or(TaskStoreError::ProofRequired)?;
let outcome = verifier.verify(proof);
results.push(VerifyEntry {
task_id: task.id.clone(),
result: outcome,
});
}
Ok(VerifyReport {
plan: plan.to_string(),
results,
})
}
fn plan_exists(&self, ref_name: &str, name: &str) -> Result<bool, TaskStoreError> {
match self.get_plan(ref_name, name) {
Ok(_) => Ok(true),
Err(TaskStoreError::PlanNotFound(_)) => Ok(false),
Err(e) => Err(e),
}
}
fn next_task_number(&self, ref_name: &str, plan: &str) -> Result<u32, TaskStoreError> {
let ids = self.task_ids(ref_name, plan)?;
let max = ids
.iter()
.filter_map(|id| id.number().ok())
.max()
.unwrap_or(0);
Ok(max + 1)
}
fn classify_blockers(
&self,
ref_name: &str,
plan: &str,
blockers: &[TaskId],
) -> Result<BlockerCheck, TaskStoreError> {
if blockers.is_empty() {
return Ok(BlockerCheck::default());
}
let tasks = self.list_tasks(ref_name, plan)?;
let mut missing = Vec::new();
let mut pending = Vec::new();
for b in blockers {
match tasks.iter().find(|t| &t.id == b) {
None => missing.push(b.clone()),
Some(t) if t.status != TaskStatus::Done => pending.push(b.clone()),
_ => {}
}
}
Ok(BlockerCheck { missing, pending })
}
fn update_task<F>(
&self,
ref_name: &str,
plan: &str,
id: &TaskId,
description: String,
mut change: F,
) -> Result<Task, TaskStoreError>
where
F: FnMut(&mut Task) -> Result<(), TaskStoreError>,
{
for _ in 0..Self::MAX_CAS_RETRIES {
let head = self.repo.head(ref_name)?;
let mut task = self.get_task(ref_name, plan, id)?;
change(&mut task)?;
let path = paths::task(&self.prefix, plan, &task.id);
let value = serde_json::to_value(&task)?;
match self.repo.set_json_cas(
ref_name,
head,
&path,
&value,
self.commit_opts(description.clone()),
) {
Ok(_) => return Ok(task),
Err(RepoError::WriteConflict) => continue,
Err(e) => return Err(e.into()),
}
}
Err(TaskStoreError::WriteConflict)
}
fn commit_opts(&self, description: impl Into<String>) -> CommitOptions {
CommitOptions::new(&self.agent_id, IntentCategory::Plan, description)
}
}
fn blocker_satisfied(tasks: &[Task], id: &TaskId) -> bool {
tasks
.iter()
.any(|t| &t.id == id && t.status == TaskStatus::Done)
}
#[derive(Default, Debug)]
struct BlockerCheck {
pending: Vec<TaskId>,
missing: Vec<TaskId>,
}
fn is_path_not_found(e: &agentstategraph::RepoError) -> bool {
matches!(
e,
agentstategraph::RepoError::Tree(agentstategraph::tree::TreeError::PathNotFound(_))
)
}
fn plan_from_tree(name: &str, plan: &serde_json::Value) -> Result<Plan, TaskStoreError> {
let meta = plan
.get(paths::META_KEY)
.ok_or_else(|| TaskStoreError::PlanNotFound(name.to_string()))?;
Ok(serde_json::from_value(meta.clone())?)
}
fn tasks_from_tree(plan: &serde_json::Value) -> Result<Vec<Task>, TaskStoreError> {
let serde_json::Value::Object(map) = plan else {
return Ok(Vec::new());
};
let mut tasks = map
.iter()
.filter(|(key, _)| key.as_str() != paths::META_KEY)
.map(|(_, value)| serde_json::from_value::<Task>(value.clone()))
.collect::<Result<Vec<_>, _>>()?;
tasks.sort_by_key(|t| t.id.clone());
Ok(tasks)
}
fn map_not_found<F>(e: agentstategraph::RepoError, make: F) -> TaskStoreError
where
F: FnOnce() -> TaskStoreError,
{
if is_path_not_found(&e) {
make()
} else {
e.into()
}
}
#[cfg(test)]
mod path_not_found_tests {
use super::is_path_not_found;
use agentstategraph::RepoError;
use agentstategraph::core::ObjectId;
use agentstategraph::tree::TreeError;
#[test]
fn path_not_found_is_classified_as_empty() {
let e = RepoError::Tree(TreeError::PathNotFound("/plans/foo".into()));
assert!(is_path_not_found(&e));
}
#[test]
fn object_not_found_is_not_empty() {
let e = RepoError::Tree(TreeError::ObjectNotFound(ObjectId::from_bytes([7u8; 32])));
assert!(
!is_path_not_found(&e),
"ObjectNotFound must propagate as an error, not read as empty"
);
}
}