agent_orchestrator/task_repository/
trait_def.rs

1use crate::dto::{TaskGraphDebugBundle, TaskItemRow, TaskSummary};
2use anyhow::Result;
3
4use super::TaskDetailRows;
5use super::command_run::NewCommandRun;
6use super::types::{DbEventRecord, TaskLogRunRow, TaskRuntimeRow};
7
8/// Synchronous repository interface for task, run, and event persistence.
9pub trait TaskRepository {
10    /// Resolves a full task identifier from an exact ID or prefix.
11    fn resolve_task_id(&self, task_id_or_prefix: &str) -> Result<String>;
12    /// Loads the summary row for a task.
13    fn load_task_summary(&self, task_id: &str) -> Result<TaskSummary>;
14    /// Loads the full detail row bundle for a task.
15    fn load_task_detail_rows(&self, task_id: &str) -> Result<TaskDetailRows>;
16    /// Loads `(total, resolved, unresolved)` item counts for a task.
17    fn load_task_item_counts(&self, task_id: &str) -> Result<(i64, i64, i64)>;
18    /// Lists task identifiers ordered from newest to oldest.
19    fn list_task_ids_ordered_by_created_desc(&self) -> Result<Vec<String>>;
20    /// Returns the latest resumable task, optionally including pending tasks.
21    fn find_latest_resumable_task_id(&self, include_pending: bool) -> Result<Option<String>>;
22    /// Loads execution state needed to resume a task.
23    fn load_task_runtime_row(&self, task_id: &str) -> Result<TaskRuntimeRow>;
24    /// Returns the first task-item identifier for a task, if any.
25    fn first_task_item_id(&self, task_id: &str) -> Result<Option<String>>;
26    /// Counts unresolved items for the task.
27    fn count_unresolved_items(&self, task_id: &str) -> Result<i64>;
28    /// Lists task items participating in the current cycle.
29    fn list_task_items_for_cycle(&self, task_id: &str) -> Result<Vec<TaskItemRow>>;
30    /// Loads the current task status string.
31    fn load_task_status(&self, task_id: &str) -> Result<Option<String>>;
32    /// Updates the task status and optionally stamps completion metadata.
33    fn set_task_status(&self, task_id: &str, status: &str, set_completed: bool) -> Result<()>;
34    /// Prepares a task for a fresh start by resetting batch-execution state.
35    fn prepare_task_for_start_batch(&self, task_id: &str) -> Result<()>;
36    /// Persists cycle counters and `init_once` completion state for a task.
37    fn update_task_cycle_state(
38        &self,
39        task_id: &str,
40        current_cycle: u32,
41        init_done: bool,
42    ) -> Result<()>;
43    /// Marks a task item as currently running.
44    fn mark_task_item_running(&self, task_item_id: &str) -> Result<()>;
45    /// Sets a terminal status for a task item.
46    fn set_task_item_terminal_status(&self, task_item_id: &str, status: &str) -> Result<()>;
47    /// Updates a task item to an arbitrary status value.
48    fn update_task_item_status(&self, task_item_id: &str, status: &str) -> Result<()>;
49    /// Persists accumulated pipeline variables back to the task item's dynamic_vars column.
50    fn update_task_item_pipeline_vars(
51        &self,
52        task_item_id: &str,
53        pipeline_vars_json: &str,
54    ) -> Result<()>;
55    /// Loads the human-readable name of a task.
56    fn load_task_name(&self, task_id: &str) -> Result<Option<String>>;
57    /// Lists recent command runs for log streaming or inspection.
58    fn list_task_log_runs(&self, task_id: &str, limit: usize) -> Result<Vec<TaskLogRunRow>>;
59    /// Inserts a new task-graph planning run record.
60    fn insert_task_graph_run(&self, run: &super::types::NewTaskGraphRun) -> Result<()>;
61    /// Updates the status of an existing task-graph run.
62    fn update_task_graph_run_status(&self, graph_run_id: &str, status: &str) -> Result<()>;
63    /// Persists one task-graph snapshot.
64    fn insert_task_graph_snapshot(
65        &self,
66        snapshot: &super::types::NewTaskGraphSnapshot,
67    ) -> Result<()>;
68    /// Loads debug bundles for graph-planning diagnostics.
69    fn load_task_graph_debug_bundles(&self, task_id: &str) -> Result<Vec<TaskGraphDebugBundle>>;
70    /// Deletes a task and returns log paths that should be cleaned up afterward.
71    fn delete_task_and_collect_log_paths(&self, task_id: &str) -> Result<Vec<String>>;
72    /// Inserts a command-run record.
73    fn insert_command_run(&self, run: &NewCommandRun) -> Result<()>;
74    /// Inserts an event record.
75    fn insert_event(&self, event: &DbEventRecord) -> Result<()>;
76    /// Updates an existing command-run record.
77    fn update_command_run(&self, run: &NewCommandRun) -> Result<()>;
78    /// Updates a command run and appends events in a single repository call.
79    fn update_command_run_with_events(
80        &self,
81        run: &NewCommandRun,
82        events: &[DbEventRecord],
83    ) -> Result<()>;
84    /// Persists a completed phase result together with its emitted events.
85    fn persist_phase_result_with_events(
86        &self,
87        run: &NewCommandRun,
88        events: &[DbEventRecord],
89    ) -> Result<()>;
90    /// Updates the operating-system PID associated with a running command.
91    fn update_command_run_pid(&self, run_id: &str, pid: i64) -> Result<()>;
92    /// Returns active child PIDs for a task.
93    fn find_active_child_pids(&self, task_id: &str) -> Result<Vec<i64>>;
94    /// Returns in-flight command runs for a task (FR-038).
95    fn find_inflight_command_runs_for_task(
96        &self,
97        task_id: &str,
98    ) -> Result<Vec<super::write_ops::InflightRunRecord>>;
99    /// Returns completed runs whose parent items are still `pending` (FR-038).
100    fn find_completed_runs_for_pending_items(
101        &self,
102        task_id: &str,
103    ) -> Result<Vec<super::write_ops::CompletedRunRecord>>;
104    /// Counts stale pending items (FR-038).
105    fn count_stale_pending_items(&self, task_id: &str) -> Result<i64>;
106    /// Counts recent heartbeat events for specified item IDs since cutoff (FR-052).
107    fn count_recent_heartbeats_for_items(
108        &self,
109        task_id: &str,
110        item_ids: &[String],
111        cutoff_ts: &str,
112    ) -> Result<i64>;
113    /// Persists the serialized pipeline-variable map for a task.
114    fn update_task_pipeline_vars(&self, task_id: &str, pipeline_vars_json: &str) -> Result<()>;
115    /// Persists the active ticket lists and preview content for a task item.
116    fn update_task_item_tickets(
117        &self,
118        task_item_id: &str,
119        ticket_files_json: &str,
120        ticket_content_json: &str,
121    ) -> Result<()>;
122}
agent_orchestrator/task_repository/trait_def.rs

agent_orchestrator/task_repository/
trait_def.rs
