agent_orchestrator/
dto.rs

1use serde::{Deserialize, Serialize};
2use serde_json::Value;
3
4/// Payload accepted by task-creation APIs.
5#[derive(Debug, Deserialize, Default)]
6#[serde(default)]
7pub struct CreateTaskPayload {
8    /// Optional human-readable task name.
9    pub name: Option<String>,
10    /// Optional task goal shown in task summaries and prompts.
11    pub goal: Option<String>,
12    /// Project identifier used to scope task execution.
13    pub project_id: Option<String>,
14    /// Workspace identifier used to resolve files and resources.
15    pub workspace_id: Option<String>,
16    /// Workflow identifier to execute for the task.
17    pub workflow_id: Option<String>,
18    /// Explicit target files to associate with the task.
19    pub target_files: Option<Vec<String>>,
20    /// Parent task identifier when the task was spawned from another task.
21    pub parent_task_id: Option<String>,
22    /// Human-readable reason for task spawning.
23    pub spawn_reason: Option<String>,
24}
25
26/// Snapshot of the active orchestrator configuration exposed by read APIs.
27#[derive(Debug, Serialize)]
28pub struct ConfigOverview {
29    /// Fully materialized configuration object.
30    pub config: crate::config::OrchestratorConfig,
31    /// YAML serialization of [`Self::config`].
32    pub yaml: String,
33    /// Monotonic configuration version stored in persistence.
34    pub version: i64,
35    /// Timestamp when the configuration was last updated.
36    pub updated_at: String,
37}
38
39/// Summary view returned by task listing APIs.
40#[derive(Debug, Serialize)]
41pub struct TaskSummary {
42    /// Stable task identifier.
43    pub id: String,
44    /// Human-readable task name.
45    pub name: String,
46    /// Current task status.
47    pub status: String,
48    /// Timestamp when execution started.
49    pub started_at: Option<String>,
50    /// Timestamp when execution completed.
51    pub completed_at: Option<String>,
52    /// Goal or mission statement associated with the task.
53    pub goal: String,
54    /// Project scope for the task.
55    pub project_id: String,
56    /// Workspace scope for the task.
57    pub workspace_id: String,
58    /// Workflow chosen for execution.
59    pub workflow_id: String,
60    /// Files targeted by the task.
61    pub target_files: Vec<String>,
62    /// Total number of task items.
63    pub total_items: i64,
64    /// Number of finished task items.
65    pub finished_items: i64,
66    /// Number of failed task items.
67    pub failed_items: i64,
68    /// Creation timestamp.
69    pub created_at: String,
70    /// Last update timestamp.
71    pub updated_at: String,
72    /// Parent task identifier when spawned from another task.
73    pub parent_task_id: Option<String>,
74    /// Spawn reason inherited from the parent task relationship.
75    pub spawn_reason: Option<String>,
76    /// Spawn depth used to prevent runaway recursive task creation.
77    pub spawn_depth: i64,
78}
79
80/// Detailed task-item record returned by task detail APIs.
81#[derive(Debug, Serialize)]
82pub struct TaskItemDto {
83    /// Stable task-item identifier.
84    pub id: String,
85    /// Owning task identifier.
86    pub task_id: String,
87    /// Execution order within the task.
88    pub order_no: i64,
89    /// QA document path associated with the item.
90    pub qa_file_path: String,
91    /// Current item status.
92    pub status: String,
93    /// Relative paths to generated ticket files.
94    pub ticket_files: Vec<String>,
95    /// Parsed ticket payloads for convenience in API consumers.
96    pub ticket_content: Vec<Value>,
97    /// Whether the item still requires a fix phase.
98    pub fix_required: bool,
99    /// Whether the latest fix phase marked the item as fixed.
100    pub fixed: bool,
101    /// Last recorded error message for the item.
102    pub last_error: String,
103    /// Timestamp when item execution started.
104    pub started_at: Option<String>,
105    /// Timestamp when item execution completed.
106    pub completed_at: Option<String>,
107    /// Last update timestamp.
108    pub updated_at: String,
109}
110
111/// Persisted command-run record returned by task detail APIs.
112#[derive(Debug, Serialize)]
113pub struct CommandRunDto {
114    /// Stable command-run identifier.
115    pub id: String,
116    /// Task-item identifier that owns the run.
117    pub task_item_id: String,
118    /// Pipeline phase that produced the run.
119    pub phase: String,
120    /// Command string that was executed.
121    pub command: String,
122    /// Pre-rendered command template before variable substitution.
123    pub command_template: Option<String>,
124    /// Working directory used for execution.
125    pub cwd: String,
126    /// Workspace identifier resolved for the run.
127    pub workspace_id: String,
128    /// Agent identifier assigned to the run.
129    pub agent_id: String,
130    /// Exit code when the process terminated normally.
131    pub exit_code: Option<i64>,
132    /// Relative path to captured stdout.
133    pub stdout_path: String,
134    /// Relative path to captured stderr.
135    pub stderr_path: String,
136    /// Timestamp when execution started.
137    pub started_at: String,
138    /// Timestamp when execution ended.
139    pub ended_at: Option<String>,
140    /// Whether the run was interrupted before completion.
141    pub interrupted: bool,
142}
143
144/// Event row returned by task event queries.
145#[derive(Debug, Serialize)]
146pub struct EventDto {
147    /// Database identifier for the event row.
148    pub id: i64,
149    /// Owning task identifier.
150    pub task_id: String,
151    /// Optional task-item identifier associated with the event.
152    pub task_item_id: Option<String>,
153    /// Event type label.
154    pub event_type: String,
155    /// Structured event payload.
156    pub payload: Value,
157    /// Event creation timestamp.
158    pub created_at: String,
159}
160
161/// Expanded task detail payload returned by `task get` style APIs.
162#[derive(Debug, Serialize)]
163pub struct TaskDetail {
164    /// Top-level task summary.
165    pub task: TaskSummary,
166    /// Task items associated with the task.
167    pub items: Vec<TaskItemDto>,
168    /// Command runs recorded for the task.
169    pub runs: Vec<CommandRunDto>,
170    /// Events recorded for the task.
171    pub events: Vec<EventDto>,
172    /// Graph-debug snapshots captured for dynamic orchestration.
173    pub graph_debug: Vec<TaskGraphDebugBundle>,
174}
175
176/// Debug bundle capturing one graph-planning attempt and its snapshots.
177#[derive(Debug, Clone, Serialize)]
178pub struct TaskGraphDebugBundle {
179    /// Graph run identifier.
180    pub graph_run_id: String,
181    /// Workflow cycle that produced the graph run.
182    pub cycle: i64,
183    /// Planner source used for the run.
184    pub source: String,
185    /// Final status for the graph run.
186    pub status: String,
187    /// Effective fallback mode when planning degraded.
188    pub fallback_mode: Option<String>,
189    /// Planner failure classification when planning failed.
190    pub planner_failure_class: Option<String>,
191    /// Planner failure message when available.
192    pub planner_failure_message: Option<String>,
193    /// Effective graph serialized as JSON.
194    pub effective_graph_json: String,
195    /// Raw planner output serialized as JSON.
196    pub planner_raw_output_json: Option<String>,
197    /// Normalized plan payload serialized as JSON.
198    pub normalized_plan_json: Option<String>,
199    /// Execution replay payload serialized as JSON.
200    pub execution_replay_json: Option<String>,
201    /// Creation timestamp.
202    pub created_at: String,
203    /// Last update timestamp.
204    pub updated_at: String,
205}
206
207/// Log-chunk payload used by log streaming or tailing APIs.
208#[derive(Debug, Serialize)]
209pub struct LogChunk {
210    /// Command-run identifier.
211    pub run_id: String,
212    /// Phase that produced the log output.
213    pub phase: String,
214    /// Collected log content.
215    pub content: String,
216    /// Relative stdout path for the run.
217    pub stdout_path: String,
218    /// Relative stderr path for the run.
219    pub stderr_path: String,
220    /// Timestamp when the run started.
221    pub started_at: Option<String>,
222}
223
224/// Lightweight task-item row used by repository and scheduler internals.
225#[derive(Debug, Clone)]
226pub struct TaskItemRow {
227    /// Task-item identifier.
228    pub id: String,
229    /// QA document path associated with the item.
230    pub qa_file_path: String,
231    /// JSON-encoded dynamic variables attached to the item.
232    pub dynamic_vars_json: Option<String>,
233    /// Optional human-readable label for the item.
234    pub label: Option<String>,
235    /// Origin of the item, such as static workflow or dynamic generation.
236    pub source: String,
237    /// Current status of the item (e.g. `pending`, `qa_passed`, `skipped`).
238    pub status: String,
239}
240
241/// Preview metadata extracted from a ticket document.
242#[derive(Debug, Clone)]
243pub struct TicketPreviewData {
244    /// Ticket status parsed from the Markdown preamble.
245    pub status: String,
246    /// QA document path referenced by the ticket.
247    pub qa_document: String,
248}
249
250/// Placeholder QA path used for tickets that are not tied to a concrete file.
251pub const UNASSIGNED_QA_FILE_PATH: &str = "__UNASSIGNED__";
252
253/// Result of running a command phase in the orchestrator pipeline.
254#[derive(Debug)]
255pub struct RunResult {
256    /// Whether the command run was considered successful by the runner.
257    pub success: bool,
258    /// Numeric process exit code.
259    pub exit_code: i64,
260    /// Relative path to captured stdout.
261    pub stdout_path: String,
262    /// Relative path to captured stderr.
263    pub stderr_path: String,
264    /// Whether execution timed out.
265    pub timed_out: bool,
266    /// Measured duration in milliseconds when available.
267    pub duration_ms: Option<u64>,
268    /// Structured agent output parsed from the run.
269    pub output: Option<crate::collab::AgentOutput>,
270    /// Validation status assigned after output validation.
271    pub validation_status: String,
272    /// Agent identifier that performed the run.
273    pub agent_id: String,
274    /// Command-run identifier.
275    pub run_id: String,
276    /// Execution profile label chosen for the run.
277    pub execution_profile: String,
278    /// Effective execution mode label.
279    pub execution_mode: String,
280    /// Whether sandbox enforcement denied execution.
281    pub sandbox_denied: bool,
282    /// Human-readable sandbox denial reason when available.
283    pub sandbox_denial_reason: Option<String>,
284    /// Sandbox violation category when available.
285    pub sandbox_violation_kind: Option<String>,
286    /// Sandbox resource kind associated with the violation.
287    pub sandbox_resource_kind: Option<String>,
288    /// Sandbox network target associated with the violation.
289    pub sandbox_network_target: Option<String>,
290}
291
292impl RunResult {
293    /// Returns `true` when the run completed without timeout and exited with code `0`.
294    pub fn is_success(&self) -> bool {
295        self.success && !self.timed_out && self.exit_code == 0
296    }
297}
agent_orchestrator/dto.rs

agent_orchestrator/
dto.rs
