orion_core/
events.rs

1use serde::{Deserialize, Serialize};
2
3use crate::messages::{Message, ToolResult};
4
5/// Events emitted by the agent loop.
6/// Mirrors pi-agent-core's event system for UI reactivity.
7///
8/// This enum is `#[non_exhaustive]`: match it with a wildcard arm, as new
9/// event variants may be added in a minor release.
10#[derive(Debug, Clone, Serialize, Deserialize)]
11#[serde(tag = "type", rename_all = "snake_case")]
12#[non_exhaustive]
13pub enum AgentEvent {
14    /// Agent begins processing a prompt.
15    AgentStart,
16
17    /// Agent finished all processing.
18    AgentEnd {
19        /// All messages produced during this `prompt()` call.
20        messages: Vec<Message>,
21    },
22
23    /// A new turn begins (one LLM call + any tool executions).
24    TurnStart,
25
26    /// A turn completed.
27    TurnEnd {
28        /// The assistant message produced by the turn.
29        message: Message,
30        /// Results of any tools the turn executed.
31        tool_results: Vec<ToolResult>,
32    },
33
34    /// A message was added (user, assistant, or tool_result).
35    MessageStart {
36        /// The message that was added.
37        message: Message,
38    },
39
40    /// Streaming delta for the current assistant message.
41    MessageDelta {
42        /// The new token/chunk of text.
43        delta: String,
44        /// Tokens generated so far in this response.
45        tokens_generated: u32,
46        /// Current generation speed.
47        tokens_per_sec: f64,
48    },
49
50    /// A message is complete.
51    MessageEnd {
52        /// The completed message.
53        message: Message,
54    },
55
56    /// Final timing statistics for a completed generation. Emitted once per
57    /// successful response so the UI / observability layer can record the real
58    /// time-to-first-token and generation time (not approximated from tps).
59    GenerationStats {
60        /// Tokens generated in the response.
61        tokens_generated: u32,
62        /// Tokens in the formatted prompt.
63        prompt_tokens: u32,
64        /// Average generation speed in tokens per second.
65        tokens_per_sec: f64,
66        /// Time to the first emitted token, in milliseconds.
67        time_to_first_token_ms: f64,
68        /// Total generation time, in milliseconds.
69        generation_time_ms: f64,
70    },
71
72    /// A tool execution started.
73    ToolExecStart {
74        /// Id of the tool call being executed.
75        tool_call_id: String,
76        /// Name of the tool being executed.
77        tool_name: String,
78        /// Arguments passed to the tool.
79        args: serde_json::Value,
80    },
81
82    /// Streaming progress from a tool execution.
83    ToolExecUpdate {
84        /// Id of the tool call reporting progress.
85        tool_call_id: String,
86        /// Name of the tool reporting progress.
87        tool_name: String,
88        /// Partial output emitted so far.
89        partial: String,
90    },
91
92    /// A tool execution completed.
93    ToolExecEnd {
94        /// Id of the completed tool call.
95        tool_call_id: String,
96        /// Name of the completed tool.
97        tool_name: String,
98        /// The tool's result.
99        result: ToolResult,
100    },
101
102    /// Context budget info after formatting.
103    ContextBudget {
104        /// Tokens used by the prepared prompt.
105        used_tokens: u32,
106        /// Maximum context tokens available.
107        max_tokens: u32,
108        /// Number of messages kept in the prompt.
109        messages_in_context: u32,
110        /// Number of messages pruned to fit.
111        messages_pruned: u32,
112    },
113
114    /// Non-fatal warning during processing.
115    Warning {
116        /// Human-readable warning text.
117        message: String,
118    },
119
120    /// Fatal error that stopped processing.
121    Error {
122        /// Human-readable error text.
123        message: String,
124    },
125}
orion_core/events.rs

orion_core/
events.rs
