agent_sdk/
events.rs

1//! Agent events for real-time streaming.
2//!
3//! The [`AgentEvent`] enum represents all events that can occur during agent
4//! execution. These events are streamed via an async channel for real-time
5//! UI updates and logging.
6//!
7//! # Event Flow
8//!
9//! A typical event sequence looks like:
10//! 1. `Start` - Agent begins processing
11//! 2. `Text` / `ToolCallStart` / `ToolCallEnd` - Processing events
12//! 3. `TurnComplete` - One LLM round-trip finished
13//! 4. `Done` - Agent completed successfully, or `Error` if failed
14
15use crate::types::{ThreadId, TokenUsage, ToolResult, ToolTier};
16use serde::{Deserialize, Serialize};
17use std::time::Duration;
18
19/// Events emitted by the agent loop during execution.
20/// These are streamed to the client for real-time UI updates.
21#[derive(Clone, Debug, Serialize, Deserialize)]
22#[serde(tag = "type", rename_all = "snake_case")]
23pub enum AgentEvent {
24    /// Agent loop has started
25    Start { thread_id: ThreadId, turn: usize },
26
27    /// Agent is "thinking" - streaming text that may be shown as typing indicator
28    Thinking { message_id: String, text: String },
29
30    /// A text delta for streaming responses
31    TextDelta { message_id: String, delta: String },
32
33    /// Complete text block from the agent
34    Text { message_id: String, text: String },
35
36    /// Agent is about to call a tool
37    ToolCallStart {
38        id: String,
39        name: String,
40        display_name: String,
41        input: serde_json::Value,
42        tier: ToolTier,
43    },
44
45    /// Tool execution completed
46    ToolCallEnd {
47        id: String,
48        name: String,
49        display_name: String,
50        result: ToolResult,
51    },
52
53    /// Progress update from an async tool operation
54    ToolProgress {
55        /// Tool call ID
56        id: String,
57        /// Tool name
58        name: String,
59        /// Human-readable display name
60        display_name: String,
61        /// Progress stage
62        stage: String,
63        /// Human-readable progress message
64        message: String,
65        /// Optional tool-specific data
66        data: Option<serde_json::Value>,
67    },
68
69    /// Tool requires confirmation before execution.
70    /// The application determines the confirmation type (normal, PIN, biometric).
71    ToolRequiresConfirmation {
72        id: String,
73        name: String,
74        input: serde_json::Value,
75        description: String,
76    },
77
78    /// Agent turn completed (one LLM round-trip)
79    TurnComplete { turn: usize, usage: TokenUsage },
80
81    /// Agent loop completed successfully
82    Done {
83        thread_id: ThreadId,
84        total_turns: usize,
85        total_usage: TokenUsage,
86        duration: Duration,
87    },
88
89    /// An error occurred during execution
90    Error { message: String, recoverable: bool },
91
92    /// Context was compacted to reduce size
93    ContextCompacted {
94        /// Number of messages before compaction
95        original_count: usize,
96        /// Number of messages after compaction
97        new_count: usize,
98        /// Estimated tokens before compaction
99        original_tokens: usize,
100        /// Estimated tokens after compaction
101        new_tokens: usize,
102    },
103
104    /// Progress update from a running subagent
105    SubagentProgress {
106        /// ID of the parent tool call that spawned this subagent
107        subagent_id: String,
108        /// Name of the subagent (e.g., "explore", "plan")
109        subagent_name: String,
110        /// Tool name that just started or completed
111        tool_name: String,
112        /// Brief context for the tool (e.g., file path, pattern)
113        tool_context: String,
114        /// Whether the tool completed (false = started, true = ended)
115        completed: bool,
116        /// Whether the tool succeeded (only meaningful if completed)
117        success: bool,
118        /// Current total tool count for this subagent
119        tool_count: u32,
120        /// Current total tokens used by this subagent
121        total_tokens: u64,
122    },
123}
124
125impl AgentEvent {
126    #[must_use]
127    pub const fn start(thread_id: ThreadId, turn: usize) -> Self {
128        Self::Start { thread_id, turn }
129    }
130
131    #[must_use]
132    pub fn thinking(message_id: impl Into<String>, text: impl Into<String>) -> Self {
133        Self::Thinking {
134            message_id: message_id.into(),
135            text: text.into(),
136        }
137    }
138
139    #[must_use]
140    pub fn text_delta(message_id: impl Into<String>, delta: impl Into<String>) -> Self {
141        Self::TextDelta {
142            message_id: message_id.into(),
143            delta: delta.into(),
144        }
145    }
146
147    #[must_use]
148    pub fn text(message_id: impl Into<String>, text: impl Into<String>) -> Self {
149        Self::Text {
150            message_id: message_id.into(),
151            text: text.into(),
152        }
153    }
154
155    #[must_use]
156    pub fn tool_call_start(
157        id: impl Into<String>,
158        name: impl Into<String>,
159        display_name: impl Into<String>,
160        input: serde_json::Value,
161        tier: ToolTier,
162    ) -> Self {
163        Self::ToolCallStart {
164            id: id.into(),
165            name: name.into(),
166            display_name: display_name.into(),
167            input,
168            tier,
169        }
170    }
171
172    #[must_use]
173    pub fn tool_call_end(
174        id: impl Into<String>,
175        name: impl Into<String>,
176        display_name: impl Into<String>,
177        result: ToolResult,
178    ) -> Self {
179        Self::ToolCallEnd {
180            id: id.into(),
181            name: name.into(),
182            display_name: display_name.into(),
183            result,
184        }
185    }
186
187    #[must_use]
188    pub fn tool_progress(
189        id: impl Into<String>,
190        name: impl Into<String>,
191        display_name: impl Into<String>,
192        stage: impl Into<String>,
193        message: impl Into<String>,
194        data: Option<serde_json::Value>,
195    ) -> Self {
196        Self::ToolProgress {
197            id: id.into(),
198            name: name.into(),
199            display_name: display_name.into(),
200            stage: stage.into(),
201            message: message.into(),
202            data,
203        }
204    }
205
206    #[must_use]
207    pub const fn done(
208        thread_id: ThreadId,
209        total_turns: usize,
210        total_usage: TokenUsage,
211        duration: Duration,
212    ) -> Self {
213        Self::Done {
214            thread_id,
215            total_turns,
216            total_usage,
217            duration,
218        }
219    }
220
221    #[must_use]
222    pub fn error(message: impl Into<String>, recoverable: bool) -> Self {
223        Self::Error {
224            message: message.into(),
225            recoverable,
226        }
227    }
228
229    #[must_use]
230    pub const fn context_compacted(
231        original_count: usize,
232        new_count: usize,
233        original_tokens: usize,
234        new_tokens: usize,
235    ) -> Self {
236        Self::ContextCompacted {
237            original_count,
238            new_count,
239            original_tokens,
240            new_tokens,
241        }
242    }
243}
agent_sdk/events.rs

agent_sdk/
events.rs
