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