agent_base/types/
events.rs

1use serde::{Deserialize, Serialize};
2use serde_json::Value;
3
4use super::approval::ApprovalRequest;
5use super::checkpoint::CheckpointData;
6use super::plan_update::PlanItem;
7use super::session::SessionId;
8
9// ---------------------------------------------------------------------------
10// UserEvent — user-space events produced by tools
11// ---------------------------------------------------------------------------
12
13/// User-space events produced by tools during execution.
14///
15/// Tools send these through `ToolContext::emit_user_event()`. The framework
16/// wraps them in [`RuntimeEvent::UserEvent`] before delivering to external
17/// consumers.
18#[derive(Clone, Debug, Serialize, Deserialize)]
19#[serde(tag = "userEventType", rename_all = "camelCase")]
20pub enum UserEvent {
21    /// Tool progress notification.
22    Progress { text: String },
23    /// Sub-agent event forwarding (used by `SubAgentTool`).
24    SubAgentEvent {
25        subagent: String,
26        event: Box<RuntimeEvent>,
27    },
28    /// User-defined structured event for custom business semantics.
29    Structured { event_type: String, data: Value },
30}
31
32// ---------------------------------------------------------------------------
33// RuntimeEvent — unified event stream for all consumers
34// ---------------------------------------------------------------------------
35
36/// Unified runtime event — the single event type for both internal and external
37/// consumers (frontends, CLIs, tests).
38#[derive(Clone, Debug, Serialize, Deserialize)]
39#[serde(tag = "runtimeEventType", rename_all = "camelCase")]
40pub enum RuntimeEvent {
41    // --- Framework system events ---
42    TextDelta {
43        session_id: SessionId,
44        text: String,
45    },
46    ThoughtDelta {
47        session_id: SessionId,
48        text: String,
49    },
50    ToolCallStarted {
51        session_id: SessionId,
52        tool_name: String,
53        args_json: String,
54    },
55    ToolCallFinished {
56        session_id: SessionId,
57        tool_name: String,
58        summary: String,
59    },
60    AwaitingApproval {
61        session_id: SessionId,
62        request: ApprovalRequest,
63    },
64    Checkpoint {
65        session_id: SessionId,
66        checkpoint: CheckpointData,
67    },
68    RunFinished {
69        session_id: SessionId,
70    },
71    RunCancelled {
72        session_id: SessionId,
73    },
74    // --- Lightweight plan update (display-only, no execution semantics) ---
75    PlanUpdated {
76        session_id: SessionId,
77        objective: String,
78        explanation: Option<String>,
79        plan: Vec<PlanItem>,
80    },
81    // --- User-space events ---
82    /// A user-space event produced by a tool.
83    UserEvent {
84        session_id: SessionId,
85        event: UserEvent,
86    },
87}
88
89impl RuntimeEvent {
90    /// Get the session ID associated with this event.
91    pub fn session_id(&self) -> &SessionId {
92        match self {
93            RuntimeEvent::TextDelta { session_id, .. } => session_id,
94            RuntimeEvent::ThoughtDelta { session_id, .. } => session_id,
95            RuntimeEvent::ToolCallStarted { session_id, .. } => session_id,
96            RuntimeEvent::ToolCallFinished { session_id, .. } => session_id,
97            RuntimeEvent::AwaitingApproval { session_id, .. } => session_id,
98            RuntimeEvent::Checkpoint { session_id, .. } => session_id,
99            RuntimeEvent::RunFinished { session_id, .. } => session_id,
100            RuntimeEvent::RunCancelled { session_id, .. } => session_id,
101            RuntimeEvent::PlanUpdated { session_id, .. } => session_id,
102            RuntimeEvent::UserEvent { session_id, .. } => session_id,
103        }
104    }
105}
agent_base/types/events.rs

agent_base/types/
events.rs
