Skip to main content

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: rap_protocol::ChoiceId,
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: rap_protocol::ChoiceId },
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}