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 { subagent: String, event: Box<RuntimeEvent> },
25    /// User-defined structured event for custom business semantics.
26    Structured { event_type: String, data: Value },
27}
28
29// ---------------------------------------------------------------------------
30// RuntimeEvent — unified event stream for all consumers
31// ---------------------------------------------------------------------------
32
33/// Unified runtime event — the single event type for both internal and external
34/// consumers (frontends, CLIs, tests).
35#[derive(Clone, Debug, Serialize, Deserialize)]
36#[serde(tag = "runtimeEventType", rename_all = "camelCase")]
37pub enum RuntimeEvent {
38    // --- Framework system events ---
39    TextDelta { session_id: SessionId, text: String },
40    ThoughtDelta { session_id: SessionId, text: String },
41    ToolCallStarted { session_id: SessionId, tool_name: String, args_json: String },
42    ToolCallFinished { session_id: SessionId, tool_name: String, summary: String },
43    AwaitingApproval { session_id: SessionId, request: ApprovalRequest },
44    Checkpoint { session_id: SessionId, checkpoint: CheckpointData },
45    RunFinished { session_id: SessionId },
46    RunCancelled { session_id: SessionId },
47    // --- Lightweight plan update (display-only, no execution semantics) ---
48    PlanUpdated { session_id: SessionId, objective: String, explanation: Option<String>, plan: Vec<PlanItem> },
49    // --- User-space events ---
50    /// A user-space event produced by a tool.
51    UserEvent { session_id: SessionId, event: UserEvent },
52}
53
54impl RuntimeEvent {
55    /// Get the session ID associated with this event.
56    pub fn session_id(&self) -> &SessionId {
57        match self {
58            RuntimeEvent::TextDelta { session_id, .. } => session_id,
59            RuntimeEvent::ThoughtDelta { session_id, .. } => session_id,
60            RuntimeEvent::ToolCallStarted { session_id, .. } => session_id,
61            RuntimeEvent::ToolCallFinished { session_id, .. } => session_id,
62            RuntimeEvent::AwaitingApproval { session_id, .. } => session_id,
63            RuntimeEvent::Checkpoint { session_id, .. } => session_id,
64            RuntimeEvent::RunFinished { session_id, .. } => session_id,
65            RuntimeEvent::RunCancelled { session_id, .. } => session_id,
66            RuntimeEvent::PlanUpdated { session_id, .. } => session_id,
67            RuntimeEvent::UserEvent { session_id, .. } => session_id,
68        }
69    }
70}
agent_base/types/events.rs

agent_base/types/
events.rs
