infinity_agent_core/system/events.rs
1//! Events emitted by the high-level agent system.
2
3use infinity_provider_protocol::Usage;
4
5use crate::message::InfinityMessage;
6
7/// A user choice requested by a tool server. Responses are POSTed to
8/// `response_url`.
9#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
10pub struct UserChoice {
11 pub id: String,
12 pub prompt: String,
13 pub choices: Vec<String>,
14 pub default: usize,
15 pub response_url: String,
16}
17
18/// A single observable event from a thread's execution.
19///
20/// This type is `Clone` and carries no
21/// provider-specific generics, so embeddings can fan events out to multiple
22/// subscribers or buffer them freely.
23#[derive(Debug, Clone)]
24pub enum AgentEvent {
25 /// A user text input was accepted into the thread's history.
26 UserInput { text: String },
27 /// A tool result (from an asynchronously dispatched tool call) was
28 /// accepted into the thread's history, or a synchronous tool produced a
29 /// result inline. Clients should render the first segment type they
30 /// support; the raw text is always included as a trailing `Text` segment.
31 ToolResult {
32 segments: Vec<rap_protocol::DisplaySegment>,
33 },
34 /// A subscription event or thread report was injected into this thread.
35 SubscriptionEvent { name: String, text: String },
36 /// A tool server requires OAuth authorization before it can proceed.
37 OAuthRequired { auth_url: String },
38 /// A compaction summary replaced the beginning of the in-memory history.
39 CompactionApplied,
40 /// A completion round is about to stream.
41 CompletionStarted,
42 /// A chunk of assistant text.
43 TextChunk { text: String },
44 /// The model started reasoning.
45 ThinkingStarted,
46 /// A chunk of reasoning text.
47 ThinkingChunk { text: String },
48 /// The model finished reasoning.
49 ThinkingEnded,
50 /// The model called a tool. `display_as` is the pretty-printed form from
51 /// the tool's display script, when available.
52 ToolCall {
53 name: String,
54 args: serde_json::Value,
55 display_as: Option<String>,
56 },
57 /// The completion round finished (its turn is synced to the store by the
58 /// time this event is observed). `usage` is the token usage reported by
59 /// the provider, if any.
60 CompletionFinished { usage: Option<Usage> },
61 /// A tool server requested a user choice. The choice has already been
62 /// persisted when this event is emitted.
63 UserChoiceRequired { choice: UserChoice },
64 /// A pending user choice became moot and has already been removed from
65 /// persistent state.
66 UserChoiceDismissed { choice_id: String },
67 /// Human-readable progress/diagnostic information (retries, warnings).
68 Info { text: String },
69}
70
71/// A live view of a thread, used to bring a newly attached subscriber up to
72/// date. Produced when a subscriber attaches to a running thread (see
73/// [`ThreadObserver::on_subscribe`](super::ThreadObserver::on_subscribe)).
74#[derive(Debug, Clone)]
75pub struct ReplaySnapshot {
76 /// Committed history followed by the in-flight buffered turn, so a
77 /// subscriber attaching while the model is streaming still sees the
78 /// partial assistant message.
79 pub history: Vec<InfinityMessage>,
80 /// In-progress reasoning text. Streamed reasoning is only committed to
81 /// history once complete, so without this a client attaching mid-thinking
82 /// would appear idle.
83 pub current_thinking: Option<String>,
84 /// Whether a completion is currently streaming.
85 pub in_progress: bool,
86 /// Choices awaiting a user response for this conversation.
87 pub pending_choices: Vec<UserChoice>,
88}