soothe_client/
events.rs

1//! Client-facing event namespace constants for the Soothe daemon wire protocol.
2//!
3//! Internal catalog types (`soothe.internal.*`) are server-only and are never
4//! broadcast to WebSocket clients.
5
6use crate::verbosity::VerbosityTier;
7
8// ---------------------------------------------------------------------------
9// Plan / goal
10// ---------------------------------------------------------------------------
11
12/// Plan created.
13pub const EVENT_PLAN_CREATED: &str = "soothe.cognition.plan.created";
14/// Plan batch started.
15pub const EVENT_PLAN_BATCH_STARTED: &str = "soothe.cognition.plan.batch.started";
16/// Plan reflected.
17pub const EVENT_PLAN_REFLECTED: &str = "soothe.cognition.plan.reflected";
18
19/// Goal created.
20pub const EVENT_GOAL_CREATED: &str = "soothe.cognition.goal.created";
21/// Goal completed.
22pub const EVENT_GOAL_COMPLETED: &str = "soothe.cognition.goal.completed";
23/// Goal failed.
24pub const EVENT_GOAL_FAILED: &str = "soothe.cognition.goal.failed";
25/// Goal deferred.
26pub const EVENT_GOAL_DEFERRED: &str = "soothe.cognition.goal.deferred";
27/// Goal batch started.
28pub const EVENT_GOAL_BATCH_STARTED: &str = "soothe.cognition.goal.batch.started";
29/// Goal reported.
30pub const EVENT_GOAL_REPORTED: &str = "soothe.cognition.goal.reported";
31/// Goal directives applied.
32pub const EVENT_GOAL_DIRECTIVES_APPLIED: &str = "soothe.cognition.goal.directives.applied";
33
34// ---------------------------------------------------------------------------
35// Subagents
36// ---------------------------------------------------------------------------
37
38/// Deep research started.
39pub const EVENT_DEEP_RESEARCH_STARTED: &str = "soothe.subagent.deep_research.started";
40/// Deep research progress.
41pub const EVENT_DEEP_RESEARCH_PROGRESS: &str = "soothe.subagent.deep_research.progress";
42/// Deep research step completed.
43pub const EVENT_DEEP_RESEARCH_STEP_COMPLETED: &str = "soothe.subagent.deep_research.step.completed";
44/// Deep research gather summary.
45pub const EVENT_DEEP_RESEARCH_GATHER_SUMMARY: &str = "soothe.subagent.deep_research.gather.summary";
46/// Deep research crawl summary.
47pub const EVENT_DEEP_RESEARCH_CRAWL_SUMMARY: &str = "soothe.subagent.deep_research.crawl.summary";
48/// Deep research completed.
49pub const EVENT_DEEP_RESEARCH_COMPLETED: &str = "soothe.subagent.deep_research.completed";
50
51// ---------------------------------------------------------------------------
52// Control / cards / tools
53// ---------------------------------------------------------------------------
54
55/// Replay complete control-plane frame.
56pub const EVENT_REPLAY_COMPLETE: &str = "replay_complete";
57/// Loop reattached control-plane frame.
58pub const EVENT_LOOP_REATTACHED_WIRE: &str = "loop_reattached";
59
60/// Card replay begin.
61pub const EVENT_CARD_REPLAY_BEGIN: &str = "card.replay_begin";
62/// Card created.
63pub const EVENT_CARD_CREATED: &str = "card.created";
64/// Card replay end.
65pub const EVENT_CARD_REPLAY_END: &str = "card.replay_end";
66
67/// Tool started.
68pub const EVENT_TOOL_STARTED: &str = "soothe.tool.execution.started";
69/// Tool completed.
70pub const EVENT_TOOL_COMPLETED: &str = "soothe.tool.execution.completed";
71/// Tool error.
72pub const EVENT_TOOL_ERROR: &str = "soothe.tool.execution.error";
73
74/// Stream tool call update.
75pub const EVENT_STREAM_TOOL_CALL_UPDATE: &str = "soothe.stream.tool_call.update";
76/// Tool call updates batch.
77pub const EVENT_TOOL_CALL_UPDATES_BATCH: &str = "tool_call_updates_batch";
78
79// ---------------------------------------------------------------------------
80// StrangeLoop / branch / protocol / output / autopilot / error
81// ---------------------------------------------------------------------------
82
83/// Strange loop started.
84pub const EVENT_STRANGE_LOOP_STARTED: &str = "soothe.cognition.strange_loop.started";
85/// Strange loop completed.
86pub const EVENT_STRANGE_LOOP_COMPLETED: &str = "soothe.cognition.strange_loop.completed";
87/// Strange loop plan decision.
88pub const EVENT_STRANGE_LOOP_PLAN_DECISION: &str = "soothe.cognition.strange_loop.plan.decision";
89/// Strange loop reasoned.
90pub const EVENT_STRANGE_LOOP_REASONED: &str = "soothe.cognition.strange_loop.reasoned";
91/// Strange loop step started.
92pub const EVENT_STRANGE_LOOP_STEP_STARTED: &str = "soothe.cognition.strange_loop.step.started";
93/// Strange loop step queued.
94pub const EVENT_STRANGE_LOOP_STEP_QUEUED: &str = "soothe.cognition.strange_loop.step.queued";
95/// Strange loop step completed.
96pub const EVENT_STRANGE_LOOP_STEP_COMPLETED: &str = "soothe.cognition.strange_loop.step.completed";
97/// Strange loop context compacted.
98pub const EVENT_STRANGE_LOOP_CONTEXT_COMPACTED: &str =
99    "soothe.cognition.strange_loop.context.compacted";
100
101/// Branch created.
102pub const EVENT_BRANCH_CREATED: &str = "soothe.cognition.branch.created";
103/// Branch retry started.
104pub const EVENT_BRANCH_RETRY_STARTED: &str = "soothe.cognition.branch.retry.started";
105
106/// Message received.
107pub const EVENT_MESSAGE_RECEIVED: &str = "soothe.protocol.message.received";
108/// Message sent.
109pub const EVENT_MESSAGE_SENT: &str = "soothe.protocol.message.sent";
110
111/// Final report.
112pub const EVENT_FINAL_REPORT: &str = "soothe.output.autonomous.final_report.reported";
113
114/// Autopilot status changed.
115pub const EVENT_AUTOPILOT_STATUS_CHANGED: &str = "soothe.system.autopilot.status.changed";
116/// Autopilot goal created.
117pub const EVENT_AUTOPILOT_GOAL_CREATED: &str = "soothe.system.autopilot.goal.created";
118/// Autopilot goal progress.
119pub const EVENT_AUTOPILOT_GOAL_PROGRESS: &str = "soothe.system.autopilot.goal.reported";
120/// Autopilot goal completed.
121pub const EVENT_AUTOPILOT_GOAL_COMPLETED: &str = "soothe.system.autopilot.goal.completed";
122/// Autopilot goal suspended.
123pub const EVENT_AUTOPILOT_GOAL_SUSPENDED: &str = "soothe.system.autopilot.goal.suspended";
124/// Autopilot goal blocked.
125pub const EVENT_AUTOPILOT_GOAL_BLOCKED: &str = "soothe.system.autopilot.goal.blocked";
126/// Autopilot dreaming entered.
127pub const EVENT_AUTOPILOT_DREAMING_ENTERED: &str = "soothe.system.autopilot.dreaming.started";
128/// Autopilot dreaming exited.
129pub const EVENT_AUTOPILOT_DREAMING_EXITED: &str = "soothe.system.autopilot.dreaming.completed";
130
131/// General failure.
132pub const EVENT_GENERAL_FAILED: &str = "soothe.error.general.failed";
133
134/// Parsed 4-segment namespace components.
135#[derive(Debug, Clone, PartialEq, Eq)]
136pub struct ParsedNamespace {
137    /// Domain (e.g. `cognition`).
138    pub domain: String,
139    /// Component (e.g. `plan`).
140    pub component: String,
141    /// Action (e.g. `created`).
142    pub action: String,
143}
144
145/// Split a 4-segment event namespace into domain / component / action.
146///
147/// Returns `None` for non-`soothe.*` paths, short paths, or `soothe.internal.*`.
148pub fn parse_namespace(ns: &str) -> Option<ParsedNamespace> {
149    let parts: Vec<&str> = ns.split('.').collect();
150    if parts.len() < 4 || parts[0] != "soothe" {
151        return None;
152    }
153    if parts[1] == "internal" {
154        return None;
155    }
156    Some(ParsedNamespace {
157        domain: parts[1].to_string(),
158        component: parts[2].to_string(),
159        action: parts[3].to_string(),
160    })
161}
162
163/// Classify an event type / namespace into a verbosity tier.
164pub fn classify_event_verbosity(event_type_or_namespace: &str) -> VerbosityTier {
165    if let Some(parsed) = parse_namespace(event_type_or_namespace) {
166        return classify_by_domain(&parsed.domain, event_type_or_namespace);
167    }
168    classify_by_event_type_string(event_type_or_namespace)
169}
170
171fn classify_by_domain(domain: &str, full: &str) -> VerbosityTier {
172    match domain {
173        "cognition" => VerbosityTier::Normal,
174        "protocol" => VerbosityTier::Detailed,
175        "tool" => VerbosityTier::Internal,
176        "subagent" => classify_subagent_event(full),
177        "autopilot" | "system" => VerbosityTier::Normal,
178        "output" | "error" => VerbosityTier::Quiet,
179        _ => VerbosityTier::Normal,
180    }
181}
182
183fn classify_subagent_event(full: &str) -> VerbosityTier {
184    let Some(parsed) = parse_namespace(full) else {
185        return VerbosityTier::Normal;
186    };
187    match parsed.action.as_str() {
188        "started" | "completed" => VerbosityTier::Normal,
189        _ => VerbosityTier::Detailed,
190    }
191}
192
193fn classify_by_event_type_string(event_type: &str) -> VerbosityTier {
194    if event_type == EVENT_FINAL_REPORT || event_type == EVENT_GENERAL_FAILED {
195        return VerbosityTier::Quiet;
196    }
197    if event_type == EVENT_TOOL_STARTED {
198        return VerbosityTier::Internal;
199    }
200    VerbosityTier::Normal
201}
202
203/// Whether the event type represents a completion milestone.
204pub fn is_completion_event(event_type: &str) -> bool {
205    event_type.ends_with(".completed")
206        || event_type.ends_with(".failed")
207        || event_type == EVENT_GENERAL_FAILED
208}
209
210/// Lifecycle subagent events (started/completed) for progress UI.
211pub fn is_subagent_progress_event(event_type: &str) -> bool {
212    let Some(parsed) = parse_namespace(event_type) else {
213        return false;
214    };
215    parsed.domain == "subagent" && matches!(parsed.action.as_str(), "started" | "completed")
216}
217
218#[cfg(test)]
219mod tests {
220    use super::*;
221
222    #[test]
223    fn parse_valid() {
224        let p = parse_namespace("soothe.cognition.plan.created").unwrap();
225        assert_eq!(p.domain, "cognition");
226        assert_eq!(p.component, "plan");
227        assert_eq!(p.action, "created");
228    }
229
230    #[test]
231    fn reject_internal() {
232        assert!(parse_namespace("soothe.internal.loop.completed").is_none());
233    }
234
235    #[test]
236    fn classify_quiet() {
237        assert_eq!(
238            classify_event_verbosity(EVENT_FINAL_REPORT),
239            VerbosityTier::Quiet
240        );
241    }
242}
soothe_client/events.rs

soothe_client/
events.rs
