Skip to main content

protocol/
watch.rs

1//! Lane-watch events: what a session's lane publishes to its watchers (the TUI, the RPC stream, herdr, the daemon's
2//! lane replica), one JSON object per event tagged by `type`. The session worker writes them from this enum and every
3//! watcher reads them back through [`WatchEvent::decode`], so a field is named in one place.
4//!
5//! Field order is the order the worker writes. A field a watcher may not get from another producer (an older worker,
6//! a remote server) reads as its default.
7
8use serde::{Deserialize, Serialize};
9use serde_json::Value;
10
11pub mod reducer;
12pub mod stream_fold;
13
14/// A queue a message can join while a run streams (`steer`, `followUp`, `nextRun`).
15#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
16#[serde(rename_all = "camelCase")]
17pub enum QueueKind {
18    Steer,
19    /// Held until the next run starts (the agent controller's `nextRun`): the run in progress never takes it, and the
20    /// next run's admission places it before its prompt.
21    NextRun,
22    /// Also what a kind this build does not know reads as.
23    #[default]
24    #[serde(other)]
25    FollowUp,
26}
27
28impl QueueKind {
29    pub fn name(self) -> &'static str {
30        match self {
31            QueueKind::Steer => "steer",
32            QueueKind::FollowUp => "followUp",
33            QueueKind::NextRun => "nextRun",
34        }
35    }
36
37    pub fn parse(name: &str) -> Option<QueueKind> {
38        match name {
39            "steer" => Some(QueueKind::Steer),
40            "followUp" => Some(QueueKind::FollowUp),
41            "nextRun" => Some(QueueKind::NextRun),
42            _ => None,
43        }
44    }
45}
46
47/// How a run, a compaction or a navigation ended.
48#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
49#[serde(rename_all = "lowercase")]
50pub enum Ended {
51    Completed,
52    Failed,
53    Aborted,
54    /// An automatic compaction a hook declined (it trimmed the context instead).
55    Declined,
56    #[default]
57    #[serde(other)]
58    Unknown,
59}
60
61impl Ended {
62    pub fn name(self) -> &'static str {
63        match self {
64            Ended::Completed => "completed",
65            Ended::Failed => "failed",
66            Ended::Aborted => "aborted",
67            Ended::Declined => "declined",
68            Ended::Unknown => "unknown",
69        }
70    }
71}
72
73/// Why something failed (`{code?, message}`).
74#[derive(Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
75pub struct Failure {
76    #[serde(default, skip_serializing_if = "Option::is_none")]
77    pub code: Option<String>,
78    #[serde(default)]
79    pub message: String,
80}
81
82/// One item of a [`WatchEvent::QueueUpdate`]: a queued message, or a host item shown as `<customType>`.
83#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
84#[serde(rename_all = "camelCase")]
85pub struct QueueItem {
86    /// `message`, or a host item's own type.
87    #[serde(rename = "type", default)]
88    pub item: String,
89    #[serde(default)]
90    pub kind: QueueKind,
91    #[serde(default)]
92    pub entry_id: String,
93    #[serde(default, skip_serializing_if = "Option::is_none")]
94    pub message: Option<Value>,
95    #[serde(default, skip_serializing_if = "Option::is_none")]
96    pub custom_type: Option<String>,
97}
98
99/// One lane-watch event.
100#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
101#[serde(tag = "type", rename_all = "snake_case", rename_all_fields = "camelCase")]
102pub enum WatchEvent {
103    RunStart {
104        #[serde(default)]
105        run_id: String,
106        #[serde(default)]
107        started_at: i64,
108        #[serde(default)]
109        lane: String,
110    },
111    RunEnd {
112        #[serde(default)]
113        lane: String,
114        #[serde(default)]
115        run_id: String,
116        #[serde(default)]
117        status: Ended,
118        /// A failed run's error (`code: run_failed`).
119        #[serde(default, skip_serializing_if = "Option::is_none")]
120        error: Option<Failure>,
121        #[serde(default)]
122        from_tip_id: Option<String>,
123        #[serde(default)]
124        tip_id: Option<String>,
125        #[serde(default)]
126        ended_at: i64,
127    },
128    /// A message started: the run's assistant answer or tool result, or a message outside a run (no `runId`).
129    MessageStart {
130        #[serde(default, skip_serializing_if = "Option::is_none")]
131        run_id: Option<String>,
132        #[serde(default)]
133        lane: String,
134        #[serde(default)]
135        message: Value,
136    },
137    /// The streaming assistant message changed: the provider frame and the usage so far, not the message (a watcher
138    /// folds the frame into the started message). An older worker's update carries the whole `message` instead.
139    MessageUpdate {
140        #[serde(default, skip_serializing_if = "Option::is_none")]
141        run_id: Option<String>,
142        #[serde(default)]
143        lane: String,
144        #[serde(default)]
145        frame: Value,
146        #[serde(default)]
147        usage: Value,
148        #[serde(default, skip_serializing_if = "Option::is_none")]
149        message: Option<Value>,
150    },
151    MessageEnd {
152        #[serde(default, skip_serializing_if = "Option::is_none")]
153        run_id: Option<String>,
154        #[serde(default)]
155        lane: String,
156        #[serde(default)]
157        message: Value,
158    },
159    ToolStart {
160        #[serde(default, skip_serializing_if = "Option::is_none")]
161        run_id: Option<String>,
162        #[serde(default)]
163        lane: String,
164        #[serde(default)]
165        tool_call_id: String,
166        #[serde(default)]
167        tool_name: String,
168        #[serde(default)]
169        args: Value,
170    },
171    ToolUpdate {
172        #[serde(default, skip_serializing_if = "Option::is_none")]
173        run_id: Option<String>,
174        #[serde(default)]
175        lane: String,
176        #[serde(default)]
177        tool_call_id: String,
178        #[serde(default)]
179        tool_name: String,
180        #[serde(default)]
181        args: Value,
182        #[serde(default)]
183        partial_result: Value,
184    },
185    ToolEnd {
186        #[serde(default, skip_serializing_if = "Option::is_none")]
187        run_id: Option<String>,
188        #[serde(default)]
189        lane: String,
190        #[serde(default)]
191        tool_call_id: String,
192        #[serde(default)]
193        tool_name: String,
194        #[serde(default)]
195        result: Value,
196        #[serde(default)]
197        is_error: bool,
198    },
199    /// The queued items now.
200    QueueUpdate {
201        #[serde(default)]
202        lane: String,
203        #[serde(default)]
204        queues: Vec<QueueItem>,
205    },
206    /// The session's name now (`None`: cleared); Rust-only, served as `ultron.session-ops` state.
207    SessionName {
208        #[serde(default)]
209        lane: String,
210        #[serde(default)]
211        name: Option<String>,
212    },
213    /// AgentSession `setSessionName` (Pi's RPC event).
214    SessionInfoChanged {
215        #[serde(default)]
216        lane: String,
217        #[serde(default, skip_serializing_if = "Option::is_none")]
218        name: Option<String>,
219    },
220    /// A journal entry joined the session (a message, a compaction, a branch summary, ...).
221    EntryAdded {
222        #[serde(default)]
223        lane: String,
224        #[serde(default)]
225        entry: Value,
226    },
227    /// A usage row, with the lane's totals after it.
228    Usage {
229        #[serde(default)]
230        lane: String,
231        #[serde(default)]
232        row: Value,
233        #[serde(default)]
234        totals: Value,
235    },
236    /// A generation's request failed and is retried after `delay_ms`.
237    RetryScheduled {
238        #[serde(default)]
239        lane: String,
240        #[serde(default, skip_serializing_if = "Option::is_none")]
241        run_id: Option<String>,
242        #[serde(default)]
243        step: String,
244        #[serde(default)]
245        attempt: u64,
246        #[serde(default)]
247        max_attempts: u64,
248        #[serde(default)]
249        delay_ms: u64,
250        #[serde(default)]
251        not_before: i64,
252        #[serde(default)]
253        error_message: String,
254    },
255    /// The retry wait ended: the step's next attempt starts.
256    RetryStart {
257        #[serde(default)]
258        lane: String,
259        #[serde(default, skip_serializing_if = "Option::is_none")]
260        run_id: Option<String>,
261        #[serde(default)]
262        step: String,
263        #[serde(default)]
264        attempt: u64,
265    },
266    /// A retried request's retries ended; `final_error` when the last attempt failed too.
267    RetryEnd {
268        #[serde(default)]
269        lane: String,
270        #[serde(default, skip_serializing_if = "Option::is_none")]
271        run_id: Option<String>,
272        #[serde(default)]
273        step: String,
274        #[serde(default)]
275        attempt: u64,
276        #[serde(default)]
277        success: bool,
278        #[serde(default, skip_serializing_if = "Option::is_none")]
279        final_error: Option<String>,
280    },
281    /// A chunk of a user `!` command's output (AgentSession `bash_execution_update`), under the command's id.
282    BashExecutionUpdate {
283        #[serde(default)]
284        lane: String,
285        #[serde(default, skip_serializing_if = "Option::is_none")]
286        id: Option<String>,
287        #[serde(default)]
288        delta: String,
289    },
290    /// A lane setting changed (`thinkingLevel`).
291    ConfigUpdate {
292        #[serde(default)]
293        lane: String,
294        #[serde(default)]
295        property: String,
296        #[serde(default)]
297        value: Value,
298    },
299    /// A compaction's or branch summary's request failed and is retried (AgentSession `onRetryScheduled`): the
300    /// retry's number, the retries allowed, the delay and the provider's error.
301    SummarizationRetryScheduled {
302        #[serde(default)]
303        lane: String,
304        #[serde(default)]
305        attempt: u64,
306        #[serde(default)]
307        max_attempts: u64,
308        #[serde(default)]
309        delay_ms: u64,
310        #[serde(default)]
311        error_message: String,
312    },
313    /// The summary's retry starts (`onRetryAttemptStart`): of a branch summary (`source: branchSummary`), or of a
314    /// compaction (`source: compaction`) for `reason`.
315    SummarizationRetryAttemptStart {
316        #[serde(default)]
317        lane: String,
318        #[serde(default)]
319        source: String,
320        #[serde(default, skip_serializing_if = "Option::is_none")]
321        reason: Option<String>,
322    },
323    /// The summary's retries ended, however they did (`onRetryFinished`).
324    SummarizationRetryFinished {
325        #[serde(default)]
326        lane: String,
327    },
328    /// A compaction started: `manual`, or `threshold` / `overflow` for one the session runs on its own in a run.
329    CompactionStart {
330        #[serde(default)]
331        lane: String,
332        #[serde(default, skip_serializing_if = "Option::is_none")]
333        run_id: Option<String>,
334        #[serde(default)]
335        reason: String,
336    },
337    CompactionEnd {
338        #[serde(default)]
339        lane: String,
340        #[serde(default, skip_serializing_if = "Option::is_none")]
341        run_id: Option<String>,
342        #[serde(default)]
343        reason: String,
344        #[serde(default)]
345        status: Ended,
346        #[serde(default, skip_serializing_if = "Option::is_none")]
347        error: Option<Failure>,
348    },
349    /// A tree navigation started (`target_id`: the entry, `None`: the root).
350    NavigationStart {
351        #[serde(default)]
352        lane: String,
353        #[serde(default)]
354        run_id: String,
355        #[serde(default)]
356        target_id: Option<String>,
357        #[serde(default)]
358        started_at: i64,
359    },
360    NavigationEnd {
361        #[serde(default)]
362        lane: String,
363        #[serde(default)]
364        run_id: String,
365        #[serde(default)]
366        status: Ended,
367        #[serde(default, skip_serializing_if = "Option::is_none")]
368        error: Option<Failure>,
369        #[serde(default)]
370        from_tip_id: Option<String>,
371        #[serde(default)]
372        tip_id: Option<String>,
373        #[serde(default)]
374        ended_at: i64,
375    },
376    /// Whether detached work of the session is active (the worker does not retire while it is).
377    Activity {
378        #[serde(default)]
379        lane: String,
380        #[serde(default)]
381        active: bool,
382    },
383}
384
385impl WatchEvent {
386    /// The event a lane-watch JSON object is; `None` for one of a type this build does not know (or a malformed one).
387    pub fn decode(event: &Value) -> Option<WatchEvent> {
388        serde_json::from_value(event.clone()).ok()
389    }
390
391    /// The event as it goes on the wire.
392    pub fn to_value(&self) -> Value {
393        serde_json::to_value(self).unwrap_or(Value::Null)
394    }
395}