feat(events): orchestration emits the agent event schema

Orchestration carried its own OrchestratorEvent enum between the
orchestrator and the SSE projection. Its variants move onto
AgentEventPayload, so orchestrated and single-agent runs share one
vocabulary, and StreamItem carries that payload directly.

Emitted frames are unchanged; the projection reads the same field sets
under a different type.

Ref: #623
Signed-off-by: Jacob Hull <jacob@planethull.com>

Author: jakedipity

crates/aura-events/src/agent.rs

@@ -17,6 +17,7 @@
 
 use serde::{Deserialize, Serialize};
 
+use crate::orchestration::{IterationTimings, RoutingMode};
 use crate::{
     AgentContext, ApprovalCompleted, ApprovalPending, ApprovalRequested, McpServerStatus,
     ProgressToken, WorkerPhase,
@@ -41,15 +42,11 @@ impl AgentEvent {
 
 #[derive(Clone, Debug, Serialize, Deserialize)]
 #[serde(tag = "outcome", rename_all = "snake_case")]
-pub enum ToolOutcome {
+pub enum Outcome {
     Success { result: String },
     Failure { error: String },
 }
 
-/// What an agent has to say about its own execution.
-///
-/// `#[non_exhaustive]` because the vocabulary grows as producers move onto this
-/// schema — orchestration events in particular are not yet modelled here.
 #[derive(Clone, Debug, Serialize, Deserialize)]
 #[serde(tag = "type", rename_all = "snake_case")]
 #[non_exhaustive]
@@ -70,6 +67,8 @@ pub enum AgentEventPayload {
 
     Reasoning {
         content: String,
+        #[serde(default, skip_serializing_if = "Option::is_none")]
+        task_id: Option<usize>,
     },
 
     /// The model's decision to call a tool, ahead of any execution.
@@ -84,14 +83,22 @@ pub enum AgentEventPayload {
         tool_name: String,
         #[serde(default, skip_serializing_if = "Option::is_none")]
         progress_token: Option<ProgressToken>,
+        /// Present when the producer knows them at start; a run that announces
+        /// the call separately carries them on [`Self::ToolRequested`].
+        #[serde(default, skip_serializing_if = "Option::is_none")]
+        arguments: Option<serde_json::Value>,
+        #[serde(default, skip_serializing_if = "Option::is_none")]
+        task_id: Option<usize>,
     },
 
     ToolComplete {
         tool_id: String,
         tool_name: String,
         duration_ms: u64,
         #[serde(flatten)]
-        outcome: ToolOutcome,
+        outcome: Outcome,
+        #[serde(default, skip_serializing_if = "Option::is_none")]
+        task_id: Option<usize>,
     },
 
     ToolProgress {
@@ -106,7 +113,7 @@ pub enum AgentEventPayload {
     WorkerPhase {
         phase: WorkerPhase,
         #[serde(default, skip_serializing_if = "Option::is_none")]
-        task_id: Option<String>,
+        task_id: Option<usize>,
     },
 
     /// Provider-billed tokens for one turn.
@@ -142,6 +149,76 @@ pub enum AgentEventPayload {
     ApprovalPending(ApprovalPending),
 
     ApprovalCompleted(ApprovalCompleted),
+
+    PlanCreated {
+        goal: String,
+        tasks: Vec<String>,
+        routing_mode: RoutingMode,
+        routing_rationale: String,
+        planning_response: String,
+    },
+
+    DirectAnswer {
+        response: String,
+        routing_rationale: String,
+    },
+
+    ClarificationNeeded {
+        question: String,
+        #[serde(default, skip_serializing_if = "Option::is_none")]
+        options: Option<Vec<String>>,
+        routing_rationale: String,
+    },
+
+    TaskStarted {
+        task_id: usize,
+        description: String,
+        orchestrator_id: String,
+    },
+
+    TaskCompleted {
+        task_id: usize,
+        duration_ms: u64,
+        orchestrator_id: String,
+        #[serde(flatten)]
+        outcome: Outcome,
+    },
+
+    /// A worker's gated call is waiting on an approval the run will not block
+    /// for; one per parked call.
+    TaskBlocked {
+        task_id: usize,
+        tool_call_id: String,
+        decision_id: String,
+        tool_name: String,
+        orchestrator_id: String,
+    },
+
+    /// The run stopped to await its parked approvals. Terminal.
+    RunParked {
+        run_id: String,
+        decision_ids: Vec<String>,
+        expires_at: String,
+        iteration: usize,
+    },
+
+    IterationComplete {
+        iteration: usize,
+        will_replan: bool,
+        reasoning: String,
+        gaps: Vec<String>,
+        timings: IterationTimings,
+    },
+
+    ReplanStarted {
+        iteration: usize,
+        /// `"coordinator"` or `"failure"`.
+        trigger: String,
+    },
+
+    Synthesizing {
+        iteration: usize,
+    },
 }
 
 #[cfg(test)]
@@ -174,6 +251,8 @@ mod tests {
             tool_id: "call_1".to_string(),
             tool_name: "list_files".to_string(),
             progress_token: None,
+            arguments: None,
+            task_id: None,
         });
         assert!(matches!(start, AgentEventPayload::ToolStart { .. }));
 
@@ -188,10 +267,11 @@ mod tests {
     #[test]
     fn tool_outcome_flattens_onto_tool_complete() {
         let json = serde_json::to_value(AgentEventPayload::ToolComplete {
+            task_id: None,
             tool_id: "call_1".to_string(),
             tool_name: "list_files".to_string(),
             duration_ms: 12,
-            outcome: ToolOutcome::Failure {
+            outcome: Outcome::Failure {
                 error: "boom".to_string(),
             },
         })
@@ -202,6 +282,29 @@ mod tests {
         assert_eq!(json["error"], "boom");
     }
 
+    /// `ToolStart` is emitted by a lone agent and by an orchestration worker,
+    /// so nothing about the payload says which frames it becomes — only the
+    /// envelope does.
+    #[test]
+    fn a_shared_variant_is_told_apart_by_its_agent_not_its_payload() {
+        let payload = || AgentEventPayload::ToolStart {
+            tool_id: "call_1".to_string(),
+            tool_name: "list_files".to_string(),
+            progress_token: None,
+            arguments: None,
+            task_id: None,
+        };
+
+        let alone = AgentEvent::single_agent(payload());
+        let worker = AgentEvent::new(
+            AgentContext::worker("log_worker", None, "coordinator"),
+            payload(),
+        );
+
+        assert!(alone.agent.is_single_agent());
+        assert!(!worker.agent.is_single_agent());
+    }
+
     #[test]
     fn an_event_carries_its_emitting_agent() {
         let event = AgentEvent::new(

crates/aura-events/src/lib.rs

@@ -101,6 +101,24 @@ impl AgentContext {
         }
     }
 
+    /// Whether this is the lone agent of an unorchestrated run.
+    ///
+    /// Several payload variants are emitted by both modes, so the projection
+    /// that turns an event into a frame reads this rather than the variant.
+    pub fn is_single_agent(&self) -> bool {
+        self.agent_id == "main"
+    }
+
+    /// The agent that plans an orchestrated run and synthesises its answer.
+    /// Workers name it as their parent.
+    pub fn coordinator() -> Self {
+        Self {
+            agent_id: "coordinator".to_string(),
+            agent_name: None,
+            parent_agent_id: None,
+        }
+    }
+
     /// Create a worker agent context with parent hierarchy
     pub fn worker(
         id: impl Into<String>,